KosmoKrator

productivity

NocoDB Lua API for KosmoKrator Agents

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

Lua Namespace

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

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.nocodb.list_records({table_id = "example_table_id", view_id = "example_view_id", limit = 1, offset = 1, where = "example_where", sort = "example_sort", fields = "example_fields"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("nocodb"))' --json
kosmo integrations:lua --eval 'print(docs.read("nocodb.list_records"))' --json

Workflow file

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

workflow.lua 
local nocodb = app.integrations.nocodb
local result = nocodb.list_records({table_id = "example_table_id", view_id = "example_view_id", limit = 1, offset = 1, where = "example_where", sort = "example_sort", fields = "example_fields"})

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

MCP-only Lua

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

NocoDB — Lua API Reference

nocodb_list_records

List records from a NocoDB table with optional filtering, sorting, and pagination.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
view_idstringnoView ID to filter records by the view’s filters.
limitintegernoMaximum number of records to return (default 25).
offsetintegernoPagination offset for skipping records.
wherestringnoNocoDB where clause for filtering (e.g., "(Status,eq,Done)").
sortstringnoJSON array of sort objects, e.g. [{"field":"Name","direction":"asc"}].
fieldsstringnoComma-separated list of field names to return.

nocodb_get_record

Get a single NocoDB record by ID.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
record_idstringyesRecord ID.
fieldsstringnoComma-separated list of field names to return.

nocodb_create_record

Create a new record in a NocoDB table.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
datastringyesJSON object of field name → value pairs (e.g., {"Name":"John","Age":30}).

nocodb_update_record

Update an existing NocoDB record.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
record_idstringyesRecord ID.
datastringyesJSON object of field name → value pairs to update (e.g., {"Status":"Done"}).

nocodb_delete_record

Delete a record from a NocoDB table.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
record_idstringyesRecord ID.

nocodb_batch_create

Create multiple records in a single NocoDB API request.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
recordsstringyesJSON array of record objects (e.g., [{"Name":"Alice"},{"Name":"Bob"}]).

nocodb_batch_update

Update multiple records in a single NocoDB API request.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
recordsstringyesJSON array of record objects, each with an "Id" key and fields to update (e.g., [{"Id":1,"Name":"Updated"}]).

nocodb_batch_delete

Delete multiple records in a single NocoDB API request.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
record_idsstringyesJSON array of record IDs to delete (e.g., [1, 2, 3]).

nocodb_list_bases

List all NocoDB bases the token has access to.

Parameters

No parameters required.

nocodb_get_base

Get details of a single NocoDB base.

Parameters

NameTypeRequiredDescription
base_idstringyesBase ID.

nocodb_list_tables

List all tables in a NocoDB base.

Parameters

NameTypeRequiredDescription
base_idstringyesBase ID.

nocodb_get_table

Get details of a single NocoDB table.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.

nocodb_create_table

Create a new table in a NocoDB base.

Parameters

NameTypeRequiredDescription
base_idstringyesBase ID.
table_namestringyesName for the new table.
columnsstringyesJSON array of column definitions (e.g., [{"column_name":"Name","uidt":"SingleLineText"},{"column_name":"Age","uidt":"Number"}]).

nocodb_list_views

List views for a NocoDB table.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.

nocodb_count_records

Count records in a NocoDB table with optional filtering.

Parameters

NameTypeRequiredDescription
table_idstringyesTable ID.
wherestringnoNocoDB where clause for filtering (e.g., "(Status,eq,Done)").

Examples

List records with filtering

local result = app.integrations.nocodb.nocodb_list_records({
  table_id = "tbxyz123",
  where = "(Status,eq,Active)",
  sort = '[{"field":"Name","direction":"asc"}]',
  limit = 10
})
for _, record in ipairs(result.records) do
  print(record.Name .. " - " .. record.Status)
end

Create a record

local result = app.integrations.nocodb.nocodb_create_record({
  table_id = "tbxyz123",
  data = '{"Name":"John","Email":"john@example.com","Status":"Active"}'
})
print("Created record ID: " .. result.Id)

Batch create records

local result = app.integrations.nocodb.nocodb_batch_create({
  table_id = "tbxyz123",
  records = '[{"Name":"Alice"},{"Name":"Bob"},{"Name":"Charlie"}]'
})

Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.nocodb.work.function_name({...})
app.integrations.nocodb.personal.function_name({...})

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

Raw agent markdown 
# NocoDB — Lua API Reference

## nocodb_list_records

List records from a NocoDB table with optional filtering, sorting, and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |
| `view_id` | string | no | View ID to filter records by the view's filters. |
| `limit` | integer | no | Maximum number of records to return (default 25). |
| `offset` | integer | no | Pagination offset for skipping records. |
| `where` | string | no | NocoDB where clause for filtering (e.g., `"(Status,eq,Done)"`). |
| `sort` | string | no | JSON array of sort objects, e.g. `[{"field":"Name","direction":"asc"}]`. |
| `fields` | string | no | Comma-separated list of field names to return. |

## nocodb_get_record

Get a single NocoDB record by ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |
| `record_id` | string | yes | Record ID. |
| `fields` | string | no | Comma-separated list of field names to return. |

## nocodb_create_record

Create a new record in a NocoDB table.

### Parameters

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

## nocodb_update_record

Update an existing NocoDB record.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |
| `record_id` | string | yes | Record ID. |
| `data` | string | yes | JSON object of field name → value pairs to update (e.g., `{"Status":"Done"}`). |

## nocodb_delete_record

Delete a record from a NocoDB table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |
| `record_id` | string | yes | Record ID. |

## nocodb_batch_create

Create multiple records in a single NocoDB API request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |
| `records` | string | yes | JSON array of record objects (e.g., `[{"Name":"Alice"},{"Name":"Bob"}]`). |

## nocodb_batch_update

Update multiple records in a single NocoDB API request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |
| `records` | string | yes | JSON array of record objects, each with an `"Id"` key and fields to update (e.g., `[{"Id":1,"Name":"Updated"}]`). |

## nocodb_batch_delete

Delete multiple records in a single NocoDB API request.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |
| `record_ids` | string | yes | JSON array of record IDs to delete (e.g., `[1, 2, 3]`). |

## nocodb_list_bases

List all NocoDB bases the token has access to.

### Parameters

*No parameters required.*

## nocodb_get_base

Get details of a single NocoDB base.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `base_id` | string | yes | Base ID. |

## nocodb_list_tables

List all tables in a NocoDB base.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `base_id` | string | yes | Base ID. |

## nocodb_get_table

Get details of a single NocoDB table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |

## nocodb_create_table

Create a new table in a NocoDB base.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `base_id` | string | yes | Base ID. |
| `table_name` | string | yes | Name for the new table. |
| `columns` | string | yes | JSON array of column definitions (e.g., `[{"column_name":"Name","uidt":"SingleLineText"},{"column_name":"Age","uidt":"Number"}]`). |

## nocodb_list_views

List views for a NocoDB table.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |

## nocodb_count_records

Count records in a NocoDB table with optional filtering.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `table_id` | string | yes | Table ID. |
| `where` | string | no | NocoDB where clause for filtering (e.g., `"(Status,eq,Done)"`). |

## Examples

### List records with filtering

```lua
local result = app.integrations.nocodb.nocodb_list_records({
  table_id = "tbxyz123",
  where = "(Status,eq,Active)",
  sort = '[{"field":"Name","direction":"asc"}]',
  limit = 10
})
for _, record in ipairs(result.records) do
  print(record.Name .. " - " .. record.Status)
end
```

### Create a record

```lua
local result = app.integrations.nocodb.nocodb_create_record({
  table_id = "tbxyz123",
  data = '{"Name":"John","Email":"john@example.com","Status":"Active"}'
})
print("Created record ID: " .. result.Id)
```

### Batch create records

```lua
local result = app.integrations.nocodb.nocodb_batch_create({
  table_id = "tbxyz123",
  records = '[{"Name":"Alice"},{"Name":"Bob"},{"Name":"Charlie"}]'
})
```

---

## Multi-Account Usage

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

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

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

-- Named accounts
app.integrations.nocodb.work.function_name({...})
app.integrations.nocodb.personal.function_name({...})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.nocodb.list_records({table_id = "example_table_id", view_id = "example_view_id", limit = 1, offset = 1, where = "example_where", sort = "example_sort", fields = "example_fields"})
print(result)

Functions

list_records Read

List records from a NocoDB table with optional filtering, sorting, and pagination.

Lua path
app.integrations.nocodb.list_records
Full name
nocodb.nocodb_list_records
ParameterTypeRequiredDescription
table_id string yes Table ID.
view_id string no View ID to filter records by the view's filters.
limit integer no Maximum number of records to return (default 25).
offset integer no Pagination offset for skipping records.
where string no NocoDB where clause for filtering (e.g., "(Status,eq,Done)").
sort string no JSON array of sort objects, e.g. [{"field":"Name","direction":"asc"}].
fields string no Comma-separated list of field names to return.
get_record Read

Get a single NocoDB record by ID.

Lua path
app.integrations.nocodb.get_record
Full name
nocodb.nocodb_get_record
ParameterTypeRequiredDescription
table_id string yes Table ID.
record_id string yes Record ID.
fields string no Comma-separated list of field names to return.
create_record Write

Create a new record in a NocoDB table.

Lua path
app.integrations.nocodb.create_record
Full name
nocodb.nocodb_create_record
ParameterTypeRequiredDescription
table_id string yes Table ID.
data string yes JSON object of field name → value pairs (e.g., {"Name":"John","Age":30}).
update_record Write

Update an existing NocoDB record.

Lua path
app.integrations.nocodb.update_record
Full name
nocodb.nocodb_update_record
ParameterTypeRequiredDescription
table_id string yes Table ID.
record_id string yes Record ID.
data string yes JSON object of field name → value pairs to update (e.g., {"Status":"Done"}).
delete_record Write

Delete a record from a NocoDB table.

Lua path
app.integrations.nocodb.delete_record
Full name
nocodb.nocodb_delete_record
ParameterTypeRequiredDescription
table_id string yes Table ID.
record_id string yes Record ID.
batch_create_records Write

Create multiple records in a single NocoDB API request.

Lua path
app.integrations.nocodb.batch_create_records
Full name
nocodb.nocodb_batch_create
ParameterTypeRequiredDescription
table_id string yes Table ID.
records string yes JSON array of record objects (e.g., [{"Name":"Alice"},{"Name":"Bob"}]).
batch_update_records Write

Update multiple records in a single NocoDB API request.

Lua path
app.integrations.nocodb.batch_update_records
Full name
nocodb.nocodb_batch_update
ParameterTypeRequiredDescription
table_id string yes Table ID.
records string yes JSON array of record objects, each with an "Id" key and fields to update (e.g., [{"Id":1,"Name":"Updated"}]).
batch_delete_records Write

Delete multiple records in a single NocoDB API request.

Lua path
app.integrations.nocodb.batch_delete_records
Full name
nocodb.nocodb_batch_delete
ParameterTypeRequiredDescription
table_id string yes Table ID.
record_ids string yes JSON array of record IDs to delete (e.g., [1, 2, 3]).
list_bases Read

List all NocoDB bases the token has access to.

Lua path
app.integrations.nocodb.list_bases
Full name
nocodb.nocodb_list_bases
ParameterTypeRequiredDescription
No parameters.
get_base Read

Get details of a single NocoDB base.

Lua path
app.integrations.nocodb.get_base
Full name
nocodb.nocodb_get_base
ParameterTypeRequiredDescription
base_id string yes Base ID.
list_tables Read

List all tables in a NocoDB base.

Lua path
app.integrations.nocodb.list_tables
Full name
nocodb.nocodb_list_tables
ParameterTypeRequiredDescription
base_id string yes Base ID.
get_table Read

Get details of a single NocoDB table.

Lua path
app.integrations.nocodb.get_table
Full name
nocodb.nocodb_get_table
ParameterTypeRequiredDescription
table_id string yes Table ID.
create_table Write

Create a new table in a NocoDB base.

Lua path
app.integrations.nocodb.create_table
Full name
nocodb.nocodb_create_table
ParameterTypeRequiredDescription
base_id string yes Base ID.
table_name string yes Name for the new table.
columns string yes JSON array of column definitions (e.g., [{"column_name":"Name","uidt":"SingleLineText"},{"column_name":"Age","uidt":"Number"}]).
list_views Read

List views for a NocoDB table.

Lua path
app.integrations.nocodb.list_views
Full name
nocodb.nocodb_list_views
ParameterTypeRequiredDescription
table_id string yes Table ID.
count_records Read

Count records in a NocoDB table with optional filtering.

Lua path
app.integrations.nocodb.count_records
Full name
nocodb.nocodb_count_records
ParameterTypeRequiredDescription
table_id string yes Table ID.
where string no NocoDB where clause for filtering (e.g., "(Status,eq,Done)").