automations

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.

Use these endpoints to list, create, read, replace, update, run and archive automations, and to inspect their source and destination files.

Base URL: https://dev-api.sheetgo.com. Start page: https://dev-api.sheetgo.com/rest/reference.md

This page documents every endpoint of the group. Request and response shapes link to model pages; fetch the model pages an endpoint links before building a body.

Guide: Rate Limiting

Guide: Smart Tags

Guide: Cell References

Every endpoint is rate limited; see the guide Rate Limiting.

POST /rest/beta/automations/run/{id}

(Obsolete) Use /automations/<id>/run instead

Deprecated

This endpoint will be removed

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Responses

200 successful operation. Schema: SuccessResponse
404 Not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

GET /rest/beta/automations/{id}/run

Get an automation's last-run status

Last-run execution status of a single automation (latest only — no history).

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Responses

200 Automation last-run status. Schema: AutomationRunStatus
404 Automation not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

POST /rest/beta/automations/{id}/run

Run an automation

Given an automation Id, the automation will start its execution

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Responses

200 successful operation. Schema: SuccessResponse
404 Not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

GET /rest/beta/automations/{id}/files

Get file sources and destinations of an automation

Return the sources and destinations of an automation.

Every source type is included (file, folder, api, webhook, integration, bigquery, outlook); write-only fields such as an api source's headers are omitted.

Destinations include generated-document and PDF destinations, which are backed by a Drive folder (and, for documents, the Docs template).

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Responses

200 File sources and destinations of the automation
404 Not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

GET /rest/beta/automations/{id}/sources

Get file sources of an automation

Return the sources of an automation.

Every source type is included (file, folder, api, webhook, integration, bigquery, outlook), in the shape GET /automations/{id} returns; write-only fields such as an api source's headers are omitted.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Responses

200 File sources of the automation
404 Not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

GET /rest/beta/automations/{id}/destinations

Get file destinations of an automation

Return the file/folder destinations of an automation.

Destinations include generated-document and PDF destinations, which are backed by a Drive folder (and, for documents, the Docs template).

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Responses

200 File destinations of the automation
404 Not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

GET /rest/beta/automations/{id}

Get a single automation

Given an automation id, returns the automation model data

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Responses

200 The automation model data. Schema: AutomationModel
404 Not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

PUT /rest/beta/automations/{id}

Replace an existing automation entirely

Column letters. Every column field — filter (columns, expressions[].column), split.column, left_join.column, remove_duplicates.columns and anonymize.columns keys — takes the spreadsheet column LETTER (D), not the header name (Status), because the engine addresses columns by position. A header name is rejected with 422 invalid_column.

To find the letter, read the source file's header row first:

GET /files/{provider}/{file_id}/structure?include=columns&tab=Orders&header_row=1 — use the source's id and provider, the tab you import and its offset_header as header_row. A folder id reads its newest spreadsheet.
Pick the letter from tabs[].columns, e.g. {"letter": "D", "index": 3, "header": "Status"}.
Use it in the automation:

"filter": {"type": "condition", "condition_type": "and",
           "expressions": [{"column": "D", "criteria": "text_is_exactly", "value": "open"}]}

The structure call works for Google Sheets, Excel, CSV and TSV on every provider. It reads the file, so call it once per source and reuse the result; repeat calls are cached until the file changes.

Processor combinations. ai, filter, remove_duplicates and anonymize can each be used on their own, and merge / left_join combine with them. These combinations are not allowed today because the features are incompatible in the engine, and are rejected with 422 invalid_processor_combination:

Combination	Why
`ai` + `remove_duplicates` / `anonymize`	the engine runs the AI step or the transformers, never both — the transformer would be silently skipped
`filter` + `remove_duplicates` / `anonymize`	the header row is lost and the first data row is corrupted
`remove_duplicates` + `anonymize`	same — and a row could be left unmasked

Automations created before this rule keep running unchanged.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Request body

Content type application/json. Optional.

Body: AutomationReplace

Responses

200 The automation model updated. Schema: AutomationModel
404 Not found
401 Authentication failed or token is invalid
403 The plan does not include this destination type
422 Invalid destination combination, recipient format, api-source shape, integration source, endpoint, api destination or bigquery combination, documents automation (invalid_documents_automation), file_filter (invalid_file_filter), Outlook automation (invalid_outlook_automation), email_filter (invalid_email_filter), or a processor combination that is not allowed (invalid_processor_combination), or a column that is not a spreadsheet letter (invalid_column)
412 send_from names an Outlook account that is not connected or cannot send mail (outlook_not_connected), or ai.model / ai.model_settings without your own OpenAI account (openai_not_connected), or an Outlook source whose account cannot read mail (outlook_not_connected, Mail.Read)

PATCH /rest/beta/automations/{id}

Rename an automation

Renames only. The body is {"name": "…"}; any other field is rejected with 422. To change sources, destinations or processors (filter, merge, ai, left_join, remove_duplicates, split, anonymize), GET the automation, edit it and send it back with PUT — GET returns everything PUT accepts, so the rest of the automation is kept.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Request body

Content type application/json. Required.

Body: AutomationPatch

Responses

200 The automation model updated. Schema: AutomationModel
404 Not found
401 Authentication failed or token is invalid
422 name missing or empty, or a field other than name (PATCH only renames)

DELETE /rest/beta/automations/{id}

Archive an automation

Given a workflow id, archive the workflow

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Automation identification

Responses

200 The automation was successfully archived. Schema: SuccessResponse
404 Not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

GET /rest/beta/automations/

Get a paginated list of automations

Return a list of automations following the pagination parameters

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`page`	query	integer	no	Page number, 1-based	default: `1`; min: 1
`per_page`	query	integer	no	Number of items per page (1-100; values above 100 are clamped to 100 and the effective size is echoed in the response)	default: `50`; min: 1

Responses

200 A paginated list of automations. Schema: PaginatedResponse_AutomationModel_
404 Not found
401 Authentication failed or token is invalid
422 Validation Error. Schema: HTTPValidationError

POST /rest/beta/automations/

Create a new automation

To find the letter, read the source file's header row first:

GET /files/{provider}/{file_id}/structure?include=columns&tab=Orders&header_row=1 — use the source's id and provider, the tab you import and its offset_header as header_row. A folder id reads its newest spreadsheet.
Pick the letter from tabs[].columns, e.g. {"letter": "D", "index": 3, "header": "Status"}.
Use it in the automation:

"filter": {"type": "condition", "condition_type": "and",
           "expressions": [{"column": "D", "criteria": "text_is_exactly", "value": "open"}]}

The structure call works for Google Sheets, Excel, CSV and TSV on every provider. It reads the file, so call it once per source and reuse the result; repeat calls are cached until the file changes.

Combination	Why
`ai` + `remove_duplicates` / `anonymize`	the engine runs the AI step or the transformers, never both — the transformer would be silently skipped
`filter` + `remove_duplicates` / `anonymize`	the header row is lost and the first data row is corrupted
`remove_duplicates` + `anonymize`	same — and a row could be left unmasked

Automations created before this rule keep running unchanged.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`x-run`	header	boolean, nullable	no	Set to true to run the automation immediately after creating it. The run is queued, so the response returns before it finishes — poll `GET /rest/beta/automations/{id}/run` for the outcome.	default: `false`

Request body

Content type application/json. Optional.

Body: AutomationCreate

Responses

200 The automation model created. Schema: AutomationModel
404 Not found
401 Authentication failed or token is invalid
403 The plan does not include this destination type
422 Invalid destination combination, recipient format, api-source shape, integration source, endpoint, api destination or bigquery combination, documents automation (invalid_documents_automation), file_filter (invalid_file_filter), Outlook automation (invalid_outlook_automation), email_filter (invalid_email_filter), or a processor combination that is not allowed (invalid_processor_combination), or a column that is not a spreadsheet letter (invalid_column)
412 send_from names an Outlook account that is not connected or cannot send mail (outlook_not_connected), or ai.model / ai.model_settings without your own OpenAI account (openai_not_connected), or an Outlook source whose account cannot read mail (outlook_not_connected, Mail.Read)

More: start page https://dev-api.sheetgo.com/rest/reference.md, everything in one file https://dev-api.sheetgo.com/rest/llms-full.txt, OpenAPI https://dev-api.sheetgo.com/rest/openapi.json.