{"openapi":"3.1.0","info":{"title":"licita-agent","version":"0.1.0","description":"Agent-native procurement intelligence API for the Spanish public sector (TED data, IT/software/cyber CPV vertical). All data endpoints return the envelope { data, meta: { request_id, price_usd, paid, provenance[] } }. Errors return { error: { code, message, hint } }. Paid endpoints use x402 v2: an unpaid request gets 402 with a base64 PAYMENT-REQUIRED header; sign the EIP-3009 transferWithAuthorization and retry with the PAYMENT-SIGNATURE header (legacy v1 X-PAYMENT still accepted). See /v1/pricing for the full flow."},"servers":[{"url":"/"}],"paths":{"/v1/search":{"get":{"operationId":"search","security":[{"paymentSignature":[]}],"summary":"Search awards, tenders and contracts","description":"Full-text + structured search. q uses Postgres FTS (spanish) over tender title/description. Price: $0.02 per call.","parameters":[{"name":"q","in":"query","required":false,"description":"Full-text query (plainto_tsquery, spanish)","schema":{"type":"string","maxLength":200}},{"name":"cpv","in":"query","required":false,"description":"CPV code or prefix, e.g. \"72\" matches 72*","schema":{"type":"string","pattern":"^\\d{2,8}(-\\d)?$"}},{"name":"buyer","in":"query","required":false,"description":"Buyer name fragment (case/accent-insensitive)","schema":{"type":"string","minLength":2,"maxLength":200}},{"name":"company","in":"query","required":false,"description":"Company name fragment (case/accent-insensitive)","schema":{"type":"string","minLength":2,"maxLength":200}},{"name":"region","in":"query","required":false,"description":"NUTS region code or prefix, e.g. \"ES61\"","schema":{"type":"string","pattern":"^[A-Za-z]{2}[A-Za-z0-9]{0,3}$"}},{"name":"from","in":"query","required":false,"description":"Start date, ISO YYYY-MM-DD (award_date / publication_date / start_date per type)","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date, ISO YYYY-MM-DD","schema":{"type":"string","format":"date"}},{"name":"type","in":"query","required":false,"description":"Row kind to search","schema":{"type":"string","enum":["award","tender","contract"],"default":"award"}},{"name":"page","in":"query","required":false,"description":"Page number (1-based)","schema":{"type":"integer","minimum":1,"default":1}},{"name":"size","in":"query","required":false,"description":"Page size (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Success envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["kind","id","source_ref","title","date","buyer","company","value","currency","cpv","tender_id","tender_source_ref"],"properties":{"kind":{"type":"string","enum":["award","tender","contract"]},"id":{"type":"integer"},"source_ref":{"type":["string","null"]},"title":{"type":["string","null"]},"date":{"type":["string","null"],"format":"date"},"buyer":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"company":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"value":{"type":["number","null"]},"currency":{"type":["string","null"],"example":"EUR"},"cpv":{"type":["string","null"],"example":"72000000"},"tender_id":{"type":["integer","null"],"description":"Tender this row belongs to (equals id for tender rows)."},"tender_source_ref":{"type":["string","null"],"description":"Tender publication reference (e.g. the TED notice number)."}}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"400":{"description":"Invalid query parameters (invalid_query)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"402":{"description":"Payment required (x402 v2). The response also carries a base64 PAYMENT-REQUIRED header whose JSON is { x402Version: 2, resource, accepts[] }; accepts[0] is the exact requirement (scheme \"exact\", CAIP-2 network, USDC asset, amount in base units, payTo, maxTimeoutSeconds, EIP-712 domain). Sign an EIP-3009 transferWithAuthorization and retry with header PAYMENT-SIGNATURE (v2; the legacy v1 X-PAYMENT header is still accepted). In dev mode obtain a proof via POST /v1/dev-faucet.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements: { x402Version: 2, resource, accepts[] }.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","enum":[1,2]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string","example":"20000"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"},"resource":{"type":"string"}}}},"hint":{"type":"string"}}}}}},"404":{"description":"Not found (not_found)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"429":{"description":"Rate limited (rate_limited)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"500":{"description":"Internal error (internal)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/v1/tenders/{id}":{"get":{"operationId":"getTender","security":[{"paymentSignature":[]}],"summary":"Full tender with awards and provenance","description":"Full tender record, its awards, and provenance including the TED notice URL. Price: $0.02 per call.","parameters":[{"name":"id","in":"path","required":true,"description":"Internal numeric id (obtain via /v1/search)","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Success envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"source_ref":{"type":["string","null"]},"notice_type":{"type":["string","null"]},"publication_date":{"type":["string","null"],"format":"date"},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"cpv_main":{"type":["string","null"]},"cpv_all":{"type":"array","items":{"type":"string"}},"procedure_type":{"type":["string","null"]},"deadline":{"type":["string","null"],"format":"date-time"},"estimated_value":{"type":["number","null"]},"currency":{"type":["string","null"]},"nuts":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"buyer":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"awards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"tender_id":{"type":["integer","null"]},"source_ref":{"type":["string","null"]},"award_date":{"type":["string","null"],"format":"date"},"lot":{"type":["string","null"]},"winner":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"value":{"type":["number","null"]},"currency":{"type":["string","null"]},"bidders_count":{"type":["integer","null"]},"framework":{"type":"boolean"},"duration_months":{"type":["number","null"]},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"}}}}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"400":{"description":"Invalid query parameters (invalid_query)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"402":{"description":"Payment required (x402 v2). The response also carries a base64 PAYMENT-REQUIRED header whose JSON is { x402Version: 2, resource, accepts[] }; accepts[0] is the exact requirement (scheme \"exact\", CAIP-2 network, USDC asset, amount in base units, payTo, maxTimeoutSeconds, EIP-712 domain). Sign an EIP-3009 transferWithAuthorization and retry with header PAYMENT-SIGNATURE (v2; the legacy v1 X-PAYMENT header is still accepted). In dev mode obtain a proof via POST /v1/dev-faucet.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements: { x402Version: 2, resource, accepts[] }.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","enum":[1,2]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string","example":"20000"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"},"resource":{"type":"string"}}}},"hint":{"type":"string"}}}}}},"404":{"description":"Not found (not_found)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"429":{"description":"Rate limited (rate_limited)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"500":{"description":"Internal error (internal)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/v1/companies/{id}":{"get":{"operationId":"getCompany","security":[{"paymentSignature":[]}],"summary":"Company profile with aggregate win stats","description":"Company profile plus cross-source identity (aliases, identifiers) and aggregates: wins, total awarded value (framework values are ceilings — see meta.caveats), top CPVs, top buyers. Price: $0.05 per call.","parameters":[{"name":"id","in":"path","required":true,"description":"Internal numeric id (obtain via /v1/search)","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Success envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"source_ref":{"type":["string","null"]},"name":{"type":"string"},"country":{"type":["string","null"]},"nif":{"type":["string","null"]},"aliases":{"type":"array","items":{"type":"string"},"description":"Alternative names observed for this company in source payloads."},"identifiers":{"type":"array","items":{"type":"object","required":["scheme","value"],"properties":{"scheme":{"type":"string","enum":["nif","ted","placsp"]},"value":{"type":"string"}}},"description":"Cross-source identity: the normalized NIF plus each source's source_ref linked to this company."},"stats":{"type":"object","properties":{"wins":{"type":"integer"},"total_awarded_value":{"type":["number","null"]},"top_cpvs":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label_en":{"type":["string","null"]},"label_es":{"type":["string","null"]},"wins":{"type":"integer"},"total_value":{"type":["number","null"]}}}},"top_buyers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"wins":{"type":"integer"},"total_value":{"type":["number","null"]}}}}}}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"400":{"description":"Invalid query parameters (invalid_query)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"402":{"description":"Payment required (x402 v2). The response also carries a base64 PAYMENT-REQUIRED header whose JSON is { x402Version: 2, resource, accepts[] }; accepts[0] is the exact requirement (scheme \"exact\", CAIP-2 network, USDC asset, amount in base units, payTo, maxTimeoutSeconds, EIP-712 domain). Sign an EIP-3009 transferWithAuthorization and retry with header PAYMENT-SIGNATURE (v2; the legacy v1 X-PAYMENT header is still accepted). In dev mode obtain a proof via POST /v1/dev-faucet.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements: { x402Version: 2, resource, accepts[] }.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","enum":[1,2]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string","example":"20000"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"},"resource":{"type":"string"}}}},"hint":{"type":"string"}}}}}},"404":{"description":"Not found (not_found)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"429":{"description":"Rate limited (rate_limited)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"500":{"description":"Internal error (internal)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/v1/companies/{id}/awards":{"get":{"operationId":"getCompanyAwards","security":[{"paymentSignature":[]}],"summary":"Paginated awards won by a company","description":"Paginated award list with tender context (tender id, source ref, buyer). Price: $0.05 per call.","parameters":[{"name":"id","in":"path","required":true,"description":"Internal numeric id (obtain via /v1/search)","schema":{"type":"integer","minimum":1}},{"name":"page","in":"query","required":false,"description":"Page number (1-based)","schema":{"type":"integer","minimum":1,"default":1}},{"name":"size","in":"query","required":false,"description":"Page size (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Success envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"tender_id":{"type":["integer","null"]},"source_ref":{"type":["string","null"]},"award_date":{"type":["string","null"],"format":"date"},"lot":{"type":["string","null"]},"winner":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"value":{"type":["number","null"]},"currency":{"type":["string","null"]},"bidders_count":{"type":["integer","null"]},"framework":{"type":"boolean"},"duration_months":{"type":["number","null"]},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"},"tender":{"type":"object","properties":{"id":{"type":["integer","null"]},"source_ref":{"type":["string","null"]},"title":{"type":["string","null"]},"cpv_main":{"type":["string","null"]},"publication_date":{"type":["string","null"],"format":"date"},"buyer":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]}}}}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"400":{"description":"Invalid query parameters (invalid_query)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"402":{"description":"Payment required (x402 v2). The response also carries a base64 PAYMENT-REQUIRED header whose JSON is { x402Version: 2, resource, accepts[] }; accepts[0] is the exact requirement (scheme \"exact\", CAIP-2 network, USDC asset, amount in base units, payTo, maxTimeoutSeconds, EIP-712 domain). Sign an EIP-3009 transferWithAuthorization and retry with header PAYMENT-SIGNATURE (v2; the legacy v1 X-PAYMENT header is still accepted). In dev mode obtain a proof via POST /v1/dev-faucet.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements: { x402Version: 2, resource, accepts[] }.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","enum":[1,2]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string","example":"20000"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"},"resource":{"type":"string"}}}},"hint":{"type":"string"}}}}}},"404":{"description":"Not found (not_found)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"429":{"description":"Rate limited (rate_limited)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"500":{"description":"Internal error (internal)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/v1/companies/{id}/opportunities":{"get":{"operationId":"getCompanyOpportunities","security":[{"paymentSignature":[]}],"summary":"Active tenders matching a company's historical CPV/buyer profile","description":"Active/recent tenders (published within 90 days or future deadline) sharing cpv_main or buyer with the company's award history, ranked by a deterministic score explained in meta.score_explanation. Price: $0.10 per call.","parameters":[{"name":"id","in":"path","required":true,"description":"Internal numeric id (obtain via /v1/search)","schema":{"type":"integer","minimum":1}},{"name":"page","in":"query","required":false,"description":"Page number (1-based)","schema":{"type":"integer","minimum":1,"default":1}},{"name":"size","in":"query","required":false,"description":"Page size (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Success envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"source_ref":{"type":["string","null"]},"title":{"type":["string","null"]},"publication_date":{"type":["string","null"],"format":"date"},"deadline":{"type":["string","null"],"format":"date-time"},"cpv_main":{"type":["string","null"]},"estimated_value":{"type":["number","null"]},"currency":{"type":["string","null"]},"nuts":{"type":["string","null"]},"url":{"type":["string","null"]},"buyer":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"score":{"type":"integer"},"same_buyer":{"type":"boolean"},"same_cpv":{"type":"boolean"}}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"400":{"description":"Invalid query parameters (invalid_query)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"402":{"description":"Payment required (x402 v2). The response also carries a base64 PAYMENT-REQUIRED header whose JSON is { x402Version: 2, resource, accepts[] }; accepts[0] is the exact requirement (scheme \"exact\", CAIP-2 network, USDC asset, amount in base units, payTo, maxTimeoutSeconds, EIP-712 domain). Sign an EIP-3009 transferWithAuthorization and retry with header PAYMENT-SIGNATURE (v2; the legacy v1 X-PAYMENT header is still accepted). In dev mode obtain a proof via POST /v1/dev-faucet.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements: { x402Version: 2, resource, accepts[] }.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","enum":[1,2]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string","example":"20000"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"},"resource":{"type":"string"}}}},"hint":{"type":"string"}}}}}},"404":{"description":"Not found (not_found)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"429":{"description":"Rate limited (rate_limited)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"500":{"description":"Internal error (internal)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/v1/buyers/{id}/history":{"get":{"operationId":"getBuyerHistory","security":[{"paymentSignature":[]}],"summary":"Buyer profile, award history, supplier concentration and recurrence","description":"Buyer profile + recent awards + top-3 supplier concentration (share by count and by value) + recurrence summary (median months between awards per CPV division). Price: $0.05 per call.","parameters":[{"name":"id","in":"path","required":true,"description":"Internal numeric id (obtain via /v1/search)","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Success envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"source_ref":{"type":["string","null"]},"name":{"type":"string"},"country":{"type":["string","null"]},"nuts":{"type":["string","null"]},"org_type":{"type":["string","null"]},"awards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"tender_id":{"type":["integer","null"]},"source_ref":{"type":["string","null"]},"award_date":{"type":["string","null"],"format":"date"},"lot":{"type":["string","null"]},"winner":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"value":{"type":["number","null"]},"currency":{"type":["string","null"]},"bidders_count":{"type":["integer","null"]},"framework":{"type":"boolean"},"duration_months":{"type":["number","null"]},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"},"tender":{"type":"object","properties":{"id":{"type":["integer","null"]},"source_ref":{"type":["string","null"]},"title":{"type":["string","null"]},"cpv_main":{"type":["string","null"]},"publication_date":{"type":["string","null"],"format":"date"},"buyer":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]}}}}}},"awards_total":{"type":"integer"},"awards_returned":{"type":"integer"},"supplier_concentration":{"type":"object","properties":{"suppliers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"wins":{"type":"integer"},"total_value":{"type":["number","null"]}}}},"distinct_suppliers":{"type":"integer"},"top3_share_by_count":{"type":["number","null"]},"top3_share_by_value":{"type":["number","null"]}}},"recurrence":{"type":"array","items":{"type":"object","properties":{"cpv_division":{"type":"string"},"awards":{"type":"integer"},"median_months_between_awards":{"type":["number","null"]}}}}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"400":{"description":"Invalid query parameters (invalid_query)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"402":{"description":"Payment required (x402 v2). The response also carries a base64 PAYMENT-REQUIRED header whose JSON is { x402Version: 2, resource, accepts[] }; accepts[0] is the exact requirement (scheme \"exact\", CAIP-2 network, USDC asset, amount in base units, payTo, maxTimeoutSeconds, EIP-712 domain). Sign an EIP-3009 transferWithAuthorization and retry with header PAYMENT-SIGNATURE (v2; the legacy v1 X-PAYMENT header is still accepted). In dev mode obtain a proof via POST /v1/dev-faucet.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements: { x402Version: 2, resource, accepts[] }.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","enum":[1,2]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string","example":"20000"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"},"resource":{"type":"string"}}}},"hint":{"type":"string"}}}}}},"404":{"description":"Not found (not_found)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"429":{"description":"Rate limited (rate_limited)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"500":{"description":"Internal error (internal)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/v1/renewals":{"get":{"operationId":"getRenewals","security":[{"paymentSignature":[]}],"summary":"Forecast renewal/re-tender signals","description":"Forecast signals (framework_expiry | duration_expiry | recurrence) joined with contract, buyer and incumbent. Signals are a deterministic heuristic over historical awards and contract dates — NOT calibrated probabilities; meta.methodology and each signal's basis expose the evidence and confidence rule behind every row. Price: $0.25 per call.","parameters":[{"name":"cpv","in":"query","required":false,"description":"CPV code or prefix, e.g. \"72\" matches 72*","schema":{"type":"string","pattern":"^\\d{2,8}(-\\d)?$"}},{"name":"buyer","in":"query","required":false,"description":"Buyer name fragment (case/accent-insensitive)","schema":{"type":"string","minLength":2,"maxLength":200}},{"name":"window_months","in":"query","required":false,"description":"Only signals whose window starts within this many months (default 12, max 36)","schema":{"type":"integer","minimum":1,"maximum":36,"default":12}},{"name":"min_confidence","in":"query","required":false,"description":"Minimum confidence","schema":{"type":"string","enum":["low","medium","high"],"default":"low"}},{"name":"page","in":"query","required":false,"description":"Page number (1-based)","schema":{"type":"integer","minimum":1,"default":1}},{"name":"size","in":"query","required":false,"description":"Page size (max 100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Success envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"signal_type":{"type":"string","enum":["framework_expiry","duration_expiry","recurrence"]},"cpv":{"type":["string","null"]},"window_start":{"type":["string","null"],"format":"date"},"window_end":{"type":["string","null"],"format":"date"},"confidence":{"type":["string","null"],"enum":["low","medium","high",null]},"basis":{},"computed_at":{"type":["string","null"],"format":"date-time"},"buyer":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"incumbent":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"contract":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"title":{"type":["string","null"]},"value":{"type":["number","null"]},"currency":{"type":["string","null"]},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"}}},{"type":"null"}]}}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"400":{"description":"Invalid query parameters (invalid_query)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"402":{"description":"Payment required (x402 v2). The response also carries a base64 PAYMENT-REQUIRED header whose JSON is { x402Version: 2, resource, accepts[] }; accepts[0] is the exact requirement (scheme \"exact\", CAIP-2 network, USDC asset, amount in base units, payTo, maxTimeoutSeconds, EIP-712 domain). Sign an EIP-3009 transferWithAuthorization and retry with header PAYMENT-SIGNATURE (v2; the legacy v1 X-PAYMENT header is still accepted). In dev mode obtain a proof via POST /v1/dev-faucet.","headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON payment requirements: { x402Version: 2, resource, accepts[] }.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","enum":[1,2]},"resource":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"}}},"accepts":{"type":"array","items":{"type":"object","properties":{"scheme":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string","example":"20000"},"payTo":{"type":"string"},"maxTimeoutSeconds":{"type":"integer"},"extra":{"type":"object"},"resource":{"type":"string"}}}},"hint":{"type":"string"}}}}}},"404":{"description":"Not found (not_found)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"429":{"description":"Rate limited (rate_limited)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"500":{"description":"Internal error (internal)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/v1/pricing":{"get":{"operationId":"getPricing","summary":"Machine-readable price ladder and payment flow","description":"Free endpoint listing all endpoint prices from the fixed price table plus payment instructions.","responses":{"200":{"description":"Success envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"currency":{"type":"string","enum":["USD"]},"payments_mode":{"type":"string","enum":["dev","x402"]},"endpoints":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string","example":"GET /v1/search"},"price_usd":{"type":"string","example":"0.02"},"free":{"type":"boolean"}}}},"payment_flow":{"type":"object"}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"400":{"description":"Invalid query parameters (invalid_query)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"404":{"description":"Not found (not_found)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"429":{"description":"Rate limited (rate_limited)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}},"500":{"description":"Internal error (internal)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/v1/stats":{"get":{"operationId":"getStats","summary":"Operator observability aggregates","description":"Free, operator-only. Requires header x-operator-key. One JSON document aggregating request_logs and payments: unique clients, requests by endpoint and by source (rest/mcp), zero-result queries, payment-required responses, payment attempts/successes, revenue (by status and by network/provider), repeat paid clients, top searches, unique user agents, top requested CPVs/buyers/companies, failed queries + rate, data-null rates.","parameters":[{"name":"x-operator-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Observability envelope","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"unique_clients":{"type":"integer"},"requests_by_endpoint":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"requests":{"type":"integer"},"paid_requests":{"type":"integer"}}}},"requests_by_source":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["rest","mcp"]},"requests":{"type":"integer"}}}},"zero_result_queries":{"type":"object","properties":{"count":{"type":"integer"},"rate":{"type":"number","nullable":true}}},"payment_required_responses":{"type":"integer"},"payments":{"type":"object","properties":{"attempts":{"type":"integer"},"successes":{"type":"integer"},"revenue_usd":{"type":"number"},"by_status":{"type":"object"},"by_network_provider":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"network":{"type":"string"},"count":{"type":"integer"},"amount_usd":{"type":"number"}}}}}},"repeat_clients":{"type":"object","properties":{"count":{"type":"integer"},"paid_requests_total":{"type":"integer"},"top":{"type":"array","items":{"type":"object","properties":{"client_key":{"type":"string"},"paid_requests":{"type":"integer"}}}}}},"top_searches":{"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"requests":{"type":"integer"}}}},"unique_user_agents":{"type":"object","properties":{"count":{"type":"integer"},"top":{"type":"array","items":{"type":"object","properties":{"user_agent":{"type":"string"},"requests":{"type":"integer"}}}}}},"top_requested":{"type":"object","properties":{"cpvs":{"type":"array"},"buyers":{"type":"array"},"companies":{"type":"array"}}},"failed_queries":{"type":"integer"},"failed_requests_rate":{"type":"object","properties":{"count":{"type":"integer"},"total":{"type":"integer"},"rate":{"type":"number","nullable":true}}},"data_null_rates":{"type":"object"},"in_memory_metrics":{"type":"object"}}},"meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}}}}}}},"401":{"description":"Missing/invalid operator key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 JSON document"}}}},"/health":{"get":{"operationId":"getHealth","summary":"Liveness/readiness probe","description":"Free, no payment hook. 200 { status: \"ok\", db: \"up\" } when a trivial SELECT 1 succeeds within a short timeout; 503 { status: \"degraded\", db: \"down\" } otherwise.","responses":{"200":{"description":"Service healthy; database reachable"},"503":{"description":"Service degraded; database unreachable"}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_query","not_found","payment_required","rate_limited","internal"]},"message":{"type":"string"},"hint":{"type":"string","description":"agent-actionable hint"}}}}},"Provenance":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}},"Meta":{"type":"object","required":["request_id","price_usd","paid","provenance"],"properties":{"request_id":{"type":"string","format":"uuid"},"price_usd":{"type":"string","example":"0.05"},"paid":{"type":"boolean"},"provenance":{"type":"array","items":{"type":"object","required":["source","source_ref"],"properties":{"source":{"type":"string","example":"ted"},"source_ref":{"type":"string","example":"123456-2026"},"url":{"type":"string","format":"uri"}}}},"page":{"type":"integer"},"total":{"type":"integer"},"caveats":{"type":"array","items":{"type":"string"}},"score_explanation":{"type":"string"},"methodology":{"type":"string","description":"Declares that the returned signals are a deterministic heuristic over historical awards/contract dates, NOT a calibrated probability."},"confidence_scale":{"type":"array","items":{"type":"string","enum":["low","medium","high"]},"description":"The only confidence labels the API emits."}}},"SearchRow":{"type":"object","required":["kind","id","source_ref","title","date","buyer","company","value","currency","cpv","tender_id","tender_source_ref"],"properties":{"kind":{"type":"string","enum":["award","tender","contract"]},"id":{"type":"integer"},"source_ref":{"type":["string","null"]},"title":{"type":["string","null"]},"date":{"type":["string","null"],"format":"date"},"buyer":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"company":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"value":{"type":["number","null"]},"currency":{"type":["string","null"],"example":"EUR"},"cpv":{"type":["string","null"],"example":"72000000"},"tender_id":{"type":["integer","null"],"description":"Tender this row belongs to (equals id for tender rows)."},"tender_source_ref":{"type":["string","null"],"description":"Tender publication reference (e.g. the TED notice number)."}}},"Award":{"type":"object","properties":{"id":{"type":"integer"},"tender_id":{"type":["integer","null"]},"source_ref":{"type":["string","null"]},"award_date":{"type":["string","null"],"format":"date"},"lot":{"type":["string","null"]},"winner":{"anyOf":[{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"}}},{"type":"null"}]},"value":{"type":["number","null"]},"currency":{"type":["string","null"]},"bidders_count":{"type":["integer","null"]},"framework":{"type":"boolean"},"duration_months":{"type":["number","null"]},"start_date":{"type":["string","null"],"format":"date"},"end_date":{"type":["string","null"],"format":"date"}}}},"securitySchemes":{"paymentSignature":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 v2 payment payload (base64 JSON) proving payment for this call. Obtained by paying the requirement in the 402 PAYMENT-REQUIRED header: an EIP-3009 transferWithAuthorization of USDC on the stated network. The legacy v1 X-PAYMENT header is also accepted."}}}}