Autosheet API
Preview — The Autosheet API is in preview and may change. If you run into issues, contact GPT for Work support.
Use the Autosheet API to run a spreadsheet agent programmatically — perform AI-driven enrichment, analysis, edits, and transformations across spreadsheets from your AI agent, workflow tool, or code. Autosheet is built on the same agent engine that powers the Agent in GPT for Sheets.
This interactive reference requires JavaScript. The summary below covers the essentials; the full machine-readable specification is at openapi.yaml.
Base URL
https://api.autosheet.com
Authentication
All requests require an API key in the X-API-Key header. Keys are issued in the format sk_autosheet_<32 alphanumeric chars> and can be created at dashboard.gptforwork.com (sign in with Google).
A deleted or unrecognized key returns 401. A disabled or revoked key returns 403, on every endpoint including Verify API Key.
Quick start
If you don't have a spreadsheet ID handy, make a copy of our sample spreadsheet — Google Sheets saves it to your Drive. Its ID is the text between /d/ and /edit in the URL.
Submit a task from your terminal:
curl https://api.autosheet.com/v1/sheets/agents \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <AUTOSHEET_API_KEY>' \
--data '{
"spreadsheet_id": "<YOUR_SPREADSHEET_ID>",
"prompt": "Score these leads against our scoring rules."
}'
Then poll the agent (using the id from the response) until the top-level status returns to idle. On success error_message and error_code are both null. If the turn failed or was interrupted, error_message carries the reason and, when available, error_code identifies the condition — branch on the code when present, since the message is generated copy that can change; a cancelled turn may include one (set when you call Stop agent). While a turn is still running, usage is null and the running subtotal is in usage_so_far. Read the agent's replies from the ordered messages array — the last assistant_message entry is its final answer. The full conversation across all turns is available from GET /v1/{platform}/agents/{id}/messages (cursor-paginated). Alternatively, to be notified on completion, provide a webhook_url in the request body when you start the agent.
Endpoints
| Method | Path | Summary |
|---|
| POST | /v1/{platform}/agents | Start agent — start a new task or add a follow-up turn |
| GET | /v1/{platform}/agents/{id} | Get agent — current status plus the latest turn's messages (with tool-call summaries) |
| GET | /v1/{platform}/agents/{id}/messages | Get agent messages — full conversation across all turns, cursor-paginated |
| POST | /v1/{platform}/agents/{id}/stop | Stop agent — cancel a running agent |
| GET | /v1/{platform}/agents/configuration | List available models for your space |
| GET | /v1/auth/verify | Verify API key — returns account info and webhook secret |
{platform} is currently sheets.
Webhooks
Provide a webhook_url when running an agent to receive a POST callback once the turn completes — on any terminal state (succeeded, failed, interrupted, or cancelled). The JSON body carries agent_id, turn_id, status, error_message (null unless the status is failed or interrupted), error_code (a machine-readable code for that failure, or null — branch on this rather than the message text), and usage (the turn's credit usage in integer nano-dollars, null unless the turn ran to its natural end).
Each request carries X-Webhook-Signature: sha256=<hex> — an HMAC-SHA256 of the raw request body, keyed with your webhook secret (returned by the Verify API Key endpoint). Verify with a constant-time comparison. Respond with any 2xx to acknowledge; non-2xx responses are not retried.
Rate and spending limits
All three limits return 429, so branch on the error code rather than the status alone. Every 429 carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; only a request-rate rejection also carries Retry-After and X-RateLimit-Reset-After.
Request rate limit — 500 requests/minute per API key, code RATE_LIMIT_EXCEEDED. This is the one case that tells you how long to wait, via Retry-After.
Concurrency limit — up to 100 active agents per API key, code CONCURRENT_LIMIT_REACHED. No Retry-After, so retry after an active agent finishes. A request rejected this way still spends one request from your per-minute budget.
Spending limits — Agents consume credits from your space balance. Space-wide and user-specific spending limits can be set in the GPT for Work dashboard. When a limit is reached, new requests are rejected with code SPENDING_LIMIT_REACHED and no Retry-After.
Every error response also carries a request_id, echoed as the X-Request-Id response header. Include it when you contact support.
OpenAPI specification
Full schema: openapi.yaml (OpenAPI 3.1, YAML).
LLM-friendly Markdown: llms.txt.
Support
gptforwork.com/support
Autosheet
part of GPT for Work