# 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](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md)

Guide: [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md)

Guide: [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md)

Every endpoint is rate limited; see the guide [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md).

<a id="post-rest-beta-automations-run-id"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/SuccessResponse.md)
- `404` Not found
- `401` Authentication failed or token is invalid
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [SuccessResponse](https://dev-api.sheetgo.com/rest/reference/models/SuccessResponse.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="get-rest-beta-automations-id-run"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/AutomationRunStatus.md)
- `404` Automation not found
- `401` Authentication failed or token is invalid
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [AutomationRunStatus](https://dev-api.sheetgo.com/rest/reference/models/AutomationRunStatus.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="post-rest-beta-automations-id-run"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/SuccessResponse.md)
- `404` Not found
- `401` Authentication failed or token is invalid
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [SuccessResponse](https://dev-api.sheetgo.com/rest/reference/models/SuccessResponse.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="get-rest-beta-automations-id-files"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="get-rest-beta-automations-id-sources"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="get-rest-beta-automations-id-destinations"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="get-rest-beta-automations-id"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/AutomationModel.md)
- `404` Not found
- `401` Authentication failed or token is invalid
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [AutomationModel](https://dev-api.sheetgo.com/rest/reference/models/AutomationModel.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="put-rest-beta-automations-id"></a>
## 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:

1. `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.
2. Pick the letter from `tabs[].columns`, e.g. `{"letter": "D", "index": 3, "header": "Status"}`.
3. Use it in the automation:

```json
"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](https://dev-api.sheetgo.com/rest/reference/models/AutomationReplace.md)

**Responses**

- `200` The automation model updated. Schema: [AutomationModel](https://dev-api.sheetgo.com/rest/reference/models/AutomationModel.md)
- `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)

Read next: [AutomationModel](https://dev-api.sheetgo.com/rest/reference/models/AutomationModel.md), [AutomationReplace](https://dev-api.sheetgo.com/rest/reference/models/AutomationReplace.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="patch-rest-beta-automations-id"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/AutomationPatch.md)

**Responses**

- `200` The automation model updated. Schema: [AutomationModel](https://dev-api.sheetgo.com/rest/reference/models/AutomationModel.md)
- `404` Not found
- `401` Authentication failed or token is invalid
- `422` `name` missing or empty, or a field other than `name` (PATCH only renames)

Read next: [AutomationModel](https://dev-api.sheetgo.com/rest/reference/models/AutomationModel.md), [AutomationPatch](https://dev-api.sheetgo.com/rest/reference/models/AutomationPatch.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="delete-rest-beta-automations-id"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/SuccessResponse.md)
- `404` Not found
- `401` Authentication failed or token is invalid
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [SuccessResponse](https://dev-api.sheetgo.com/rest/reference/models/SuccessResponse.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="get-rest-beta-automations"></a>
## 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_](https://dev-api.sheetgo.com/rest/reference/models/PaginatedResponse_AutomationModel_.md)
- `404` Not found
- `401` Authentication failed or token is invalid
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [PaginatedResponse_AutomationModel_](https://dev-api.sheetgo.com/rest/reference/models/PaginatedResponse_AutomationModel_.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

<a id="post-rest-beta-automations"></a>
## POST /rest/beta/automations/

**Create a new automation**

**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:

1. `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.
2. Pick the letter from `tabs[].columns`, e.g. `{"letter": "D", "index": 3, "header": "Status"}`.
3. Use it in the automation:

```json
"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 |
| --- | --- | --- | --- | --- | --- |
| `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](https://dev-api.sheetgo.com/rest/reference/models/AutomationCreate.md)

**Responses**

- `200` The automation model created. Schema: [AutomationModel](https://dev-api.sheetgo.com/rest/reference/models/AutomationModel.md)
- `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)

Read next: [AutomationCreate](https://dev-api.sheetgo.com/rest/reference/models/AutomationCreate.md), [AutomationModel](https://dev-api.sheetgo.com/rest/reference/models/AutomationModel.md), [Smart Tags](https://dev-api.sheetgo.com/rest/guides/smart-tags.md), [Cell References](https://dev-api.sheetgo.com/rest/guides/cell-references.md).

---

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.