{"openapi":"3.1.0","info":{"title":"Companies House Registry (BYOK) API","version":"0.1.0","description":"Companies House Registry (BYOK) lets an AI assistant read your own Companies House Registry data through the Companies House Registry API with a key you supply (Companies House API key). Read-only: 10 tools (advanced_company_search, search_companies_alphabetically, search_dissolved_companies, get_registered_office_address, get_company_insolvency, get_company_exemptions, list_uk_establishments,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-companieshouse-registry.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-companieshouse-registry/docs"},"termsOfService":"https://connectorbay.com/byok-companieshouse-registry/terms"},"servers":[{"url":"https://byok-companieshouse-registry.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-companieshouse-registry/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/advanced_company_search":{"post":{"operationId":"advanced_company_search","summary":"Search UK companies by name fragments, status, type, SIC code, location and incorporation or dissolution dates; returns ","description":"Search UK companies by name fragments, status, type, SIC code, location and incorporation or dissolution dates; returns company number, status, dates, SIC codes and registered office. Use for \"Which active private limited companies incorporated in 2026 have SIC code 62012\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_name_includes":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words the company name must contain.","title":"Company Name Includes"},"company_name_excludes":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words the company name must not contain.","title":"Company Name Excludes"},"company_status":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Status filter such as active, dissolved, liquidation; several values separated by commas.","title":"Company Status"},"company_type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Company type filter such as ltd, plc or llp; several values separated by commas.","title":"Company Type"},"sic_codes":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"SIC codes to match, separated by commas, for example 62012,62020.","title":"Sic Codes"},"location":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Place name or town to match against the registered office.","title":"Location"},"incorporated_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest incorporation date, YYYY-MM-DD.","title":"Incorporated From"},"incorporated_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Latest incorporation date, YYYY-MM-DD.","title":"Incorporated To"},"dissolved_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest dissolution date, YYYY-MM-DD.","title":"Dissolved From"},"dissolved_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Latest dissolution date, YYYY-MM-DD.","title":"Dissolved To"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Size"},"start_index":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result number to start from, for paging; 0 is the first.","title":"Start Index"}},"title":"advanced_company_searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_companies_alphabetically":{"post":{"operationId":"search_companies_alphabetically","summary":"List companies whose names sort next to a name, with company number, status and type; page with the ordered_alpha_key_wi","description":"List companies whose names sort next to a name, with company number, status and type; page with the ordered_alpha_key_with_id values. Use for \"What companies are listed alphabetically around the name Northwind Traders\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Company name to place in the alphabetical list.","maxLength":200,"title":"Q","type":"string"},"search_above":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"ordered_alpha_key_with_id from a previous result to page upwards.","title":"Search Above"},"search_below":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"ordered_alpha_key_with_id from a previous result to page downwards.","title":"Search Below"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Size"}},"required":["q"],"title":"search_companies_alphabeticallyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_dissolved_companies":{"post":{"operationId":"search_dissolved_companies","summary":"Search dissolved UK companies by name, as an alphabetical list, best match or previous company name; returns dissolution","description":"Search dissolved UK companies by name, as an alphabetical list, best match or previous company name; returns dissolution date and old names. Use for \"Find dissolved UK companies named Blue Anchor Trading\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Company name to search for.","maxLength":200,"title":"Q","type":"string"},"search_type":{"description":"Kind of search: alphabetical, best-match or previous-name-dissolved.","enum":["alphabetical","best-match","previous-name-dissolved"],"title":"Search Type","type":"string"},"search_above":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"ordered_alpha_key_with_id from a previous result, for alphabetical paging up.","title":"Search Above"},"search_below":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"ordered_alpha_key_with_id from a previous result, for alphabetical paging down.","title":"Search Below"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return (1 to 100).","title":"Size"},"start_index":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Result number to start from for best-match and previous-name searches.","title":"Start Index"}},"required":["q","search_type"],"title":"search_dissolved_companiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_registered_office_address":{"post":{"operationId":"get_registered_office_address","summary":"Get the current registered office address of a UK company. Use for \"What is the registered office address of company 000","description":"Get the current registered office address of a UK company. Use for \"What is the registered office address of company 00000006\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, for example SC123456).","maxLength":12,"title":"Company Number","type":"string"}},"required":["company_number"],"title":"get_registered_office_addressArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_company_insolvency":{"post":{"operationId":"get_company_insolvency","summary":"Get insolvency cases for a UK company: case type, dates, case number and status. Use for \"Is company 00000006 in an inso","description":"Get insolvency cases for a UK company: case type, dates, case number and status. Use for \"Is company 00000006 in an insolvency process\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, for example SC123456).","maxLength":12,"title":"Company Number","type":"string"}},"required":["company_number"],"title":"get_company_insolvencyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_company_exemptions":{"post":{"operationId":"get_company_exemptions","summary":"Get the disclosure exemptions recorded for a UK company, such as exemption from keeping a PSC register for listed compan","description":"Get the disclosure exemptions recorded for a UK company, such as exemption from keeping a PSC register for listed companies. Use for \"Does company 00000006 have any PSC register exemptions\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, for example SC123456).","maxLength":12,"title":"Company Number","type":"string"}},"required":["company_number"],"title":"get_company_exemptionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_uk_establishments":{"post":{"operationId":"list_uk_establishments","summary":"List the UK establishments registered by an overseas company: company number, name, status and locality. Use for \"Which ","description":"List the UK establishments registered by an overseas company: company number, name, status and locality. Use for \"Which UK establishments does overseas company FC000001 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Company number of the overseas company, for example FC000001.","maxLength":12,"title":"Company Number","type":"string"}},"required":["company_number"],"title":"list_uk_establishmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_company_registers":{"post":{"operationId":"get_company_registers","summary":"Get where a company keeps its statutory registers (directors, secretaries, members, PSC): register type and where it was","description":"Get where a company keeps its statutory registers (directors, secretaries, members, PSC): register type and where it was moved to. Use for \"Where does company 00000006 keep its statutory registers\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, for example SC123456).","maxLength":12,"title":"Company Number","type":"string"}},"required":["company_number"],"title":"get_company_registersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_charge_details":{"post":{"operationId":"get_charge_details","summary":"Get one registered charge of a UK company: charge code, status, key dates, classification and who is entitled to it. Use","description":"Get one registered charge of a UK company: charge code, status, key dates, classification and who is entitled to it. Use for \"Show the details of charge abc123 on company 00000006\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, for example SC123456).","maxLength":12,"title":"Company Number","type":"string"},"charge_id":{"description":"Charge id taken from the company's charge list.","maxLength":100,"title":"Charge Id","type":"string"}},"required":["company_number","charge_id"],"title":"get_charge_detailsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_filing_history_item":{"post":{"operationId":"get_filing_history_item","summary":"Get one filing of a UK company by transaction id: type, category, date, description and page count. Use for \"Show filing","description":"Get one filing of a UK company by transaction id: type, category, date, description and page count. Use for \"Show filing transaction MzIxMjM0NTY3OGFkaXF6a2N4 for company 00000006\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, for example SC123456).","maxLength":12,"title":"Company Number","type":"string"},"transaction_id":{"description":"Transaction id taken from the company's filing history list.","maxLength":100,"title":"Transaction Id","type":"string"}},"required":["company_number","transaction_id"],"title":"get_filing_history_itemArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}