KosmoKrator

data

REST Countries Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

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

MCP-only Lua

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

REST Countries

Namespace: rest-countries

Use this integration to retrieve public country reference data from REST Countries v3.1: names, ISO codes, capitals, regions, currencies, languages, flags, translations, demonyms, maps, borders, time zones, and independence.

Authentication

REST Countries v3.1 is public and requires no credentials.

Tools

  • rest_countries_all: retrieve all countries with selected fields.
  • rest_countries_name: search by common or official country name.
  • rest_countries_alpha: retrieve one country by cca2, ccn3, cca3, or cioc code.
  • rest_countries_alpha_codes: retrieve multiple countries by code list.
  • rest_countries_currency: search by currency code or name.
  • rest_countries_language: search by language code or name.
  • rest_countries_capital: search by capital city.
  • rest_countries_region: filter by region.
  • rest_countries_subregion: filter by subregion.
  • rest_countries_demonym: search by demonym.
  • rest_countries_translation: search by translated country name.
  • rest_countries_independent: filter by independence status.

Return Notes

Responses are returned under data and keep REST Countries field names intact. Use fields to keep payloads small, for example name,cca2,cca3,capital,region,population. REST Countries currently allows up to 10 requested fields.

The all endpoint requires fields. If omitted, this integration uses: name,cca2,cca3,capital,region,subregion,population,flags.

Examples

local countries = tools.rest_countries_all({
  fields = "name,cca2,cca3,capital,region,population"
})

local germany = tools.rest_countries_alpha({
  code = "DEU",
  fields = "name,capital,currencies,languages,flags"
})

local eurozone = tools.rest_countries_currency({
  currency = "eur",
  fields = "name,cca2,currencies"
})
Raw agent markdown 
# REST Countries

Namespace: `rest-countries`

Use this integration to retrieve public country reference data from REST
Countries v3.1: names, ISO codes, capitals, regions, currencies, languages,
flags, translations, demonyms, maps, borders, time zones, and independence.

## Authentication

REST Countries v3.1 is public and requires no credentials.

## Tools

- `rest_countries_all`: retrieve all countries with selected fields.
- `rest_countries_name`: search by common or official country name.
- `rest_countries_alpha`: retrieve one country by `cca2`, `ccn3`, `cca3`, or
  `cioc` code.
- `rest_countries_alpha_codes`: retrieve multiple countries by code list.
- `rest_countries_currency`: search by currency code or name.
- `rest_countries_language`: search by language code or name.
- `rest_countries_capital`: search by capital city.
- `rest_countries_region`: filter by region.
- `rest_countries_subregion`: filter by subregion.
- `rest_countries_demonym`: search by demonym.
- `rest_countries_translation`: search by translated country name.
- `rest_countries_independent`: filter by independence status.

## Return Notes

Responses are returned under `data` and keep REST Countries field names intact.
Use `fields` to keep payloads small, for example
`name,cca2,cca3,capital,region,population`. REST Countries currently allows
up to 10 requested fields.

The `all` endpoint requires fields. If omitted, this integration uses:
`name,cca2,cca3,capital,region,subregion,population,flags`.

## Examples

```lua
local countries = tools.rest_countries_all({
  fields = "name,cca2,cca3,capital,region,population"
})

local germany = tools.rest_countries_alpha({
  code = "DEU",
  fields = "name,capital,currencies,languages,flags"
})

local eurozone = tools.rest_countries_currency({
  currency = "eur",
  fields = "name,cca2,currencies"
})
```
Metadata-derived Lua example 
local result = app.integrations.rest_countries.all({})
print(result)

Functions

all Read

Retrieve all countries with selected fields.

Lua path
app.integrations.rest_countries.all
Full name
rest-countries.rest_countries_all
ParameterTypeRequiredDescription
No parameters.
by_name Read

Search countries by common or official name.

Lua path
app.integrations.rest_countries.by_name
Full name
rest-countries.rest_countries_name
ParameterTypeRequiredDescription
No parameters.
by_code Read

Retrieve one country by alpha, numeric, or IOC code.

Lua path
app.integrations.rest_countries.by_code
Full name
rest-countries.rest_countries_alpha
ParameterTypeRequiredDescription
No parameters.
by_codes Read

Retrieve multiple countries by code list.

Lua path
app.integrations.rest_countries.by_codes
Full name
rest-countries.rest_countries_alpha_codes
ParameterTypeRequiredDescription
No parameters.
by_currency Read

Search countries by currency code or name.

Lua path
app.integrations.rest_countries.by_currency
Full name
rest-countries.rest_countries_currency
ParameterTypeRequiredDescription
No parameters.
by_language Read

Search countries by language code or name.

Lua path
app.integrations.rest_countries.by_language
Full name
rest-countries.rest_countries_language
ParameterTypeRequiredDescription
No parameters.
by_capital Read

Search countries by capital city.

Lua path
app.integrations.rest_countries.by_capital
Full name
rest-countries.rest_countries_capital
ParameterTypeRequiredDescription
No parameters.
by_region Read

Filter countries by region.

Lua path
app.integrations.rest_countries.by_region
Full name
rest-countries.rest_countries_region
ParameterTypeRequiredDescription
No parameters.
by_subregion Read

Filter countries by subregion.

Lua path
app.integrations.rest_countries.by_subregion
Full name
rest-countries.rest_countries_subregion
ParameterTypeRequiredDescription
No parameters.
by_demonym Read

Search countries by demonym.

Lua path
app.integrations.rest_countries.by_demonym
Full name
rest-countries.rest_countries_demonym
ParameterTypeRequiredDescription
No parameters.
by_translation Read

Search countries by translated country name.

Lua path
app.integrations.rest_countries.by_translation
Full name
rest-countries.rest_countries_translation
ParameterTypeRequiredDescription
No parameters.
independent Read

List independent or non-independent countries.

Lua path
app.integrations.rest_countries.independent
Full name
rest-countries.rest_countries_independent
ParameterTypeRequiredDescription
No parameters.