Use the REST API and API tokens
Updated
The REST API lets a program do what a person does on screen: list, read, create, change and delete records, and read how a base is built. A program signs in with an API token, which acts as you, with your permissions, in one workspace.
Create a token
- Open the menu under your initials or picture and choose My Account.
- Under API Tokens, press Manage tokens.
- Press Add new token, type a Title that says which program will use it, and pick the Workspace.
- Press Create token.
- Copy the token from the green box that appears, and keep it somewhere safe. It is shown only this once: Artavolo keeps only a fingerprint of it, so nobody, not even us, can read it back. Lost it? Use Generate new token.
Choose the bases a token reaches
- In Manage tokens, press the pencil under the token.
- Switch Enable off for every base the program does not need. The switch at the top turns the whole token off.
- Press Save.
The same menu has Rename, Generate new token (the old value stops working, and the new one is shown once) and Remove.
Call the API
Send the token in an API-KEY header, or use Basic authentication with your e-mail address as the user name and the token as the password. Writes are sent as JSON.
- The data API has one resource per table under
/api/v2/bases/{code}/tables/{table}/rows, where{code}is the code in the base's address. A read returns up to 10,000 records a page (100 by default) and can filter, sort, search and group. One request can create up to 100 records. - The Airtable-compatible API answers Airtable's own paths at
/v0, so scripts written for Airtable keep working.
A write through the API does what the same edit on screen does: it follows the base's rules on who may add, change and delete, is recorded in the audit log, starts the table's automations and sends the base's webhooks. A deleted record goes to the table's trash for 30 days.
Good to know
- A token can do only what you can do. If you are a read-only member of a base, so is the token. When someone leaves a workspace, their tokens stop working there too.
- Treat a token as a password: keep it on a server, never in a web page, a phone app or a code repository. If it may have leaked, use Generate new token or Remove.
- Give each program its own token, so you can switch one off without stopping the others.
- In our cloud a token may send 600 requests a minute, and a whole workspace 3,000. Over that the answer is
429with aRetry-Afterheader. On your own server there is no limit unless an administrator sets one. - Formula, lookup, rollup and AI fields are read-only through the API. Files are uploaded separately, not written as values.
- Assistants such as Claude and ChatGPT connect through the AI connector instead, which has its own connections; they are listed under Connected assistants in the same window. An AI connector token is refused by the data API.