{"openapi":"3.1.0","info":{"title":"Companies House (BYOK) API","version":"0.1.0","description":"Companies House (BYOK) lets an AI assistant read your own Companies House data through the Companies House API with a key you supply (Companies House API key). Read-only: 7 tools (search_companies, get_company, list_company_officers, list_filing_history, list_company_charges, search_officers, list_officer_appointments). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-companieshouse.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-companieshouse/docs"},"termsOfService":"https://connectorbay.com/byok-companieshouse/terms"},"servers":[{"url":"https://byok-companieshouse.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-companieshouse/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/search_companies":{"post":{"operationId":"search_companies","summary":"Search UK registered companies by name or number; returns company number, name, status, type, incorporation date and a s","description":"Search UK registered companies by name or number; returns company number, name, status, type, incorporation date and a short address. Use for \"Find UK companies called Acme Widgets\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Company name or number to search for.","maxLength":200,"title":"Q","type":"string"},"items_per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Results per page, 1 to 50 (the service has its own default when omitted).","title":"Items Per Page"},"start_index":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Index of the first result to return; 0 starts at the first.","title":"Start Index"}},"required":["q"],"title":"search_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_company":{"post":{"operationId":"get_company","summary":"Get a UK company profile by number: name, status, type, incorporation and cessation dates, SIC codes, registered office ","description":"Get a UK company profile by number: name, status, type, incorporation and cessation dates, SIC codes, registered office address, accounts and confirmation statement dates, and charge and insolvency flags. Use for \"Show the company profile of 00000006\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, e.g. SC123456).","maxLength":12,"title":"Company Number","type":"string"}},"required":["company_number"],"title":"get_companyArguments","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_company_officers":{"post":{"operationId":"list_company_officers","summary":"List the officers (directors, secretaries, members) of a company with role, appointment and resignation dates, nationali","description":"List the officers (directors, secretaries, members) of a company with role, appointment and resignation dates, nationality, occupation and country of residence. Addresses and birth dates are not returned by this connector. Use for \"Who are the directors 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, e.g. SC123456).","maxLength":12,"title":"Company Number","type":"string"},"items_per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Results per page, 1 to 50 (the service has its own default when omitted).","title":"Items Per Page"},"start_index":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Index of the first result to return; 0 starts at the first.","title":"Start Index"},"order_by":{"anyOf":[{"enum":["appointed_on","resigned_on","surname"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by appointed_on, resigned_on or surname.","title":"Order By"}},"required":["company_number"],"title":"list_company_officersArguments","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_filing_history":{"post":{"operationId":"list_filing_history","summary":"List a company's filing history (accounts, confirmation statements, officer changes ...) with date, category, type, desc","description":"List a company's filing history (accounts, confirmation statements, officer changes ...) with date, category, type, description and links to the documents. Use for \"What has company 00000006 filed recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, e.g. SC123456).","maxLength":12,"title":"Company Number","type":"string"},"category":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated filing categories to keep, for example accounts or confirmation-statement,officers.","title":"Category"},"items_per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Results per page, 1 to 50 (the service has its own default when omitted).","title":"Items Per Page"},"start_index":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Index of the first result to return; 0 starts at the first.","title":"Start Index"}},"required":["company_number"],"title":"list_filing_historyArguments","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_company_charges":{"post":{"operationId":"list_company_charges","summary":"List the charges (mortgages and security) registered against a company, with status, creation and satisfaction dates and","description":"List the charges (mortgages and security) registered against a company, with status, creation and satisfaction dates and who they are in favour of. Use for \"Does company 00000006 have any outstanding charges\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_number":{"description":"Companies House company number, for example 00000006 (letters allowed, e.g. SC123456).","maxLength":12,"title":"Company Number","type":"string"},"items_per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Results per page, 1 to 50 (the service has its own default when omitted).","title":"Items Per Page"},"start_index":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Index of the first result to return; 0 starts at the first.","title":"Start Index"}},"required":["company_number"],"title":"list_company_chargesArguments","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_officers":{"post":{"operationId":"search_officers","summary":"Search company officers by name; returns the name, how many appointments they hold and links to their appointment lists.","description":"Search company officers by name; returns the name, how many appointments they hold and links to their appointment lists. Birth dates are not returned by this connector. Use for \"Find company officers named Jane Example\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Officer name to search for.","maxLength":200,"title":"Q","type":"string"},"items_per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Results per page, 1 to 50 (the service has its own default when omitted).","title":"Items Per Page"},"start_index":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Index of the first result to return; 0 starts at the first.","title":"Start Index"}},"required":["q"],"title":"search_officersArguments","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_officer_appointments":{"post":{"operationId":"list_officer_appointments","summary":"List the company appointments of one officer by officer id (the id is in the officer's links from list_company_officers ","description":"List the company appointments of one officer by officer id (the id is in the officer's links from list_company_officers or search_officers): company name, number and status, role and dates. Use for \"Which companies is officer abc123XYZ appointed to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"officer_id":{"description":"Officer id taken from the officer's links, for example abc123XYZ-example.","maxLength":60,"title":"Officer Id","type":"string"},"filter":{"anyOf":[{"const":"active","type":"string"},{"type":"null"}],"default":null,"description":"Use active to list only current appointments.","title":"Filter"},"items_per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Results per page, 1 to 50 (the service has its own default when omitted).","title":"Items Per Page"},"start_index":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Index of the first result to return; 0 starts at the first.","title":"Start Index"}},"required":["officer_id"],"title":"list_officer_appointmentsArguments","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}}}}