KosmoKrator

data

Companies House Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Companies House KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.companies_house.*. Use lua_read_doc("integrations.companies-house") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Companies House workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.companies_house.search_all({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("companies-house"))' --json
kosmo integrations:lua --eval 'print(docs.read("companies-house.search_all"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local companies_house = app.integrations.companies_house
local result = companies_house.search_all({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.companies_house, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.companies_house.default.* or app.integrations.companies_house.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Companies House, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Companies House

Namespace: companies_house

The Companies House integration uses the official UK Public Data API. It requires a Companies House API key and sends it as the Basic auth username with an empty password.

Use company search first when you do not know the exact company number. For due diligence workflows, fetch the company profile, filing history, officers, charges, PSC list/statements, insolvency, and exemptions separately instead of assuming a search result contains the full record.

Common Tools

  • companies_house_search_companies searches by company name or company number.
  • companies_house_advanced_search_companies supports official filters such as status, type, SIC code, incorporation dates, and location.
  • companies_house_company_profile retrieves the current company profile by company_number.
  • companies_house_filing_history lists filings; use companies_house_filing_history_item for a specific transaction_id.
  • companies_house_officers lists company officers; use companies_house_officer_appointments when following an officer across companies.
  • companies_house_charges and companies_house_charge cover mortgage and charge records.
  • companies_house_psc_list, companies_house_psc_statements, and the PSC detail tools cover persons with significant control.
  • companies_house_disqualified_officer_natural and companies_house_disqualified_officer_corporate fetch disqualified officer detail records.

Notes For Agents

Company numbers are strings. Preserve leading zeroes. PSC and officer detail IDs usually come from links in list responses; do not invent them from names.

List endpoints accept pagination fields such as items_per_page and start_index. When comparing companies, keep payloads small by fetching only the sections you need.

Examples use fake values:

local matches = companies_house.search_companies({
  q = "example holdings",
  items_per_page = 5
})

local profile = companies_house.company_profile({
  company_number = "00000006"
})

local filings = companies_house.filing_history({
  company_number = "00000006",
  category = "accounts",
  items_per_page = 10
})

local pscs = companies_house.psc_list({
  company_number = "00000006",
  items_per_page = 10
})

The integration returns the normalized JSON shape provided by Companies House. It removes empty query values and comma-joins array query filters such as category and sic_codes.

Raw agent markdown 
# Companies House

Namespace: `companies_house`

The Companies House integration uses the official UK Public Data API. It requires a Companies House API key and sends it as the Basic auth username with an empty password.

Use company search first when you do not know the exact company number. For due diligence workflows, fetch the company profile, filing history, officers, charges, PSC list/statements, insolvency, and exemptions separately instead of assuming a search result contains the full record.

## Common Tools

- `companies_house_search_companies` searches by company name or company number.
- `companies_house_advanced_search_companies` supports official filters such as status, type, SIC code, incorporation dates, and location.
- `companies_house_company_profile` retrieves the current company profile by `company_number`.
- `companies_house_filing_history` lists filings; use `companies_house_filing_history_item` for a specific `transaction_id`.
- `companies_house_officers` lists company officers; use `companies_house_officer_appointments` when following an officer across companies.
- `companies_house_charges` and `companies_house_charge` cover mortgage and charge records.
- `companies_house_psc_list`, `companies_house_psc_statements`, and the PSC detail tools cover persons with significant control.
- `companies_house_disqualified_officer_natural` and `companies_house_disqualified_officer_corporate` fetch disqualified officer detail records.

## Notes For Agents

Company numbers are strings. Preserve leading zeroes. PSC and officer detail IDs usually come from links in list responses; do not invent them from names.

List endpoints accept pagination fields such as `items_per_page` and `start_index`. When comparing companies, keep payloads small by fetching only the sections you need.

Examples use fake values:

```lua
local matches = companies_house.search_companies({
  q = "example holdings",
  items_per_page = 5
})

local profile = companies_house.company_profile({
  company_number = "00000006"
})

local filings = companies_house.filing_history({
  company_number = "00000006",
  category = "accounts",
  items_per_page = 10
})

local pscs = companies_house.psc_list({
  company_number = "00000006",
  items_per_page = 10
})
```

The integration returns the normalized JSON shape provided by Companies House. It removes empty query values and comma-joins array query filters such as `category` and `sic_codes`.
Metadata-derived Lua example 
local result = app.integrations.companies_house.search_all({})
print(result)

Functions

search_all Read

Search companies, officers, and disqualified officers.

Lua path
app.integrations.companies_house.search_all
Full name
companies-house.companies_house_search_all
ParameterTypeRequiredDescription
No parameters.
search_officers Read

Search company officers.

Lua path
app.integrations.companies_house.search_officers
Full name
companies-house.companies_house_search_officers
ParameterTypeRequiredDescription
No parameters.
search_disqualified_officers Read

Search disqualified officers.

Lua path
app.integrations.companies_house.search_disqualified_officers
Full name
companies-house.companies_house_search_disqualified_officers
ParameterTypeRequiredDescription
No parameters.
company_profile Read

Retrieve a company profile.

Lua path
app.integrations.companies_house.company_profile
Full name
companies-house.companies_house_company_profile
ParameterTypeRequiredDescription
No parameters.
registered_office_address Read

Retrieve a registered office address.

Lua path
app.integrations.companies_house.registered_office_address
Full name
companies-house.companies_house_registered_office_address
ParameterTypeRequiredDescription
No parameters.
officers Read

List company officers.

Lua path
app.integrations.companies_house.officers
Full name
companies-house.companies_house_officers
ParameterTypeRequiredDescription
No parameters.
officer_appointment Read

Retrieve one company officer appointment.

Lua path
app.integrations.companies_house.officer_appointment
Full name
companies-house.companies_house_officer_appointment
ParameterTypeRequiredDescription
No parameters.
officer_appointments Read

List appointments for an officer.

Lua path
app.integrations.companies_house.officer_appointments
Full name
companies-house.companies_house_officer_appointments
ParameterTypeRequiredDescription
No parameters.
registers Read

Retrieve company registers.

Lua path
app.integrations.companies_house.registers
Full name
companies-house.companies_house_registers
ParameterTypeRequiredDescription
No parameters.
filing_history Read

List company filing history.

Lua path
app.integrations.companies_house.filing_history
Full name
companies-house.companies_house_filing_history
ParameterTypeRequiredDescription
No parameters.
filing_history_item Read

Retrieve one filing history item.

Lua path
app.integrations.companies_house.filing_history_item
Full name
companies-house.companies_house_filing_history_item
ParameterTypeRequiredDescription
No parameters.
charges Read

List company charges.

Lua path
app.integrations.companies_house.charges
Full name
companies-house.companies_house_charges
ParameterTypeRequiredDescription
No parameters.
charge Read

Retrieve one company charge.

Lua path
app.integrations.companies_house.charge
Full name
companies-house.companies_house_charge
ParameterTypeRequiredDescription
No parameters.
insolvency Read

Retrieve insolvency information.

Lua path
app.integrations.companies_house.insolvency
Full name
companies-house.companies_house_insolvency
ParameterTypeRequiredDescription
No parameters.
exemptions Read

Retrieve company disclosure exemptions.

Lua path
app.integrations.companies_house.exemptions
Full name
companies-house.companies_house_exemptions
ParameterTypeRequiredDescription
No parameters.
uk_establishments Read

List UK establishments for an overseas company.

Lua path
app.integrations.companies_house.uk_establishments
Full name
companies-house.companies_house_uk_establishments
ParameterTypeRequiredDescription
No parameters.
psc_list Read

List persons with significant control.

Lua path
app.integrations.companies_house.psc_list
Full name
companies-house.companies_house_psc_list
ParameterTypeRequiredDescription
No parameters.
psc_statements Read

List PSC statements.

Lua path
app.integrations.companies_house.psc_statements
Full name
companies-house.companies_house_psc_statements
ParameterTypeRequiredDescription
No parameters.
psc_individual Read

Retrieve an individual PSC.

Lua path
app.integrations.companies_house.psc_individual
Full name
companies-house.companies_house_psc_individual
ParameterTypeRequiredDescription
No parameters.
psc_corporate_entity Read

Retrieve a corporate-entity PSC.

Lua path
app.integrations.companies_house.psc_corporate_entity
Full name
companies-house.companies_house_psc_corporate_entity
ParameterTypeRequiredDescription
No parameters.
psc_super_secure Read

Retrieve a super-secure PSC.

Lua path
app.integrations.companies_house.psc_super_secure
Full name
companies-house.companies_house_psc_super_secure
ParameterTypeRequiredDescription
No parameters.
psc_individual_beneficial_owner Read

Retrieve an individual beneficial owner PSC.

Lua path
app.integrations.companies_house.psc_individual_beneficial_owner
Full name
companies-house.companies_house_psc_individual_beneficial_owner
ParameterTypeRequiredDescription
No parameters.
psc_corporate_beneficial_owner Read

Retrieve a corporate-entity beneficial owner PSC.

Lua path
app.integrations.companies_house.psc_corporate_beneficial_owner
Full name
companies-house.companies_house_psc_corporate_entity_beneficial_owner
ParameterTypeRequiredDescription
No parameters.
psc_super_secure_beneficial_owner Read

Retrieve a super-secure beneficial owner PSC.

Lua path
app.integrations.companies_house.psc_super_secure_beneficial_owner
Full name
companies-house.companies_house_psc_super_secure_beneficial_owner
ParameterTypeRequiredDescription
No parameters.
psc_statement Read

Retrieve one PSC statement.

Lua path
app.integrations.companies_house.psc_statement
Full name
companies-house.companies_house_psc_statement
ParameterTypeRequiredDescription
No parameters.
natural_disqualified_officer Read

Retrieve a natural disqualified officer.

Lua path
app.integrations.companies_house.natural_disqualified_officer
Full name
companies-house.companies_house_disqualified_officer_natural
ParameterTypeRequiredDescription
No parameters.
corporate_disqualified_officer Read

Retrieve a corporate disqualified officer.

Lua path
app.integrations.companies_house.corporate_disqualified_officer
Full name
companies-house.companies_house_disqualified_officer_corporate
ParameterTypeRequiredDescription
No parameters.