KosmoKrator

data

Convex Lua API for KosmoKrator Agents

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

7 functions 4 read 3 write Bearer token auth
Submit Convex feedback View package source

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.

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": "[email protected]"}'
})

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": "[email protected]"}'
})
```

## 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.convex_list_tables({})
print(result)

Functions

convex_list_tables

List all tables in the Convex deployment.

Operation
Read read
Full name
convex.convex_list_tables
ParameterTypeRequiredDescription
No parameters.

convex_get_table

Get metadata and schema for a specific Convex table.

Operation
Read read
Full name
convex.convex_get_table
ParameterTypeRequiredDescription
table string yes Table name or ID.

convex_query_documents

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

Operation
Read read
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.

convex_create_document

Create a new document in a Convex table.

Operation
Write write
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}).

convex_update_document

Update an existing document in a Convex table.

Operation
Write write
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.

convex_delete_document

Delete a document from a Convex table.

Operation
Write write
Full name
convex.convex_delete_document
ParameterTypeRequiredDescription
table string yes Table name.
document_id string yes Document ID.

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.

Operation
Read read
Full name
convex.convex_get_current_user
ParameterTypeRequiredDescription
No parameters.