{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "Whirrwork API", "version": "1.1.1", "summary": "Robot jobs, providers by country, sourced prices with append-only history, cost estimates, RFQ templates and RFQ submission.", "description": "Free, public API of Whirrwork, the honest marketplace for jobs people hire robots to do.\n\n- **No key** for reads. Rate limits: ~120 reads/min and 6 writes/min per IP (429 + Retry-After).\n- **Pagination**: list endpoints take `limit` + `offset` and return a `pagination` object plus RFC 8288 `Link` and `X-Total-Count` headers.\n- **Field selection**: `fields=id,name,...` on list and item endpoints (`fields=full` for full objects where supported).\n- **Caching**: every GET returns a weak `ETag`; send `If-None-Match` to get `304 Not Modified`.\n- **Errors**: always `{\"error\": code, \"message\", \"status\", \"docs\"}` (+ `issues` for validation).\n- **Languages**: use-case text in en, es, pt-BR, fr, de, zh, zh-Hant, ja, ar, hi, ko, id, tr via `lang` or `Accept-Language` (machine-translated; English authoritative).\n- **Stable ids**: use case, provider and category ids are slugs and do not change; price observation ids are permanent.\n- **Prices** are published benchmarks with `source_url` + `as_of`, never quotes. Converted values name their FX rate, date and source (ECB via Frankfurter; ExchangeRate-API fallback).\n- **RFQs** must be for a real buyer who consented to supplier contact. A human reviews every RFQ before forwarding; nothing is sent automatically.\n\nMCP server with the same capabilities: https://whirrwork.com/mcp (tools: search_use_cases, get_use_case, list_categories, find_providers, get_provider, compare_providers, get_prices, get_price_history, estimate_cost, list_countries, get_rfq_template, submit_rfq, get_rfq_status).\n\nData license: CC BY 4.0, attribute \"Whirrwork\".", "contact": { "name": "Whirrwork", "url": "https://whirrwork.com/agents/" }, "license": { "name": "CC BY 4.0 (data)", "identifier": "CC-BY-4.0" } }, "externalDocs": { "description": "Agent guide and quickstarts", "url": "https://whirrwork.com/agents/" }, "servers": [ { "url": "https://whirrwork.com" } ], "tags": [ { "name": "search" }, { "name": "directory" }, { "name": "geo" }, { "name": "prices" }, { "name": "rfq" }, { "name": "meta" } ], "paths": { "/api/search": { "get": { "tags": [ "search" ], "operationId": "search", "summary": "Natural-language search (12 languages) across use cases, providers and guides", "description": "Queries are logged anonymously (no IP; PII patterns scrubbed) as a demand signal. With country, use cases include providers_in_country and providers are re-ranked by coverage.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 300 }, "description": "What the buyer needs, in any supported language", "example": "limpieza de ventanas con drones", "required": true }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/near" }, { "$ref": "#/components/parameters/lang" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50 } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" }, "example": { "query": "drone light show", "detected_language": "en", "language": "en", "country": "AE", "use_cases": [ { "id": "drone-light-show", "name": "Drone light show", "category_id": "events", "url": "https://whirrwork.com/use-cases/drone-light-show/", "provider_count": 40, "price_summary": "$185–$850 / drone", "score": 25.1, "providers_in_country": 6 } ], "providers": [], "guides": [] } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/categories": { "get": { "tags": [ "directory" ], "operationId": "listCategories", "summary": "List categories", "parameters": [ { "$ref": "#/components/parameters/lang" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/use-cases": { "get": { "tags": [ "directory" ], "operationId": "listUseCases", "summary": "List use cases (jobs robots do)", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Category id" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search filter (any language)" }, { "name": "has_prices", "in": "query", "schema": { "type": "boolean" }, "description": "Only jobs with sourced benchmarks" }, { "name": "has_providers", "in": "query", "schema": { "type": "boolean" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "name", "-name", "provider_count", "-provider_count", "price_points", "-price_points" ], "default": "name" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/lang" } ], "responses": { "200": { "description": "OK (paginated)", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Total-Count": { "$ref": "#/components/headers/XTotalCount" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "language": { "type": "string" }, "use_cases": { "type": "array", "items": { "$ref": "#/components/schemas/UseCaseSummary" } } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/use-cases/{id}": { "get": { "tags": [ "directory" ], "operationId": "getUseCase", "summary": "One use case: prices (with USD), history counts, RFQ checklist, rules, providers ranked for a country", "parameters": [ { "$ref": "#/components/parameters/ucId" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/region" }, { "$ref": "#/components/parameters/lang" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UseCase" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/use-cases/{id}/rfq-template": { "get": { "tags": [ "rfq" ], "operationId": "getRfqTemplate", "summary": "Fields a supplier needs to quote this job", "parameters": [ { "$ref": "#/components/parameters/ucId" }, { "$ref": "#/components/parameters/lang" } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RfqTemplate" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/providers": { "get": { "tags": [ "directory", "geo" ], "operationId": "findProviders", "summary": "Find providers; ranked by coverage of a place with the reason", "description": "Ranking with a country: serves region (4) > lists country (3) > lists part of country (2.8) > HQ in country (2; not a service area) > worldwide (1). Coverage is country-level unless a provider published regions.", "parameters": [ { "name": "use_case", "in": "query", "schema": { "type": "string" }, "description": "Use case id", "example": "drone-light-show" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/region" }, { "$ref": "#/components/parameters/near" }, { "name": "hq_country", "in": "query", "schema": { "type": "string" }, "description": "Only providers headquartered here" }, { "name": "engagement_model", "in": "query", "schema": { "type": "string", "enum": [ "service", "rental", "raas", "purchase" ] } }, { "name": "robot_type", "in": "query", "schema": { "type": "string" }, "description": "Substring match, e.g. drone" }, { "name": "has_pricing", "in": "query", "schema": { "type": "boolean" } }, { "name": "has_contact", "in": "query", "schema": { "type": "boolean" } }, { "name": "max_price_usd", "in": "query", "schema": { "type": "number" }, "description": "Lowest published price (USD-converted) at or below this" }, { "name": "include_global", "in": "query", "schema": { "type": "boolean", "default": true } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Keyword filter" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "relevance", "name", "-name", "price", "-price", "last_checked" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "OK (paginated)", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Total-Count": { "$ref": "#/components/headers/XTotalCount" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "country": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "near_source": { "type": "string" }, "ranking": { "type": "string" }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }, "note": { "type": "string" } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/providers/{id}": { "get": { "tags": [ "directory" ], "operationId": "getProvider", "summary": "One provider", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "sky-elements" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provider" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/compare": { "get": { "tags": [ "directory" ], "operationId": "compareProviders", "summary": "Compare 2-10 providers side by side (alias: /api/providers/compare)", "parameters": [ { "name": "ids", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated provider ids", "example": "sky-elements,verge-aero", "required": true }, { "$ref": "#/components/parameters/country" }, { "name": "use_case", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comparison" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/countries": { "get": { "tags": [ "geo" ], "operationId": "listCountries", "summary": "Coverage counts per country and sub-region", "parameters": [ { "$ref": "#/components/parameters/lang" } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "global_providers": { "type": "integer" }, "sub_regions_total": { "type": "integer" }, "precision": { "type": "string" }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/CountryCoverage" } } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/prices": { "get": { "tags": [ "prices" ], "operationId": "getPrices", "summary": "Current sourced prices (benchmarks + provider-published)", "parameters": [ { "name": "use_case", "in": "query", "schema": { "type": "string" }, "description": "Use case id", "example": "crop-spraying-drone" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider id" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "description": "Only rows quoted in this currency" }, { "name": "convert", "in": "query", "schema": { "type": "string" }, "description": "Add a converted value in this ISO 4217 currency", "example": "USD" }, { "name": "include_providers", "in": "query", "schema": { "type": "boolean", "default": true } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/fields" } ], "responses": { "200": { "description": "OK (paginated)", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Total-Count": { "$ref": "#/components/headers/XTotalCount" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "license": { "type": "string" }, "note": { "type": "string" }, "fx": { "type": "object" }, "summary": { "type": [ "object", "null" ] }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/PriceRow" } } } } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/prices/history": { "get": { "tags": [ "prices" ], "operationId": "getPriceHistory", "summary": "Append-only price observations and series trends", "description": "Every price ever recorded. observed_at = when Whirrwork recorded it; as_of = the date the source states. A changed price adds an observation whose supersedes points at the previous one. Nothing is overwritten or deleted.", "parameters": [ { "name": "use_case", "in": "query", "schema": { "type": "string" }, "description": "Use case id", "example": "crop-spraying-drone" }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider id" }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "YYYY-MM-DD (observed_at >= since)", "example": "2026-01-01" }, { "name": "series", "in": "query", "schema": { "type": "string" }, "description": "series_key" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "OK (paginated)", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Link": { "$ref": "#/components/headers/Link" }, "X-Total-Count": { "$ref": "#/components/headers/XTotalCount" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceHistory" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/estimate": { "get": { "tags": [ "prices" ], "operationId": "estimateCost", "summary": "Cost estimate from sourced benchmarks only (shows its basis)", "description": "unit price × quantity with exact unit conversions; prefers benchmarks matching the country; optional currency conversion at a dated ECB rate. Returns estimate=null with a reason when no benchmark fits.", "parameters": [ { "name": "use_case", "in": "query", "schema": { "type": "string" }, "description": "Use case id", "example": "crop-spraying-drone", "required": true }, { "name": "quantity", "in": "query", "schema": { "type": "number", "exclusiveMinimum": 0 }, "description": "How many units", "example": 500 }, { "name": "unit", "in": "query", "schema": { "type": "string" }, "description": "hectare, acre, show, month, sq ft…", "example": "hectare" }, { "$ref": "#/components/parameters/country" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "description": "Result currency", "example": "USD" } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Estimate" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/fx": { "get": { "tags": [ "prices" ], "operationId": "getFx", "summary": "FX snapshot used for conversions (rates per 1 USD, dated, sourced)", "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fx" } } } }, "304": { "$ref": "#/components/responses/NotModified" } } } }, "/api/changelog": { "get": { "tags": [ "meta" ], "operationId": "getChangelog", "summary": "Platform releases, data changes per snapshot, snapshot list", "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "$ref": "#/components/responses/NotModified" } } } }, "/api/whereami": { "get": { "tags": [ "geo" ], "operationId": "whereAmI", "summary": "Country Cloudflare sees for this request (IP-based; never stored)", "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "precision": { "type": "string" } } } } } } } } }, "/api/rfq": { "post": { "tags": [ "rfq" ], "operationId": "submitRfq", "summary": "Submit a request for quotes for a consenting buyer", "description": "Stored, auto-matched by use case + country, reviewed by a human before forwarding. Nothing is sent automatically. Accepts JSON or form-encoded. Mark tests with \"test\": true.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RfqInput" }, "example": { "use_case_id": "commercial-floor-scrubbing", "job": "Autonomous floor scrubbing for a 4,000 m² warehouse, nightly", "country": "CA", "location": "Toronto, ON", "budget_max": 2500, "budget_currency": "CAD", "extra": { "facility-type": "warehouse", "square-footage-m-to-be-cleaned": "4000 m²" }, "contact_email": "buyer@example.com", "consent": true, "agent_name": "MyAgent", "test": true } } } }, "responses": { "201": { "description": "Created", "headers": { "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RfqCreated" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/BadRequest" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/rfq/{id}": { "get": { "tags": [ "rfq" ], "operationId": "getRfqStatus", "summary": "RFQ status + status history (needs the access key from creation)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RfqStatus" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/demand": { "get": { "tags": [ "meta" ], "operationId": "getDemand", "summary": "Anonymized demand buckets (n>=3) per use case, last 90 days", "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/mcp": { "post": { "tags": [ "meta" ], "operationId": "mcp", "summary": "Remote MCP server (Streamable HTTP, JSON-RPC 2.0, stateless)", "description": "Tools: search_use_cases, get_use_case, list_categories, find_providers, get_provider, compare_providers, get_prices, get_price_history, estimate_cost, list_countries, get_rfq_template, submit_rfq, get_rfq_status. Server card: https://whirrwork.com/mcp/server-card", "requestBody": { "content": { "application/json": { "schema": { "type": "object" }, "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_use_cases", "arguments": { "query": "inspect a wind turbine", "country": "GB" } } } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Notification accepted" } } } } }, "components": { "headers": { "ETag": { "description": "Weak entity tag; send If-None-Match to revalidate", "schema": { "type": "string" } }, "Link": { "description": "RFC 8288 next/prev links", "schema": { "type": "string" } }, "XTotalCount": { "description": "Total matching items", "schema": { "type": "integer" } } }, "parameters": { "ucId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "drone-light-show", "description": "Use case id (stable slug)" }, "country": { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "AE", "description": "ISO 3166-1 alpha-2 or English country name" }, "region": { "name": "region", "in": "query", "schema": { "type": "string" }, "example": "US-CA", "description": "Sub-country region (ISO 3166-2 code or name) where providers publish one" }, "near": { "name": "near", "in": "query", "schema": { "type": "string" }, "example": "me", "description": "\"me\" = country Cloudflare sees for this request (never stored), or a country. Coordinates are not supported." }, "lang": { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "en", "es", "pt-BR", "fr", "de", "zh", "zh-Hant", "ja", "ar", "hi", "ko", "id", "tr" ] }, "example": "es", "description": "Language for use-case text; overrides Accept-Language" }, "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "Page size (endpoint-specific default/max)" }, "offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "fields": { "name": "fields", "in": "query", "schema": { "type": "string" }, "example": "id,name,url", "description": "Comma-separated fields to return (id always included)" } }, "responses": { "NotModified": { "description": "Not modified (ETag matched)" }, "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "bad_country", "message": "Couldn't recognise country \"Narnia\".", "status": 400, "docs": "https://whirrwork.com/agents/#rest" } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limited", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Machine-readable code" }, "message": { "type": "string" }, "status": { "type": "integer" }, "docs": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "returned": { "type": "integer" }, "next_offset": { "type": [ "integer", "null" ] }, "next": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] } } }, "Converted": { "type": [ "object", "null" ], "description": "Clearly-labelled currency conversion", "properties": { "currency": { "type": "string" }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "available": { "type": "boolean" }, "fx": { "type": "object", "properties": { "pair": { "type": "string" }, "rate": { "type": "number" }, "rate_date": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": "string" } } }, "note": { "type": "string" } } }, "Price": { "type": "object", "properties": { "description": { "type": "string" }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "currency": { "type": "string", "example": "USD" }, "unit": { "type": "string", "example": "per acre" }, "region": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "as_of": { "type": "string", "example": "2026-10" } } }, "PriceRow": { "allOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "benchmark", "provider_published" ] }, "use_case_id": { "type": [ "string", "null" ] }, "provider_id": { "type": [ "string", "null" ] }, "display": { "type": "string" }, "older_price": { "type": "boolean" }, "converted": { "$ref": "#/components/schemas/Converted" } } } ] }, "Category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "name_en": { "type": "string" }, "description": { "type": "string" }, "use_case_count": { "type": "integer" }, "url": { "type": "string" } } }, "UseCaseSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "name_en": { "type": "string" }, "category_id": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "url": { "type": "string" }, "provider_count": { "type": "integer" }, "price_benchmark_count": { "type": "integer" }, "price_summary": { "type": [ "string", "null" ] } } }, "UseCase": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category_id": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "language": { "type": "string" }, "machine_translated": { "type": "boolean" }, "buyer_phrases": { "type": "array", "items": { "type": "string" } }, "robot_types": { "type": "array", "items": { "type": "string" } }, "engagement_models": { "type": "array", "items": { "type": "string" } }, "what_to_specify_in_rfq": { "type": "array", "items": { "type": "string" } }, "price_benchmarks": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "object", "properties": { "older_price": { "type": "boolean" }, "usd": { "$ref": "#/components/schemas/Converted" } } } ] } }, "price_summary": { "type": [ "object", "null" ] }, "price_history": { "type": "object", "properties": { "observations": { "type": "integer" }, "series": { "type": "integer" }, "changed_series": { "type": "integer" }, "url": { "type": "string" } } }, "regulatory_notes": { "type": "string" }, "buyer_tips": { "type": "array", "items": { "type": "string" } }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hq_country": { "type": [ "string", "null" ] }, "service_regions": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "coverage": { "type": "string" }, "coverage_reason": { "type": [ "string", "null" ] }, "has_published_pricing": { "type": "boolean" } } } }, "url": { "type": "string" }, "rfq_url": { "type": "string" }, "rfq_template_url": { "type": "string" }, "geo_url": { "type": "string" } } }, "ServiceArea": { "type": "object", "properties": { "country": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "derived_from": { "type": "string", "enum": [ "service_areas", "service_regions" ] } } }, "Provider": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "website": { "type": [ "string", "null" ] }, "hq_country": { "type": [ "string", "null" ] }, "service_regions": { "type": "array", "items": { "type": "string" } }, "service_areas": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceArea" } }, "engagement_models": { "type": "array", "items": { "type": "string" } }, "robot_types": { "type": "array", "items": { "type": "string" } }, "use_case_ids": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "pricing": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "object", "properties": { "usd": { "$ref": "#/components/schemas/Converted" } } } ] } }, "min_published_price_usd": { "type": [ "number", "null" ] }, "contact": { "type": "object", "properties": { "email": { "type": [ "string", "null" ] }, "rfq_url": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, "last_checked": { "type": "string" }, "coverage": { "type": "string", "enum": [ "serves_region", "serves_country", "serves_part_of_country", "headquartered_in_country", "works_worldwide", "serves_other_part_of_country", "none" ] }, "coverage_reason": { "type": [ "string", "null" ] } } }, "Comparison": { "type": "object", "properties": { "country": { "type": [ "string", "null" ] }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }, "shared_use_cases": { "type": "array", "items": { "type": "object" } }, "matrix": { "type": "object" }, "note": { "type": "string" } } }, "CountryCoverage": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "providers_serving": { "type": "integer" }, "providers_serving_part": { "type": "integer" }, "providers_hq": { "type": "integer" }, "sub_regions": { "type": "array", "items": { "type": "object", "properties": { "region": { "type": "string" }, "slug": { "type": "string" }, "region_code": { "type": [ "string", "null" ] }, "providers": { "type": "integer" } } } } } }, "PriceObservation": { "allOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "object", "required": [ "id", "series_key", "observed_at", "content_hash", "source_url" ], "properties": { "id": { "type": "string", "example": "po_20261025_ab1ef3fe974c" }, "series_key": { "type": "string" }, "kind": { "type": "string", "enum": [ "benchmark", "provider_published" ] }, "use_case_id": { "type": [ "string", "null" ] }, "use_case_ids": { "type": "array", "items": { "type": "string" } }, "provider_id": { "type": [ "string", "null" ] }, "observed_at": { "type": "string", "format": "date-time" }, "content_hash": { "type": "string", "example": "sha256:…" }, "supersedes": { "type": [ "string", "null" ] }, "origin": { "type": "string", "enum": [ "backfill", "build" ] }, "current": { "type": "boolean" }, "usd": { "$ref": "#/components/schemas/Converted" } } } ] }, "PriceSeries": { "type": "object", "properties": { "series_key": { "type": "string" }, "kind": { "type": "string" }, "use_case_id": { "type": [ "string", "null" ] }, "provider_id": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "currency": { "type": "string" }, "unit": { "type": "string" }, "region": { "type": "string" }, "source_url": { "type": "string" }, "observations": { "type": "integer" }, "first_observed_at": { "type": "string" }, "last_observed_at": { "type": "string" }, "current": { "type": "boolean" }, "latest": { "type": "object" }, "trend": { "type": [ "object", "null" ], "properties": { "from": { "type": "number" }, "to": { "type": "number" }, "change_pct": { "type": "number" }, "direction": { "type": "string", "enum": [ "up", "down", "flat" ] } } } } }, "PriceHistory": { "type": "object", "properties": { "total": { "type": "integer" }, "source": { "type": "string", "enum": [ "d1", "bundle" ] }, "tracking_since": { "type": "string" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/PriceObservation" } }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/PriceSeries" } }, "note": { "type": "string" }, "license": { "type": "string" } } }, "Estimate": { "type": "object", "properties": { "use_case_id": { "type": "string" }, "quantity": { "type": [ "number", "null" ] }, "unit": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "estimate": { "type": [ "object", "null" ], "properties": { "low": { "type": "number" }, "high": { "type": "number" }, "currency": { "type": "string" }, "based_on": { "type": "integer" } } }, "reason": { "type": "string" }, "method": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } }, "basis": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "description": { "type": "string" }, "unit_price": { "type": "object" }, "region": { "type": [ "string", "null" ] }, "region_match": { "type": "string" }, "source_url": { "type": "string" }, "as_of": { "type": "string" }, "unit_conversion": { "type": [ "string", "null" ] }, "cost": { "type": "object" }, "cost_converted": { "type": "object" }, "used_in_range": { "type": "boolean" } } } }, "available_units": { "type": "array", "items": { "type": "string" } }, "fx_date": { "type": "string" } } }, "Fx": { "type": "object", "properties": { "base": { "type": "string", "const": "USD" }, "date": { "type": "string" }, "rates": { "type": "object", "additionalProperties": { "type": "number" } }, "source_by_currency": { "type": "object", "additionalProperties": { "type": "string" } }, "sources": { "type": "object" } } }, "RfqTemplate": { "type": "object", "properties": { "use_case_id": { "type": "string" }, "use_case": { "type": "string" }, "submit": { "type": "object" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" }, "description": { "type": "string" } } } }, "supplier_checklist": { "type": "array", "items": { "type": "string" } }, "regulatory_notes": { "type": [ "string", "null" ] }, "example": { "$ref": "#/components/schemas/RfqInput" }, "notes": { "type": "array", "items": { "type": "string" } } } }, "SearchResult": { "type": "object", "properties": { "query": { "type": "string" }, "detected_language": { "type": "string" }, "language": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "use_cases": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/UseCaseSummary" }, { "type": "object", "properties": { "score": { "type": "number" }, "matched_language": { "type": "string" }, "providers_in_country": { "type": "integer" }, "geo_url": { "type": "string" } } } ] } }, "providers": { "type": "array", "items": { "type": "object" } }, "guides": { "type": "array", "items": { "type": "object" } }, "suggestion": { "type": "string" } } }, "RfqStatusEnum": { "type": "string", "enum": [ "received", "matched", "sent_to_suppliers", "quoted", "closed" ] }, "RfqInput": { "type": "object", "required": [ "job", "country", "contact_email", "consent" ], "properties": { "use_case_id": { "type": "string" }, "job": { "type": "string", "maxLength": 300 }, "country": { "type": "string" }, "location": { "type": "string", "maxLength": 200 }, "date_start": { "type": "string", "format": "date" }, "date_end": { "type": "string", "format": "date" }, "date_flexible": { "type": "boolean" }, "budget_min": { "type": "number" }, "budget_max": { "type": "number" }, "budget_currency": { "type": "string" }, "details": { "type": "string", "maxLength": 5000 }, "extra": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "contact_name": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "contact_company": { "type": "string" }, "contact_phone": { "type": "string", "maxLength": 40, "description": "Optional, international format (+country code)" }, "consent": { "type": "boolean", "const": true }, "agent_name": { "type": "string" }, "provider_hint": { "type": "string" }, "test": { "type": "boolean" } } }, "RfqCreated": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/RfqStatusEnum" }, "matched_provider_ids": { "type": "array", "items": { "type": "string" } }, "status_url": { "type": "string" }, "message": { "type": "string" }, "is_test": { "type": "boolean" } } }, "RfqStatus": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/RfqStatusEnum" }, "use_case_id": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "matched_provider_count": { "type": "integer" }, "status_history": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string" }, "from_status": { "type": [ "string", "null" ] }, "to_status": { "type": "string" } } } } } } } } }