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. For local automation, see the CLI.

Authentication

1. Sign in at 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.

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:

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	read	List accessible spreadsheets.
POST	/sheets	create	Create a spreadsheet from a document.
GET	/sheets/{pid}/workbook	read	List worksheet tabs and their structure.
GET	/sheets/{pid}/range	read	Read cells in an A1 range.
GET	/sheets/{pid}/snapshot	read	Read the complete document and its revision.
POST	/sheets/{pid}/cells	write	Write cell values or formulas.
POST	/sheets/{pid}/save	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 for retry behavior and Zapier for the Create Spreadsheet Row workflow.