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. Consigue una clave de desarrollador gratuita
Date de alta para subir tu límite a 200 peticiones por minuto. La clave se devuelve una sola vez en el cuerpo de la respuesta.
curl -X POST https://omnicost.com/api/v1/keys/signup \
-H 'Content-Type: application/json' \
-d '{"email":"tu@ejemplo.com","name":"Tu nombre"}'
# → { "key": "omc_pub_xxxx" }3. Envía la clave como bearer token
Añade la cabecera Authorization a cada petición autenticada:
curl 'https://omnicost.com/api/v1/search?q=hormigon%20HA-25' \
-H 'Authorization: Bearer omc_pub_xxxx'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 son abiertos y no requieren credenciales, pero cada nivel tiene su propio límite de uso. Para subir tu límite, crea una clave de desarrollador gratuita con una sola petición POST y envíala en cada llamada como bearer token. Las claves públicas llevan el prefijo omc_pub_; las claves de organización, emitidas desde un workspace de Omnicost para límites de producción más altos, llevan el prefijo omc_org_. El acceso a la API, el acceso MCP y el agente integrado están incluidos en los mismos planes de workspace.
Authorization: Bearer omc_pub_xxxxLímites de uso
Tres niveles, cada uno informa 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 desarrollador gratuita | 200 pet/min | Clave omc_pub_ de /keys/signup. Se informa como tier: "public_dev". |
| 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 publica su propio techo de nivel gratuito por separado: 200 peticiones por minuto y un tope de 10.000 peticiones al mes, declarados 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 la clave que llama.
GET /api/v1/usage
-H 'Authorization: Bearer omc_pub_xxxx'/api/v1/keys/signup · /api/v1/keys/revokeCrea una clave de desarrollador gratuita (se devuelve una sola vez) o revoca la clave que llama. El alta requiere un email y un nombre.
POST /api/v1/keys/signup
{ "email": "tu@ejemplo.com", "name": "Tu nombre" }
# → { "key": "omc_pub_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.