airtable

Create records with a POST to /v0/{baseId}/{table} containing a fields object, and update with PATCH to the record URL, which merges only supplied fields. Use performUpsert with fieldsToMergeOn to insert or update by a key field like Email without knowing record IDs.

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 braces must be percent-encoded.

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 with a valid token means the token's Access list does not include that base, since personal access tokens 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 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.