{"openapi":"3.0.0","info":{"title":"Truee Search API","version":"1.0.0","description":"Public documentation for AI search clients. All data access requires an `x-api-key` unless a specific endpoint says otherwise.\n\n## Introduction\nTruee is a verified business registry built for AI agents, search products, and applications that need primary-source business data instead of scraped pages.\n\n## Quickstart\n1. Create an AI company account in Truee.\n2. Copy your API key.\n3. Call `POST /registry/search` for natural language search or `GET /registry/query` for structured search.\n4. Use the returned `id` or `slug` to fetch a full business profile.\n\n## Authentication\nSend your API key as `x-api-key: YOUR_KEY`. Public metadata endpoints explicitly marked as unauthenticated do not require a key.\n\n## Query Businesses\nUse natural language search when the user query is raw text. Use structured search when your app or agent already knows keywords, category, and location.\n\n## Business Data Schema\nSearch returns compact or standard result cards. Full profile endpoints return verified business identity, locations, products, services, media, trust signals, freshness, and qualification status.\n\n## MCP Server\nMCP-compatible clients can use `/mcp` with the same API key. Machine-readable MCP docs are available at `/mcp/docs`.\n\n## Errors\nErrors return JSON with `success: false`, a human-readable `error`, and where available a stable `code`.\n\n## Rate Limits\nNatural language search costs 2 query units. Structured search and profile fetches cost 1 query unit. Limits are enforced by the AI company account plan."},"servers":[{"url":"/api/v1"}],"x-tagGroups":[{"name":"Truee Search API","tags":["Introduction","Quickstart","Authentication","Query Businesses","Business Data Schema","MCP Server","Errors","Rate Limits"]}],"tags":[{"name":"Introduction","description":"What Truee is and how the public search surface works."},{"name":"Quickstart","description":"The fastest path from API key to first search result."},{"name":"Authentication","description":"How to authenticate requests with an AI company API key."},{"name":"Query Businesses","description":"Natural language and structured business search endpoints."},{"name":"Business Data Schema","description":"Business profile, category, and sync response shapes."},{"name":"MCP Server","description":"MCP endpoint and tools for AI agents."},{"name":"Errors","description":"Error format and common failure responses."},{"name":"Rate Limits","description":"Query costs, quotas, and rate-limit behavior."}],"paths":{"/registry/stats":{"get":{"tags":["Introduction"],"summary":"Global statistics","description":"Returns the total number of businesses, countries, and industries indexed in the registry. **No authentication required.**","responses":{"200":{"description":"Statistics retrieved","content":{"application/json":{"example":{"success":true,"data":{"total_businesses":6420,"total_countries":18,"total_industries":112}}}}}}}},"/registry/categories":{"get":{"tags":["Business Data Schema","Query Businesses"],"summary":"Business categories","description":"Returns the category reference used by search filters and structured queries. Pass `selector=true` for a compact selector-friendly response. **No authentication required.**","parameters":[{"name":"selector","in":"query","schema":{"type":"boolean","default":false},"description":"Return a compact list optimized for UI selectors."}],"responses":{"200":{"description":"Categories retrieved","content":{"application/json":{"example":{"success":true,"data":[{"id":"cat_fintech","name":"Financial Technology","slug":"financial-technology"}],"timestamp":"2026-05-20T10:00:00.000Z"}}}}}}},"/registry/search":{"get":{"tags":["Quickstart","Authentication","Query Businesses","Errors","Rate Limits"],"summary":"Natural language search","description":"Search the global business registry using a natural language query.\n\nThe query is parsed by an AI model to extract intent, location, and category before searching — so phrases like **\"find me a fintech company in Ikeja Lagos\"** or **\"maize supplier Kano Nigeria\"** work correctly without any pre-processing on your side.\n\n**Query cost: 2** — the AI parsing step counts as an additional unit against your daily/monthly limit. Use `GET /registry/query` instead if you can pre-extract intent yourself.\n\n**Authentication:** `x-api-key` header required.","security":[{"api_key_auth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200,"example":"fintech company in Lagos"},"description":"Natural language search query. Location and intent are extracted automatically."},{"name":"view","in":"query","schema":{"type":"string","enum":["compact","standard"],"default":"compact"},"description":"`compact` — lightweight list items. `standard` — includes highlights, subcategories, and structured location. Full profiles require a separate `/registry/businesses/{id}` call."},{"name":"country","in":"query","schema":{"type":"string","example":"NG"},"description":"ISO-2 country code or full country name."},{"name":"state","in":"query","schema":{"type":"string","example":"Lagos"},"description":"State or province."},{"name":"city","in":"query","schema":{"type":"string","example":"Lagos"},"description":"City name."},{"name":"area","in":"query","schema":{"type":"string","example":"Ikeja"},"description":"Neighbourhood, market, or district."},{"name":"industry","in":"query","schema":{"type":"string","example":"Financial Technology"},"description":"Industry or category filter."},{"name":"verified_only","in":"query","schema":{"type":"boolean","default":false},"description":"Return only fully verified businesses."},{"name":"qualification","in":"query","schema":{"type":"string","enum":["qualified_only","partial_or_better","all"],"default":"all"}},{"name":"verification_status","in":"query","schema":{"type":"string","enum":["UNVERIFIED","VERIFIED","EXPIRED"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Results per page. Max 100."},{"name":"lat","in":"query","schema":{"type":"number","minimum":-90,"maximum":90},"description":"Latitude for proximity search."},{"name":"lng","in":"query","schema":{"type":"number","minimum":-180,"maximum":180},"description":"Longitude for proximity search."},{"name":"radius","in":"query","schema":{"type":"number","minimum":1,"maximum":1000,"default":50},"description":"Proximity radius in km."}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrySearchResponse"},"example":{"success":true,"data":{"requestId":"req_a1b2c3","query":"fintech company in Lagos","resolvedSearchType":"business_search","detected":{"intent":"find_business","category":"Financial Technology","product_terms":[],"service_terms":[],"business_model_hints":{"audience":"B2B","operating_model":null,"commerce_type":null},"normalized_query":"fintech","area":null,"city":"Lagos","state":null,"country":"NG"},"meta":{"view":"compact","limit":10,"returned_count":10,"total_matches":47,"qualified_matches":32,"searchTimeMs":230},"results":[{"id":"biz_abc123","name":"Paysnug Technology Limited","slug":"paysnug-technology-limited","title":"Paysnug Technology Limited - Fintech in Lagos","summary":"B2B payment infrastructure and payroll software for African businesses.","category":"Financial Technology","location":"Victoria Island, Lagos, Lagos State, NG","verified":true,"freshness":"FRESH","qualification_status":"QUALIFIED","match_score":0.92,"ranking_reason":"Strong match for fintech in Lagos. Verified business with fresh data.","profile_url":"https://usetruee.com/b/paysnug-technology-limited","data_url":"https://api.usetruee.com/api/v1/registry/businesses/paysnug-technology-limited"}]},"timestamp":"2026-05-20T10:00:00.000Z"}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit or query quota exceeded"}}},"post":{"tags":["Quickstart","Authentication","Query Businesses","Errors","Rate Limits"],"summary":"Natural language search (POST)","description":"Same as `GET /registry/search` but accepts the query as a JSON body. Useful when the query string is long or contains special characters.\n\n**Query cost: 2.**\n\n**Authentication:** `x-api-key` header required.","security":[{"api_key_auth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","maxLength":200,"example":"logistics company in Nairobi Kenya"},"view":{"type":"string","enum":["compact","standard"],"default":"compact"},"country":{"type":"string","example":"KE"},"state":{"type":"string"},"city":{"type":"string","example":"Nairobi"},"area":{"type":"string"},"industry":{"type":"string"},"verified_only":{"type":"boolean","default":false},"qualification":{"type":"string","enum":["qualified_only","partial_or_better","all"],"default":"all"},"page":{"type":"integer","minimum":1,"default":1},"limit":{"type":"integer","minimum":1,"maximum":100,"default":10}}},"example":{"q":"logistics company in Nairobi Kenya","view":"compact","limit":10}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrySearchResponse"}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit or query quota exceeded"}}}},"/registry/query":{"get":{"tags":["Authentication","Query Businesses","Errors","Rate Limits"],"summary":"Structured search (cheaper)","description":"Search the registry using pre-extracted intent. No AI parsing happens — your keywords, location, and category go directly to the search engine.\n\n**Use this endpoint when:**\n- You are an AI agent that has already parsed the user's query into structured fields.\n- You want to filter or browse by category/location without a free-text query.\n- You need lower latency and lower cost.\n\n**Query cost: 1** — half the cost of natural language search because no AI model is invoked.\n\nThe internal routing between Meilisearch and Postgres is automatic — you do not control or see it.\n\n**Authentication:** `x-api-key` header required.","security":[{"api_key_auth":[]}],"parameters":[{"name":"keywords","in":"query","schema":{"type":"string","maxLength":200,"example":"fintech"},"description":"Core search keywords, already extracted from the user query. Do not pass the full natural language sentence here."},{"name":"intent","in":"query","schema":{"type":"string","enum":["find_business","find_product","find_service"],"default":"find_business"},"description":"What the user is looking for."},{"name":"category","in":"query","schema":{"type":"string","example":"Financial Technology"},"description":"Inferred business category."},{"name":"view","in":"query","schema":{"type":"string","enum":["compact","standard"],"default":"compact"},"description":"`compact` — lightweight list items. `standard` — includes highlights, subcategories, and structured location. Full profiles require a separate `/registry/businesses/{id}` call."},{"name":"country","in":"query","schema":{"type":"string","example":"NG"},"description":"ISO-2 country code or full country name."},{"name":"state","in":"query","schema":{"type":"string","example":"Lagos"},"description":"State or province."},{"name":"city","in":"query","schema":{"type":"string","example":"Lagos"},"description":"City name."},{"name":"area","in":"query","schema":{"type":"string","example":"Ikeja"},"description":"Neighbourhood, market, or district."},{"name":"industry","in":"query","schema":{"type":"string","example":"Financial Technology"},"description":"Industry or category filter."},{"name":"verified_only","in":"query","schema":{"type":"boolean","default":false},"description":"Return only fully verified businesses."},{"name":"qualification","in":"query","schema":{"type":"string","enum":["qualified_only","partial_or_better","all"],"default":"all"}},{"name":"verification_status","in":"query","schema":{"type":"string","enum":["UNVERIFIED","VERIFIED","EXPIRED"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Results per page. Max 100."},{"name":"lat","in":"query","schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lng","in":"query","schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"radius","in":"query","schema":{"type":"number","minimum":1,"maximum":1000,"default":50}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrySearchResponse"},"example":{"success":true,"data":{"requestId":"req_d4e5f6","query":"fintech","resolvedSearchType":"business_search","detected":{"intent":"find_business","category":"Financial Technology","product_terms":[],"service_terms":[],"business_model_hints":{"audience":"B2B","operating_model":null,"commerce_type":null},"normalized_query":"fintech","area":"Ikeja","city":"Lagos","state":"Lagos","country":"NG"},"meta":{"view":"compact","limit":10,"returned_count":8,"total_matches":21,"qualified_matches":18,"searchTimeMs":65},"results":[{"id":"biz_abc123","name":"Paysnug Technology Limited","slug":"paysnug-technology-limited","title":"Paysnug Technology Limited - Fintech in Lagos","summary":"B2B payment infrastructure and payroll software for African businesses.","category":"Financial Technology","location":"Victoria Island, Lagos, Lagos State, NG","verified":true,"freshness":"FRESH","qualification_status":"QUALIFIED","match_score":0.92,"ranking_reason":"Strong match for fintech in Lagos. Verified business with fresh data.","profile_url":"https://usetruee.com/b/paysnug-technology-limited","data_url":"https://api.usetruee.com/api/v1/registry/businesses/paysnug-technology-limited"}]},"timestamp":"2026-05-20T10:00:00.000Z"}}}},"401":{"description":"Missing or invalid API key"},"429":{"description":"Rate limit or query quota exceeded"}}}},"/registry/businesses/{idOrSlug}":{"get":{"tags":["Authentication","Business Data Schema","Errors","Rate Limits"],"summary":"Full business profile","description":"Returns the complete, verifiable profile of a single business — including all branches, products, services, media, and trust signals. Use the `id` or `slug` from a search result.\n\n**Query cost: 1.**\n\n**Authentication:** `x-api-key` header required.","security":[{"api_key_auth":[]}],"parameters":[{"name":"idOrSlug","in":"path","required":true,"schema":{"type":"string","example":"paysnug-technology-limited"},"description":"Business UUID or slug from a search result."}],"responses":{"200":{"description":"Full profile returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryFullProfileResponse"}}}},"401":{"description":"Missing or invalid API key"},"404":{"description":"Business not found"}}}},"/registry/updated":{"get":{"tags":["Authentication","Business Data Schema","Errors","Rate Limits"],"summary":"Delta sync","description":"Returns only the business IDs and change types that have been updated since a given timestamp. Use this to keep a local cache in sync without re-fetching the full directory.\n\n**Query cost: 1.**\n\n**Authentication:** `x-api-key` header required.","security":[{"api_key_auth":[]}],"parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date-time","example":"2026-05-01T00:00:00Z"},"description":"Return records updated after this ISO 8601 timestamp."},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"List of changed records","content":{"application/json":{"example":{"success":true,"data":{"items":[{"business_id":"biz_abc123","change_type":"UPDATED","updated_at":"2026-05-19T14:23:00Z","business_name":"Paysnug Technology Limited","industry":"Financial Technology"}],"total":1}}}}},"401":{"description":"Missing or invalid API key"}}}},"/mcp/docs":{"get":{"servers":[{"url":"/"}],"tags":["MCP Server"],"summary":"MCP server documentation","description":"Returns the machine-readable MCP server metadata, transport URL, authentication requirements, and available tools. **No authentication required.**","responses":{"200":{"description":"MCP documentation returned","content":{"application/json":{"example":{"success":true,"data":{"name":"Truee MCP Server","transport":"HTTP JSON-RPC","endpoint":"/mcp","authentication":{"header":"x-api-key"},"tools":["search_businesses","query_businesses","get_business","list_categories"]}}}}}}}}},"components":{"securitySchemes":{"api_key_auth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"RegistryDetected":{"type":"object","description":"What the search engine understood from the query.","properties":{"intent":{"type":"string","enum":["find_business","find_product","find_service"],"example":"find_business"},"category":{"type":"string","nullable":true,"example":"Financial Technology"},"product_terms":{"type":"array","items":{"type":"string"},"example":[]},"service_terms":{"type":"array","items":{"type":"string"},"example":[]},"business_model_hints":{"type":"object","properties":{"audience":{"type":"string","nullable":true,"enum":["B2B","B2C","COMBINATION",null],"example":"B2B"},"operating_model":{"type":"string","nullable":true,"enum":["ONLINE","PHYSICAL","HYBRID",null]},"commerce_type":{"type":"string","nullable":true,"enum":["retail","wholesale","marketplace",null]}}},"normalized_query":{"type":"string","nullable":true,"example":"fintech","description":"Core search keywords after intent extraction."},"area":{"type":"string","nullable":true,"example":"Ikeja"},"city":{"type":"string","nullable":true,"example":"Lagos"},"state":{"type":"string","nullable":true,"example":"Lagos"},"country":{"type":"string","nullable":true,"example":"NG"}}},"RegistrySearchMeta":{"type":"object","properties":{"view":{"type":"string","enum":["compact","standard"]},"limit":{"type":"integer","example":10},"returned_count":{"type":"integer","example":10},"total_matches":{"type":"integer","example":47},"qualified_matches":{"type":"integer","example":32},"searchTimeMs":{"type":"integer","example":230},"no_results_reason":{"type":"string","nullable":true,"example":"47 businesses match before location filters, but none match city \"Kano\". Try broadening the location.","description":"Only present when results are empty due to location narrowing."},"broadened_match_count":{"type":"integer","nullable":true,"example":47}}},"RegistryCompactResult":{"type":"object","required":["id","name","slug","title","summary","category","verified","freshness","qualification_status","match_score","profile_url","data_url"],"properties":{"id":{"type":"string","example":"biz_abc123"},"name":{"type":"string","example":"Paysnug Technology Limited"},"slug":{"type":"string","example":"paysnug-technology-limited"},"title":{"type":"string","example":"Paysnug Technology Limited - Fintech in Lagos"},"summary":{"type":"string","example":"B2B payment infrastructure and payroll software for African businesses."},"category":{"type":"string","example":"Financial Technology"},"location":{"type":"string","example":"Victoria Island, Lagos, NG","description":"Formatted location string (compact view)."},"verified":{"type":"boolean","example":true},"freshness":{"type":"string","enum":["FRESH","RECENT","STALE","LEGACY"],"example":"FRESH","description":"FRESH = confirmed in last 90 days. RECENT = 90–180 days. STALE = 180+ days."},"qualification_status":{"type":"string","enum":["QUALIFIED","PARTIAL","INCOMPLETE"],"example":"QUALIFIED"},"match_score":{"type":"number","minimum":0,"maximum":1,"example":0.92},"ranking_reason":{"type":"string","example":"Strong match for fintech in Lagos. Verified business with fresh data."},"profile_url":{"type":"string","format":"uri","example":"https://usetruee.com/b/paysnug-technology-limited"},"data_url":{"type":"string","format":"uri","example":"https://api.usetruee.com/api/v1/registry/businesses/paysnug-technology-limited"}}},"RegistryStandardResult":{"allOf":[{"$ref":"#/components/schemas/RegistryCompactResult"},{"type":"object","properties":{"highlights":{"type":"array","items":{"type":"string"},"example":["Operates in Lagos, Nigeria.","Offers payroll software and payment APIs."]},"subcategories":{"type":"array","items":{"type":"string"},"example":["Payments","Payroll","B2B SaaS"]},"location":{"type":"object","properties":{"country":{"type":"string","example":"Nigeria"},"state":{"type":"string","nullable":true,"example":"Lagos"},"city":{"type":"string","nullable":true,"example":"Lagos"},"area":{"type":"string","nullable":true,"example":"Victoria Island"}}}}}]},"RegistrySearchResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"requestId":{"type":"string","example":"req_a1b2c3"},"query":{"type":"string","nullable":true,"example":"fintech company in Lagos","description":"The original query string. Null for structured searches."},"resolvedSearchType":{"type":"string","enum":["business_search"]},"detected":{"$ref":"#/components/schemas/RegistryDetected"},"meta":{"$ref":"#/components/schemas/RegistrySearchMeta"},"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/RegistryCompactResult"},{"$ref":"#/components/schemas/RegistryStandardResult"}]}}}},"timestamp":{"type":"string","format":"date-time"}},"example":{"success":true,"data":{"requestId":"req_a1b2c3","query":"fintech company in Lagos","resolvedSearchType":"business_search","detected":{"intent":"find_business","category":"Financial Technology","product_terms":[],"service_terms":[],"business_model_hints":{"audience":"B2B","operating_model":null,"commerce_type":null},"normalized_query":"fintech","area":null,"city":"Lagos","state":null,"country":"NG"},"meta":{"view":"compact","limit":10,"returned_count":10,"total_matches":47,"qualified_matches":32,"searchTimeMs":230},"results":[{"id":"biz_abc123","name":"Paysnug Technology Limited","slug":"paysnug-technology-limited","title":"Paysnug Technology Limited - Fintech in Lagos","summary":"B2B payment infrastructure and payroll software for African businesses.","category":"Financial Technology","location":"Victoria Island, Lagos, Lagos State, NG","verified":true,"freshness":"FRESH","qualification_status":"QUALIFIED","match_score":0.92,"ranking_reason":"Strong match for fintech in Lagos. Verified business with fresh data.","profile_url":"https://usetruee.com/b/paysnug-technology-limited","data_url":"https://api.usetruee.com/api/v1/registry/businesses/paysnug-technology-limited"}]},"timestamp":"2026-05-20T10:00:00.000Z"}},"RegistryFullProfileResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","example":"biz_abc123"},"name":{"type":"string","example":"Paysnug Technology Limited"},"slug":{"type":"string","example":"paysnug-technology-limited"},"status":{"type":"string","enum":["ACTIVE_VERIFIED","ACTIVE_UNVERIFIED","INACTIVE","SUSPENDED"]},"verified":{"type":"boolean"},"data_url":{"type":"string","format":"uri"},"profile_url":{"type":"string","format":"uri"},"updated_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"tagline":{"type":"string","nullable":true},"what_they_do":{"type":"object","additionalProperties":true},"where_they_are":{"type":"object","additionalProperties":true},"who_they_serve":{"type":"object","additionalProperties":true},"contact":{"type":"object","additionalProperties":true},"branches":{"type":"array","items":{"type":"object","additionalProperties":true}},"products":{"type":"array","items":{"type":"object","additionalProperties":true}},"services":{"type":"array","items":{"type":"object","additionalProperties":true}},"announcements":{"type":"array","items":{"type":"object","additionalProperties":true}},"media":{"type":"array","items":{"type":"object","additionalProperties":true}},"trust_signals":{"type":"array","items":{"type":"object","additionalProperties":true}},"freshness":{"type":"object","additionalProperties":true},"scores":{"type":"object","additionalProperties":true},"qualification_status":{"type":"string","enum":["QUALIFIED","PARTIAL","INCOMPLETE"]},"meta":{"type":"object","additionalProperties":true}}},"timestamp":{"type":"string","format":"date-time"}}}}}}