Sheetgo REST API
Create and run workflows and automations, schedule them, read forms and run results, browse connected storage, and more.
Base URL: https://dev-api.sheetgo.com/rest · Public endpoints: https://dev-api.sheetgo.com/rest/beta/… · Auth: Authorization: Bearer sg_… · 74 endpoints
Where the documentation is
On this site every endpoint is documented in full: one page per group with every parameter, request body, response and error, plus the models each page uses. Start from the endpoint index.
Live, always the latest (served by the API itself, public, no key needed):
| Page | Best for |
|---|---|
| Swagger UI | People: try requests in the browser (needs JavaScript). |
| ReDoc | People: read the reference with the guides. |
| Reference · Markdown | People and AI: the same content as these pages, regenerated on every deploy. Add .md to any page for Markdown. |
| llms.txt · llms-full.txt | AI agents: an index, and everything in one file (about 450 KB). |
| openapi.json | Code generators and tools: the OpenAPI 3 spec. |
Quickstart
With curl below. For complete Python programs (errors and retries, pagination, create and run an automation, column letters), see Python examples.
# 1. List your workflows
curl -s "https://dev-api.sheetgo.com/rest/beta/workflows/?page=1&per_page=20" \
-H "Authorization: Bearer $SHEETGO_API_KEY"
# 2. List the automations (also called connections) of your account
curl -s "https://dev-api.sheetgo.com/rest/beta/automations/" \
-H "Authorization: Bearer $SHEETGO_API_KEY"
# 3. Run one automation: 200 means the run was QUEUED, not finished
curl -s -X POST "https://dev-api.sheetgo.com/rest/beta/automations/AUTOMATION_ID/run" \
-H "Authorization: Bearer $SHEETGO_API_KEY"
# 4. Poll its last run until "execution" is no longer "running"
curl -s "https://dev-api.sheetgo.com/rest/beta/automations/AUTOMATION_ID/run" \
-H "Authorization: Bearer $SHEETGO_API_KEY"Before you create or replace an automation, read the automations page and the models it lists: the request body has many source, processor and destination types.
Conventions
- Lists take
page(from 1) andper_page(1-100, default 50). The response'stotalis the number of pages, not of items. - Collection URLs end with a slash (
/beta/workflows/,/beta/automations/). APOSTwithout it is redirected. - Runs are asynchronous.
POST …/runanswers200once the run is queued. PollGET …/runfor the outcome. - Google Sheets are on the
driveprovider. File endpoints and automation sources useprovider: "drive"for Google Drive and Google Sheets. - Columns are letters. Fields that name a column take the spreadsheet letter (
"E"), not the header text.GET /beta/files/{provider}/{file_id}/structure?include=columnsmaps letters to headers. - OAuth2 (for apps acting for other Sheetgo users) is enabled on request: see the auth group and contact support. For your own scripts and agents, use an API key.
- Placeholders. Some fields accept
{{smart tags}}(values from your data) and{{Tab!A1}}cell references; see the guides.
Errors
Read the status code first, then the body. The body shape depends on the endpoint:
| Shape | Where | Example |
|---|---|---|
{code, detail} | Most newer endpoints (automations, triggers, files, dashboards, sharing, BigQuery…). code is a stable snake_case value to branch on; some add fields such as reason. | {"code": "invalid_column", "reason": "…", "detail": "…"} |
{status: 0, error, detail} | Outlook and Gmail endpoints. | {"status": 0, "error": "invalid_limit", "detail": "…"} |
{detail: [{loc, msg, type}]} | 422 request validation, on every endpoint. loc is the path to the bad field. | {"detail": [{"loc": ["body", "name"], "msg": "Field required", "type": "missing"}]} |
{code, message} with HTTP 200 | Older create/update/run routes (the SuccessResponse model): code: 1 means success. | {"code": 1, "message": "OK"} |
| Status | Meaning | What to do |
|---|---|---|
401 | Missing, wrong or revoked API key. | Check the Authorization: Bearer sg_… header. |
403 | The key's scopes, your role on the workflow, or your plan do not allow this. | Read detail; widen the key's scope or ask the workflow owner. |
404 | The id does not exist or your account cannot see it. | Check the id (and the provider for files). |
409 | Conflicts with the current state (a limit reached, a circular trigger…). | Read code/detail; do not retry unchanged. |
412 | A required account is not connected or authorised (Outlook, OpenAI, BigQuery…). | Connect or authorise it in the Sheetgo web app, then retry. |
422 | The request failed validation, or breaks a rule (for example an invalid processor combination). | Fix the field named in loc or code. |
429 | Rate limit exceeded. | Wait Retry-After seconds. See Rate Limiting. |
502 | The storage provider (Google, Microsoft, BigQuery…) failed. | Retry with backoff. |
Each operation on the group pages lists the status codes it can return.
All endpoints
Grouped as in the reference. Each row links to the operation's full documentation on its group page.
Workflows & Automations
workflows22 endpoints
A workflow is an automated process that connects your spreadsheets and files and moves data between them — on a schedule or on demand — so a task that would otherwise be manual runs by itself. It is the top-level container that holds automations, forms and triggers.
Full documentation: api-workflows.html · latest: https://dev-api.sheetgo.com/rest/reference/workflows
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/workflows/ | Get a paginated list of workflows |
| POST | /rest/beta/workflows/ | Create a new workflow |
| POST | /rest/beta/workflows/run/{id} | (Obsolete) Use /workflows/<id>/run instead (deprecated) |
| GET | /rest/beta/workflows/{id} | Get a single workflow |
| PATCH | /rest/beta/workflows/{id} | Update an existing workflow |
| DELETE | /rest/beta/workflows/{id} | Archive a workflow |
| POST | /rest/beta/workflows/{id}/change-owner | Transfer workflow ownership |
| GET | /rest/beta/workflows/{id}/collaborators | List a workflow's collaborators |
| POST | /rest/beta/workflows/{id}/collaborators | Add collaborators to a workflow |
| DELETE | /rest/beta/workflows/{id}/collaborators | Remove all collaborators from a workflow |
| PATCH | /rest/beta/workflows/{id}/collaborators/{email} | Change a collaborator's role |
| DELETE | /rest/beta/workflows/{id}/collaborators/{email} | Remove a collaborator |
| GET | /rest/beta/workflows/{id}/destinations | Get file destinations of all automations in a workflow |
| GET | /rest/beta/workflows/{id}/files | Get file sources and destinations of all automations in a workflow |
| GET | /rest/beta/workflows/{id}/general-access | Get a workflow's general (domain/team) access |
| PUT | /rest/beta/workflows/{id}/general-access | Set a workflow's general (domain/team) access |
| DELETE | /rest/beta/workflows/{id}/general-access | Revoke a workflow's general (domain/team) access |
| POST | /rest/beta/workflows/{id}/leave | Leave a shared workflow |
| POST | /rest/beta/workflows/{id}/request-access | Ask a workflow's owner for access |
| GET | /rest/beta/workflows/{id}/run | Get a workflow's last-run status |
| POST | /rest/beta/workflows/{id}/run | Run a single workflow |
| GET | /rest/beta/workflows/{id}/sources | Get file sources of all automations in a workflow |
automations12 endpoints
An automation (also called a connection) is a single data transfer inside a workflow: it pulls data from one or more sources, optionally consolidates, filters or merges it, and writes the result to one or more destinations — all without manual copy-paste.
Full documentation: api-automations.html · latest: https://dev-api.sheetgo.com/rest/reference/automations
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/automations/ | Get a paginated list of automations |
| POST | /rest/beta/automations/ | Create a new automation |
| POST | /rest/beta/automations/run/{id} | (Obsolete) Use /automations/<id>/run instead (deprecated) |
| GET | /rest/beta/automations/{id} | Get a single automation |
| PUT | /rest/beta/automations/{id} | Replace an existing automation entirely |
| PATCH | /rest/beta/automations/{id} | Rename an automation |
| DELETE | /rest/beta/automations/{id} | Archive an automation |
| GET | /rest/beta/automations/{id}/destinations | Get file destinations of an automation |
| GET | /rest/beta/automations/{id}/files | Get file sources and destinations of an automation |
| GET | /rest/beta/automations/{id}/run | Get an automation's last-run status |
| POST | /rest/beta/automations/{id}/run | Run an automation |
| GET | /rest/beta/automations/{id}/sources | Get file sources of an automation |
triggers3 endpoints
A trigger defines what makes a workflow run automatically, so you set it once instead of running the workflow by hand. A trigger can be a recurring schedule (e.g. every 15 minutes, or every weekday at 09:00) or the completion of another workflow (chaining one run after another). Each workflow has at most one active trigger.
Full documentation: api-triggers.html · latest: https://dev-api.sheetgo.com/rest/reference/triggers
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/workflows/{id}/trigger | Get a workflow's automation trigger |
| PUT | /rest/beta/workflows/{id}/trigger | Set or replace a workflow's automation trigger |
| DELETE | /rest/beta/workflows/{id}/trigger | Turn off a workflow's automation trigger |
dashboards5 endpoints
Dashboards turn a workflow's data into shareable visual summaries. Each workflow has a single dashboard; add indicator, table and chart-reference elements to it, read an element's live values, and publish the dashboard to get a viewer URL.
Full documentation: api-dashboards.html · latest: https://dev-api.sheetgo.com/rest/reference/dashboards
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/workflows/{id}/dashboard | Get a workflow's dashboard |
| POST | /rest/beta/workflows/{id}/dashboard/elements | Add elements to a workflow's dashboard |
| DELETE | /rest/beta/workflows/{id}/dashboard/elements/{element_id} | Delete one dashboard element |
| GET | /rest/beta/workflows/{id}/dashboard/elements/{element_id}/data | Read one dashboard element's current values |
| PUT | /rest/beta/workflows/{id}/dashboard/publish | Publish or unpublish a workflow's dashboard |
Forms & Integrations
forms7 endpoints
A Sheetgo form collects data straight into a workflow. Its fields come from your spreadsheet's columns, and every submission is appended as a new row — a simple way to feed a workflow from people instead of another system.
Full documentation: api-forms.html · latest: https://dev-api.sheetgo.com/rest/reference/forms
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/workflows/{workflow_id}/forms/ | Get a paginated list of forms |
| POST | /rest/beta/workflows/{workflow_id}/forms/ | Create a new form |
| GET | /rest/beta/workflows/{workflow_id}/forms/{form_id} | Get a form |
| PATCH | /rest/beta/workflows/{workflow_id}/forms/{form_id} | Update an existing form |
| DELETE | /rest/beta/workflows/{workflow_id}/forms/{form_id} | Delete a form |
| GET | /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses | Get a form's responses (paginated) |
| HEAD | /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses | Inspect a form's responses metadata without downloading them |
webhook3 endpoints
A webhook is a private URL that lets external systems push data into a workflow over HTTP. Your app sends a JSON payload and Sheetgo lands it in the workflow — optionally triggering a full run — with no Google APIs or OAuth to manage on your side.
Full documentation: api-webhook.html · latest: https://dev-api.sheetgo.com/rest/reference/webhook
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/automations/{automation_id}/webhook | Retrieve an automation's webhook |
| POST | /rest/beta/webhook/{public_id} | Push values to a webhook and trigger its bound automation |
| GET | /rest/beta/workflows/{workflow_id}/webhooks | List a workflow's webhooks |
api-destination2 endpoints
API as a destination turns a workflow's output into a live, read-only JSON feed at a private URL. Each workflow run refreshes the data; consumers fetch it on demand with an API key, with pagination, sorting and conditional (ETag) requests.
Full documentation: api-api-destination.html · latest: https://dev-api.sheetgo.com/rest/reference/api-destination
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/api-destination/{public_id} | Read data from an API-as-Destination endpoint |
| HEAD | /rest/beta/api-destination/{public_id} | Inspect API-as-Destination metadata without downloading data |
integrations2 endpoints
Integrations are pre-configured sources for third-party services — currently Shopify and QuickBooks. Instead of describing an HTTP request yourself, you pick a data source from a menu and Sheetgo supplies the URL, credentials, pagination and response parsing for the account you authorized.
Full documentation: api-integrations.html · latest: https://dev-api.sheetgo.com/rest/reference/integrations
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/integrations | List integrations and connected accounts |
| GET | /rest/beta/integrations/{provider}/options | List a provider's data sources |
outlook5 endpoints
Integration endpoints used by the Sheetgo add-in for Microsoft Outlook to connect mailbox data to workflows.
Full documentation: api-outlook.html · latest: https://dev-api.sheetgo.com/rest/reference/outlook
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/outlook/messages | List Messages |
| POST | /rest/beta/outlook/messages/batch | Batch Messages |
| GET | /rest/beta/outlook/messages/{message_id} | Get Message |
| GET | /rest/beta/outlook/messages/{message_id}/attachments/{attachment_id} | Get Attachment |
| POST | /rest/beta/outlook/send | Send |
gmail1 endpoint
Send email through a connected Google account.
Full documentation: api-gmail.html · latest: https://dev-api.sheetgo.com/rest/reference/gmail
| Method | Path | What it does |
|---|---|---|
| POST | /rest/beta/gmail/send | Send |
Storage
files5 endpoints
Browse and search the storage providers connected to your account — Google Drive, OneDrive, SharePoint and Dropbox — to find the ids you need when building an automation.
Full documentation: api-files.html · latest: https://dev-api.sheetgo.com/rest/reference/files
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/files/{provider} | Browse a folder |
| GET | /rest/beta/files/{provider}/roots | List browsable entry points |
| GET | /rest/beta/files/{provider}/search | Search files and folders by name |
| GET | /rest/beta/files/{provider}/{file_id} | Get one file or folder |
| GET | /rest/beta/files/{provider}/{file_id}/structure | Describe what is inside a file |
bigquery5 endpoints
BigQuery can be both a source and a destination for an automation: read a table or a query's results into a spreadsheet, or load a spreadsheet's rows into a BigQuery table.
Full documentation: api-bigquery.html · latest: https://dev-api.sheetgo.com/rest/reference/bigquery
| Method | Path | What it does |
|---|---|---|
| GET | /rest/beta/bigquery/projects | List BigQuery projects |
| GET | /rest/beta/bigquery/projects/{project}/datasets | List a project's datasets |
| GET | /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables | List a dataset's tables |
| GET | /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table} | Read one table's schema |
| POST | /rest/beta/bigquery/projects/{project}/validate-query | Validate a query without running it |
Authentication
auth2 endpoints
OAuth2 authorization endpoints — exchange a Client ID / Client Secret for an access token, for developer and customer integrations. For most use cases an API key generated on your Account page is simpler (see Authentication above).
Full documentation: api-auth.html · latest: https://dev-api.sheetgo.com/rest/reference/auth
| Method | Path | What it does |
|---|---|---|
| POST | /rest/auth/refresh | Creates a new access token from a refresh token |
| POST | /rest/auth/token | Exchange authentication code for a access token and a refresh token |
Guides
| Guide | What it covers |
|---|---|
| Rate Limiting | To keep the platform fast and fair, the API limits how many requests each account can make in a short window. If you exceed the limit, further requests are temporarily rejected with HTTP 429 (Too Many Requests) until the window resets. Rate limits protect you too — they stop a runaway script from exhausting your account's capacity. |
| API Key Scopes | Sheetgo API keys let apps, scripts, and AI agents act on your Sheetgo account. By default a key can do everything you can — read, edit, run, and delete any workflow, automation, form, and more. |
| Smart Tags | A smart tag is a {{placeholder}} that Sheetgo replaces with a value from your data while an automation runs. They are used by the document destination — both inside the Google Docs template and in the destination's file_name. |
| Cell References | A cell reference is a {{Tab!Ref}} placeholder you put inside an api source's request. When the automation runs, Sheetgo reads that cell from the automation's Google Sheets destination and substitutes the value before the request goes out — so the request changes as your sheet changes, with no API call needed. |