KosmoKrator

data

OpenFIGI Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.openfigi.*. Use lua_read_doc("integrations.openfigi") 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 OpenFIGI workflow without starting an interactive agent session.

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

Workflow file

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

workflow.lua 
local openfigi = app.integrations.openfigi
local result = openfigi.mapping({})

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.openfigi, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.openfigi.default.* or app.integrations.openfigi.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need OpenFIGI, 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.

OpenFIGI

Namespace: openfigi

OpenFIGI maps third-party security identifiers to Financial Instrument Global Identifiers (FIGIs). The API works without an API key at lower rate limits. Configure api_key when you need higher request limits; it is sent as the X-OPENFIGI-APIKEY header.

Tools

  • openfigi_mapping maps identifiers such as ticker, ISIN, CUSIP, SEDOL, and Bloomberg IDs to FIGIs.
  • openfigi_mapping_values lists supported enum values for mapping job fields such as idType, exchCode, micCode, and currency.
  • openfigi_search searches for FIGIs using keywords and optional filters.
  • openfigi_filter filters instruments using OpenFIGI filter fields. Prefer this for structured discovery workflows.
  • openfigi_schema returns the current OpenAPI schema from /schema.

Notes For Agents

Mapping jobs require idType and idValue. Add filters such as exchCode, micCode, currency, marketSecDes, securityType, or securityType2 when the identifier is ambiguous.

Search and filter responses may include next. Pass that value as start with the same filter payload to fetch the next page.

Examples use fake values:

local mapped = openfigi.mapping({
  jobs = {
    { idType = "TICKER", idValue = "IBM", exchCode = "US" },
    { idType = "ID_ISIN", idValue = "US4592001014" }
  }
})

local id_types = openfigi.mapping_values({
  key = "idType"
})

local results = openfigi.filter({
  query = "IBM",
  exchCode = "US",
  marketSecDes = "Equity"
})

OpenFIGI v3 returns warning for normal no-match mapping results and error for request errors. The integration preserves successful response payloads as returned by the API and only turns HTTP-level failures into tool errors.

Raw agent markdown 
# OpenFIGI

Namespace: `openfigi`

OpenFIGI maps third-party security identifiers to Financial Instrument Global Identifiers (FIGIs). The API works without an API key at lower rate limits. Configure `api_key` when you need higher request limits; it is sent as the `X-OPENFIGI-APIKEY` header.

## Tools

- `openfigi_mapping` maps identifiers such as ticker, ISIN, CUSIP, SEDOL, and Bloomberg IDs to FIGIs.
- `openfigi_mapping_values` lists supported enum values for mapping job fields such as `idType`, `exchCode`, `micCode`, and `currency`.
- `openfigi_search` searches for FIGIs using keywords and optional filters.
- `openfigi_filter` filters instruments using OpenFIGI filter fields. Prefer this for structured discovery workflows.
- `openfigi_schema` returns the current OpenAPI schema from `/schema`.

## Notes For Agents

Mapping jobs require `idType` and `idValue`. Add filters such as `exchCode`, `micCode`, `currency`, `marketSecDes`, `securityType`, or `securityType2` when the identifier is ambiguous.

Search and filter responses may include `next`. Pass that value as `start` with the same filter payload to fetch the next page.

Examples use fake values:

```lua
local mapped = openfigi.mapping({
  jobs = {
    { idType = "TICKER", idValue = "IBM", exchCode = "US" },
    { idType = "ID_ISIN", idValue = "US4592001014" }
  }
})

local id_types = openfigi.mapping_values({
  key = "idType"
})

local results = openfigi.filter({
  query = "IBM",
  exchCode = "US",
  marketSecDes = "Equity"
})
```

OpenFIGI v3 returns `warning` for normal no-match mapping results and `error` for request errors. The integration preserves successful response payloads as returned by the API and only turns HTTP-level failures into tool errors.
Metadata-derived Lua example 
local result = app.integrations.openfigi.mapping({})
print(result)

Functions

mapping Read

Map third-party identifiers to FIGIs.

Lua path
app.integrations.openfigi.mapping
Full name
openfigi.openfigi_mapping
ParameterTypeRequiredDescription
No parameters.
mapping_values Read

List supported values for OpenFIGI mapping job properties.

Lua path
app.integrations.openfigi.mapping_values
Full name
openfigi.openfigi_mapping_values
ParameterTypeRequiredDescription
No parameters.
filter Read

Filter for FIGIs using OpenFIGI instrument filters.

Lua path
app.integrations.openfigi.filter
Full name
openfigi.openfigi_filter
ParameterTypeRequiredDescription
No parameters.
schema Read

Retrieve the current OpenFIGI OpenAPI schema.

Lua path
app.integrations.openfigi.schema
Full name
openfigi.openfigi_schema
ParameterTypeRequiredDescription
No parameters.