# Use the REST API and API tokens

> Create an API token, choose the bases it reaches, and read and write records over the REST API. Limits, permissions and when to use something else.

Source: https://artavolo.com/page/rest-api-and-tokens

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

1. Open the menu under your initials or picture and choose **My Account**.
2. Under **API Tokens**, press **Manage tokens**.
3. Press **Add new token**, type a **Title** that says which program will use it, and pick the **Workspace**.
4. Press **Create token**.
5. Open the small menu beside the token's name and copy the token.

## Choose the bases a token reaches

1. In **Manage tokens**, press the pencil under the token.
2. Switch **Enable** off for every base the program does not need. The switch at the top turns the whole token off.
3. Press **Save**.

The same menu has **Rename**, **Generate new token** (the old value stops working) 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](https://artavolo.com/docs/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](https://artavolo.com/page/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 `429` with a `Retry-After` header. 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.

## Related

- [Use Airtable's API with Artavolo](https://artavolo.com/page/airtable-compatible-api)
- [Send changes to another system with webhooks](https://artavolo.com/page/webhooks)
- [Connect Claude or ChatGPT](https://artavolo.com/page/connect-claude-chatgpt)
- [Data API reference](https://artavolo.com/docs/data-api)
