Models used on this page
Every request and response model referenced above, including nested ones (64). The full catalogue is on api-models.html.
AutomationRunStatus
The outcome of an automation's LAST run. There is no run history.
| Field | Type | | Description |
|---|
automation_id | string | required | Id of the automation this status belongs to. |
docs_link | string | nullable | URL of the help article for this error, when one exists. Null unless result is error. |
duration_seconds | number | nullable | How long the last run took, in seconds. Null before the first run completes. |
error_count | integer | nullable | Number of individual errors recorded during the run (a run can fail on several rows or files). Null when not tracked. |
execution | string | required | Live phase: running while the run is enqueued, executing or cancelling; completed once it has stopped. Poll until this is completed before trusting result. |
message | string | nullable | Human-readable explanation of the run's outcome — the stored run message when there is one, otherwise the standard description for status_code. Null on success and before the first run. |
result | string | required | Outcome of the last finished run: never_run (it has not run yet), success, or error. While execution is running, this still describes the PREVIOUS run. |
status_code | integer | optional | Sheetgo result code behind result: 0 = never run, 1 = success, anything greater = the specific error. Useful when you want to branch on the exact failure.
Default: 0 |
Used by: GET /rest/beta/automations/{id}/run
BigQueryPartition
Partitioning for a table Sheetgo creates.
Omit field for ingestion-time partitioning; name a column for
field-based. There is no third setting: BigQuery infers the partition
column's type from the table schema, so presence of field is the whole
distinction.
Only applied when the table is created. An existing table keeps its own
partitioning, so change it with write_mode: "recreate".
| Field | Type | | Description |
|---|
field | string | nullable | Column to partition by. It must exist in the transferred data -- check with GET /rest/beta/bigquery/.../tables/{table}. Omit for ingestion-time partitioning. |
granularity | BigQueryPartitionGranularity | optional | Partition size: HOUR, DAY, MONTH or YEAR.
Default: "DAY" |
require_filter | boolean | optional | Require queries against the table to filter on the partition column. Applied only when the table is created.
Default: false |
BigQueryPartitionGranularity
Type: one of "HOUR", "DAY", "MONTH", "YEAR"
BigQueryWriteMode
What happens to data already in the destination table.
Read by BigQueryManager.merge_temporary_to_destination.
Type: one of "append", "truncate", "recreate"
ChangeOwnerIn
| Field | Type | | Description |
|---|
email | string (email) | required | Email of the collaborator to transfer ownership to. They must already be a collaborator on the workflow; the current owner becomes a manager. |
Used by: POST /rest/beta/workflows/{id}/change-owner
CollaboratorOut
| Field | Type | | Description |
|---|
email | string | required | The collaborator's email address, which identifies them everywhere in this API. |
is_owner | boolean | optional | True for the workflow's owner. The owner cannot be removed or have their role changed — transfer ownership instead.
Default: false |
role | string | required | owner | manager | collaborator |
CollaboratorRoleUpdate
| Field | Type | | Description |
|---|
role | one of "collaborator", "manager" | required | The role to move this collaborator to: collaborator or manager. The owner's role cannot be changed here. |
update_file_access | boolean | optional | Also grant/revoke file access to match the role
Default: false |
Used by: PATCH /rest/beta/workflows/{id}/collaborators/{email}
CollaboratorsAdd
| Field | Type | | Description |
|---|
emails | array of string (email) | required | Emails to invite
Min items: 1 |
file_access | one of "reader", "commenter", "writer" | optional | File permission when share_files is true
Default: "writer" |
message | string | nullable | Optional note included in the invitation |
role | one of "collaborator", "manager" | required | collaborator | manager |
share_files | boolean | optional | Also grant access to the workflow's files
Default: false |
skip_invitation | boolean | optional | Add silently, without the invitation email
Default: false |
Used by: POST /rest/beta/workflows/{id}/collaborators
CollaboratorsOut
| Field | Type | | Description |
|---|
collaborators | array of CollaboratorOut | optional | Everyone with access to the workflow, the owner included. |
owner | string | nullable | Email of the workflow's owner. |
Used by: GET /rest/beta/workflows/{id}/collaborators, POST /rest/beta/workflows/{id}/collaborators, PATCH /rest/beta/workflows/{id}/collaborators/{email}, DELETE /rest/beta/workflows/{id}/collaborators/{email}
ContentType
What a folder source reads: spreadsheets, or documents for AI extraction.
Type: one of "spreadsheets", "documents"
DestinationApiPublish
Publish the automation's rows to a Sheetgo-hosted endpoint you can poll.
Read it back with GET /rest/beta/api-destination/{public_id}, which needs
an API key carrying the api-destination scope.
| Field | Type | | Description |
|---|
append | boolean | optional | Add each run's rows under the previous ones instead of replacing them. The column headers must match the existing ones or the run fails.
Default: false |
public_id | string | nullable | Read-only. Assigned by Sheetgo when the automation is created; ignored if you send it. |
type | "api" | required | Publishes the rows as a read-only JSON API endpoint hosted by Sheetgo. |
url | string | nullable | Read-only. Where to fetch the published data. Requires an API key with the api-destination scope. |
DestinationBigQuery-Output
Load the automation's rows into a BigQuery table.
The table is created on the first run if it does not exist; the dataset
is not, and must already exist.
Must be the automation's only destination, and at most one per automation --
see validate_bigquery_automation.
| Field | Type | | Description |
|---|
dataset | string | required | Existing BigQuery dataset id. Sheetgo does not create datasets. |
partition | BigQueryPartition | nullable | Omit for an unpartitioned table. |
project | string | required | GCP project id |
schema_evolution | boolean | optional | Add columns to the destination table when the transferred data has new ones. With the default false, extra columns fail the run instead. Only ever adds -- never removes, renames or retypes.
Default: false |
table | string | required | Table id. Created on the first run if it does not exist. |
type | "bigquery" | required | Writes the rows into a BigQuery table. Must be the only destination. |
write_mode | BigQueryWriteMode | optional | append adds rows; truncate clears the data but keeps the schema and partitioning; recreate drops and rebuilds the table from the transferred data.
Default: "append" |
DestinationDocument
Generate one Google Docs file per row from a template (docs-merge).
| Field | Type | | Description |
|---|
file_name | string | required | Name pattern for each generated document. Supports {{Column}} smart tags, which are replaced with that row's value — e.g. "Invoice {{Customer}} {{Month}}". See the Smart Tags section. |
folder_name | string | nullable | Name of a new folder to create instead of using an existing one. Provide this or id. |
generator_controller | boolean | optional | Add a column to the source data holding a link to each generated document.
Default: true |
generator_controller_prefix | string | nullable | Prefix for the control column's header. Defaults to the automation name. |
id | string | nullable | Id of an existing folder to write into. Provide this or folder_name. |
markdown_formatting | boolean | optional | Render markdown found in cell values as formatted text in the document.
Default: false |
parent_id | string | nullable | Folder to create folder_name inside. Defaults to the drive root. Only valid together with folder_name. |
provider | "drive" | optional | Storage provider. Generated documents and PDFs are Google Drive only.
Default: "drive" |
template_id | string | required | Id of the Google Docs file used as the template. Google Drive only. Google Docs are not returned by default by the file endpoints — find one with GET /rest/beta/files/drive?type=gdocs. |
type | "document" | required | Generates a Google Docs document per row from a template (docs-merge). |
unused_fields | UnusedFields | optional | What to do when a {{Tag}} in the template matches no source column: error fails the run, ignore leaves it blank.
Default: "error" |
DestinationFile
| Field | Type | | Description |
|---|
append | boolean | nullable | Data will be added under previous entries to track historical changes
Default: false |
enforce_header_match | boolean | optional | Documents folder source only: line documents' columns up by position instead of by name. Ignored with one_tab_per_document.
Default: false |
file_type | FileType | required | The file type |
id | string | required | Id of the destination file or folder |
identify_data | IdentifyDataType | nullable | It will create an extra column in the destination tab, identifying the latest transfers of your new sheet and/or the source file of each row of data, making data traceable when merging sources. |
lock_destination_tab | boolean | nullable | Lock the destination tab and clear added columns with each transfer
Default: true |
one_tab_per_document | boolean | optional | Documents folder source only: one tab per document (up to 100) instead of all documents in one tab.
Default: false |
parse_data | boolean | nullable | Convert text to numbers, dates, and formulas
Default: true |
provider | Provider | required | The storage provider that hosts the file or folder |
sheet_name | string | nullable | The sheet name |
type | "file" | required | Writes the result into an existing file. |
write_summary_tab | boolean | optional | Documents folder source only: add a Files tab listing each document read, its status and row count.
Default: false |
DestinationFolder
| Field | Type | | Description |
|---|
append | boolean | nullable | Data will be added under previous entries to track historical changes
Default: false |
enforce_header_match | boolean | optional | Documents folder source only: line documents' columns up by position instead of by name. Ignored with one_tab_per_document.
Default: false |
file_type | "folder" | optional | Always folder. Fixed by the destination type; present so folder and file destinations share one shape.
Default: "folder" |
folder_name | string | nullable | Outlook source only: name of a new folder Sheetgo creates when the automation is saved. Provide this or id. Each create makes a new folder (a repeated POST makes another); GET then returns its id. |
id | string | nullable | Id of an existing folder. Provide this or folder_name. |
identify_data | IdentifyDataType | nullable | It will create an extra column in the destination tab, identifying the latest transfers of your new sheet and/or the source file of each row of data, making data traceable when merging sources. |
lock_destination_tab | boolean | nullable | Lock the destination tab and clear added columns with each transfer
Default: true |
one_tab_per_document | boolean | optional | Documents folder source only: one tab per document (up to 100) instead of all documents in one tab.
Default: false |
parent_id | string | nullable | Folder to create folder_name inside. Defaults to the provider's root. Only valid with folder_name. |
parse_data | boolean | nullable | Convert text to numbers, dates, and formulas
Default: true |
provider | Provider | required | The storage provider that hosts the file or folder |
sheet_name | string | nullable | The sheet name |
type | "folder" | required | Writes into a folder: new files per split value, or the files an Outlook source saves. |
write_summary_tab | boolean | optional | Documents folder source only: add a Files tab listing each document read, its status and row count.
Default: false |
DestinationMailMerge
Send one personalized email per row, rendered from body.
| Field | Type | | Description |
|---|
bcc | array of string (email) or string | nullable | Bcc recipients. Same forms as to. |
body | string | required | Email body template as plain text. Each line becomes one paragraph. {{Column}} smart tags are replaced per row. |
cc | array of string (email) or string | nullable | Cc recipients. Same forms as to. |
generator_controller | boolean | optional | Add a column to the source data tracking each email sent.
Default: true |
generator_controller_prefix | string | nullable | Prefix for the control column's header. Defaults to the automation name. |
markdown_formatting | boolean | optional | Render markdown found in cell values as formatted text.
Default: false |
multiple_email_split | boolean | optional | Send a separate email per address when a column holds several.
Default: false |
remove_sheetgo_layout | boolean | optional | Send without the Sheetgo email layout.
Default: false |
reply_to | string | nullable | Reply-To: one address, or a "{{Header}}" reference. |
send_from | SendFrom | optional | Which mailbox sends the emails: gmail (default), outlook_personal (a personal Microsoft account) or outlook_work (a work or school Microsoft account). An Outlook account must be connected in Sheetgo with permission to send mail, or the request is rejected with 412 outlook_not_connected.
Default: "gmail" |
subject | string | required | Email subject. Supports {{Column}} smart tags. |
to | array of string (email) or string | required | Recipients: a list of addresses, one address, or a "{{Header}}" reference to read the address from a column. |
track_click | boolean | optional | Track when a recipient clicks a link.
Default: false |
track_open | boolean | optional | Track when a recipient opens the email.
Default: false |
type | "mail_merge" | required | Sends one personalized email per row (mail merge). |
unused_fields | UnusedFields | optional | What to do when a {{Tag}} matches no source column: error fails the run, ignore leaves it blank.
Default: "error" |
use_plain_text | boolean | optional | Send the body as plain text instead of formatted HTML.
Default: false |
DestinationPDF
Export the automation's output to PDF into a Drive folder (converter).
What gets converted depends on the automation's other destinations: with a
document destination the generated documents are converted; with a file
destination the file written by the automation is converted; with neither,
the automation's source files are.
| Field | Type | | Description |
|---|
folder_name | string | nullable | Name of a new folder to create instead of using an existing one. Provide this or id. |
id | string | nullable | Id of an existing folder to write into. Provide this or folder_name. |
merge_files | boolean | optional | Combine every generated PDF into a single file.
Default: false |
page_orientation | PageOrientation | optional | Page orientation of the generated PDF.
Default: "portrait" |
paper_size | PaperSize | optional | Page size of the generated PDF.
Default: "letter" |
parent_id | string | nullable | Folder to create folder_name inside. Defaults to the drive root. Only valid together with folder_name. |
provider | "drive" | optional | Storage provider. Generated documents and PDFs are Google Drive only.
Default: "drive" |
scale | one of 1, 2, 3, 4 | optional | Fit-to-page scaling: 1 normal, 2 fit to width, 3 fit to height, 4 fit to page.
Default: 1 |
type | "pdf" | required | Generates a PDF per row, by converting the merged document. |
DestinationShare
Email the files this automation produced.
| Field | Type | | Description |
|---|
bcc | array of string (email) or string | nullable | Bcc recipients. Same forms as to. |
body | string | nullable | Email body as plain text. Each line becomes one paragraph. Supports {{Column}} smart tags. |
cc | array of string (email) or string | nullable | Cc recipients. Same forms as to. |
file_access_role | FileAccessRole | optional | Access granted by a shared link. Ignored for attachments.
Default: "writer" |
file_sending_method | FileSendingMethod | optional | Send the files as shared links or as attachments.
Default: "shared_link" |
group_files_by_recipient | boolean | optional | Send one email per recipient covering all their files, instead of one email per file.
Default: true |
multiple_email_split | boolean | optional | Send a separate email per address when a column holds several.
Default: false |
remove_sheetgo_layout | boolean | optional | Send without the Sheetgo email layout.
Default: false |
reply_to | string | nullable | Reply-To: one address, or a "{{Header}}" reference. |
send_from | SendFrom | optional | Alpha — sending share emails from Outlook is not offered in the Sheetgo web app yet and may change. Which mailbox sends the emails: gmail (default), outlook_personal (a personal Microsoft account) or outlook_work (a work or school Microsoft account). An Outlook account must be connected in Sheetgo with permission to send mail, or the request is rejected with 412 outlook_not_connected.
Default: "gmail" |
subject | string | required | Email subject. Supports {{Column}} smart tags. |
to | array of string (email) or string | required | Recipients: a list of addresses, one address, or a "{{Header}}" reference to read the address from a column. |
track_click | boolean | optional | Track when a recipient clicks a link.
Default: false |
track_open | boolean | optional | Track when a recipient opens the email.
Default: false |
type | "share" | required | Emails the automation's output as an attachment or link. |
use_plain_text | boolean | optional | Send the body as plain text instead of formatted HTML.
Default: false |
DestinationWebhook
POST the automation's rows to an endpoint you own.
Note the direction: as a source, webhook means Sheetgo mints a URL
you POST into; as a destination it means Sheetgo POSTs out to a URL
you own.
Must be the automation's only destination — see validate_api_automation.
| Field | Type | | Description |
|---|
body | string | optional | Body template. {{DATA}} is every row including the header, {{ROWS}} is the rows as objects keyed by header; {{for}}, {{if}} and {{except-last}} are also available. This is a different syntax from smart tags and from cell references.
Default: "{{DATA}}" |
endpoint | string | required | URL that receives the request. |
headers | object (map of string → string) | nullable | HTTP headers sent with the request. Write-only — never returned by a read, and a PUT that omits it clears it. |
method | one of "post", "put", "patch", "delete" | optional | HTTP method used to send the data.
Default: "post" |
type | "webhook" | required | POSTs the resulting rows to your endpoint (outgoing webhook). Must be the only destination. |
EmailFilter-Output
Which emails an Outlook source reads. Groups nest (at most 3 deep).
| Field | Type | | Description |
|---|
condition_type | one of "and", "or" | optional | and: every rule must match; or: any rule.
Default: "and" |
rules | array of EmailFilter-Output or EmailFilterRule | required | Conditions or nested groups.
Min items: 1 |
EmailFilterRule
One condition of an Outlook source's email_filter.
| Field | Type | | Description |
|---|
field | one of "subject", "sender", "to", "cc", "attachment_name", "attachment_size", "has_attachment" | required | subject, sender (from address), to, cc (addresses), attachment_name, attachment_size (MB) or has_attachment. |
operator | string | required | Text fields: contains, not_contains, is, is_empty, is_not_empty. attachment_size: greater_than, greater_or_equal, less_than, less_or_equal, is_not. has_attachment: is. |
value | boolean or integer or number or string | nullable | Text for text fields (omit for is_empty / is_not_empty); a number of MB for attachment_size; true or false for has_attachment. |
FileAccessRole
Type: one of "reader", "writer"
FileFilter-Output
Which files inside a folder source are read. Groups nest.
| Field | Type | | Description |
|---|
condition_type | one of "and", "or" | optional | and: every rule must match; or: any rule.
Default: "and" |
rules | array of FileFilter-Output or FileFilterRule | required | Conditions or nested groups.
Min items: 1 |
FileFilterRule
One condition of a folder source's file_filter.
| Field | Type | | Description |
|---|
field | one of "file_name", "file_type", "date_modified", "content" | required | What to test: file_name, file_type, date_modified or content (an emptiness check by size, not a text search). |
operator | string | required | file_name: contains, not_contains, starts_with, is. file_type: is, is_not. date_modified: within, before, after, between. content: is_empty, is_not_empty, is_near_empty, is_not_near_empty. |
value | string | nullable | Text for file_name; a type for file_type (google_sheets, excel, csv, tsv, pdf, google_docs); today/last_week/last_month for within; a YYYY-MM-DD date for before / after / between. Omit for content. |
value_to | string | nullable | End date (YYYY-MM-DD) for between only. |
FileSendingMethod
How the files reach the recipient. Wire values use a hyphen.
Type: one of "shared_link", "attachment"
FileType
Type: one of "gsheets", "xlsx", "csv", "tsv", "folder"
GeneralAccessOut
| Field | Type | | Description |
|---|
access_type | string | required | restrict | domain | team |
role | string | nullable | The role granted to everyone covered by access_type. Null when access_type is restrict, where nobody is covered. |
Used by: GET /rest/beta/workflows/{id}/general-access, PUT /rest/beta/workflows/{id}/general-access, DELETE /rest/beta/workflows/{id}/general-access
GeneralAccessSet
| Field | Type | | Description |
|---|
access_type | one of "restrict", "domain", "team" | required | Who gets access beyond the named collaborators: restrict (nobody), domain (anyone in the owner's email domain) or team (the owner's Sheetgo team). |
role | one of "collaborator", "manager" | nullable | Role to grant them — collaborator or manager. Ignored when access_type is restrict. |
Used by: PUT /rest/beta/workflows/{id}/general-access
HTTPValidationError
Used by: GET /rest/beta/workflows/, POST /rest/beta/workflows/, POST /rest/beta/workflows/run/{id}, GET /rest/beta/workflows/{id}, PATCH /rest/beta/workflows/{id}, DELETE /rest/beta/workflows/{id}, GET /rest/beta/workflows/{id}/collaborators, POST /rest/beta/workflows/{id}/collaborators, DELETE /rest/beta/workflows/{id}/collaborators, PATCH /rest/beta/workflows/{id}/collaborators/{email}, DELETE /rest/beta/workflows/{id}/collaborators/{email}, GET /rest/beta/workflows/{id}/destinations, GET /rest/beta/workflows/{id}/files, GET /rest/beta/workflows/{id}/general-access, PUT /rest/beta/workflows/{id}/general-access, DELETE /rest/beta/workflows/{id}/general-access, POST /rest/beta/workflows/{id}/leave, POST /rest/beta/workflows/{id}/request-access, GET /rest/beta/workflows/{id}/run, POST /rest/beta/workflows/{id}/run, GET /rest/beta/workflows/{id}/sources, GET /rest/beta/automations/, POST /rest/beta/automations/run/{id}, GET /rest/beta/automations/{id}, DELETE /rest/beta/automations/{id}, GET /rest/beta/automations/{id}/destinations, GET /rest/beta/automations/{id}/files, GET /rest/beta/automations/{id}/run, POST /rest/beta/automations/{id}/run, GET /rest/beta/automations/{id}/sources, GET /rest/beta/workflows/{id}/trigger, DELETE /rest/beta/workflows/{id}/trigger, GET /rest/beta/workflows/{id}/dashboard, DELETE /rest/beta/workflows/{id}/dashboard/elements/{element_id}, GET /rest/beta/workflows/{id}/dashboard/elements/{element_id}/data, PUT /rest/beta/workflows/{id}/dashboard/publish, GET /rest/beta/workflows/{workflow_id}/forms/, POST /rest/beta/workflows/{workflow_id}/forms/, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}, PATCH /rest/beta/workflows/{workflow_id}/forms/{form_id}, DELETE /rest/beta/workflows/{workflow_id}/forms/{form_id}, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses, HEAD /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses, GET /rest/beta/automations/{automation_id}/webhook, GET /rest/beta/workflows/{workflow_id}/webhooks, GET /rest/beta/api-destination/{public_id}, HEAD /rest/beta/api-destination/{public_id}, GET /rest/beta/integrations/{provider}/options, GET /rest/beta/outlook/messages, POST /rest/beta/outlook/messages/batch, GET /rest/beta/outlook/messages/{message_id}, GET /rest/beta/outlook/messages/{message_id}/attachments/{attachment_id}, POST /rest/beta/outlook/send, POST /rest/beta/gmail/send, GET /rest/beta/files/{provider}, GET /rest/beta/files/{provider}/roots, GET /rest/beta/files/{provider}/search, GET /rest/beta/files/{provider}/{file_id}, GET /rest/beta/bigquery/projects, GET /rest/beta/bigquery/projects/{project}/datasets, GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables, GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}, POST /rest/beta/bigquery/projects/{project}/validate-query, POST /rest/auth/refresh, POST /rest/auth/token
IdentifyDataType
Type: one of "source_file_location", "source_file_name", "source_file_creation_date", "source_file_update_date", "source_tab_name", "destination_file_transfer_datetime"
ImportMode
Which files a folder source imports, ordered by modified time.
Type: one of "all_newest_first", "all_oldest_first", "newest_file", "oldest_file"
IntegrationProvider
Third-party services with a pre-configured, server-managed API source.
Distinct from Provider, which lists storage backends. The value is also
the prefix of the compound service_origin a compiled source carries
(shopify:<shop>), which is what makes core-lib's load_provider_manager
pick the provider-specific request manager.
Type: one of "shopify", "quickbooks"
Used by: GET /rest/beta/integrations/{provider}/options
OutlookAccount
Which connected Microsoft account reads the mailbox.
Type: one of "personal", "work"
OutlookMailbox
The mailbox folder to read — the three the web app offers.
Type: one of "inbox", "archive", "sent_items"
PageOrientation
Type: one of "portrait", "landscape"
PaginatedResponse_WorkflowModel_
| Field | Type | | Description |
|---|
page | integer | nullable | Page number
Default: 1 |
per_page | integer | nullable | Number of items per page
Default: 50 |
results | array of WorkflowModel | optional | List of results |
total | integer | nullable | Total number of pages
Default: 0 |
Used by: GET /rest/beta/workflows/
PaperSize
Type: one of "letter", "tabloid", "legal", "statement", "executive", "folio", "A3", "A4", "A5", "B4", "B5"
Provider
Type: one of "drive", "onedrive", "sharepoint", "dropbox"
Used by: GET /rest/beta/files/{provider}, GET /rest/beta/files/{provider}/roots, GET /rest/beta/files/{provider}/search, GET /rest/beta/files/{provider}/{file_id}, GET /rest/beta/files/{provider}/{file_id}/structure
SendFrom
Which mailbox sends an email destination's messages.
Each value is one of the three (mimetype, service_origin) pairs Core API's
validator accepts for an email interface (connection/utils.py
_is_email_interface), which the share service reads to pick the sender
(sheetgo-microservices/share/mail_provider.py). Mirrors the web app's
EmailSendFrom (web-app/src/constants/Mail/index.js).
Type: one of "gmail", "outlook_personal", "outlook_work"
SourceAllTabs
Type: one of "all_tabs"
SourceAPI
Request an HTTP endpoint and use the JSON it returns as source data.
Cannot be combined with file, folder or webhook sources — see
validate_api_automation.
| Field | Type | | Description |
|---|
auth | SourceAuth | nullable | OAuth2 token refresh. Write-only — never returned by a read, and a PUT that omits it clears it. |
body | string | nullable | Request body, sent as JSON when the endpoint expects it. Supports {{Tab!Ref}} cell references. Do not put credentials here — unlike headers, it is returned by reads. |
data_root | string | nullable | Dotted path to the list of records inside the response, e.g. data.orders. Omit to let Sheetgo detect it. |
endpoint | string | required | URL to request. Supports {{Tab!Ref}} cell references — see the Cell References section. |
header_root | string | nullable | Dotted path to a list of column names inside the response, used as the header row. |
headers | object (map of string → string) | nullable | HTTP headers sent with the request, e.g. {"Authorization": "Bearer …"}. Supports {{Tab!Ref}} cell references. Write-only — never returned by a read, and a PUT that omits it clears it. |
method | one of "get", "post" | optional | HTTP method. Only GET and POST can read data.
Default: "get" |
name | string | nullable | Label for this source. Also used as the destination tab name when several sources are transferred without a merge. Defaults to API. |
pagination | one of (chosen by type): type: "cursor" → PaginationCursor, type: "header-link" → PaginationHeaderLink, type: "link" → PaginationLink, type: "offset" → PaginationOffset, type: "page" → PaginationPage, type: "query-offset" → PaginationQueryOffset | nullable | How to walk a paginated endpoint. Omit for a single request. |
type | "api" | required | Marks this source as an API request: Sheetgo calls your endpoint and turns the response into rows. Cannot be combined with file, folder or webhook sources. |
SourceAuth
OAuth2 refresh for an API source.
⚠️ refresh_params typically carries a client secret and a refresh token.
Automation interface payloads are NOT encrypted at rest, and the engine
ROTATES the refresh token in place after a successful refresh
(sheetgo-microservices getvalues/service_api.py:71-77) — so the stored
value can change without any API call.
| Field | Type | | Description |
|---|
auth_method | "oauth2" | required | Only oauth2 is supported. The engine refreshes the token on a 401/403 and retries. |
auth_type | string | optional | Scheme used in the Authorization header after a refresh, e.g. Bearer.
Default: "Bearer" |
refresh_headers | object (map of string → string) | nullable | Extra headers sent with the refresh request. |
refresh_params | object (map of string → string) | nullable | Form body of the refresh request, e.g. client_id, client_secret, refresh_token. Write-only: never returned by a read. |
refresh_url | string | required | Token endpoint called to refresh. |
SourceBigQuery
Read a BigQuery table, or the results of a query over it.
project + dataset + table are always required -- they form the
interface id the engine reads the project back out of, and they match the
web app, where selecting a table is mandatory and the SQL is seeded from it.
Cannot be combined with any other source, and at most one per automation --
see validate_bigquery_automation.
| Field | Type | | Description |
|---|
dataset | string | required | BigQuery dataset id |
name | string | nullable | Label for this source. Also used as the destination tab name. Defaults to the table name. |
project | string | required | GCP project id. List them with GET /rest/beta/bigquery/projects. |
query | string | nullable | Standard-SQL query to run instead of reading the whole table. Validate it first with POST /rest/beta/bigquery/projects/{project}/validate-query. Omit it and Sheetgo reads every row of the table -- there is no implicit row limit, so add your own LIMIT here if you want one. |
table | string | required | BigQuery table id |
type | "bigquery" | required | Marks this source as BigQuery. Only one BigQuery source per automation, and it cannot be mixed with other source kinds. |
SourceFile
| Field | Type | | Description |
|---|
data_ranges | string | nullable | The data range |
date_format | string | nullable | Format for date fields
Default: "#month/day/YEAR" |
file_type | FileType | required | The file type |
id | string | required | Id of the source file or folder |
offset_header | integer | nullable | The header position
Default: 1 |
provider | Provider | required | The storage provider that hosts the file or folder |
sheet_tabs | string or SourceAllTabs or array of string | nullable | One or more sheet tab names or all_tabs |
type | "file" | required | Marks this source as a single file — one spreadsheet, CSV, TSV or Excel workbook. |
SourceFolder-Output
| Field | Type | | Description |
|---|
content_type | ContentType | optional | spreadsheets reads Sheets / Excel / CSV / TSV files. documents reads Google Docs, PDF, Word (.docx) and text files through the AI step (ai.prompt required).
Default: "spreadsheets" |
data_ranges | string | nullable | The data range |
date_format | string | nullable | Format for date fields
Default: "#month/day/YEAR" |
file_filter | FileFilter-Output | nullable | Only read the files that match these conditions. |
file_type | "folder" | required | Always folder. Fixed by the source type; present so folder and file sources share one shape. |
id | string | required | Id of the source file or folder |
import | ImportMode | optional | Which files to import, by modified time: every file newest or oldest first, or only the newest / oldest one. Applied after file_filter and process_once.
Default: "all_newest_first" |
include_subfolders | boolean | optional | Also read files inside subfolders.
Default: false |
offset_header | integer | nullable | The header position
Default: 1 |
process_once | boolean | optional | Documents only: skip files already read by an earlier run (new or changed files are read again). Ignored for spreadsheets.
Default: true |
provider | Provider | required | The storage provider that hosts the file or folder |
sheet_tabs | string or SourceAllTabs or array of string | nullable | One or more sheet tab names or all_tabs |
type | "folder" | required | Marks this source as a folder: every matching file inside it is read. |
SourceIntegration
A pre-configured third-party source (Shopify, QuickBooks).
Everything an api source makes you supply -- URL, headers, token,
pagination, response parsing -- is built server-side per provider from the
authorized account's credentials, so only the choice of data source (and,
for QuickBooks reports, its parameters) is yours.
Unlike SourceAPI, this round-trips completely on a read: it holds no
caller-supplied secret, so nothing has to be write-only.
Counts as an api-like source for the no-mixing rule -- see
validate_api_automation.
| Field | Type | | Description |
|---|
account | string | nullable | Which authorized account to use — the shop domain for Shopify, the realm (company) id for QuickBooks. Optional: omit it and Sheetgo uses your only connection for that provider. With several connected, omitting it is a 422. |
data_source | string | required | Which data to pull, e.g. get_products. Get the list from GET /rest/beta/integrations/{provider}/options. |
name | string | nullable | Label for this source. Also used as the destination tab name when several sources are transferred without a merge. Defaults to the provider's display name. |
parameters | object (map of string → string) | nullable | Values for the parameters that data source declares. Only QuickBooks reports declare any; sending parameters to anything else is a 422. |
provider | IntegrationProvider | required | The integration to read from. List them with GET /rest/beta/integrations. |
type | "integration" | required | Marks this source as a pre-configured integration (Shopify, QuickBooks). URL, auth and pagination are managed by Sheetgo. |
SourceOutlook-Output
Read emails from an Outlook mailbox folder and save their file
attachments (or bodies as HTML) into one existing folder destination.
Must be the only source, with no processors and exactly one folder
destination — see validate_outlook_automation.
| Field | Type | | Description |
|---|
account | OutlookAccount | optional | personal (a personal Microsoft account) or work (work or school). It must be connected in Sheetgo with permission to read mail (412 outlook_not_connected otherwise).
Default: "personal" |
email_filter | EmailFilter-Output | nullable | Only read the emails that match these conditions. Omit to read every email (each run scans at most 1000). |
extract | OutlookExtract | optional | attachments saves each email's file attachments; body saves each email's body as <subject>.html.
Default: "attachments" |
mailbox | OutlookMailbox | optional | inbox, archive or sent_items.
Default: "inbox" |
name | string | nullable | Label for the source. Defaults to Outlook. |
process_once | boolean | optional | Skip emails already saved by an earlier run.
Default: true |
type | "outlook" | required | Marks this source as Outlook: emails from a mailbox folder, saved as files into a folder destination. |
SourceWebhook
| Field | Type | | Description |
|---|
name | string | nullable | Optional label for the webhook source |
type | "webhook" | required | Marks this source as a webhook: your system pushes data in, rather than Sheetgo pulling it. |
SuccessResponse
The legacy success envelope, returned by the pre-existing CRUD routes.
It always carries HTTP 200; the outcome is in code/type, not the status
line. Newer endpoints return the resource directly instead.
| Field | Type | | Description |
|---|
code | integer | optional | Result code. 1 means the operation succeeded.
Default: 1 |
message | string | optional | Human-readable confirmation of what happened.
Default: "OK" |
type | string | optional | Kind of result — success for this envelope.
Default: "success" |
Used by: POST /rest/beta/workflows/run/{id}, DELETE /rest/beta/workflows/{id}, POST /rest/beta/workflows/{id}/run, POST /rest/beta/automations/run/{id}, DELETE /rest/beta/automations/{id}, POST /rest/beta/automations/{id}/run, DELETE /rest/beta/workflows/{workflow_id}/forms/{form_id}
UnusedFields
What happens to a {{Tag}} in the template that no source column matches.
Type: one of "ignore", "error"
ValidationError
| Field | Type | | Description |
|---|
loc | array of string or integer | required | |
msg | string | required | |
type | string | required | |
WorkflowArchive
Workflow archive
| Field | Type | | Description |
|---|
delete_automations | boolean | nullable | All automations for the workflow should also be archived
Default: false |
Used by: DELETE /rest/beta/workflows/{id}
WorkflowAutomationModel
| Field | Type | | Description |
|---|
destinations | array of one of (chosen by type): type: "api" → DestinationApiPublish, type: "bigquery" → DestinationBigQuery-Output, type: "document" → DestinationDocument, type: "file" → DestinationFile, type: "folder" → DestinationFolder, type: "mail_merge" → DestinationMailMerge, type: "pdf" → DestinationPDF, type: "share" → DestinationShare, type: "webhook" → DestinationWebhook or one of (chosen by type): type: "api" → DestinationApiPublish, type: "bigquery" → DestinationBigQuery-Output, type: "document" → DestinationDocument, type: "file" → DestinationFile, type: "folder" → DestinationFolder, type: "mail_merge" → DestinationMailMerge, type: "pdf" → DestinationPDF, type: "share" → DestinationShare, type: "webhook" → DestinationWebhook | nullable | Destinations of the automation |
id | string | required | Id of the automation |
input_count | integer | nullable | Number of inputs of the automation
Default: 0 |
last_updating_user | string | nullable | Last updated user of the automation |
name | string | nullable | Name of the automation |
output_count | integer | nullable | Number of outputs of the automation
Default: 0 |
owner | string | required | Owner of the automation |
sources | array of SourceFile or SourceFolder-Output or SourceWebhook or SourceAPI or SourceIntegration or SourceBigQuery or SourceOutlook-Output | optional | Source files/folders of the automation |
status | integer | nullable | Execution status of the automation
Default: 1 |
WorkflowCreate
New workflow creation
| Field | Type | | Description |
|---|
category | string | nullable | Workflow category |
description | string | nullable | Workflow description |
name | string | optional | Name of the new workflow
Default: "Untitled workflow" |
Used by: POST /rest/beta/workflows/
WorkflowModel
Data presentation model for Workflow
| Field | Type | | Description |
|---|
automations | object (map of string → WorkflowAutomationModel) | required | Automations present in this workflow |
category | string | nullable | Category of the workflow |
description | string | required | Description of the workflow |
forms | array of string | required | Forms present in this workflow |
id | string | required | Workflow identification |
name | string | required | Name of the workflow |
owner | string | required | Owner of the workflow |
running | boolean | nullable | True if workflow is running
Default: false |
scheduled | boolean | nullable | True if workflow is scheduled
Default: false |
shared | boolean | optional | True if workflow is shared
Default: false |
users | array of string | required | List of users in this workflow |
Used by: POST /rest/beta/workflows/, GET /rest/beta/workflows/{id}, PATCH /rest/beta/workflows/{id}
WorkflowPatch
Workflow patch
| Field | Type | | Description |
|---|
category | string | nullable | Workflow category |
description | string | nullable | Workflow description |
name | string | nullable | Name of the workflow |
Used by: PATCH /rest/beta/workflows/{id}
WorkflowRunStatus
The outcome of a workflow's LAST run, plus one entry per automation.
When the workflow itself has never been run as a whole but its automations
have, the top-level result, message and duration_seconds are derived
from automations — worst result wins, so a single failed automation makes
the workflow error.
| Field | Type | | Description |
|---|
automations | array of AutomationRunStatus | optional | Per-automation breakdown of the same run, one entry per automation in the workflow. |
docs_link | string | nullable | URL of the help article for this error, when one exists. |
duration_seconds | number | nullable | How long the last run took, in seconds. When derived from automations, this is the longest automation duration. |
execution | string | required | Live phase: running if the workflow or any of its automations is still executing, otherwise completed. |
last_failed_automation_id | string | nullable | Id of the automation that failed, so you can go straight to it without scanning automations. Null when nothing failed. |
message | string | nullable | Human-readable explanation of the outcome, from the workflow run when there is one, otherwise from the failing automation. Null on success and before the first run. |
result | string | required | Outcome of the last finished run: never_run, success or error. error if ANY automation failed. |
started_at | string | nullable | When the last WORKFLOW run started. Null when the workflow has only ever been run one automation at a time — running a single automation records no workflow start time, and none is invented here. |
workflow_id | string | required | Id of the workflow this status belongs to. |
Used by: GET /rest/beta/workflows/{id}/run