# REST API

Use the VisiGrid REST API to work with spreadsheets stored in your VisiGrid
account. Scripts and integrations can list accessible workbooks, read cells,
create spreadsheets, and write values or formulas. Local files must first be
saved to your cloud account.

**Base URL:** `https://app.visigrid.app/api/connector`

This reference covers the spreadsheet REST endpoints. For an AI assistant
using MCP, see the [Claude Connector](https://docs.visigrid.app/connector/). For local automation, see
the [CLI](https://docs.visigrid.app/cli/install/).

## Authentication

1. Sign in at [app.visigrid.app](https://app.visigrid.app) and verify your email.
2. Open **Settings** and create a personal API token with the scopes your
   integration needs. For Zapier, choose **write**, which also allows reads.
3. Copy the token, which starts with `vgp_`. The full secret is shown only once.
4. Send it in the `Authorization` header on every request.

```http
Authorization: Bearer YOUR_PERSONAL_API_TOKEN
```

Keep the token in an environment variable or secret store. Do not place it in
a URL, commit it to source control, or embed it in browser code.

| Scope | Allows |
| --- | --- |
| `read` | List spreadsheets; read snapshots, workbook structure, and cell ranges. |
| `write` | Write cells and save complete snapshots. Includes `read`. |
| `create` | Create spreadsheets. Add `read` or `write` separately if needed. |

Scopes do not grant access beyond the account's spreadsheet permissions.
Owners and editors can write; viewers can read. The list endpoint includes
spreadsheets shared with the account as well as its own spreadsheets.

Tokens expire after 30, 90, or 365 days (365 by default). An account can have
up to 20 active tokens. Revoke tokens in Settings when they are no longer
needed. Expiration, revocation, a password change, or signing out everywhere
invalidates a token; an unverified account cannot use one.

These endpoints also accept OAuth access tokens issued by VisiGrid. A browser
login token, an old `vk_` API key, and a Zapier CLI deploy key are not personal
API tokens and cannot authenticate these requests.

## First request

Set `VISIGRID_API_TOKEN` in your environment, then list your spreadsheets:

```bash
curl --fail-with-body \
  -H "Authorization: Bearer $VISIGRID_API_TOKEN" \
  https://app.visigrid.app/api/connector/sheets
```

The response is a JSON array, or `[]` if no spreadsheets are accessible.
Use a spreadsheet's **`pid` UUID** in subsequent endpoint URLs. Do not use
its internal numeric `id`. In snapshot, workbook, range, and cell-write
responses, the same UUID is named `sheet_id`.

## Endpoints

Paths below are relative to the base URL. `{pid}` identifies a whole workbook;
`sheet_index` selects a worksheet tab inside it.

| Method | Path | Scope | Purpose |
| --- | --- | --- | --- |
| GET | [`/sheets`](https://docs.visigrid.app/api/spreadsheets/#list-spreadsheets) | `read` | List accessible spreadsheets. |
| POST | [`/sheets`](https://docs.visigrid.app/api/spreadsheets/#create-a-spreadsheet) | `create` | Create a spreadsheet from a document. |
| GET | [`/sheets/{pid}/workbook`](https://docs.visigrid.app/api/spreadsheets/#get-workbook-structure) | `read` | List worksheet tabs and their structure. |
| GET | [`/sheets/{pid}/range`](https://docs.visigrid.app/api/spreadsheets/#read-a-range) | `read` | Read cells in an A1 range. |
| GET | [`/sheets/{pid}/snapshot`](https://docs.visigrid.app/api/spreadsheets/#get-a-snapshot) | `read` | Read the complete document and its revision. |
| POST | [`/sheets/{pid}/cells`](https://docs.visigrid.app/api/spreadsheets/#write-cells) | `write` | Write cell values or formulas. |
| POST | [`/sheets/{pid}/save`](https://docs.visigrid.app/api/spreadsheets/#save-a-complete-snapshot) | `write` | Replace the complete document. |

Send `Content-Type: application/json` with POST requests. Unknown request
fields are rejected. Success responses are JSON with HTTP 200, except
creation, which returns HTTP 201.

## Write workflow

1. Read the current cells or snapshot and its `revision`.
2. Build your edits from that data.
3. Send that revision as `expected_revision` with the write.
4. If the API returns HTTP 409 `revision_conflict`, reread and recompute your
   edits before trying again.

`expected_revision` is required, including when its value is `0`. It checks
the whole workbook, not just the selected tab. Revisions are concurrency
tokens: use the returned value rather than predicting the next one.

See [errors and limits](https://docs.visigrid.app/api/errors/) for retry behavior and
[Zapier](https://docs.visigrid.app/api/zapier/) for the Create Spreadsheet Row workflow.