# Airtable

> Manage records and bases in Airtable with full CRUD operations, search with formula filtering, and base schema inspection.

Source: https://cotera.co/docs/reference/tools/individual-tools/airtable

---

**Authentication Type:** API Key
**Description:** Manage records and bases in Airtable with full CRUD operations, search with formula filtering, and base schema inspection.

***

## Authentication

To authenticate with Airtable, you'll need a Personal Access Token:

1. Go to [Airtable Token Creation](https://airtable.com/create/tokens)
2. Click **Create new token** and give it a descriptive name
3. Add the scopes you need:
   * `data.records:read` -- required for reading records
   * `data.records:write` -- required for creating, updating, and deleting records
   * `schema.bases:read` -- required for listing bases and reading schemas
4. Select which bases the token can access (all bases, or specific ones)
5. Click **Create token** and copy the value

You'll need to provide:

* **apiKey** `string`: Your Airtable Personal Access Token

> **Security tip:** Create separate tokens for read-only and read-write access. Use the minimum scopes required for your use case, and restrict access to only the bases you need.

***

## Records

### Create Record

Create a new record (row) in an Airtable table. Field names must match the column names in your table exactly.

**Operation Type:** Mutation (Write)

**Parameters:**

* **baseId** `string` (required): The ID of the Airtable base (e.g., `appABC123def456`)
* **tableId** `string` (required): The ID or name of the table (e.g., `tblXYZ789` or `Contacts`)
* **fields** `object` (required): Key-value pairs of field names to values. Keys are the field names, values are the data to set.
* **typecast** `boolean` (nullable): If `true`, Airtable will attempt to convert string values to the appropriate cell type (e.g., turning `"42"` into a number). Default `false`.

**Returns:**

* **id** `string`: The ID of the newly created record
* **createdTime** `string`: ISO 8601 timestamp of when the record was created
* **fields** `object`: The field values of the created record

**Example Usage:**

```json
{
  "baseId": "appABC123def456",
  "tableId": "Contacts",
  "fields": {
    "Name": "Jane Smith",
    "Email": "jane@example.com",
    "Company": "Acme Corp",
    "Status": "Active"
  },
  "typecast": false
}
```

***

### Get Record

Retrieve a single record from an Airtable table by its record ID.

**Operation Type:** Query (Read)

**Parameters:**

* **baseId** `string` (required): The ID of the Airtable base
* **tableId** `string` (required): The ID or name of the table
* **recordId** `string` (required): The ID of the record to retrieve (e.g., `recABC123`)

**Returns:**

* **id** `string`: The record ID
* **createdTime** `string`: ISO 8601 timestamp of when the record was created
* **fields** `object`: The field values of the record

**Example Usage:**

```json
{
  "baseId": "appABC123def456",
  "tableId": "Contacts",
  "recordId": "recXYZ789abc012"
}
```

***

### Search Records

Search for records in an Airtable table with optional filtering, sorting, field selection, and pagination.

**Operation Type:** Query (Read)

**Parameters:**

* **baseId** `string` (required): The ID of the Airtable base
* **tableId** `string` (required): The ID or name of the table
* **filterByFormula** `string` (nullable): An [Airtable formula](https://support.airtable.com/docs/formula-field-reference) to filter records. Only records where the formula evaluates to `true` are returned.
* **fields** `array of strings` (nullable): List of field names to include in the response. If omitted, all fields are returned.
* **sort** `array of objects` (nullable): List of sort criteria. Each object has:
  * **field** `string`: The field name to sort by
  * **direction** `string`: Sort direction (`asc` or `desc`)
* **maxRecords** `number` (nullable): Maximum number of records to return (default 100)
* **view** `string` (nullable): The name or ID of a view to use. When specified, only records visible in that view are returned, and the view's filters and sorts are applied.

**Returns:**

* **records** `array of objects`: List of matching records
  * **id** `string`: The record ID
  * **createdTime** `string`: ISO 8601 timestamp of when the record was created
  * **fields** `object`: The field values of the record

**Example Usage:**

```json
{
  "baseId": "appABC123def456",
  "tableId": "Contacts",
  "filterByFormula": "AND({Status} = 'Active', {Company} = 'Acme Corp')",
  "fields": ["Name", "Email", "Company"],
  "sort": [{ "field": "Name", "direction": "asc" }],
  "maxRecords": 50
}
```

***

### Update Record

Update an existing record in an Airtable table. Only the fields you specify will be updated; other fields remain unchanged.

**Operation Type:** Mutation (Write)

**Parameters:**

* **baseId** `string` (required): The ID of the Airtable base
* **tableId** `string` (required): The ID or name of the table
* **recordId** `string` (required): The ID of the record to update
* **fields** `object` (required): Key-value pairs of field names to new values. Only specified fields are updated.
* **typecast** `boolean` (nullable): If `true`, Airtable will attempt to convert string values to the appropriate cell type. Default `false`.

**Returns:**

* **id** `string`: The record ID
* **createdTime** `string`: ISO 8601 timestamp of when the record was created
* **fields** `object`: The full field values of the updated record

**Example Usage:**

```json
{
  "baseId": "appABC123def456",
  "tableId": "Contacts",
  "recordId": "recXYZ789abc012",
  "fields": {
    "Status": "Churned",
    "Notes": "Account closed on 2025-03-15"
  }
}
```

***

### Delete Record

Delete a record from an Airtable table. This action is permanent and cannot be undone.

**Operation Type:** Mutation (Write)

**Parameters:**

* **baseId** `string` (required): The ID of the Airtable base
* **tableId** `string` (required): The ID or name of the table
* **recordId** `string` (required): The ID of the record to delete

**Returns:**

* **id** `string`: The ID of the deleted record
* **deleted** `boolean`: `true` if the record was successfully deleted

**Example Usage:**

```json
{
  "baseId": "appABC123def456",
  "tableId": "Contacts",
  "recordId": "recXYZ789abc012"
}
```

***

## Bases

### List Bases

List all Airtable bases that your token has access to. Use this to discover base IDs for use with other operations.

**Operation Type:** Query (Read)

**Parameters:**

None.

**Returns:**

* **bases** `array of objects`: List of accessible bases
  * **id** `string`: The base ID (e.g., `appABC123def456`)
  * **name** `string`: The human-readable name of the base
  * **permissionLevel** `string`: Your permission level for this base (e.g., `create`, `edit`, `comment`, `read`)

**Example Usage:**

```json
{}
```

***

### Get Base Schema

Retrieve the schema of an Airtable base, including all tables and their field definitions. Use this to discover table IDs, field names, and field types before querying or writing records.

**Operation Type:** Query (Read)

**Parameters:**

* **baseId** `string` (required): The ID of the Airtable base

**Returns:**

* **tables** `array of objects`: List of tables in the base
  * **id** `string`: The table ID (e.g., `tblXYZ789`)
  * **name** `string`: The table name
  * **description** `string` (nullable): Description of the table
  * **fields** `array of objects`: List of fields in the table
    * **id** `string`: The field ID
    * **name** `string`: The field name
    * **type** `string`: The field type (e.g., `singleLineText`, `number`, `singleSelect`, `multipleAttachments`)
    * **description** `string` (nullable): Description of the field

**Example Usage:**

```json
{
  "baseId": "appABC123def456"
}
```

***

## Common Use Cases

**CRM & Contact Management:**

* Search for contacts by status, company, or custom fields using formula filters
* Create new contact records when leads come in from other tools
* Update deal stages and contact statuses as they progress through your pipeline
* Sync contact data between Airtable and other systems

**Project & Task Tracking:**

* Query open tasks filtered by assignee, due date, or priority
* Update task statuses and add notes as work progresses
* Create new tasks or issues from external triggers (e.g., support tickets, form submissions)
* List all tables in a project base to understand its structure before building automations

**Inventory & Asset Management:**

* Search for products by category, stock level, or supplier
* Update inventory quantities after orders are fulfilled
* Create records for new assets and track their lifecycle
* Use schema inspection to discover field types and build dynamic integrations

**Data Operations & Integration:**

* List all accessible bases to discover available data sources
* Inspect base schemas to understand table structures before building workflows
* Bulk-read records with formula filtering for reporting and analytics
* Use typecast to flexibly import data from external systems without strict type matching