Quick start in 3 steps
1. Call the catalog with no auth
Public read endpoints work anonymously at 60 requests per minute per IP. Try one item:
curl 'https://omnicost.com/api/v1/items?limit=1'2. Get a free developer key
Sign up for a key to raise your limit to 200 requests per minute. The key is returned once in the response body.
curl -X POST https://omnicost.com/api/v1/keys/signup \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","name":"Your name"}'
# → { "key": "omc_pub_xxxx" }3. Send the key as a bearer token
Add an Authorization header to every authenticated request:
curl 'https://omnicost.com/api/v1/search?q=hormigon%20HA-25' \
-H 'Authorization: Bearer omc_pub_xxxx'Base URL
All REST endpoints are served from a single production base URL. There is no separate sandbox host — anonymous reads are safe to test against directly.
https://omnicost.com/api/v1Authentication
Public read endpoints are open and need no credentials, but each tier has its own rate limit. To raise your limit, create a free developer key with a single POST request and send it on every call as a bearer token. Public keys are prefixed omc_pub_; organization keys, issued from an Omnicost workspace for higher production limits, are prefixed omc_org_. API access, MCP access, and the in-app agent are included in the same workspace plans.
Authorization: Bearer omc_pub_xxxxRate limits
Three tiers, each reporting its limit back in the response meta:
| Anonymous | 60 req/min per IP | No key. Reported as tier: "anon". |
|---|---|---|
| Free developer key | 200 req/min | omc_pub_ key from /keys/signup. Reported as tier: "public_dev". |
| Organization key | Higher production limits | omc_org_ key from a workspace plan. Reported as tier: "org". |
The MCP server publishes its own free-tier ceiling separately: 200 requests per minute and a 10,000 requests-per-month cap, declared in /.well-known/mcp.json. When you exceed a limit, the API returns an error object with a retry_after_seconds hint.
Endpoints
Every endpoint below maps to a real route documented in the OpenAPI spec. Examples show abbreviated live shapes.
/api/v1/itemsList canonical catalog items. Each item is one real-world product aggregated across vendors, with a trust-weighted median price. Paginate with the opaque cursor.
GET /api/v1/items?limit=1
{
"items": [
{
"id": "ci_1d97def3-...",
"name": "Hydraulic crane rental rate",
"unit": "hour",
"vendor_count": 1,
"observation_count": 1,
"median_price": { "cents": 4959, "currency": "USD", "recorded_at": "2026-06-16T05:15:06Z" },
"updated_at": "2026-06-16T05:15:06Z"
}
],
"cursor": "MTc4MTU4...",
"meta": { "tier": "anon", "rate_limit_per_min": 60 }
}/api/v1/items/{id}Fetch one canonical item with its full vendor breakdown and 90-day price history. Send Accept: text/markdown for an LLM-readable rendering.
GET /api/v1/items/ci_1d97def3-...
{
"item": { "id": "ci_1d97def3-...", "name": "...", "median_price": { ... } },
"vendors": [
{ "vendor_sku_id": "vsku_...", "source": { "name": "...", "region": "ES", "trust_score": 82, "url": "..." },
"price": { "cents": 5100, "currency": "USD" }, "observed_at": "..." }
],
"price_history": [ { "recorded_at": "...", "price_cents": 4959, "currency": "USD" } ]
}/api/v1/searchSemantic search over the canonical catalog using Vectorize embeddings. Required q parameter; optional limit. Results are canonical items with an added relevance score.
GET /api/v1/search?q=hormigon%20HA-25&limit=5
{
"query": "hormigon HA-25",
"results": [
{ "id": "ci_...", "name": "...", "median_price": { ... }, "score": 0.91 }
],
"mode": "vector"
}/api/v1/feeds/items.atom · .rss · /region/{ES|US|AR|MX|CL|CO|PE|BR|GB|EU}Delta feeds of recently updated items, as Atom or RSS, globally or per region. Useful for keeping an external mirror in sync without polling every item.
GET /api/v1/feeds/region/ES # Atom feed of recent Spain updates/api/v1/pricing · /api/v1/usage/pricing lists the public access limits per tier. /usage returns the current usage and remaining quota for the calling key.
GET /api/v1/usage
-H 'Authorization: Bearer omc_pub_xxxx'/api/v1/keys/signup · /api/v1/keys/revokeCreate a free developer key (returns it once) or revoke the calling key. Signup takes an email and a name.
POST /api/v1/keys/signup
{ "email": "you@example.com", "name": "Your name" }
# → { "key": "omc_pub_xxxx" }MCP server
For AI agents, Omnicost exposes the same catalog over the Model Context Protocol at /api/mcp, using the streamable-HTTP transport with OAuth2 (scopes catalog:read and catalog:search). The discovery card at /.well-known/mcp.json lists four tools — search_catalog, get_item, list_categories, and get_decomposition (the BC3 recipe tree of materials, labor, and machinery per unit). Point any MCP-capable client at the discovery URL to connect.
Data model
- Each canonical item aggregates N vendor SKUs — one per source.
- Each vendor SKU links to a crawl source with a trust_score from 0 to 100.
- median_price_cents is computed nightly, weighted by source trust.
- cpv_code (EU CPV) is set only when the source provides it — never AI-assigned.