airtable

Send a POST request to /v0/{baseId}/{table} with a JSON body containing a fields object to create records, or a PATCH request with the record ID to update. Add performUpsert with fieldsToMergeOn to insert-or-update based on a key field like Email.

Pass a URL-encoded Airtable formula such as {Status}='Todo' as the filterByFormula query parameter. Encode it with Python's urllib.parse.quote rather than hand-escaping, since field names with spaces or special characters break unencoded URLs.

Airtable requires a personal access token starting with pat, sent as a Bearer token in the Authorization header. The token needs data.records:read and data.records:write scopes, and each target base must be added to the token's Access list.

A 403 on a specific base means the personal access token's Access list does not include that base, not that the token is invalid. Open https://airtable.com/create/tokens and add the missing base to the token's access scope.

The API allows 5 requests per second per base and returns 429 with a Retry-After header when exceeded. Batch create and delete endpoints accept a maximum of 10 records per request, and list endpoints return at most 100 records per page.

Use PATCH for updates because it merges only the supplied fields and preserves everything else. PUT replaces the entire record and clears any field you did not include, which can silently delete data.