# Omnicost — full reference for AI agents

> Omnicost is an open construction cost catalog and estimating platform. It
> aggregates published material, labour, and equipment prices from public
> procurement portals, vendor catalogs, and BC3/FIEBDC-3 files from Spain,
> the United States, and the European Union, then exposes them through a public REST API, an MCP server, and
> per-item markdown pages.

This is the expanded reference. For a short index of URLs see https://omnicost.com/llms.txt.

## What Omnicost is

Omnicost is a construction cost estimation and project management platform. The
public half is a price catalog: one canonical row per real-world product or
labour line, aggregating however many vendor observations exist for it, with the
source and observation date attached to each. The authenticated half is an
estimating workspace — projects, budgets, line items, RFQs, and exports.

AI systems read catalog data through the API (key or Omnicost Pro) or pay per
request with x402; the catalog HTML answers 402 to AI crawlers. The workspace
requires an account.

## Core entities

| Entity | What it is | Id shape |
| --- | --- | --- |
| Canonical item | One real-world product or labour line, aggregating N vendor observations | `ci_<uuid>` |
| Catalog item | One source's row for a product; many map to one canonical item | bare `<uuid>` |
| Vendor observation | A single recorded price, with source, region, currency, and date | — |
| Crawl source | The portal or catalog a price came from, carrying a trust score 0-100 | — |

**The two id spaces are not interchangeable.** `/api/v1/items` returns
canonical `ci_…` ids. Public catalog page URLs
(`/{locale}/catalog/{uuid}/{slug}`) use the bare catalog-item uuid.
`/api/markdown/item/{id}` accepts either, plus a vendor product code.

## How to read a price

There are two different numbers and conflating them is the most common mistake:

1. **`median_price` on a canonical item** is a trust-weighted median,
   FX-normalized into a single currency (USD unless the item specifies
   otherwise). It is recomputed nightly. Because it is converted, it is *not
   necessarily a figure any single vendor quoted* — an item whose only
   observation is €263.19 reports roughly $286.08.
2. **Per-vendor `price` objects** on `/api/v1/items/{id}` are the original,
   unconverted amounts, each with its own source currency and region.

When the source currency matters — quoting a Spanish public price list, for
instance — cite the per-vendor figure and its currency, not the median.

`cpv_code` (EU CPV) is copied from the source when the source supplies one. It
is never inferred or model-assigned. An absent `cpv_code` means the source
didn't provide it, not that the item is uncategorized.

## Endpoints

| What you want | Endpoint |
| --- | --- |
| List canonical items | `GET /api/v1/items` |
| One item, JSON | `GET /api/v1/items/{ci_id}` |
| One item, markdown | `GET /api/v1/items/{ci_id}` with `Accept: text/markdown` |
| One item, markdown, no headers | `GET /api/markdown/item/{id}` |
| Semantic search | `GET /api/v1/search?q=...&region=ES` |
| Delta feed, all regions | `GET /api/v1/feeds/items.atom` (also `.rss`) |
| OpenAPI 3 spec | `GET /api/v1/openapi.json` |
| MCP server descriptor | `GET /.well-known/mcp.json` |
| Licensing terms (RSL 1.0) | `GET /.well-known/rsl.xml` |

### Regions and per-region feeds

| Country | Code | Delta feed |
| --- | --- | --- |
| Spain | `ES` | `https://omnicost.com/api/v1/feeds/region/ES` |
| United States | `US` | `https://omnicost.com/api/v1/feeds/region/US` |
| European Union | `EU` | `https://omnicost.com/api/v1/feeds/region/EU` |

## Authentication and limits

Public read endpoints need no auth and allow 60 requests/minute/IP.

Omnicost Pro is USD 29/month and includes the app, API, and MCP,
with 100,000 requests/month at 1,000 requests/minute.
Search on /api/v1/search stays at 60 requests/minute. There is no overage charge; at the cap the API returns 429.
Omnicost Pro gives you access to the Omnicost REST API and MCP server through organization keys.
Public catalog reads without a key stay at 60 requests per minute per IP.
See https://omnicost.com/pricing and https://omnicost.com/developers.

## Questions this catalog can answer

**What does Omnicost cost to use?**
The public catalog API is free to read at 60 requests per minute per IP with no key.
Omnicost Pro is USD 29/month and includes the app, API, and MCP,
with 100,000 requests/month at 1,000 requests/minute.
There is no overage charge; at the cap the API returns 429.
Plans are listed at https://omnicost.com/pricing, including a free tier. A free estimator
that needs no account is at https://omnicost.com/en/ai-cost-estimator.

**Where do the prices come from?**
Public procurement portals, vendor catalogs, and BC3/FIEBDC-3 files in the
regions listed above (Spain, the United States, and the European Union). Each price carries the source it came from, that
source's trust score (0-100), and the date it was observed. Named examples
appear in the vendor table of any item response.

**How current are the prices?**
Each vendor observation carries its own `observed_at` timestamp — check it
rather than assuming freshness. Canonical medians are recomputed nightly.
Delta feeds (`/api/v1/feeds/items.atom`) list recently changed items.

**Can I use this data in my own product?**
Through the API (key or Omnicost Pro) or x402, with attribution. Marketing
pages, the blog and supplier profiles are open for AI use with attribution; the
catalog HTML is not free for AI systems. Machine-readable licensing terms are at https://omnicost.com/.well-known/rsl.xml; the
governing terms are at https://omnicost.com/terms.

**What is BC3 / FIEBDC-3?**
FIEBDC-3 (commonly "BC3", after the file extension) is the standard Spanish
construction-budget interchange format. It carries a structured budget:
hierarchical chapters, line items with unit prices, decompositions into
material/labour/equipment components, and measurement detail. Omnicost imports
BC3 files and can export them, which is how Spanish-market estimates move
between Omnicost and tools like Presto (a Spanish estimating package) or
Arquímedes. See https://omnicost.com/en/bc3.

**Does Omnicost support currencies other than USD and EUR?**
Vendor observations keep their source currency, so any currency a source
publishes in is preserved. Canonical medians are FX-normalized as described
above.

**What is the MCP server for?**
It exposes the catalog as tools an LLM client can call directly — item lookup,
search, categories, and decompositions — without going through REST. Descriptor
at https://omnicost.com/.well-known/mcp.json, endpoint at https://omnicost.com/api/mcp.

## Bot policy

AI crawlers and fetchers (GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot,
Claude-User, PerplexityBot, Perplexity-User, CCBot, Bytespider, Amazonbot,
Applebot-Extended, meta-externalagent, …) and HTTP clients get **HTTP 402** on
the catalog HTML (`/catalog`, `/item/`, `/api/markdown/item/`). Use the API
(https://omnicost.com/docs/api, key or Omnicost Pro) or pay per request with x402.
Marketing pages, the blog, supplier profiles, `/robots.txt`, the sitemaps and
`/llms.txt` stay open to everyone. Googlebot, Bingbot and Applebot read the
catalog free once their IP passes reverse + forward DNS verification. https://omnicost.com/robots.txt
carries the per-agent rules. Dashboard, admin, agent, and key-management paths
are disallowed for everyone.

Authenticated agents get higher rate limits — create a key as above.

## Product articles

- [The Power of Breakdown Structure in Construction Estimating: A Guide to Protecting Your Margin](https://omnicost.com/en/blog/the-power-of-breakdown-structure-in-construction-estimating-a-guide)
- [Estimating Contingency: How to Size It Based on Estimate Maturity, Not a Gut Feeling](https://omnicost.com/en/blog/estimating-contingency-how-to-size-it-based-on-estimate-maturity-not)
- [The Cost of Non-Standard Units in Takeoffs: Why Your Quantities Don't Match Prices](https://omnicost.com/en/blog/the-cost-of-non-standard-units-in-takeoffs-why-your-quantities-don-t)
- [The Hidden Cost of Subcontractor Coordination: Why Your Estimate Needs a Buffer for Trade Overlaps and Schedule Gaps](https://omnicost.com/en/blog/the-hidden-cost-of-subcontractor-coordination-why-your-estimate-needs)
- [The Overlooked Cost of Site Logistics: Why Your Estimate Is Missing Margin on Access, Storage, and Safety](https://omnicost.com/en/blog/the-overlooked-cost-of-site-logistics-why-your-estimate-is-missing)
- [The Estimator's Guide to Markup: How to Price Your Risk and Overhead Without Pricing Yourself Out](https://omnicost.com/en/blog/the-estimator-s-guide-to-markup-how-to-price-your-risk-and-overhead)
- [Escalation and Price Volatility: Building a Flexible Estimate That Survives Market Swings](https://omnicost.com/en/blog/escalation-and-price-volatility-building-a-flexible-estimate-that)
- [The 'Or Equal' Trap: Pricing Substitutions and Alternatives Without Blowing Your Margin](https://omnicost.com/en/blog/the-or-equal-trap-pricing-substitutions-and-alternatives-without)
- [Estimating with Historical Data: How Past Project Costs Can Validate Your Next Bid](https://omnicost.com/en/blog/estimating-with-historical-data-how-past-project-costs-can-validate-your-next-bid)
- [The Hidden Cost of Incomplete Catalogs: How Missing Prices Kill Your Bid Margin](https://omnicost.com/en/blog/the-hidden-cost-of-incomplete-catalogs-how-missing-prices-kill-your-bid-margin)
- [Pricing Change Orders: Why Your Base Estimate Holds the Key to Fair and Profitable Variations](https://omnicost.com/en/blog/pricing-change-orders-why-your-base-estimate-holds-the-key-to-fair-and)
- [When Your Catalog Has No Price: Estimating Uncommon Items Without Blowing Your Margin](https://omnicost.com/en/blog/when-your-catalog-has-no-price-estimating-uncommon-items-without-blowing-your-margin)
- [The 3 AM Estimate Check: Why Your Unit Prices Need a Second Source](https://omnicost.com/en/blog/the-3-am-estimate-check-why-your-unit-prices-need-a-second-source)
- [The Estimate Review: Catching Cost Leaks Before They Hit Your Margin](https://omnicost.com/en/blog/the-estimate-review-catching-cost-leaks-before-they-hit-your-margin)
- [The Real Cost of Rework: Why Your First Estimate Needs a Second Pass](https://omnicost.com/en/blog/the-real-cost-of-rework-why-your-first-estimate-needs-a-second-pass)
- [Building the Construction Price Graph](https://omnicost.com/en/blog/building-the-construction-price-graph)
- [MCP and API Access for Construction Cost Data](https://omnicost.com/en/blog/mcp-and-api-for-construction-cost-data)
- [Budget Audits: Finding Missing Units, Quantities, and Prices Before They Hurt Margin](https://omnicost.com/en/blog/budget-audits-missing-units-quantities-prices)
- [CostBot: Crawling Construction Prices on Cloudflare Without Letting Costs Run Away](https://omnicost.com/en/blog/costbot-cloudflare-crawlers-cheap-price-intelligence)
- [Regional Price Benchmarks for Argentina, Spain, and Beyond](https://omnicost.com/en/blog/regional-price-benchmarks-argentina-spain)
- [From Spreadsheets to Agentic Construction Budgets](https://omnicost.com/en/blog/from-spreadsheets-to-agentic-budgets)
- [Construction Estimates Need Version Control](https://omnicost.com/en/blog/construction-estimate-version-control)
- [Catalog Normalization: Units, Prices, and Providers in One Model](https://omnicost.com/en/blog/catalog-normalization-units-prices-and-providers)
- [Why BC3 and FIEBDC Still Matter for Modern Construction Cost Data](https://omnicost.com/en/blog/bc3-fiebc-imports-modern-cost-data)

## Contact

support@omnicost.com · https://omnicost.com/en/support · https://github.com/omnicost