Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Airtable integration lets your agents discover, read, and write records across your Airtable workspaces. Works with any standard or custom table — agents can enumerate the bases they have access to, inspect fields at runtime, and perform full CRUD operations, including batch upserts.

​
Features

  • Dynamic Discovery: Agents can list accessible bases and inspect table schemas (fields, types, select choices, views) without hardcoded configuration
  • Flexible Search: Three query modes — free-text searchTerm + searchFields, full filterByFormula, or plain list with sort/view/fields
  • Full CRUD + Upsert: Create, read, update, delete, and batch-upsert records (up to 10 per call — Airtable’s API limit)
  • Field Typecasting: Optional typecast flag coerces string values to existing select options, numbers, and dates so agents don’t have to format values exactly
  • View-Aware Queries: Scope results to a named view so the agent honors the same filters your team uses in the UI
  • Offset Pagination: Seamlessly page through large tables via the nextOffset cursor

​
Prerequisites

  • Active Airtable account (free tier works)
  • A Personal Access Token (PAT) with the correct scopes and the right bases granted

​
Setup Guide

1

Create a Personal Access Token

Go to airtable.com/create/tokens/new. Give the token a descriptive name (e.g., “Aster Agents”).Add these scopes:
  • data.records:read — read table records
  • data.records:write — create, update, and delete records
  • schema.bases:read — discover bases, tables, and field metadata
Under Access, select every base the agent should be able to reach. You can add specific bases now and grant more later by editing the token.Copy the generated token — it starts with pat and is only shown once.
PATs are tied to the creating user’s permissions. If that user loses access to a base, the token loses access to that base too. For long-lived service use, create the PAT under a dedicated service account.
2

Enable Airtable Integration

In Aster Agents, navigate to Control Hub > Integrations and locate the Airtable card. Click Connect to begin setup.
3

Configure Connection

Provide your Airtable token:
  • Personal Access Token: The pat token from Step 1
4

Add Tools to Your Agent

Edit your agent and enable the Airtable tools you need:
  • Get Airtable Schema — list bases, or inspect tables and fields inside a base
  • Search Airtable — find records with free-text search, formula filters, and sorting
  • Manage Airtable Records — create, read, update, upsert, and delete records
We recommend enabling all three — agents use Get Schema first to discover the baseId, tableIdOrName, and field names before searching or writing.

​
Available Tools

​
Get Airtable Schema

Discover the structure of your Airtable workspace:
  • Without a baseId: returns every base the integration has access to (id, name, permission level)
  • With a baseId: returns every table in that base with fields (id, name, type, description, select choices) and views
Agents should call this first — they use the returned IDs as input to the other two tools.

​
Search Airtable

Query records in a table with three modes:
  • Free-text: searchTerm + searchFields — case-insensitive substring match across the listed fields, built via OR(SEARCH(...))
  • Formula: filterByFormula — any valid Airtable formula, for AND/OR logic, date math, linked-record filtering, etc.
  • Plain list: no filter — returns records optionally scoped to a view, with sort/fields/maxRecords applied
Supports offset-based pagination. Responses include nextOffset when more records are available.

​
Manage Airtable Records

Perform CRUD operations:
  • get — retrieve a single record by ID
  • create — insert 1–10 records in one call
  • update — patch specific fields on existing records (requires each record’s id)
  • upsert — batch insert-or-update using fieldsToMergeOn as the match criteria
  • delete — remove records by ID (single via recordId, or up to 10 via records[].id)
Use typecast: true when writing human-readable values to select / number / date fields — Airtable will coerce strings to match existing options.

​
Security Considerations

  • Grant only the bases you need — PATs can be scoped to specific bases; avoid “all workspaces” unless the agent genuinely needs it
  • Use minimum scopes — if the agent only reads, don’t grant data.records:write
  • Rotate PATs periodically — Airtable tokens do not expire automatically; treat them like long-lived API keys
  • Use a dedicated service user — creating the PAT under a shared service account avoids losing access when an individual leaves
  • Monitor token activity — Airtable’s token settings page shows last-used timestamps

​
Troubleshooting

  • Verify your token is correct and starts with pat
  • Check the token hasn’t been revoked in your Airtable token list
  • Confirm the creating user still has access to the base (PAT permissions inherit from that user)
  • The token must explicitly list the base under Access — it’s not sufficient for the user to have base access
  • Use airtable_get_schema (without a baseId) to see exactly which bases the token can reach
  • tableIdOrName accepts either the table ID (starts with tbl) or its display name — IDs are more stable against renames
  • Airtable limits each base to 5 requests per second per integration
  • The tool surfaces a clear error with the retry-after duration when hit
  • For bulk work, use the batch upsert action with up to 10 records per call rather than single-record creates
  • By default, writing a string that doesn’t exactly match an existing option fails
  • Pass typecast: true to let Airtable coerce the string to an existing option (or create a new one for single/multi-select)
  • For linked records, pass an array of record IDs (not names)
  • Wrap field names in {} — e.g., {Status}='Active'
  • Escape single quotes in string literals as \'
  • Use Airtable’s formula playground to validate complex formulas before passing them in