Empieza en 3 pasos
1. Llama al catálogo sin autenticación
Los endpoints de lectura pública funcionan de forma anónima a 60 peticiones por minuto por IP. Prueba con un ítem:
curl 'https://omnicost.com/api/v1/items?limit=1'2. Busca en el catálogo
La búsqueda semántica funciona sin clave. Respeta el límite anónimo:
curl 'https://omnicost.com/api/v1/search?q=hormigon%20HA-25&limit=5'3. Lee el contrato OpenAPI
Genera un cliente tipado a partir del documento OpenAPI 3.1 en vivo:
curl 'https://omnicost.com/api/v1/openapi.json'URL base
Todos los endpoints REST se sirven desde una única URL base de producción. No hay un host de sandbox aparte — las lecturas anónimas se pueden probar directamente sin riesgo.
https://omnicost.com/api/v1Autenticación
Los endpoints de lectura pública del catálogo son abiertos y no requieren credenciales — corren bajo un límite anónimo por IP. Los límites de producción más altos llegan con una clave de organización de workspace Omnicost (omc_org_…), emitida desde un workspace con sesión iniciada. La API, MCP y el agente integrado usan los mismos planes de workspace. No hay una página de alta de clave free en el navegador.
Authorization: Bearer omc_org_xxxxLímites de uso
Los niveles informan su límite en el meta de la respuesta:
| Anónimo | 60 pet/min por IP | Sin clave. Se informa como tier: "anon". |
|---|---|---|
| Clave de organización | Límites de producción más altos | Clave omc_org_ de un plan de workspace. Se informa como tier: "org". |
El servidor MCP declara sus techos en /.well-known/mcp.json. Al superar un límite, la API devuelve un objeto de error con una pista retry_after_seconds.
Endpoints
Cada endpoint de abajo corresponde a una ruta real documentada en la especificación OpenAPI. Los ejemplos muestran formas reales abreviadas.
/api/v1/itemsLista los ítems canónicos del catálogo. Cada ítem es un producto real agregado entre proveedores, con un precio mediano ponderado por confianza. Pagina con el cursor opaco.
GET /api/v1/items?limit=1
{
"items": [
{
"id": "ci_1d97def3-...",
"name": "Alquiler de grúa hidráulica",
"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}Obtén un ítem canónico con su desglose completo de proveedores y su histórico de precios de 90 días. Envía Accept: text/markdown para una representación legible por LLM.
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/searchBúsqueda semántica sobre el catálogo canónico mediante embeddings de Vectorize. Parámetro q obligatorio; limit opcional. Los resultados son ítems canónicos con una puntuación de relevancia añadida.
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}Feeds de novedades de ítems actualizados recientemente, en Atom o RSS, globales o por región. Útiles para mantener un mirror externo sincronizado sin sondear cada ítem.
GET /api/v1/feeds/region/ES # Feed Atom de novedades de España/api/v1/pricing · /api/v1/usage/pricing lista los límites de acceso públicos por nivel. /usage devuelve el uso actual y la cuota restante de una clave de workspace autenticada.
GET /api/v1/usage
-H 'Authorization: Bearer omc_org_xxxx'Servidor MCP
Para agentes de IA, Omnicost expone el mismo catálogo mediante el Model Context Protocol en /api/mcp, con transporte streamable-HTTP y OAuth2 (ámbitos catalog:read y catalog:search). La tarjeta de descubrimiento en /.well-known/mcp.json lista cuatro herramientas — search_catalog, get_item, list_categories y get_decomposition (el árbol de receta BC3 de materiales, mano de obra y maquinaria por unidad). Apunta cualquier cliente compatible con MCP a la URL de descubrimiento para conectarte.
Modelo de datos
- Cada ítem canónico agrega N SKUs de proveedor — uno por fuente.
- Cada SKU de proveedor se vincula a una fuente de crawl con un trust_score de 0 a 100.
- median_price_cents se calcula cada noche, ponderado por la confianza de la fuente.
- cpv_code (CPV de la UE) solo se asigna cuando la fuente lo proporciona — nunca lo asigna la IA.