{"schema_version":"1.0","api_version":"2026-03-29","base_url":"https://btob.dev","description":"btob.dev API reference — Europe's B2B Data Layer. 34M+ companies across 12+ European countries and steadily growing, queryable by AI agents and developers.","docs_url":"https://btob.dev/docs/api","authentication":{"description":"All endpoints except /api/health require an API key.","methods":[{"type":"bearer","header":"Authorization","format":"Bearer btob_live_<key>"},{"type":"api_key_header","header":"X-API-Key","format":"btob_live_<key>"}],"key_prefix":"btob_live_","obtain_url":"https://btob.dev/docs/api"},"rate_limits":{"per_api_key":{"requests":60,"window":"1 minute"},"per_ip":{"requests":60,"window":"1 minute"},"exceeded_error_code":"rate_limit_exceeded"},"response_headers":{"X-API-Version":"API version string (e.g. 2026-03-29)","X-Request-Id":"UUID for this request — include in bug reports","X-Total-Count":"Total matching results (search endpoint only)"},"error_shape":{"description":"All errors return a consistent JSON envelope.","example":{"error":{"code":"authentication_required","message":"An API key is required. Pass it as Bearer token or X-API-Key header.","status":401,"docs":"https://btob.dev/docs/api","request_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}}},"error_codes":[{"code":"authentication_required","http_status":401,"description":"No API key provided or key is invalid."},{"code":"invalid_request","http_status":400,"description":"Missing required parameter or parameter fails validation."},{"code":"not_found","http_status":404,"description":"The requested supplier ID or slug does not exist."},{"code":"rate_limit_exceeded","http_status":429,"description":"Exceeded 60 requests per minute for this API key or IP."},{"code":"internal_error","http_status":500,"description":"Unexpected server error. Retry with exponential backoff."},{"code":"service_unavailable","http_status":503,"description":"Downstream service (e.g. semantic search) temporarily unavailable."}],"endpoints":[{"id":"health","method":"GET","path":"/api/health","summary":"Health check","description":"Returns server status and API version. No authentication required.","auth_required":false,"params":[],"response_fields":[{"name":"status","type":"string","description":"Always \"ok\" when healthy."},{"name":"version","type":"string","description":"API version date string."}],"example_response":{"status":"ok","version":"2026-03-29"}},{"id":"search","method":"GET","path":"/api/v1/suppliers/search","summary":"Keyword search","description":"Full-text keyword search across 34M+ European suppliers (and growing). Supports filtering by country and pagination.","auth_required":true,"params":[{"name":"q","in":"query","type":"string","required":true,"max_length":200,"description":"Search query. Required and must be non-empty."},{"name":"country","in":"query","type":"string","required":false,"description":"ISO 3166-1 alpha-2 country code to filter results (e.g. \"DE\", \"FR\", \"GB\")."},{"name":"limit","in":"query","type":"integer","required":false,"default":20,"maximum":100,"description":"Number of results to return. Capped at 100."},{"name":"offset","in":"query","type":"integer","required":false,"default":0,"description":"Pagination offset. Must be >= 0."}],"response_envelope":{"query":"The search query string echo.","total":"Total number of matching results.","count":"Number of results in this page.","has_more":"Boolean — true if more results exist beyond this page.","next_offset":"Integer offset for the next page, or null if no more results.","results":"Array of supplier objects."},"response_fields":[{"name":"id","type":"string (uuid)","description":"Unique supplier UUID."},{"name":"name","type":"string","description":"Company name in Latin script."},{"name":"slug","type":"string","description":"URL-safe identifier used in profile URLs."},{"name":"country","type":"string","description":"ISO 3166-1 alpha-2 country code."},{"name":"city","type":"string | null","description":"City of registered address."},{"name":"industries","type":"string[]","description":"List of industry labels."},{"name":"description","type":"string | null","description":"Short company description."},{"name":"qualityScore","type":"number | null","description":"Data completeness score (integer, 0–100)."},{"name":"trustLevel","type":"string | null","description":"Data trust level (e.g. \"verified\", \"registry\")."},{"name":"employeeRange","type":"string | null","description":"Employee count range (e.g. \"10-49\")."},{"name":"registrationNumber","type":"string | null","description":"Official company registration number."}],"response_headers":["X-Total-Count","X-API-Version","X-Request-Id"]},{"id":"semantic_search","method":"GET","path":"/api/v1/suppliers/semantic","summary":"Semantic / natural language search","description":"Vector-similarity search using natural language. Returns suppliers semantically matching the query description. Returns 503 if the embedding service is unavailable.","auth_required":true,"params":[{"name":"q","in":"query","type":"string","required":true,"max_length":200,"description":"Natural language query (e.g. \"manufacturers of biodegradable packaging in Scandinavia\")."},{"name":"limit","in":"query","type":"integer","required":false,"default":20,"maximum":100,"description":"Number of results to return. Capped at 100."},{"name":"offset","in":"query","type":"integer","required":false,"default":0,"maximum":100000,"description":"Pagination offset. Capped at 100000."}],"response_envelope":{"query":"The search query string echo.","count":"Number of results returned.","has_more":"Boolean — true if more results exist.","results":"Array of supplier objects (same fields as keyword search results)."},"response_fields":[{"name":"id","type":"string (uuid)","description":"Unique supplier UUID."},{"name":"name","type":"string","description":"Company name in Latin script."},{"name":"slug","type":"string","description":"URL-safe identifier."},{"name":"country","type":"string","description":"ISO 3166-1 alpha-2 country code."},{"name":"city","type":"string | null","description":"City of registered address."},{"name":"industries","type":"string[]","description":"List of industry labels."},{"name":"description","type":"string | null","description":"Short company description."},{"name":"qualityScore","type":"number | null","description":"Data completeness score (integer, 0–100)."},{"name":"trustLevel","type":"string | null","description":"Data trust level."},{"name":"employeeRange","type":"string | null","description":"Employee count range."},{"name":"registrationNumber","type":"string | null","description":"Official registration number."}],"notes":"Returns HTTP 503 with error code \"service_unavailable\" if the embedding service is down."},{"id":"get_supplier_by_id","method":"GET","path":"/api/v1/suppliers/{id}","summary":"Get supplier by UUID","description":"Fetch a single supplier's full profile by its UUID. Returns 404 if not found or suppressed.","auth_required":true,"params":[{"name":"id","in":"path","type":"string (uuid)","required":true,"description":"Supplier UUID."}],"response_fields":[{"name":"id","type":"string (uuid)","description":"Unique supplier UUID."},{"name":"name","type":"string","description":"Company name in Latin script."},{"name":"nameLocal","type":"string | null","description":"Company name in local script/language."},{"name":"slug","type":"string","description":"URL-safe identifier used in profile URLs."},{"name":"country","type":"string","description":"ISO 3166-1 alpha-2 country code."},{"name":"regionCode","type":"string | null","description":"Region or state code."},{"name":"city","type":"string | null","description":"City of registered address."},{"name":"postalCode","type":"string | null","description":"Postal code."},{"name":"website","type":"string | null","description":"Company website URL."},{"name":"description","type":"string | null","description":"Short company description."},{"name":"registrationNumber","type":"string | null","description":"Official company registration number."},{"name":"vatNumber","type":"string | null","description":"VAT identification number."},{"name":"legalForm","type":"string | null","description":"Legal entity type (e.g. \"GmbH\", \"Ltd\", \"SAS\")."},{"name":"companyType","type":"string | null","description":"Company classification."},{"name":"employeeRange","type":"string | null","description":"Employee count range (e.g. \"10-49\", \"50-249\")."},{"name":"revenueRange","type":"string | null","description":"Annual revenue range."},{"name":"industries","type":"string[]","description":"List of industry labels."},{"name":"productsServices","type":"string[]","description":"List of products or services offered."},{"name":"capabilities","type":"object | null","description":"Structured capability data."},{"name":"qualityScore","type":"number | null","description":"Data completeness score (integer, 0–100)."},{"name":"trustLevel","type":"string | null","description":"Data trust level."},{"name":"status","type":"string | null","description":"Company status (e.g. \"active\", \"dissolved\")."},{"name":"verifiedAt","type":"string | null","description":"ISO 8601 date of last verification."},{"name":"createdAt","type":"string","description":"ISO 8601 date record was created."},{"name":"updatedAt","type":"string","description":"ISO 8601 date record was last updated."},{"name":"certifications","type":"object[]","description":"Array of certification objects (may be empty)."}]},{"id":"get_supplier_by_slug","method":"GET","path":"/api/v1/suppliers/by-slug/{slug}","summary":"Get supplier by slug","description":"Fetch a single supplier's full profile by its URL slug. Returns identical fields to the by-ID endpoint.","auth_required":true,"params":[{"name":"slug","in":"path","type":"string","required":true,"description":"URL-safe supplier slug (e.g. \"siemens-ag-de\")."}],"response_fields":"Same 25 fields as GET /api/v1/suppliers/{id} plus certifications array.","notes":"Slugs appear in profile URLs: https://btob.dev/suppliers/{slug}"},{"id":"list_countries","method":"GET","path":"/api/v1/countries","summary":"List available countries","description":"Returns all countries present in the database with their supplier counts. CZ and ES are excluded from results.","auth_required":true,"params":[],"response_envelope":{"countries":"Array of country objects."},"response_fields":[{"name":"country","type":"string","description":"ISO 3166-1 alpha-2 country code."},{"name":"supplier_count","type":"integer","description":"Number of suppliers indexed for this country."}],"notes":"Returns 12+ countries (steadily growing). CZ and ES currently excluded. Cache-Control: max-age=3600. Call this endpoint for the latest list."},{"id":"list_industries","method":"GET","path":"/api/v1/industries","summary":"List available industries","description":"Returns distinct industry labels across all suppliers with their supplier counts. Limited to the top 500 industries by count.","auth_required":true,"params":[],"response_envelope":{"industries":"Array of industry objects."},"response_fields":[{"name":"industry","type":"string","description":"Industry label string."},{"name":"supplier_count","type":"integer","description":"Number of suppliers in this industry."}],"notes":"Returns up to 500 industries. Cache-Control: max-age=3600."}],"agent_formats":{"description":"Machine-readable supplier profiles served without authentication.","formats":[{"path":"/suppliers/{slug}/business.json","type":"JSON-LD","vocabulary":"http://data.europa.eu/ux2/nace2/","description":"EU-vocabulary JSON-LD profile suitable for knowledge graph ingestion."},{"path":"/suppliers/{slug}/profile.md","type":"Markdown","description":"LLM-readable markdown profile with all structured fields."}]},"mcp":{"description":"Model Context Protocol server — add EU supplier skills directly to your AI agent.","endpoint":"https://btob.dev/mcp","tool_count":7,"docs_url":"https://btob.dev/docs/mcp"},"data":{"total_companies":"34M+ and steadily growing","countries_available":12,"country_codes":["DE","FR","GB","RO","BE","PL","NO","FI","IE","LV","EE","SI"],"source":"European government business registries"}}