> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vis42.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Airtable

> Connect Airtable with a Personal Access Token so VIS42 agents can read and update your bases, tables, and records.

Connect Airtable to let VIS42 agents work with your structured data — budgets, vendor lists, CRM pipelines, audit trackers, anything you keep in an Airtable base. Your agents can list bases, inspect table schemas, query records with filters, and create or update rows.

Airtable is the fastest integration to set up: no OAuth redirect, no consent screen — you paste a **Personal Access Token (PAT)** you generate yourself, and the connection is live in seconds.

## What your agents can do

Once connected, VIS42 agents have five Airtable capabilities:

* **List bases** your PAT can access, with their IDs and permission levels
* **List tables** within a base, with every column's name and type
* **Query records** with an Airtable `filterByFormula` expression, a view, sort rules, and page size
* **Create** a new record in any table, passing a `fields` object mapping column name → value
* **Update** a record (PATCH semantics — only the fields you pass are changed; all other columns are preserved)

Example prompts:

* Ask **Themis** to *"compare our actual revenue this quarter to the forecasts in my Airtable Budget base"* and it will list tables and query records.
* Ask **Pluto** to *"log this compliance finding as a new row in my Audit Log table in Airtable"* and it will create a record.
* Ask **Mercury** to *"mark invoice INV-042 as Paid in my CRM Airtable"* and it will update the matching record.

## Create a Personal Access Token

<Steps>
  <Step title="Open Airtable token creator">
    Go to [airtable.com/create/tokens](https://airtable.com/create/tokens) and click **Create new token**.
  </Step>

  <Step title="Name the token">
    Use something recognizable, for example **VIS42 agent access**.
  </Step>

  <Step title="Pick scopes">
    Enable these three — they cover all five capabilities above:

    * `data.records:read`
    * `data.records:write`
    * `schema.bases:read`

    <Warning>
      Without `schema.bases:read`, your agents can't discover which bases exist or inspect table columns. Without `data.records:write`, create and update prompts will fail.
    </Warning>
  </Step>

  <Step title="Grant access to bases">
    Under **Access**, pick the bases you want VIS42 to read and write. You can add more bases later by editing the token in Airtable — no need to reconnect in VIS42.
  </Step>

  <Step title="Create and copy">
    Click **Create token**. Airtable shows the token **once** — it starts with `pat…`. Copy it immediately.
  </Step>
</Steps>

## Connect the token in VIS42

<Steps>
  <Step title="Open agent settings">
    Open any agent (Mercury, Themis, or Pluto) and scroll to the **Connected Services** section.
  </Step>

  <Step title="Click Connect on the Airtable card">
    An input field expands below the card.
  </Step>

  <Step title="Paste the token">
    Paste your `pat…` token and click **Save**. VIS42 validates the token with Airtable before storing it — if the token is invalid or missing scopes, you'll see an inline error.
  </Step>

  <Step title="Done">
    The card flips to **Enabled** and shows the email of the Airtable account the token belongs to. Agents can now use it.
  </Step>
</Steps>

## Access scope

<Warning>
  VIS42 can only work with bases and tables the token explicitly has access to. When you mint the token, you choose which bases to grant — nothing else in your Airtable is reachable.
</Warning>

To change which bases VIS42 sees:

* **In Airtable**: go to [airtable.com/create/tokens](https://airtable.com/create/tokens) → find your VIS42 token → **Edit** → adjust the base list → **Save**. No re-connection needed in VIS42.
* **To disconnect entirely**: either **Revoke** the token in Airtable, or click **Disconnect** on the Airtable card in VIS42's agent settings. Revoking in Airtable is the strongest option — it immediately invalidates the token everywhere it's used.

## Querying with formulas

Airtable's `filterByFormula` is a powerful server-side filter. Your agents pass raw formula strings through to Airtable — the same ones you'd write in an Airtable formula field.

Common patterns:

```text theme={null}
{Status}='Open'
```

```text theme={null}
AND({Status}='Open', {Amount}>100)
```

```text theme={null}
OR({Owner}='You', {Priority}='High')
```

```text theme={null}
DATETIME_DIFF(TODAY(), {DueDate}, 'days') < 7
```

See [Airtable's formula reference](https://support.airtable.com/docs/formula-field-reference) for the full function list. When in doubt, ask your agent to query a small page first (`page_size: 5`) to check the formula returns what you expect.

## Privacy and scope

* The connection is **per user, per business** — each team member creates and pastes their own token.
* VIS42 stores the PAT encrypted at rest.
* VIS42 can only access bases the token is scoped to — nothing else in your Airtable account.
* Tokens do not expire automatically. They stay valid until you revoke them in Airtable or disconnect in VIS42.
* Disconnect at any time from **Connected Services** in the agent settings page. The record is removed from VIS42 — revoke the token in Airtable too if you want it invalidated immediately.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'The token is invalid or does not have the required scopes'">
    Either the token was revoked, mistyped, or missing one of the required scopes. Create a new token with `data.records:read`, `data.records:write`, and `schema.bases:read`, then reconnect.
  </Accordion>

  <Accordion title="Agent says it can't see a specific base">
    The token isn't scoped to that base. In Airtable, edit the VIS42 token and add the base under **Access**. No need to reconnect in VIS42 — the next request will use the updated scope.
  </Accordion>

  <Accordion title="Create or update fails with 'Unknown field' or 'Invalid value'">
    The `fields` object doesn't match the table schema. Ask the agent to list the table's fields first (`airtable-list-tables`), then retry with the exact field names and types Airtable expects (for example, single-select values must match existing options).
  </Accordion>

  <Accordion title="Agent returns 'No records matched the query'">
    Either the filter returns zero rows (try without a formula first) or the `view` name limits the visible rows. Remove `view` and `filter_by_formula` to see if records exist at all.
  </Accordion>

  <Accordion title="I want to revoke access from Airtable's side">
    Go to [airtable.com/create/tokens](https://airtable.com/create/tokens) → find the VIS42 token → **Revoke**. This invalidates the token immediately. You'll also want to click **Disconnect** in VIS42's agent settings to clear the local record.
  </Accordion>
</AccordionGroup>