KosmoKrator

data

Xata Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local xata = app.integrations.xata
local result = xata.list_databases({})

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

MCP-only Lua

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

Xata Lua API Reference

Namespace: app.integrations.xata

Configure an API key plus a database API endpoint such as https://example.us-east-1.xata.sh. Workspace management tools also need workspace_id.

Workspace Management

local databases = app.integrations.xata.list_databases({
  workspace_id = "ws_example"
})

local branch = app.integrations.xata.create_branch({
  workspace_id = "ws_example",
  database = "app",
  branch = "preview"
})

Tools:

  • list_databases({ workspace_id })
  • create_database({ workspace_id, database, body })
  • list_branches({ workspace_id, database })
  • create_branch({ workspace_id, database, branch, body })

Schema

local schema = app.integrations.xata.get_schema({
  database = "app",
  branch = "main"
})

Use update_schema({ database, branch, body }) for schema changes. The body is passed through to Xata unchanged.

Records

local created = app.integrations.xata.insert_record({
  database = "app",
  branch = "main",
  table = "contacts",
  body = {
    name = "Ada Lovelace",
    email = "[email protected]"
  }
})

local record = app.integrations.xata.get_record({
  database = "app",
  branch = "main",
  table = "contacts",
  record_id = created.id
})

Record tools:

  • get_record
  • insert_record
  • update_record
  • delete_record

Query, Search, Aggregates, And Transactions

local rows = app.integrations.xata.query_table({
  database = "app",
  branch = "main",
  table = "contacts",
  body = {
    columns = { "name", "email" },
    page = { size = 25 }
  }
})

local search = app.integrations.xata.search_branch({
  database = "app",
  branch = "main",
  body = {
    query = "ada",
    tables = { { table = "contacts" } }
  }
})

Additional tools:

  • aggregate_table({ database, branch, table, body })
  • vector_search({ database, branch, table, body })
  • transaction({ database, branch, body })

Responses are the normalized JSON returned by Xata.

Raw agent markdown 
# Xata Lua API Reference

Namespace: `app.integrations.xata`

Configure an API key plus a database API endpoint such as `https://example.us-east-1.xata.sh`. Workspace management tools also need `workspace_id`.

## Workspace Management

```lua
local databases = app.integrations.xata.list_databases({
  workspace_id = "ws_example"
})

local branch = app.integrations.xata.create_branch({
  workspace_id = "ws_example",
  database = "app",
  branch = "preview"
})
```

Tools:

- `list_databases({ workspace_id })`
- `create_database({ workspace_id, database, body })`
- `list_branches({ workspace_id, database })`
- `create_branch({ workspace_id, database, branch, body })`

## Schema

```lua
local schema = app.integrations.xata.get_schema({
  database = "app",
  branch = "main"
})
```

Use `update_schema({ database, branch, body })` for schema changes. The body is passed through to Xata unchanged.

## Records

```lua
local created = app.integrations.xata.insert_record({
  database = "app",
  branch = "main",
  table = "contacts",
  body = {
    name = "Ada Lovelace",
    email = "[email protected]"
  }
})

local record = app.integrations.xata.get_record({
  database = "app",
  branch = "main",
  table = "contacts",
  record_id = created.id
})
```

Record tools:

- `get_record`
- `insert_record`
- `update_record`
- `delete_record`

## Query, Search, Aggregates, And Transactions

```lua
local rows = app.integrations.xata.query_table({
  database = "app",
  branch = "main",
  table = "contacts",
  body = {
    columns = { "name", "email" },
    page = { size = 25 }
  }
})

local search = app.integrations.xata.search_branch({
  database = "app",
  branch = "main",
  body = {
    query = "ada",
    tables = { { table = "contacts" } }
  }
})
```

Additional tools:

- `aggregate_table({ database, branch, table, body })`
- `vector_search({ database, branch, table, body })`
- `transaction({ database, branch, body })`

Responses are the normalized JSON returned by Xata.
Metadata-derived Lua example 
local result = app.integrations.xata.list_databases({})
print(result)

Functions

list_databases Read

List databases in a Xata workspace.

Lua path
app.integrations.xata.list_databases
Full name
xata.xata_list_databases
ParameterTypeRequiredDescription
No parameters.
create_database Write

Create a Xata database in a workspace.

Lua path
app.integrations.xata.create_database
Full name
xata.xata_create_database
ParameterTypeRequiredDescription
No parameters.
list_branches Read

List branches for a Xata database.

Lua path
app.integrations.xata.list_branches
Full name
xata.xata_list_branches
ParameterTypeRequiredDescription
No parameters.
create_branch Write

Create a branch for a Xata database.

Lua path
app.integrations.xata.create_branch
Full name
xata.xata_create_branch
ParameterTypeRequiredDescription
No parameters.
get_schema Read

Read schema for a database branch.

Lua path
app.integrations.xata.get_schema
Full name
xata.xata_get_schema
ParameterTypeRequiredDescription
No parameters.
update_schema Write

Update schema for a database branch.

Lua path
app.integrations.xata.update_schema
Full name
xata.xata_update_schema
ParameterTypeRequiredDescription
No parameters.
query_table Read

Query records from a table.

Lua path
app.integrations.xata.query_table
Full name
xata.xata_query_table
ParameterTypeRequiredDescription
No parameters.
search_branch Read

Search records across a branch.

Lua path
app.integrations.xata.search_branch
Full name
xata.xata_search_branch
ParameterTypeRequiredDescription
No parameters.
get_record Read

Get one record by table and id.

Lua path
app.integrations.xata.get_record
Full name
xata.xata_get_record
ParameterTypeRequiredDescription
No parameters.
insert_record Write

Insert a record into a table.

Lua path
app.integrations.xata.insert_record
Full name
xata.xata_insert_record
ParameterTypeRequiredDescription
No parameters.
update_record Write

Patch a record by table and id.

Lua path
app.integrations.xata.update_record
Full name
xata.xata_update_record
ParameterTypeRequiredDescription
No parameters.
delete_record Write

Delete a record by table and id.

Lua path
app.integrations.xata.delete_record
Full name
xata.xata_delete_record
ParameterTypeRequiredDescription
No parameters.
aggregate_table Read

Run table aggregation queries.

Lua path
app.integrations.xata.aggregate_table
Full name
xata.xata_aggregate_table
ParameterTypeRequiredDescription
No parameters.
transaction Write

Execute a branch transaction.

Lua path
app.integrations.xata.transaction
Full name
xata.xata_transaction
ParameterTypeRequiredDescription
No parameters.