1. Create a Personal Access Token (PAT) at https://airtable.com/create/tokens (tokens start with

   pat...

   ).
2. Grant these scopes (minimum):

   • data.records:read

     — read rows

   • data.records:write

     — create / update / delete rows

   • schema.bases:read

     — list bases and tables
3. Important: in the same token UI, add each base you want to access to the token's Access list. PATs are scoped per-base — a valid token on the wrong base returns

   403

   .
4. Store the token in

   ~/.hermes/.env

   (or via

   hermes setup

   ):

   AIRTABLE_API_KEY=pat_your_token_here

Note: legacy

key...

API keys were deprecated Feb 2024. Only PATs and OAuth tokens work now.

• Endpoint:

  https://api.airtable.com/v0

• Auth header:

  Authorization: Bearer $AIRTABLE_API_KEY

• All requests use JSON (

  Content-Type: application/json

  for any POST/PATCH/PUT body).
• Object IDs: bases

  app...

  , tables

  tbl...

  , records

  rec...

  , fields

  fld...

  . IDs never change; names can. Prefer IDs in automations.
• Rate limit: 5 requests/sec/base.

  429

  → back off. Burst on a single base will be throttled.

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

-s

python3 -m json.tool

jq

FORMULA="{Status}='Todo'"
ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA")
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

• Exact match:

  {Email}='user@example.com'

• Contains:

  FIND('bug', LOWER({Title}))

• Multiple conditions:

  AND({Status}='Todo', {Priority}='High')

• Or:

  OR({Owner}='alice', {Owner}='bob')

• Not empty:

  NOT({Assignee}='')

• Date comparison:

  IS_AFTER({Due}, TODAY())

1. Confirm auth.

   curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases -H "Authorization: Bearer $AIRTABLE_API_KEY"

   — expect

   200

   .
2. Find the base. List bases (step above) OR ask the user for the

   app...

   ID directly if the token lacks

   schema.bases:read

   .
3. Inspect the schema.

   GET /v0/meta/bases/$BASE_ID/tables

   — cache the exact field names and primary-field name locally in the session before mutating anything.
4. Read before you write. For "update X where Y",

   filterByFormula

   first to resolve the

   rec...

   ID, then

   PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID

   . Never guess record IDs.
5. Batch writes. Combine related creates into one 10-record POST to stay under the 5 req/sec budget.
6. Destructive ops. Deletions can't be undone via API. If the user says "delete all Xs", echo back the filter + record count and confirm before firing.

• filterByFormula

  MUST be URL-encoded. Field names with spaces or non-ASCII also need encoding (

  {My Field}

  →

  %7BMy%20Field%7D

  ). Use Python stdlib (pattern above) — never hand-escape.
• Empty fields are omitted from responses. A missing

  "Assignee"

  key doesn't mean the field doesn't exist — it means this record's value is empty. Check the schema (step 3) before concluding a field is missing.
• PATCH vs PUT.

  PATCH

  merges supplied fields into the record.

  PUT

  replaces the record entirely and clears any field you didn't include. Default to

  PATCH

  .
• Single-select options must exist. Writing

  "Status": "Shipping"

  when

  Shipping

  isn't in the field's option list errors with

  INVALID_MULTIPLE_CHOICE_OPTIONS

  unless you pass

  "typecast": true

  (which auto-creates the option).
• Per-base token scoping. A

  403

  on one base while another works means the token's Access list doesn't include that base — not a scope or auth issue. Send the user to https://airtable.com/create/tokens to grant it.
• Rate limits are per base, not per token. 5 req/sec on

  baseA

  and 5 req/sec on

  baseB

  is fine; 6 req/sec on

  baseA

  alone will throttle. Monitor the

  Retry-After

  header on

  429

  .

• Always use the

  terminal

  tool with

  curl

  . Do NOT use

  web_extract

  (it can't send auth headers) or

  browser_navigate

  (needs UI auth and is slow).

• AIRTABLE_API_KEY

  flows from

  ~/.hermes/.env

  into the subprocess automatically when this skill is loaded — no need to re-export it before each

  curl

  call.
• Escape curly braces in formulas carefully. In a heredoc body,

  {Status}

  is literal. In a shell argument,

  {Status}

  is safe outside

  {...}

  brace-expansion context — but pass dynamic strings through

  python3 urllib.parse.quote

  before splicing into a URL.
• Pretty-print with

  python3 -m json.tool

  (always present) rather than

  jq

  (optional). Only reach for

  jq

  when you need filtering/projection.
• Pagination is per-page, not global. Airtable's 100-record cap is a hard limit; there is no way to bump it. Loop with

  offset

  until the field is absent.
• Read the

  errors

  array on non-2xx responses — Airtable returns structured error codes like

  AUTHENTICATION_REQUIRED

  ,

  INVALID_PERMISSIONS

  ,

  MODEL_ID_NOT_FOUND

  ,

  INVALID_MULTIPLE_CHOICE_OPTIONS

  that tell you exactly what's wrong.