Airlua

Airtable API client for Lua

Features

• We aim to support all Airtable API features natively
• Built in protection against Airtable injections
• Support for modifying/getting records using field values, not just record IDs

Installation

Airlua requires Astra, a modern lua runtime with built in support for HTTP requests, and many other useful functions. Astra allows Airlua to be 100% written in Lua.

Once you have Astra installed, simply download airtable.lua and add it to your project folder, or run:

luarocks install airtable-lua

Note: for installation with luarocks, use "airtable-lua" instead of airtable for imports

Also, make sure to set AIRTABLE_API_KEY in your .env

Progress

Type	Percent	Completed
Records	100%	All routes supported
Tables	100%	All routes supported
Fields	100%	All routes supported
Comments	100%	All routes supported
Bases	100%	All routes supported

Docs

Records

airtable.list(base_id, table_name, view, params)

Lists records from a table.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• view (string, optional) - The name of a view to filter by
• params (table, optional) - Additional parameters (e.g., filterByFormula, maxRecords, sort)

Returns: Table containing records array, or nil and error message

local records, err = airtable.list("appXXXXXXXXXX", "Tasks", "Grid view", {maxRecords = 10})

---

airtable.get(base_id, table_name, record_id)

Retrieves a single record by its ID.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• record_id (string) - The ID of the record to retrieve

Returns: Record object, or nil and error message

local record, err = airtable.get("appXXXXXXXXXX", "Tasks", "recXXXXXXXXXX")

---

airtable.getByField(base_id, table_name, field, value)

Retrieves the first record matching a field value.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• field (string) - The field name to search by
• value (string) - The value to match

Returns: First matching record, or nil/error message

local record = airtable.getByField("appXXXXXXXXXX", "Users", "Email", "user@example.com")

---

airtable.create(base_id, table_name, fields)

Creates a new record in the table.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• fields (table, optional) - The field values for the new record

Returns: Created record object, or nil and error message

local record, err = airtable.create("appXXXXXXXXXX", "Tasks", {Name = "New Task", Status = "Todo"})

---

airtable.update(base_id, table_name, record_id, fields)

Updates an existing record by its ID.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• record_id (string) - The ID of the record to update
• fields (table) - The field values to update

Returns: Updated record object, or nil and error message

local record, err = airtable.update("appXXXXXXXXXX", "Tasks", "recXXXXXXXXXX", {Status = "Done"})

---

airtable.updateByField(base_id, table_name, field, value, updatedFields)

Updates the first record matching a field value.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• field (string) - The field name to search by
• value (string) - The value to match
• updatedFields (table) - The field values to update

Returns: Updated record object, or nil and error message

local record, err = airtable.updateByField("appXXXXXXXXXX", "Users", "Email", "user@example.com", {Name = "Updated Name"})

---

airtable.delete(base_id, table_name, record_id)

Deletes a record by its ID.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• record_id (string) - The ID of the record to delete

Returns: Deletion confirmation object, or nil and error message

local result, err = airtable.delete("appXXXXXXXXXX", "Tasks", "recXXXXXXXXXX")

---

Bulk Records

airtable.createBulk(base_id, table_name, recordsArray)

Creates multiple records in a single request (max 10 per request).

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• recordsArray (table) - Array of field tables for each record

Returns: Table containing records array with created records, or nil and error message

local result, err = airtable.createBulk("appXXXXXXXXXX", "Tasks", {
    {Name = "Task 1", Status = "Todo"},
    {Name = "Task 2", Status = "In Progress"},
    {Name = "Task 3", Status = "Done"}
})

---

airtable.updateBulk(base_id, table_name, recordsArray)

Updates multiple records in a single request (max 10 per request).

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• recordsArray (table) - Array of tables, each with id and fields properties

Returns: Table containing records array with updated records, or nil and error message

local result, err = airtable.updateBulk("appXXXXXXXXXX", "Tasks", {
    {id = "recXXXXXXXXX1", fields = {Status = "Done"}},
    {id = "recXXXXXXXXX2", fields = {Status = "Done"}},
})

---

airtable.deleteBulk(base_id, table_name, recordIds)

Deletes multiple records in a single request (max 10 per request).

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• recordIds (table) - Array of record IDs to delete

Returns: Table containing records array with deletion confirmations, or nil and error message

local result, err = airtable.deleteBulk("appXXXXXXXXXX", "Tasks", {
    "recXXXXXXXXX1",
    "recXXXXXXXXX2",
    "recXXXXXXXXX3"
})

---

Tables

airtable.createTable(base_id, name, fields, description)

Creates a new table in a base.

Parameters:

• base_id (string) - The ID of the Airtable base
• name (string) - The name of the table
• fields (table) - Array of field configurations (at least one required). The first field becomes the primary field.
• description (string, optional) - Table description (max 20,000 characters)

Returns: Created table object, or nil and error message

local newTable, err = airtable.createTable("appXXXXXXXXXX", "My Table", {
    {name = "Name", type = "singleLineText"},
    {name = "Notes", type = "multilineText"},
    {name = "Status", type = "singleSelect", options = {choices = {{name = "Todo"}, {name = "Done"}}}}
}, "Optional description")

---

airtable.updateTable(base_id, table_id, options)

Updates an existing table's name, description, or date dependency settings.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_id (string) - The ID or name of the table
• options (table) - Table options to update:
  • name (string, optional) - The new name of the table
  • description (string, optional) - New table description (max 20,000 characters)
  • dateDependencySettings (table, optional) - Date dependency settings

Returns: Updated table object, or nil and error message

local table, err = airtable.updateTable("appXXXXXXXXXX", "tblXXXXXXXXXX", {
    name = "Renamed Table",
    description = "Updated description"
})

---

Fields

airtable.createField(base_id, table_id, fieldtype, options)

Creates a new field in a table.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_id (string) - The ID of the table
• fieldtype (string) - The type of field to create (e.g., "singleLineText", "number", "checkbox")
• options (table) - Field options:
  • name (string) - The name of the field
  • description (string, optional) - Field description (max 20,000 characters)

Returns: Created field object, or nil and error message

local field, err = airtable.createField("appXXXXXXXXXX", "tblXXXXXXXXXX", "singleLineText", {
    name = "New Field",
    description = "A description of this field"
})

---

airtable.updateField(base_id, table_id, field_id, options)

Updates an existing field in a table.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_id (string) - The ID of the table
• field_id (string) - The ID of the field to update
• options (table) - Field options to update:
  • name (string, optional) - The new name of the field
  • description (string, optional) - New field description (max 20,000 characters)

Returns: Updated field object, or nil and error message

local field, err = airtable.updateField("appXXXXXXXXXX", "tblXXXXXXXXXX", "fldXXXXXXXXXX", {
    name = "Renamed Field",
    description = "Updated description"
})

---

Comments

airtable.listComments(base_id, table_name, record_id)

Lists all comments on a record.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• record_id (string) - The ID of the record

Returns: Table containing comments array, or nil and error message

local comments, err = airtable.listComments("appXXXXXXXXXX", "Tasks", "recXXXXXXXXXX")

---

airtable.createComment(base_id, table_name, record_id, text, parentCommentId)

Creates a new comment on a record.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• record_id (string) - The ID of the record
• text (string) - The comment text
• parentCommentId (string, optional) - The ID of a parent comment for replies

Returns: Created comment object, or nil and error message

local comment, err = airtable.createComment("appXXXXXXXXXX", "Tasks", "recXXXXXXXXXX", "This is a comment")

---

airtable.updateComment(base_id, table_name, record_id, comment_id, content)

Updates an existing comment.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• record_id (string) - The ID of the record
• comment_id (string) - The ID of the comment to update
• content (string) - The new comment text

Returns: Updated comment object, or nil and error message

local comment, err = airtable.updateComment("appXXXXXXXXXX", "Tasks", "recXXXXXXXXXX", "comXXXXXXXXXX", "Updated comment")

---

airtable.deleteComment(base_id, table_name, record_id, comment_id)

Deletes a comment.

Parameters:

• base_id (string) - The ID of the Airtable base
• table_name (string) - The name or ID of the table
• record_id (string) - The ID of the record
• comment_id (string) - The ID of the comment to delete

Returns: Deletion confirmation object, or nil and error message

local result, err = airtable.deleteComment("appXXXXXXXXXX", "Tasks", "recXXXXXXXXXX", "comXXXXXXXXXX")

---

Utilities

airtable.sanitizeFormulaValue(value)

Sanitizes a value for safe use in Airtable formulas by escaping quotes and removing parentheses.

Parameters:

• value (any) - The value to sanitize

Returns: Sanitized string

---

airtable.validateFormula(formula)

Validates a formula string to ensure it doesn't contain potentially dangerous patterns.

Parameters:

• formula (string) - The formula to validate

Returns: true if valid, or false and error message

---

Bases

airtable.listBases(offset)

Lists all bases accessible by the API token.

Parameters:

• offset (string, optional) - Pagination offset for fetching additional pages of bases

Returns: Table containing bases array and optional offset for pagination, or nil and error message

local result, err = airtable.listBases()
for _, base in ipairs(result.bases) do
    print(base.name, base.id)
end

---

airtable.getBaseSchema(base_id, include)

Returns the schema of all tables in a base.

Parameters:

• base_id (string) - The ID of the Airtable base
• include (table, optional) - Array of additional fields to include (e.g., {"visibleFieldIds"})

Returns: Table containing tables array with schema information, or nil and error message

local schema, err = airtable.getBaseSchema("appXXXXXXXXXX")
for _, tbl in ipairs(schema.tables) do
    print(tbl.name, tbl.id)
end

---

airtable.createBase(workspace_id, name, tables)

Creates a new base in a workspace.

Parameters:

• workspace_id (string) - The ID of the workspace where the base will be created
• name (string) - The name for the new base
• tables (table) - Array of table configurations (at least one required)

Returns: Created base object with id and tables, or nil and error message

local newBase, err = airtable.createBase("wspXXXXXXXXXX", "My New Base", {
    {
        name = "Tasks",
        fields = {
            {name = "Name", type = "singleLineText"},
            {name = "Status", type = "singleSelect", options = {choices = {{name = "Todo"}, {name = "Done"}}}}
        }
    }
})