KosmoKrator

data

Convex Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local convex = app.integrations.convex
local result = convex.list_tables({})

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

MCP-only Lua

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

Client for the Convex REST API — Lua API Reference

convex_list_tables

List all tables in the Convex deployment.

Example

local result = app.integrations.convex.convex_list_tables({
})

convex_get_table

Get metadata and schema for a specific Convex table.

Parameters

NameTypeRequiredDescription
tablestringyesTable name or ID.

Example

local result = app.integrations.convex.convex_get_table({
  table = "users"
})

convex_query_documents

Query documents from a Convex table with optional filtering and pagination.

Parameters

NameTypeRequiredDescription
tablestringyesTable name.
filterstringnoJSON object of field name → value pairs to filter documents by.
orderstringnoField name to order results by. Prefix with ”-” for descending (e.g., “-createdAt”).
limitintegernoMaximum number of documents to return.
cursorstringnoPagination cursor from a previous response.

Example

local result = app.integrations.convex.convex_query_documents({
  table = "users"
  filter = '{"status": "active"}'
  limit = 50
})

convex_create_document

Create a new document in a Convex table.

Parameters

NameTypeRequiredDescription
tablestringyesTable name.
fieldsstringyesJSON object of field name → value pairs (e.g., {“name”:“John”,“age”:30}).

Example

local result = app.integrations.convex.convex_create_document({
  table = "users"
  fields = '{"name": "John", "email": "john@example.com"}'
})

convex_update_document

Update an existing document in a Convex table.

Parameters

NameTypeRequiredDescription
tablestringyesTable name.
document_idstringyesDocument ID.
fieldsstringyesJSON object of field name → value pairs to update.

Example

local result = app.integrations.convex.convex_update_document({
  table = "users"
  document_id = "doc_abc123"
  fields = '{"name": "Jane"}'
})

convex_delete_document

Delete a document from a Convex table.

Parameters

NameTypeRequiredDescription
tablestringyesTable name.
document_idstringyesDocument ID.

Example

local result = app.integrations.convex.convex_delete_document({
  table = "users"
  document_id = "doc_abc123"
})

convex_get_current_user

Get the authenticated Convex user’s profile information. Returns account details like name and email. Use this to verify API connectivity.

Example

local result = app.integrations.convex.convex_get_current_user({
})

Multi-Account Usage

If you have multiple convex accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.convex.function_name({...})

-- Explicit default (portable across setups)
app.integrations.convex.default.function_name({...})

-- Named accounts
app.integrations.convex.staging.function_name({...})
app.integrations.convex.production.function_name({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Client for the Convex REST API — Lua API Reference

## convex_list_tables

List all tables in the Convex deployment.

### Example

```lua
local result = app.integrations.convex.convex_list_tables({
})
```

## convex_get_table

Get metadata and schema for a specific Convex table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table` | string | yes | Table name or ID. |

### Example

```lua
local result = app.integrations.convex.convex_get_table({
  table = "users"
})
```

## convex_query_documents

Query documents from a Convex table with optional filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table` | string | yes | Table name. |
| `filter` | string | no | JSON object of field name → value pairs to filter documents by. |
| `order` | string | no | Field name to order results by. Prefix with "-" for descending (e.g., "-createdAt"). |
| `limit` | integer | no | Maximum number of documents to return. |
| `cursor` | string | no | Pagination cursor from a previous response. |

### Example

```lua
local result = app.integrations.convex.convex_query_documents({
  table = "users"
  filter = '{"status": "active"}'
  limit = 50
})
```

## convex_create_document

Create a new document in a Convex table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table` | string | yes | Table name. |
| `fields` | string | yes | JSON object of field name → value pairs (e.g., {"name":"John","age":30}). |

### Example

```lua
local result = app.integrations.convex.convex_create_document({
  table = "users"
  fields = '{"name": "John", "email": "john@example.com"}'
})
```

## convex_update_document

Update an existing document in a Convex table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table` | string | yes | Table name. |
| `document_id` | string | yes | Document ID. |
| `fields` | string | yes | JSON object of field name → value pairs to update. |

### Example

```lua
local result = app.integrations.convex.convex_update_document({
  table = "users"
  document_id = "doc_abc123"
  fields = '{"name": "Jane"}'
})
```

## convex_delete_document

Delete a document from a Convex table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table` | string | yes | Table name. |
| `document_id` | string | yes | Document ID. |

### Example

```lua
local result = app.integrations.convex.convex_delete_document({
  table = "users"
  document_id = "doc_abc123"
})
```

## convex_get_current_user

Get the authenticated Convex user's profile information. Returns account details like name and email. Use this to verify API connectivity.

### Example

```lua
local result = app.integrations.convex.convex_get_current_user({
})
```

---

## Multi-Account Usage

If you have multiple convex accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.convex.function_name({...})

-- Explicit default (portable across setups)
app.integrations.convex.default.function_name({...})

-- Named accounts
app.integrations.convex.staging.function_name({...})
app.integrations.convex.production.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.convex.list_tables({})
print(result)

Functions

list_tables Read

List all tables in the Convex deployment.

Lua path
app.integrations.convex.list_tables
Full name
convex.convex_list_tables
ParameterTypeRequiredDescription
No parameters.
get_table Read

Get metadata and schema for a specific Convex table.

Lua path
app.integrations.convex.get_table
Full name
convex.convex_get_table
ParameterTypeRequiredDescription
table string yes Table name or ID.
query_documents Read

Query documents from a Convex table with optional filtering and pagination.

Lua path
app.integrations.convex.query_documents
Full name
convex.convex_query_documents
ParameterTypeRequiredDescription
table string yes Table name.
filter string no JSON object of field name → value pairs to filter documents by.
order string no Field name to order results by. Prefix with "-" for descending (e.g., "-createdAt").
limit integer no Maximum number of documents to return.
cursor string no Pagination cursor from a previous response.
create_document Write

Create a new document in a Convex table.

Lua path
app.integrations.convex.create_document
Full name
convex.convex_create_document
ParameterTypeRequiredDescription
table string yes Table name.
fields string yes JSON object of field name → value pairs (e.g., {"name":"John","age":30}).
update_document Write

Update an existing document in a Convex table.

Lua path
app.integrations.convex.update_document
Full name
convex.convex_update_document
ParameterTypeRequiredDescription
table string yes Table name.
document_id string yes Document ID.
fields string yes JSON object of field name → value pairs to update.
delete_document Write

Delete a document from a Convex table.

Lua path
app.integrations.convex.delete_document
Full name
convex.convex_delete_document
ParameterTypeRequiredDescription
table string yes Table name.
document_id string yes Document ID.
get_current_user Read

Get the authenticated Convex user's profile information. Returns account details like name and email. Use this to verify API connectivity.

Lua path
app.integrations.convex.get_current_user
Full name
convex.convex_get_current_user
ParameterTypeRequiredDescription
No parameters.