airtable

Send a POST to /v0/{baseId}/{table} with a JSON body containing a fields object to create records, or PATCH a specific record ID to merge updates. Use performUpsert with fieldsToMergeOn to create-or-update by 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 and curly braces require encoding.

You need a personal access token with data.records:read, data.records:write, and schema.bases:read scopes. The token must also have each target base added to its Access list, otherwise requests to that base return 403.

A 403 usually means the personal access token's Access list does not include that specific base, since PATs are scoped per-base. Add the base at airtable.com/create/tokens rather than changing scopes.

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

Use PATCH, which merges only the supplied fields and preserves everything else. PUT replaces the entire record and clears any field you did not include, so it is risky for partial updates.