KosmoKrator

data

IPstack Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.ipstack.standard_lookup({ip = "example_ip", fields = "example_fields", hostname = true, security = true, language = "example_language"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("ipstack"))' --json
kosmo integrations:lua --eval 'print(docs.read("ipstack.standard_lookup"))' --json

Workflow file

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

workflow.lua 
local ipstack = app.integrations.ipstack
local result = ipstack.standard_lookup({ip = "example_ip", fields = "example_fields", hostname = true, security = true, language = "example_language"})

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

MCP-only Lua

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

IPstack Lua Reference

Namespace: ipstack

This integration covers the three official IPstack endpoint shapes:

  • Standard lookup: GET /{ip}
  • Bulk lookup: GET /{ip1},{ip2}
  • Requester lookup: GET /check

All tools return IPstack’s JSON response directly. Optional fields can request nested response sections such as location, timezone, currency, connection, and security.

ipstack.lookup_ip

Look up one IP address or domain.

local result = app.integrations.ipstack.lookup_ip({
  ip = "134.201.250.155",
  fields = { "main", "location", "timezone" },
  language = "en"
})

Optional parameters:

  • fields: array of field names.
  • hostname: boolean, requests hostname lookup.
  • security: boolean, requests the paid security module.
  • language: response language code, such as en, de, fr, or pt-br.

ipstack.lookup_bulk

Look up up to 50 IP addresses or domains in one request.

local result = app.integrations.ipstack.lookup_bulk({
  ips = { "134.201.250.155", "72.229.28.185" },
  fields = { "main", "connection" }
})

Bulk lookup is plan-dependent in IPstack.

ipstack.lookup_requester

Detect and geolocate the IP address making the API request.

local result = app.integrations.ipstack.lookup_requester({
  fields = { "main", "location" }
})

Notes

IPstack represents timezone, currency, connection, and security data as optional response fields on the lookup endpoints. They are not separate API operations, so this package exposes them through fields rather than separate tools.

Raw agent markdown 
# IPstack Lua Reference

Namespace: `ipstack`

This integration covers the three official IPstack endpoint shapes:

- Standard lookup: `GET /{ip}`
- Bulk lookup: `GET /{ip1},{ip2}`
- Requester lookup: `GET /check`

All tools return IPstack's JSON response directly. Optional fields can request nested response sections such as `location`, `timezone`, `currency`, `connection`, and `security`.

## `ipstack.lookup_ip`

Look up one IP address or domain.

```lua
local result = app.integrations.ipstack.lookup_ip({
  ip = "134.201.250.155",
  fields = { "main", "location", "timezone" },
  language = "en"
})
```

Optional parameters:

- `fields`: array of field names.
- `hostname`: boolean, requests hostname lookup.
- `security`: boolean, requests the paid security module.
- `language`: response language code, such as `en`, `de`, `fr`, or `pt-br`.

## `ipstack.lookup_bulk`

Look up up to 50 IP addresses or domains in one request.

```lua
local result = app.integrations.ipstack.lookup_bulk({
  ips = { "134.201.250.155", "72.229.28.185" },
  fields = { "main", "connection" }
})
```

Bulk lookup is plan-dependent in IPstack.

## `ipstack.lookup_requester`

Detect and geolocate the IP address making the API request.

```lua
local result = app.integrations.ipstack.lookup_requester({
  fields = { "main", "location" }
})
```

## Notes

IPstack represents timezone, currency, connection, and security data as optional response fields on the lookup endpoints. They are not separate API operations, so this package exposes them through `fields` rather than separate tools.
Metadata-derived Lua example 
local result = app.integrations.ipstack.standard_lookup({ip = "example_ip", fields = "example_fields", hostname = true, security = true, language = "example_language"})
print(result)

Functions

standard_lookup Read

Look up geolocation data for a single IP address using IPstack. Returns country, region, city, coordinates, and more.

Lua path
app.integrations.ipstack.standard_lookup
Full name
ipstack.ipstack_lookup_ip
ParameterTypeRequiredDescription
ip string yes The IPv4 or IPv6 address or domain to look up (e.g., "134.201.250.155").
fields array no Optional response fields, such as ["main", "location", "timezone", "currency", "connection", "security"].
hostname boolean no Set true to request hostname lookup.
security boolean no Set true to request the paid security module.
language string no Response language code (e.g., "en", "de", "fr"). Defaults to English.
bulk_lookup Read

Look up geolocation data for multiple IP addresses at once (up to 50). Returns an array of geolocation results.

Lua path
app.integrations.ipstack.bulk_lookup
Full name
ipstack.ipstack_lookup_bulk
ParameterTypeRequiredDescription
ips array yes Array of IPv4 or IPv6 addresses or domains to look up (max 50, e.g., ["134.201.250.155", "72.229.28.185"]).
fields array no Optional response fields, such as ["main", "location", "timezone", "currency", "connection", "security"].
hostname boolean no Set true to request hostname lookup.
security boolean no Set true to request the paid security module.
language string no Response language code (e.g., "en", "de", "fr"). Defaults to English.
requester_lookup Read

Detect and geolocate the IP address making the API request using the official IPstack /check endpoint.

Lua path
app.integrations.ipstack.requester_lookup
Full name
ipstack.ipstack_lookup_requester
ParameterTypeRequiredDescription
fields array no Optional response fields, such as ["main", "location", "timezone", "currency", "connection", "security"].
hostname boolean no Set true to request hostname lookup.
security boolean no Set true to request the paid security module.
language string no Response language code (e.g., "en", "de", "fr"). Defaults to English.