KosmoKrator

productivity

Airtable Lua API for KosmoKrator Agents

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

Lua Namespace

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

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

Workflow file

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

workflow.lua 
local airtable = app.integrations.airtable
local result = airtable.api_get({})

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

MCP-only Lua

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

Airtable Integration

Namespace: app.integrations.airtable

Use this integration to read and write Airtable bases through the Web API. Configure an Airtable Personal Access Token or OAuth access token with the scopes required for the target base, records, schema, comments, or webhooks.

Common Workflows

List Records

local result = app.integrations.airtable.list_records({
  base_id = "appXXXXXXXXXXXX",
  table = "Contacts",
  view = "Active",
  pageSize = 100
})

The response contains records and may contain an offset. Pass the offset into the next call to continue pagination.

Create or Update Records

local created = app.integrations.airtable.create_record({
  base_id = "appXXXXXXXXXXXX",
  table = "Contacts",
  fields = {
    Name = "Ada Lovelace",
    Email = "ada@example.test"
  }
})

local updated = app.integrations.airtable.update_record({
  base_id = "appXXXXXXXXXXXX",
  table = "Contacts",
  record_id = "recXXXXXXXXXXXX",
  fields = {
    Status = "Active"
  }
})

For bulk writes, use create_records, update_records, or upsert_records with the Airtable records payload shape. Airtable limits record batch operations to small batches, so split large syncs before calling the tool.

Inspect Schema

local schema = app.integrations.airtable.get_base_schema({
  base_id = "appXXXXXXXXXXXX"
})

Schema metadata includes tables, fields, and views. Use table IDs and field IDs when changing schema with create_table, update_table, create_field, and update_field.

Comments

local comment = app.integrations.airtable.create_comment({
  base_id = "appXXXXXXXXXXXX",
  table = "Contacts",
  record_id = "recXXXXXXXXXXXX",
  text = "Follow up next week."
})

The comment tools operate on a specific record: list_comments, create_comment, update_comment, and delete_comment.

Webhooks

local webhook = app.integrations.airtable.create_webhook({
  base_id = "appXXXXXXXXXXXX",
  payload = {
    notificationUrl = "https://example.test/airtable",
    specification = {
      options = {
        filters = {
          dataTypes = { "tableData" }
        }
      }
    }
  }
})

Use list_webhook_payloads to fetch payloads for a webhook. Airtable webhook payload delivery and retention have their own limits, so persist cursors and process payloads promptly.

Coverage Notes

Focused tools cover authenticated user lookup, base listing, base schema metadata, table and field schema writes, record CRUD and bulk/upsert operations, record comments, base webhooks, webhook payloads, and raw api_get, api_post, api_patch, and api_delete escape hatches.

Airtable uses exact query parameter names such as filterByFormula, maxRecords, and pageSize. Use the query object for array-style parameters such as fields[], sort[], or records[] when a focused parameter is not listed.

Raw agent markdown 
# Airtable Integration

Namespace: `app.integrations.airtable`

Use this integration to read and write Airtable bases through the Web API. Configure an Airtable Personal Access Token or OAuth access token with the scopes required for the target base, records, schema, comments, or webhooks.

## Common Workflows

### List Records

```lua
local result = app.integrations.airtable.list_records({
  base_id = "appXXXXXXXXXXXX",
  table = "Contacts",
  view = "Active",
  pageSize = 100
})
```

The response contains `records` and may contain an `offset`. Pass the `offset` into the next call to continue pagination.

### Create or Update Records

```lua
local created = app.integrations.airtable.create_record({
  base_id = "appXXXXXXXXXXXX",
  table = "Contacts",
  fields = {
    Name = "Ada Lovelace",
    Email = "ada@example.test"
  }
})

local updated = app.integrations.airtable.update_record({
  base_id = "appXXXXXXXXXXXX",
  table = "Contacts",
  record_id = "recXXXXXXXXXXXX",
  fields = {
    Status = "Active"
  }
})
```

For bulk writes, use `create_records`, `update_records`, or `upsert_records` with the Airtable `records` payload shape. Airtable limits record batch operations to small batches, so split large syncs before calling the tool.

### Inspect Schema

```lua
local schema = app.integrations.airtable.get_base_schema({
  base_id = "appXXXXXXXXXXXX"
})
```

Schema metadata includes tables, fields, and views. Use table IDs and field IDs when changing schema with `create_table`, `update_table`, `create_field`, and `update_field`.

### Comments

```lua
local comment = app.integrations.airtable.create_comment({
  base_id = "appXXXXXXXXXXXX",
  table = "Contacts",
  record_id = "recXXXXXXXXXXXX",
  text = "Follow up next week."
})
```

The comment tools operate on a specific record: `list_comments`, `create_comment`, `update_comment`, and `delete_comment`.

### Webhooks

```lua
local webhook = app.integrations.airtable.create_webhook({
  base_id = "appXXXXXXXXXXXX",
  payload = {
    notificationUrl = "https://example.test/airtable",
    specification = {
      options = {
        filters = {
          dataTypes = { "tableData" }
        }
      }
    }
  }
})
```

Use `list_webhook_payloads` to fetch payloads for a webhook. Airtable webhook payload delivery and retention have their own limits, so persist cursors and process payloads promptly.

## Coverage Notes

Focused tools cover authenticated user lookup, base listing, base schema metadata, table and field schema writes, record CRUD and bulk/upsert operations, record comments, base webhooks, webhook payloads, and raw `api_get`, `api_post`, `api_patch`, and `api_delete` escape hatches.

Airtable uses exact query parameter names such as `filterByFormula`, `maxRecords`, and `pageSize`. Use the `query` object for array-style parameters such as `fields[]`, `sort[]`, or `records[]` when a focused parameter is not listed.
Metadata-derived Lua example 
local result = app.integrations.airtable.api_get({})
print(result)

Functions

api_get Read

Call any Airtable Web API GET endpoint with query parameters.

Lua path
app.integrations.airtable.api_get
Full name
airtable.airtable_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call any Airtable Web API POST endpoint with a JSON payload.

Lua path
app.integrations.airtable.api_post
Full name
airtable.airtable_api_post
ParameterTypeRequiredDescription
No parameters.
api_patch Write

Call any Airtable Web API PATCH endpoint with a JSON payload.

Lua path
app.integrations.airtable.api_patch
Full name
airtable.airtable_api_patch
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call any Airtable Web API DELETE endpoint with query parameters.

Lua path
app.integrations.airtable.api_delete
Full name
airtable.airtable_api_delete
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Get the currently authenticated Airtable user.

Lua path
app.integrations.airtable.get_current_user
Full name
airtable.airtable_get_current_user
ParameterTypeRequiredDescription
No parameters.
list_bases Read

List Airtable bases accessible to the token.

Lua path
app.integrations.airtable.list_bases
Full name
airtable.airtable_list_bases
ParameterTypeRequiredDescription
No parameters.
get_base_schema Read

Get table, field, and view schema metadata for a base.

Lua path
app.integrations.airtable.get_base_schema
Full name
airtable.airtable_get_base_schema
ParameterTypeRequiredDescription
No parameters.
create Write

Create a table in an Airtable base.

Lua path
app.integrations.airtable.create
Full name
airtable.airtable_create_table
ParameterTypeRequiredDescription
No parameters.
update Write

Update table metadata in an Airtable base.

Lua path
app.integrations.airtable.update
Full name
airtable.airtable_update_table
ParameterTypeRequiredDescription
No parameters.
create_field Write

Create a field in an Airtable table.

Lua path
app.integrations.airtable.create_field
Full name
airtable.airtable_create_field
ParameterTypeRequiredDescription
No parameters.
update_field Write

Update field metadata in an Airtable table.

Lua path
app.integrations.airtable.update_field
Full name
airtable.airtable_update_field
ParameterTypeRequiredDescription
No parameters.
list_views Read

List views by reading Airtable base schema metadata.

Lua path
app.integrations.airtable.list_views
Full name
airtable.airtable_list_views
ParameterTypeRequiredDescription
No parameters.
list_records Read

List records from an Airtable table.

Lua path
app.integrations.airtable.list_records
Full name
airtable.airtable_list_records
ParameterTypeRequiredDescription
No parameters.
get_record Read

Get a single Airtable record.

Lua path
app.integrations.airtable.get_record
Full name
airtable.airtable_get_record
ParameterTypeRequiredDescription
No parameters.
create_record Write

Create one Airtable record.

Lua path
app.integrations.airtable.create_record
Full name
airtable.airtable_create_record
ParameterTypeRequiredDescription
No parameters.
create_records Write

Create multiple Airtable records in one request.

Lua path
app.integrations.airtable.create_records
Full name
airtable.airtable_create_records
ParameterTypeRequiredDescription
No parameters.
update_record Write

Update one Airtable record.

Lua path
app.integrations.airtable.update_record
Full name
airtable.airtable_update_record
ParameterTypeRequiredDescription
No parameters.
update_records Write

Update multiple Airtable records in one request.

Lua path
app.integrations.airtable.update_records
Full name
airtable.airtable_update_records
ParameterTypeRequiredDescription
No parameters.
upsert_records Write

Create or update records using Airtable performUpsert.

Lua path
app.integrations.airtable.upsert_records
Full name
airtable.airtable_upsert_records
ParameterTypeRequiredDescription
No parameters.
delete_record Write

Delete one Airtable record.

Lua path
app.integrations.airtable.delete_record
Full name
airtable.airtable_delete_record
ParameterTypeRequiredDescription
No parameters.
delete_records Write

Delete multiple Airtable records using records[] query parameters.

Lua path
app.integrations.airtable.delete_records
Full name
airtable.airtable_delete_records
ParameterTypeRequiredDescription
No parameters.
list_comments Read

List comments for an Airtable record.

Lua path
app.integrations.airtable.list_comments
Full name
airtable.airtable_list_comments
ParameterTypeRequiredDescription
No parameters.
create_comment Write

Create a comment on an Airtable record.

Lua path
app.integrations.airtable.create_comment
Full name
airtable.airtable_create_comment
ParameterTypeRequiredDescription
No parameters.
update_comment Write

Update a comment on an Airtable record.

Lua path
app.integrations.airtable.update_comment
Full name
airtable.airtable_update_comment
ParameterTypeRequiredDescription
No parameters.
delete_comment Write

Delete a comment from an Airtable record.

Lua path
app.integrations.airtable.delete_comment
Full name
airtable.airtable_delete_comment
ParameterTypeRequiredDescription
No parameters.
list_webhooks Read

List Airtable webhooks for a base.

Lua path
app.integrations.airtable.list_webhooks
Full name
airtable.airtable_list_webhooks
ParameterTypeRequiredDescription
No parameters.
create_webhook Write

Create an Airtable webhook for a base.

Lua path
app.integrations.airtable.create_webhook
Full name
airtable.airtable_create_webhook
ParameterTypeRequiredDescription
No parameters.
delete_webhook Write

Delete an Airtable webhook.

Lua path
app.integrations.airtable.delete_webhook
Full name
airtable.airtable_delete_webhook
ParameterTypeRequiredDescription
No parameters.
list_webhook_payloads Read

List webhook payloads for an Airtable webhook.

Lua path
app.integrations.airtable.list_webhook_payloads
Full name
airtable.airtable_list_webhook_payloads
ParameterTypeRequiredDescription
No parameters.