Models · REST API · Sheetgo Developers

REST API · 147 models

All models

Every request and response model of the REST API, field by field, grouped by the endpoints that use it. A model appears once, under the group whose endpoints use it most directly (for example the destination types are under automations); models used by three or more groups are under Common. "Used by" under each model lists every operation that references it. Types link to other models on this page. Fields marked required must be sent; for a "one of", the type field says which variant to use.

Used by workflows14 models Used by automations73 models Used by triggers4 models Used by dashboards6 models Used by forms7 models Used by webhook2 models Used by integrations6 models Used by outlook4 models Used by gmail1 model Used by files11 models Used by bigquery10 models Used by auth3 models Common (used by 3 or more groups)6 models

Used by workflows

Models used by the workflows endpoints, including nested ones. That page also lists every model its operations use.

`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}

`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

`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/

`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

Used by automations

Models used by the automations endpoints, including nested ones. That page also lists every model its operations use.

`AIProcessor`

Field	Type		Description
`model`	string	nullable	OpenAI model id (e.g. `gpt-5.2`) or Assistant id (`asst_…`). Needs your own OpenAI account connected in the Sheetgo web app (412 `openai_not_connected` otherwise). Without it, a connected key still runs Sheetgo's default model.
`model_settings`	`ModelSettings`	nullable	Model parameters. Same OpenAI-account requirement as `model`.
`on_processing_error`	`OnProcessingError`	nullable	Documents folder only: `continue` (default) keeps going when a document cannot be read; `stop` fails the run.
`prompt`	string	required	The AI prompt: what the AI step should do with the data. For a documents folder source it says what to extract, and its wording is the column contract.

`AnonymizeMethod`

The web app's masking methods (core-lib v1/dataframe/anonymizer.py).

Type: one of "salted_hash", "hash", "nullify", "redact", "partial_email", "partial_start", "partial_end", "generalization"

`AnonymizeMode`

automatic: Google DLP (Sheetgo's project) detects personal data and hashes it. custom: a masking method per column.

Type: one of "automatic", "custom"

`AnonymizeProcessor`

Mask personal data before it reaches the destination (the web app's Anonymize step).

Field	Type		Description
`columns`	object (map of string → `AnonymizeMethod`)	nullable	Custom mode only: column LETTER (`A`, `B`, …) → method: salted_hash, hash, nullify, redact, partial_email, partial_start (first 2 characters + ), partial_end ( + last 4), generalization (numbers grouped into ranges).
`mode`	`AnonymizeMode`	optional	`automatic`: personal data is detected (Google DLP, on Sheetgo's account) and hashed. `custom`: you choose a method per column. Not combinable today with `ai`, `filter` or `remove_duplicates` (features incompatible in the engine) — see Processor combinations. Default: `"custom"`

`AutomationCreate`

Field	Type		Description
`ai`	`AIProcessor`	nullable	AI step options
`anonymize`	`AnonymizeProcessor`	nullable	Anonymize step options. Not combinable today with `ai`, `filter` or `remove_duplicates` (features incompatible in the engine) — see Processor combinations.
`destinations`	array of one of (chosen by `type`): `type: "api"` → `DestinationApiPublish`, `type: "bigquery"` → `DestinationBigQuery-Input`, `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-Input`, `type: "document"` → `DestinationDocument`, `type: "file"` → `DestinationFile`, `type: "folder"` → `DestinationFolder`, `type: "mail_merge"` → `DestinationMailMerge`, `type: "pdf"` → `DestinationPDF`, `type: "share"` → `DestinationShare`, `type: "webhook"` → `DestinationWebhook`	nullable	Destinations to connect to
`filter`	`FilterCondition-Input` or `FilterColumn` or `FilterQuery`	nullable	Filter step options. Columns are spreadsheet LETTERS — get them from `GET /files/{provider}/{file_id}/structure?include=columns` on the source file (see Column letters). Not combinable today with `remove_duplicates` or `anonymize` (features incompatible in the engine) — see Processor combinations.
`left_join`	`LeftJoinProcessor`	nullable	Left join step options
`merge`	`MergeProcessor`	nullable	Merge step options
`name`	string	required	Name of the automation
`number_format`	boolean	nullable	Number format Default: `false`
`remove_duplicates`	`RemoveDuplicatesProcessor`	nullable	Remove duplicate rows. Not combinable today with `ai`, `filter` or `anonymize` (features incompatible in the engine) — see Processor combinations.
`sources`	array of `SourceFile` or `SourceFolder-Input` or `SourceWebhook` or `SourceAPI` or `SourceIntegration` or `SourceBigQuery` or `SourceOutlook-Input`	required	List of sources to connect to
`split`	`Split`	nullable	Split step options
`transfer_format`	boolean	nullable	Transfer format Default: `false`
`workflow_id`	string	required	Id of the workflow this automation belongs to

Used by: POST /rest/beta/automations/

`AutomationModel`

Field	Type		Description
`ai`	`AIProcessor`	nullable	The AI step, when the automation has one.
`anonymize`	`AnonymizeProcessor`	nullable	The Anonymize step, when the automation has one.
`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
`execution`	`ExecutionStatus`	nullable	Execution status of the automation Default: `"completed"`
`filter`	`FilterCondition-Output` or `FilterColumn` or `FilterQuery`	nullable	The Filter step, when the automation has one the API can represent (nested groups, colour filters and conditions combined with a column selection read back as null).
`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
`left_join`	`LeftJoinProcessor`	nullable	The Left join step, when the automation has one.
`merge`	`MergeProcessor`	nullable	The Merge step, when the automation has one.
`name`	string	required	Name of the automation
`output_count`	integer	nullable	Number of outputs of the automation Default: `0`
`owner`	string	required	Owner of the automation
`remove_duplicates`	`RemoveDuplicatesProcessor`	nullable	The Remove duplicates step, when the automation has one.
`sources`	array of `SourceFile` or `SourceFolder-Output` or `SourceWebhook` or `SourceAPI` or `SourceIntegration` or `SourceBigQuery` or `SourceOutlook-Output`	optional	Sources of the automation
`split`	`Split`	nullable	The Split step, when the automation has one.
`status`	integer	nullable	Execution result code: 0 = never executed, 1 = executed successfully, > 1 = error (inspect status_message / status_docs_link). Default: `0`
`status_docs_link`	string	nullable	Documentation link for the error when status > 1.
`status_message`	string	nullable	Human-readable error description when status > 1.

Used by: POST /rest/beta/automations/, GET /rest/beta/automations/{id}, PUT /rest/beta/automations/{id}, PATCH /rest/beta/automations/{id}

`AutomationPatch`

Rename only. Unknown fields are rejected (SG-14706): they used to be dropped with a 200, and a missing name was saved as null, blanking the automation.

Field	Type		Description
`name`	string	required	New name of the automation Min length: `1`

Used by: PATCH /rest/beta/automations/{id}

`AutomationReplace`

Field	Type		Description
`ai`	`AIProcessor`	nullable	AI step options
`anonymize`	`AnonymizeProcessor`	nullable	Anonymize step options. Not combinable today with `ai`, `filter` or `remove_duplicates` (features incompatible in the engine) — see Processor combinations.
`destinations`	array of one of (chosen by `type`): `type: "api"` → `DestinationApiPublish`, `type: "bigquery"` → `DestinationBigQuery-Input`, `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-Input`, `type: "document"` → `DestinationDocument`, `type: "file"` → `DestinationFile`, `type: "folder"` → `DestinationFolder`, `type: "mail_merge"` → `DestinationMailMerge`, `type: "pdf"` → `DestinationPDF`, `type: "share"` → `DestinationShare`, `type: "webhook"` → `DestinationWebhook`	nullable	Destinations to connect to
`filter`	`FilterCondition-Input` or `FilterColumn` or `FilterQuery`	nullable	Filter step options. Columns are spreadsheet LETTERS — get them from `GET /files/{provider}/{file_id}/structure?include=columns` on the source file (see Column letters). Not combinable today with `remove_duplicates` or `anonymize` (features incompatible in the engine) — see Processor combinations.
`id`	string	required	Id of the automation
`left_join`	`LeftJoinProcessor`	nullable	Left join step options
`merge`	`MergeProcessor`	nullable	Merge step options
`name`	string	required	Name of the automation
`number_format`	boolean	nullable	Number format Default: `false`
`remove_duplicates`	`RemoveDuplicatesProcessor`	nullable	Remove duplicate rows. Not combinable today with `ai`, `filter` or `anonymize` (features incompatible in the engine) — see Processor combinations.
`sources`	array of `SourceFile` or `SourceFolder-Input` or `SourceWebhook` or `SourceAPI` or `SourceIntegration` or `SourceBigQuery` or `SourceOutlook-Input`	required	List of sources to connect to
`split`	`Split`	nullable	Split step options
`transfer_format`	boolean	nullable	Transfer format Default: `false`
`workflow_id`	string	required	Id of the workflow this automation belongs to

Used by: PUT /rest/beta/automations/{id}

`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"

`ConditionExpression`

Field	Type		Description
`column`	string	optional	Spreadsheet column letter (`A`, `B`, … `AA`), uppercase, as in the web app — not the header name. Find letters with `GET /files/{provider}/{file_id}/structure?include=columns`. Example: `"D"`
`criteria`	`ExpressionCriteria`	optional	The criteria
`value`	number or integer or string	nullable	The value

`ConditionType`

Type: one of "and", "or"

`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-Input`

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"`

`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-Input`

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-Input` or `EmailFilterRule`	required	Conditions or nested groups. Min items: `1`

`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`.

`ExecutionStatus`

Type: one of "completed", "running"

`ExpressionCriteria`

Type: one of "number_gt", "number_gte", "number_lt", "number_lte", "number_eq", "number_neq", "date_is", "date_is_before", "date_is_after", "text_contains", "text_does_not_contain", "text_is_exactly", "is_empty", "is_not_empty", "is_true", "is_false"

`FileAccessRole`

Type: one of "reader", "writer"

`FileFilter-Input`

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-Input` or `FileFilterRule`	required	Conditions or nested groups. Min items: `1`

`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"

`FilterColumn`

Field	Type		Description
`columns`	array of string	optional	The selected columns. Each is a spreadsheet column letter (`A`, `B`, … `AA`), uppercase, as in the web app — not the header name. Find letters with `GET /files/{provider}/{file_id}/structure?include=columns`. Example: `["A", "C"]`
`type`	`"column"`	required	A column filter: choose which columns are carried through.

`FilterCondition-Input`

Field	Type		Description
`columns`	array of string	nullable	The selected columns. Each is a spreadsheet column letter (`A`, `B`, … `AA`), uppercase, as in the web app — not the header name. Find letters with `GET /files/{provider}/{file_id}/structure?include=columns`. Example: `["A", "C"]`
`condition_type`	`ConditionType`	nullable	The filter condition type
`expressions`	array of `ConditionExpression`	nullable	The filter expression
`type`	`"condition"`	required	A condition filter: keep rows where a column matches a comparison.

`FilterCondition-Output`

Field	Type		Description
`columns`	array of string	nullable	The selected columns. Each is a spreadsheet column letter (`A`, `B`, … `AA`), uppercase, as in the web app — not the header name. Find letters with `GET /files/{provider}/{file_id}/structure?include=columns`. Example: `["A", "C"]`
`condition_type`	`ConditionType`	nullable	The filter condition type
`expressions`	array of `ConditionExpression`	nullable	The filter expression
`type`	`"condition"`	required	A condition filter: keep rows where a column matches a comparison.

`FilterQuery`

Field	Type		Description
`query`	string	required	The filter query string
`type`	`"query"`	required	A query filter: keep rows matching an sgql expression.

`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"

`KeepDuplicateType`

Type: one of "first", "last"

`LeftJoinProcessor`

Field	Type		Description
`column`	string	optional	Spreadsheet column letter (`A`, `B`, … `AA`), uppercase, as in the web app — not the header name. Find letters with `GET /files/{provider}/{file_id}/structure?include=columns`. Example: `"A"`

`MergeProcessor`

Field	Type		Description
`offset_header`	integer	optional	The header position Default: `1`
`remove_header`	boolean	optional	Remove header during the merge process Default: `false`

`ModelSettings`

OpenAI settings the AI step passes to the model. Honoured only with the user's own OpenAI key (core-lib ai_processor/processors.py).

Field	Type		Description
`frequency_penalty`	number	nullable
`max_completion_tokens`	integer	nullable
`presence_penalty`	number	nullable
`reasoning_effort`	one of `"low"`, `"medium"`, `"high"`	nullable	Applied by the engine only to models whose id starts with `o`.
`temperature`	number	nullable
`top_p`	number	nullable

`OnProcessingError`

What a documents run does when one document cannot be read.

Type: one of "continue", "stop"

`OutlookAccount`

Which connected Microsoft account reads the mailbox.

Type: one of "personal", "work"

`OutlookExtract`

Type: one of "attachments", "body"

`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_AutomationModel_`

Field	Type		Description
`page`	integer	nullable	Page number Default: `1`
`per_page`	integer	nullable	Number of items per page Default: `50`
`results`	array of `AutomationModel`	optional	List of results
`total`	integer	nullable	Total number of pages Default: `0`

Used by: GET /rest/beta/automations/

`PaginationCursor`

Follow a cursor until the response says there is no more.

Field	Type		Description
`cursor_param`	string	optional	Request parameter carrying the cursor. Default: `"cursor"`
`has_more_key`	string	optional	Response key holding the more-pages flag. Default: `"has_more"`
`limit`	integer	nullable	Stop once this many items have been collected. Omit (or 0) to keep going until the endpoint runs out.
`next_cursor_key`	string	optional	Response key holding the next cursor. Default: `"next_cursor"`
`rate_limit`	string	nullable	Pause between requests. Either "N/seconds" — e.g. "100/10" for 100 requests per 10 seconds — or a plain number of seconds, e.g. "0.5".
`scope`	one of `"query"`, `"body"`	optional	Where the paging parameters are placed: the query string or the JSON body. Default: `"query"`
`type`	`"cursor"`	required	Selects cursor pagination: the response carries an opaque cursor that is sent back to fetch the next page.

`PaginationHeaderLink`

Follow a next-page link found in a response header (e.g. RFC 5988 Link).

Field	Type		Description
`limit`	integer	nullable	Stop once this many items have been collected. Omit (or 0) to keep going until the endpoint runs out.
`next_link_key`	string	optional	Response header holding the next-page URL. Default: `"next"`
`rate_limit`	string	nullable	Pause between requests. Either "N/seconds" — e.g. "100/10" for 100 requests per 10 seconds — or a plain number of seconds, e.g. "0.5".
`type`	`"header-link"`	required	Selects header-link pagination: the next page's URL is read from the response's `Link` header.

`PaginationLink`

Follow a next-page link found in the response body.

Field	Type		Description
`limit`	integer	nullable	Stop once this many items have been collected. Omit (or 0) to keep going until the endpoint runs out.
`next_link_key`	string	optional	Response key holding the next-page URL. Default: `"next"`
`rate_limit`	string	nullable	Pause between requests. Either "N/seconds" — e.g. "100/10" for 100 requests per 10 seconds — or a plain number of seconds, e.g. "0.5".
`type`	`"link"`	required	Selects link pagination: the next page's full URL is read out of the response body.

`PaginationOffset`

Advance an offset by the limit until a short page comes back.

Field	Type		Description
`limit`	integer	nullable	Stop once this many items have been collected. Omit (or 0) to keep going until the endpoint runs out.
`limit_param`	string	optional	Request parameter carrying the page size. Default: `"limit"`
`offset_param`	string	optional	Request parameter carrying the offset. Default: `"offset"`
`rate_limit`	string	nullable	Pause between requests. Either "N/seconds" — e.g. "100/10" for 100 requests per 10 seconds — or a plain number of seconds, e.g. "0.5".
`scope`	one of `"query"`, `"body"`	optional	Where the paging parameters are placed: the query string or the JSON body. Default: `"query"`
`type`	`"offset"`	required	Selects offset pagination: a row offset is advanced by the page size on each request.

`PaginationPage`

Increment a page number until a short page comes back.

Field	Type		Description
`limit`	integer	nullable	Stop once this many items have been collected. Omit (or 0) to keep going until the endpoint runs out.
`page_param`	string	optional	Request parameter carrying the page number. Default: `"page"`
`per_page_param`	string	optional	Request parameter carrying the page size. Default: `"per_page"`
`rate_limit`	string	nullable	Pause between requests. Either "N/seconds" — e.g. "100/10" for 100 requests per 10 seconds — or a plain number of seconds, e.g. "0.5".
`scope`	one of `"query"`, `"body"`	optional	Where the paging parameters are placed: the query string or the JSON body. Default: `"query"`
`type`	`"page"`	required	Selects page-number pagination: a page counter is incremented until the response runs out of rows.

`PaginationQueryOffset`

Rewrite offset/limit keywords inside a SQL-like query parameter.

Field	Type		Description
`limit`	integer	nullable	Stop once this many items have been collected. Omit (or 0) to keep going until the endpoint runs out.
`query_key`	string	optional	Request parameter holding the query string. Default: `"query"`
`query_limit_key`	string	optional	Keyword inside the query that sets the page size. Default: `"limit"`
`query_offset_key`	string	optional	Keyword inside the query that sets the offset. Default: `"offset"`
`rate_limit`	string	nullable	Pause between requests. Either "N/seconds" — e.g. "100/10" for 100 requests per 10 seconds — or a plain number of seconds, e.g. "0.5".
`type`	`"query-offset"`	required	Selects query-offset pagination: the offset travels in the query string of the request URL.

`PaperSize`

Type: one of "letter", "tabloid", "legal", "statement", "executive", "folio", "A3", "A4", "A5", "B4", "B5"

`RemoveDuplicatesProcessor`

Field	Type		Description
`columns`	array of string	optional	The selected columns. Each is a spreadsheet column letter (`A`, `B`, … `AA`), uppercase, as in the web app — not the header name. Find letters with `GET /files/{provider}/{file_id}/structure?include=columns`. Example: `["A", "C"]`
`keep`	`KeepDuplicateType`	optional	Keep duplicated rows Default: `"first"`

`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-Input`

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-Input`	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.

`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-Input`

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-Input`	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.

`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.

`Split`

Field	Type		Description
`column`	string	optional	Spreadsheet column letter (`A`, `B`, … `AA`), uppercase, as in the web app — not the header name. Find letters with `GET /files/{provider}/{file_id}/structure?include=columns`. Example: `"C"`

`UnusedFields`

What happens to a {{Tag}} in the template that no source column matches.

Type: one of "ignore", "error"

Used by triggers

Models used by the triggers endpoints, including nested ones. That page also lists every model its operations use.

`FormSubmissionTriggerIn`

Run this workflow whenever a bound Sheetgo form receives a new response.

Field	Type		Description
`form_id`	string	required	Id of a form attached to this workflow.
`type`	`"form_submission"`	required	Selects a form_submission trigger: the workflow runs each time the form named by `form_id` receives a response.

Used by: PUT /rest/beta/workflows/{id}/trigger

`TimeTriggerIn`

Time/smart schedule. Either friendly fields OR a raw cron, not both.

Field	Type		Description
`cron`	string	nullable	Power-user escape hatch. Mutually exclusive with friendly fields.
`day_of_month`	integer or string	nullable	monthly only: 1..31 or 'last'
`every`	integer	nullable	minutes: 15\|30 ; hourly: 1\|2\|4\|6\|8\|12
`frequency`	one of `"minutes"`, `"hourly"`, `"daily"`, `"weekly"`, `"monthly"`	nullable	Schedule frequency
`time`	string	nullable	HH:MM for daily/weekly/monthly. Minute is coerced to :00.
`timezone`	string	nullable	IANA timezone; defaults to the workflow's current timezone.
`type`	`"time"`	required	Selects a time trigger: the workflow runs on a schedule. Set either the friendly fields below or `cron`, not both.
`weekday`	string or array of string	nullable	weekly only: a day name (sunday..saturday) or a list of names

Used by: PUT /rest/beta/workflows/{id}/trigger

`TriggerOut`

Read model echoed by GET and returned by PUT.

Only the fields belonging to the active trigger type are populated; all others are null. When active is false, type is null too and every other field is empty — that is the shape of a workflow with no trigger.

Field	Type		Description
`active`	boolean	optional	Whether a trigger is currently set and enabled. When false, every other field is null and the workflow runs only on demand. Default: `false`
`after_workflow_id`	string	nullable	workflow_finished triggers only: the id of the parent workflow whose completion starts this one.
`cron`	string	nullable	time triggers only: the effective five-field cron expression the schedule resolved to. Always present for a time trigger, whether it was created from `cron` or from the friendly fields.
`day_of_month`	integer or string	nullable	time triggers, monthly only: the day of the month (1..31), or the string `last` for the final day of each month.
`every`	integer	nullable	time triggers only: the interval within `frequency` — minutes: 15 or 30; hourly: 1, 2, 4, 6, 8 or 12.
`form_id`	string	nullable	form_submission triggers only: the id of the form whose new responses start this workflow.
`frequency`	string	nullable	time triggers only: `minutes`, `hourly`, `daily`, `weekly` or `monthly`. Null when the trigger was set with a raw `cron`.
`time`	string	nullable	time triggers only: `HH:MM` in `timezone`, for daily, weekly and monthly frequencies. The minute is always `:00`.
`timezone`	string	nullable	time triggers only: the IANA timezone the schedule is evaluated in (for example `Europe/Madrid`).
`type`	one of `"time"`, `"workflow_finished"`, `"form_submission"`	nullable	Which kind of trigger is set, and therefore which fields below are populated. Null when `active` is false.
`weekday`	string or array of string	nullable	time triggers, weekly only: a day name (`sunday`..`saturday`), or a list of them when the schedule repeats on several days.

Used by: GET /rest/beta/workflows/{id}/trigger, PUT /rest/beta/workflows/{id}/trigger, DELETE /rest/beta/workflows/{id}/trigger

`WorkflowFinishedTriggerIn`

Run this workflow when another workflow finishes.

Field	Type		Description
`after_workflow_id`	string	required	Parent workflow whose completion triggers this one (named 'after_' to distinguish it from the path {id}).
`type`	`"workflow_finished"`	required	Selects a workflow_finished trigger: the workflow runs when the workflow named by `after_workflow_id` completes.

Used by: PUT /rest/beta/workflows/{id}/trigger

Used by dashboards

Models used by the dashboards endpoints, including nested ones. That page also lists every model its operations use.

`AuthConfigIn`

Access restriction. Only domain restriction is exposed.

specificUsers is deliberately absent: the internal PUT emails every address in it via SendGrid (dashboard/models.py:190), which would let an API key mail arbitrary recipients.

Field	Type		Description
`domain`	boolean	required	Restrict to the workflow owner's email domain

Used by: PUT /rest/beta/workflows/{id}/dashboard/publish

`DashboardOut`

A workflow's single dashboard: its elements and its publication state.

Field	Type		Description
`elements`	array of `ElementOut`	optional	Every element on the dashboard, in stored order. Empty for a workflow whose dashboard has not been built yet.
`publish`	`PublishOut`	required	Whether the dashboard is published, and under what access restrictions.

Used by: GET /rest/beta/workflows/{id}/dashboard

`ElementDataOut`

One element's current values.

page/per_page/total are populated for table only; the other types have nothing to paginate.

Field	Type		Description
`data`	any	optional	The element's current values, read live from the spreadsheet. A single value for `indicator`, a list of rows for `table`, and the chart's image or reference for `chart`.
`id`	string	required	Id of the element these values belong to.
`page`	integer	nullable	Current page of rows, 1-based. Populated for `table` only.
`per_page`	integer	nullable	Rows per page in this response. Populated for `table` only.
`total`	integer	nullable	Total rows, for table elements
`type`	`ElementType`	required	The element's kind, which determines the shape of `data`.

Used by: GET /rest/beta/workflows/{id}/dashboard/elements/{element_id}/data

`ElementOut`

One stored element, in public vocabulary.

Field	Type		Description
`added_by`	string	nullable	Email of the user who added the element.
`added_on`	string	nullable	When the element was added, ISO 8601.
`chart_id`	integer	nullable	Numeric id of the referenced chart. Set for `chart` elements only; get it from `GET /files/{provider}/{file_id}/structure`.
`error`	string	nullable	Stored render error, when one was persisted. Usually null even for a broken element: errors are written during a build and not saved (workflow/controller.py:759). Read the element's /data to be sure.
`file_id`	string	nullable	Id of the Google Sheets file the element reads from.
`id`	string	required	Element id. Use it for delete and data reads.
`range`	string	nullable	A1 range the element reads, without the tab name (for example `B2:D50`). Set for `indicator` and `table`; null for `chart`.
`stored_role`	string	nullable	Internal role, echoed when `type` is `other`
`stored_type`	string	nullable	Internal type, echoed when `type` is `other`
`tab_id`	integer	nullable	Numeric id of the tab the element reads from. Null for `chart` elements, which point at a chart rather than a tab.
`tab_name`	string	nullable	Name of that tab at the time the element was stored. Null for `chart` elements. Renaming the tab does not update this.
`title`	string	nullable	Label shown above the element on the dashboard.
`type`	`ElementType`	required	Element kind: `indicator` (a single value), `table` (a range of rows) or `chart` (a reference to a chart already in the spreadsheet). `other` means an element the web app created that this API does not model — see `stored_type`.

Used by: POST /rest/beta/workflows/{id}/dashboard/elements

`ElementType`

Type: one of "indicator", "table", "chart", "other"

Used by: POST /rest/beta/workflows/{id}/dashboard/elements

`PublishOut`

The dashboard's current publication state.

Field	Type		Description
`auth_config`	object	nullable	The access restriction applied when `require_auth` is true — `{"domain": true}` limits viewers to the owner's email domain. Null when unrestricted.
`public_id`	string	nullable	Stable public identifier minted at first publish; it forms the `url`. Null until the dashboard has been published once.
`require_auth`	boolean	optional	Whether a viewer must be signed in to open the dashboard. Only meaningful while `shared` is `public`. Default: `false`
`shared`	string	required	`public` if the dashboard is published and reachable at `url`, `private` if it is not.
`url`	string	nullable	Viewer URL; null while private and never published

Used by: PUT /rest/beta/workflows/{id}/dashboard/publish

Used by forms

Models used by the forms endpoints, including nested ones. That page also lists every model its operations use.

`FormCreate`

Form creation data

Field	Type		Description
`confirmation_message`	string	nullable	Confirmation message
`description`	string	nullable	Form description
`include_header`	boolean	nullable	True if include header Default: `false`
`limit_responses`	boolean	nullable	True if should limit responses Default: `false`
`require_auth`	boolean	nullable	True if it requires authentication Default: `false`
`source`	`FormFile`	required	Form fields source file
`target`	`FormFile`	required	Response destination file
`title`	string	optional	Title for the form Default: `"Untitled form"`

Used by: POST /rest/beta/workflows/{workflow_id}/forms/

`FormFile`

Used in form creation and update

Field	Type		Description
`file_type`	`FileType`	required	Type of the file
`id`	string	required	Id of the file
`name`	string	required	Name of the file
`provider`	`Provider`	required	Service origin of the file
`tab_id`	integer	required	Tab id of the file
`tab_name`	string	required	Tab name of the file

`FormFileModel`

For displaying data

Field	Type		Description
`file_type`	`FileType`	nullable	Type of the file
`id`	string	required	Id of the file
`name`	string	nullable	Name of the file
`provider`	`Provider`	nullable	Service origin of the file
`tab_id`	integer	nullable	Tab id of the file
`tab_name`	string	nullable	Tab name of the file

`FormModel`

For displaying data

Field	Type		Description
`confirmation_message`	string	nullable	Confirmation message
`description`	string	nullable	Form description
`id`	string	optional	Form identification
`include_header`	boolean	nullable	True if include header Default: `false`
`limit_responses`	boolean	nullable	True if should limit responses Default: `false`
`require_auth`	boolean	nullable	True if it requires authentication Default: `false`
`source`	`FormFileModel`	nullable	Form fields source file
`target`	`FormFileModel`	nullable	Response destination file
`title`	string	optional	Title for the form Default: `"Untitled form"`

Used by: 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}

`FormPatch`

Form update data

Field	Type		Description
`confirmation_message`	string	nullable	Confirmation message
`description`	string	nullable	Form description
`limit_responses`	boolean	nullable	Limit each respondent to one response. Must be sent together with `require_auth` — identifying the respondent is how the limit is enforced.
`require_auth`	boolean	nullable	Require respondents to authenticate. SG-14657 — must be sent together with `limit_responses`; sending one alone is a 422. Setting `limit_responses` true forces this on.
`source`	`FormFile`	nullable	Form fields source file
`sync_fields_after_submission`	boolean	nullable	True it should sync fields after submission
`target`	`FormFile`	nullable	Response destination file
`title`	string	nullable	Title for the form

Used by: PATCH /rest/beta/workflows/{workflow_id}/forms/{form_id}

`PaginatedResponse`

Field	Type		Description
`page`	integer	nullable	Page number Default: `1`
`per_page`	integer	nullable	Number of items per page Default: `50`
`results`	array	optional	List of results
`total`	integer	nullable	Total number of pages Default: `0`

Used by: GET /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses

`PaginatedResponse_FormModel_`

Field	Type		Description
`page`	integer	nullable	Page number Default: `1`
`per_page`	integer	nullable	Number of items per page Default: `50`
`results`	array of `FormModel`	optional	List of results
`total`	integer	nullable	Total number of pages Default: `0`

Used by: GET /rest/beta/workflows/{workflow_id}/forms/

Used by webhook

Models used by the webhook endpoints, including nested ones. That page also lists every model its operations use.

`WebhookBody`

Field	Type		Description
`async_dispatch`	boolean	optional	Default False — the automation is dispatched synchronously and the 202 is returned once dispatch has started. Pass True to dispatch asynchronously and return 202 as soon as the request is accepted; useful for high-throughput producers. Default: `false`
`run_workflow`	boolean	optional	If True, after this automation finishes, the parent workflow's other automations are re-run synchronously. Default: `false`
`values`	array of array of string	required	Tabular values to push (rows of strings) Min items: `1`

Used by: POST /rest/beta/webhook/{public_id}

`WebhookOut`

A webhook endpoint bound to one automation's webhook source.

Field	Type		Description
`active`	boolean	optional	False once the webhook has been deleted. A deleted webhook stops accepting pushes; webhooks are removed with their automation, never on their own. Default: `true`
`automation_id`	string	nullable	Id of the automation this webhook feeds. Null only for a webhook that is not yet bound to one.
`created_at`	string (date-time)	nullable	When the webhook was minted, ISO 8601.
`public_id`	string	required	The webhook's public identifier — the `{public_id}` path segment in `url`. Treat it as a secret: anyone holding it can push data to the automation.
`url`	string	required	Full URL to POST your JSON payload to. This is the value to configure in the external system that will push data.

Used by: GET /rest/beta/automations/{automation_id}/webhook

Used by integrations

Models used by the integrations endpoints, including nested ones. That page also lists every model its operations use.

`DataSourceOut`

One thing you can ask a provider for.

Field	Type		Description
`description`	string	optional	What it returns Default: `""`
`id`	string	required	Pass this back as `sources[].data_source`
`kind`	string	required	`query` for records, `report` for a report
`name`	string	required	Display name
`parameters`	object (map of string → `DataSourceParameter`)	optional	Parameters this data source accepts, keyed by name. Empty for everything except QuickBooks reports.

`DataSourceParameter`

One parameter a data source accepts.

When options is present it is the authority: date_macro declares type: date but its options are macro strings like "Last Month", so a value is checked against options first and against type only when no options are declared.

Field	Type		Description
`description`	string	nullable	What it controls
`format`	string	nullable	Expected format when the type is `date`
`name`	string	nullable	Display name
`optional_for`	array of string	nullable	Advisory: supplying this parameter makes those alternatives unnecessary. Nothing is enforced as required.
`options`	array of string	nullable	Accepted values. When present, the only accepted values.
`type`	string	nullable	`date` or `string`

`IntegrationAccount`

One authorized account for a provider.

Field	Type		Description
`account`	string	required	Pass this back as `sources[].account`. The shop domain for Shopify, the realm (company) id for QuickBooks.
`connected_at`	string (date-time)	nullable	When the account was authorized
`may_be_revoked`	boolean	optional	True when the stored credentials are gone — the account must be re-authorized in the web app before it will run. Default: `false`

`IntegrationListResponse`

Standard envelope. The provider list is fixed and short, so there are no paging query params -- same as GET /files/{provider}/roots.

Field	Type		Description
`page`	integer	nullable	Page number Default: `1`
`per_page`	integer	nullable	Number of items per page Default: `50`
`results`	array of `IntegrationOut`	optional	List of results
`total`	integer	nullable	Total number of pages Default: `0`

Used by: GET /rest/beta/integrations

`IntegrationOptionsResponse`

Everything selectable for one provider.

Field	Type		Description
`data_sources`	array of `DataSourceOut`	optional	Every data source this provider exposes. Use a `key` from here as an integration source's `data_source`.
`provider`	string	required	The provider these options belong to, e.g. `shopify` or `quickbooks`.

Used by: GET /rest/beta/integrations/{provider}/options

`IntegrationOut`

One provider, with whatever the caller has authorized for it.

Field	Type		Description
`accounts`	array of `IntegrationAccount`	optional	Authorized accounts. Empty when not connected — authorization happens in the Sheetgo web app, not here.
`connected`	boolean	required	True when at least one account is authorized
`name`	string	required	Display name
`provider`	string	required	Pass this back as `sources[].provider`

Used by outlook

Models used by the outlook endpoints, including nested ones. That page also lists every model its operations use.

`AttachmentIn`

Field	Type		Description
`content_base64`	string	required	The file's bytes, base64-encoded. All attachments on one message must total no more than 3 MB decoded.
`content_type`	string	required	MIME type of the attachment, e.g. `application/pdf`.
`filename`	string	required	File name the recipient will see, including the extension.

`BatchBody`

Fetch several messages in one request, by id.

Field	Type		Description
`ids`	array of string	required	Message ids to fetch. At most 50, or 10 when `include_attachments` is true. Min items: `1`
`include_attachments`	boolean	optional	Whether to return each message's attachment content as well as its metadata. Lowers the batch cap to 10. Default: `false`

Used by: POST /rest/beta/outlook/messages/batch

`BodyContent`

Field	Type		Description
`content`	string	required	The message body itself, in the format named by `content_type`.
`content_type`	one of `"text"`, `"html"`	optional	How `content` should be interpreted: `text` for plain text, `html` for an HTML body. Default: `"text"`

`SendBody`

One message to send through the authorized Outlook account.

Field	Type		Description
`attachments`	array of `AttachmentIn`	optional	Files to attach: at most 10, totalling no more than 3 MB once decoded. Default: `[]`
`bcc`	array of string	optional	Blind-carbon-copy recipients, hidden from other recipients. Default: `[]`
`body`	`BodyContent`	required	The message body and whether it is plain text or HTML.
`cc`	array of string	optional	Carbon-copy recipients, visible to everyone. Default: `[]`
`save_to_sent_items`	boolean	optional	Whether to keep a copy in the account's Sent Items folder. Set false to send without recording it. Default: `true`
`subject`	string	optional	Subject line. Optional; defaults to an empty subject. Default: `""`
`to`	array of string	required	Primary recipients. At least one is required; `to`, `cc` and `bcc` together may not exceed 50 addresses. Min items: `1`

Used by: POST /rest/beta/outlook/send

Used by gmail

Models used by the gmail endpoints, including nested ones. That page also lists every model its operations use.

`GmailSendBody`

One message to send through the authorized Gmail account.

Gmail always stores a sent message in SENT, so there is no equivalent of Outlook's save_to_sent_items.

Field	Type		Description
`attachments`	array of `AttachmentIn`	optional	Files to attach: at most 10, totalling no more than 3 MB once decoded. Default: `[]`
`bcc`	array of string	optional	Blind-carbon-copy recipients, hidden from other recipients. Default: `[]`
`body`	`BodyContent`	required	The message body and whether it is plain text or HTML.
`cc`	array of string	optional	Carbon-copy recipients, visible to everyone. Default: `[]`
`subject`	string	optional	Subject line. Optional; defaults to an empty subject. Default: `""`
`to`	array of string	required	Primary recipients. At least one is required; `to`, `cc` and `bcc` together may not exceed 50 addresses. Min items: `1`

Used by: POST /rest/beta/gmail/send

Used by files

Models used by the files endpoints, including nested ones. That page also lists every model its operations use.

`ChartItem`

One chart already drawn in the spreadsheet.

Field	Type		Description
`chart_id`	integer	required	Numeric chart id. Pass as `chart_id` when creating a dashboard element.
`chart_type`	string	nullable	Normalized chart type, e.g. column, line, pie
`supported`	boolean	optional	False when Sheetgo cannot render this chart type on a dashboard Default: `true`
`tab_id`	integer	nullable	Numeric id of the tab the chart is drawn on.
`tab_name`	string	nullable	Name of that tab.
`title`	string	nullable	The chart's title as set in the spreadsheet, when it has one.

`ColumnItem`

One column of a tab's header row.

Field	Type		Description
`header`	string	nullable	The header cell exactly as stored (not trimmed — match it verbatim); null when the cell is empty.
`index`	integer	required	Zero-based column position.
`letter`	string	required	Spreadsheet column letter — the value automation column fields take (`filter`, `split`, `remove_duplicates`, `left_join`, `anonymize`).

`FileItem`

One file or folder, normalized across all four storage providers.

Field	Type		Description
`created_at`	string	nullable	ISO-8601 creation time as reported by the provider
`file_type`	`FileTypeFilter`	nullable	Automation file type; null when the item is outside the supported set
`id`	string	required	Provider id. Usable as an automation source/destination id, and as `parent` when browsing.
`is_folder`	boolean	optional	True when the item can be used as a `parent` Default: `false`
`kind`	`ItemKind`	optional	file \| folder \| site \| shared_drive \| virtual Default: `"file"`
`mime_type`	string	nullable	Provider mimetype
`modified_at`	string	nullable	ISO-8601 last-modified time as reported by the provider
`name`	string	nullable	Display name
`parent_id`	string	nullable	Containing folder id, when the provider reports one
`provider`	string	required	drive \| onedrive \| sharepoint \| dropbox
`size`	integer	nullable	Size in bytes; null or 0 for folders and for providers that omit it
`supports_structure`	boolean	optional	True when `GET /files/{provider}/{file_id}/structure` can describe this item (any spreadsheet: Google Sheets, Excel, CSV, TSV). Not a claim about reading its values. Default: `false`
`web_url`	string	nullable	Link to open the item in the provider UI; null when unavailable

Used by: GET /rest/beta/files/{provider}/{file_id}

`FileListResponse`

Standard paginated envelope plus a truncation flag.

truncated is true when the enumeration ceiling (FILE_DISCOVERY_MAX_ITEMS, or the internal byte ceiling) was reached, so items past it are not reachable by paging. Narrow with type or search.

Field	Type		Description
`page`	integer	nullable	Page number Default: `1`
`per_page`	integer	nullable	Number of items per page Default: `50`
`results`	array of `FileItem`	optional	List of results
`total`	integer	nullable	Total number of pages Default: `0`
`truncated`	boolean	optional	True when the listing was capped Default: `false`

Used by: GET /rest/beta/files/{provider}, GET /rest/beta/files/{provider}/roots, GET /rest/beta/files/{provider}/search

`FileStructureResponse`

What is inside one file.

Discriminated by file_type: the matching body key is populated and the others are absent. Today only spreadsheet exists; a future document variant adds document without changing this URL.

Field	Type		Description
`file_id`	string	required	Id of the file that was inspected.
`file_type`	string	required	Body discriminator, e.g. `spreadsheet`
`name`	string	nullable	The file's name.
`provider`	string	required	Storage provider the file lives on.
`resolved_file`	`ResolvedFile`	nullable	Set when `file_id` was a folder: the newest spreadsheet in it, whose structure is returned.
`spreadsheet`	`SpreadsheetStructure`	nullable	The spreadsheet's tabs, named ranges and charts. Populated when `file_type` is `spreadsheet`, absent otherwise.

Used by: GET /rest/beta/files/{provider}/{file_id}/structure

`FileTypeFilter`

Public type vocabulary.

The spreadsheet and folder values mirror :class:newapi.models.beta.connections.FileType, so such a value can be handed straight back in an automation payload as file_type.

gdocs is the exception: it has no FileType counterpart because a Google Docs id is passed as the document destination's template_id, a field that carries no file type. It is also the only value not returned by default -- ask for it explicitly.

Type: one of "gsheets", "xlsx", "csv", "tsv", "folder", "gdocs"

`ItemKind`

What a result is, beyond its file type.

site, shared_drive and virtual are only ever emitted by the /roots endpoint; browse and search return file or folder.

Type: one of "file", "folder", "site", "shared_drive", "virtual"

`NamedRangeItem`

One named range.

Field	Type		Description
`id`	string	nullable	Provider namedRangeId
`name`	string	nullable	The name as defined in the spreadsheet
`range`	string	nullable	A1 range the name resolves to
`tab_id`	integer	nullable	Numeric id of the tab the named range lives on.
`tab_name`	string	nullable	Name of that tab.

`ResolvedFile`

The spreadsheet a folder id resolved to.

Field	Type		Description
`id`	string	required	Id of the spreadsheet that was read.
`name`	string	nullable	Its name.

`SpreadsheetStructure`

Spreadsheet body of a structure response.

A section is null when it was not requested via include, and an empty list when it was requested and the spreadsheet has none.

Field	Type		Description
`charts`	array of `ChartItem`	nullable	Charts already drawn in the spreadsheet. Each carries the `chart_id` a chart-reference dashboard element needs.
`columns_truncated`	boolean	nullable	Present when `include=columns` was requested. True when at least one tab's `columns` is null because only the first tabs are read by default (pass `all_tabs=true` or `tab=`) or the read ran out of time.
`named_ranges`	array of `NamedRangeItem`	nullable	Named ranges defined in the spreadsheet.
`tabs`	array of `TabItem`	nullable	The spreadsheet's tabs, in workbook order. Each carries the `tab_id` a dashboard element needs.

`TabItem`

One tab (sheet) of a spreadsheet.

Field	Type		Description
`cols`	integer	nullable	Grid column count
`columns`	array of `ColumnItem`	nullable	Letter → header map of this tab, when `include=columns` read it. Null when not requested, or not read (see `columns_truncated`).
`hidden`	boolean	optional	True when the tab is hidden in the UI Default: `false`
`id`	integer	nullable	Numeric Google sheetId (Google Sheets only; null for Excel/CSV, whose tabs are identified by `name`). Pass as `tab_id` when creating a dashboard element.
`index`	integer	nullable	Zero-based position
`name`	string	nullable	Tab title
`rows`	integer	nullable	Grid row count
`type`	string	nullable	Provider sheet type, e.g. GRID

Used by bigquery

Models used by the bigquery endpoints, including nested ones. That page also lists every model its operations use.

`BigQueryDataset`

Field	Type		Description
`id`	string	required	Dataset id. Pass this back as `dataset`.
`name`	string	nullable	Display name

`BigQueryDatasetListResponse`

Field	Type		Description
`page`	integer	nullable	Page number Default: `1`
`per_page`	integer	nullable	Number of items per page Default: `50`
`results`	array of `BigQueryDataset`	optional	List of results
`total`	integer	nullable	Total number of pages Default: `0`
`truncated`	boolean	optional	True when the listing hit `BIGQUERY_DISCOVERY_MAX_ITEMS`, so items past it are not reachable by paging. Default: `false`

Used by: GET /rest/beta/bigquery/projects/{project}/datasets

`BigQueryPartitioningInfo`

How an existing table is partitioned.

An existing table keeps its own partitioning regardless of what a destination payload asks for, so this is what a destination will actually write into.

Field	Type		Description
`field`	string	nullable	Partition column; null for ingestion-time partitioning
`granularity`	string	nullable	HOUR, DAY, MONTH or YEAR
`is_ingestion_time`	boolean	optional	True when partitioned by ingestion time Default: `false`
`type`	string	nullable	The column's BigQuery type

`BigQueryProject`

One GCP project visible to the authorized account.

Field	Type		Description
`id`	string	required	Project id. Pass this back as `project` in an automation source or destination.
`name`	string	nullable	Display name
`numeric_id`	string	nullable	The project's numeric id. Accepted as `project` too, but the string id above is the readable form.

`BigQueryProjectListResponse`

Field	Type		Description
`page`	integer	nullable	Page number Default: `1`
`per_page`	integer	nullable	Number of items per page Default: `50`
`results`	array of `BigQueryProject`	optional	List of results
`total`	integer	nullable	Total number of pages Default: `0`
`truncated`	boolean	optional	True when the listing hit `BIGQUERY_DISCOVERY_MAX_ITEMS`, so items past it are not reachable by paging. Default: `false`

Used by: GET /rest/beta/bigquery/projects

`BigQueryTable`

Field	Type		Description
`id`	string	required	Table id. Pass this back as `table`.
`name`	string	nullable	Display name

`BigQueryTableDetail`

One table, with the typed schema a destination's partition.field needs.

Field	Type		Description
`dataset`	string	required	Dataset the table belongs to.
`num_bytes`	integer	nullable	Size in bytes
`num_rows`	integer	nullable	Row count as BigQuery reports it
`partitioning`	`BigQueryPartitioningInfo`	nullable	Null when the table is not partitioned
`project`	string	required	Google Cloud project the table belongs to.
`schema`	object (map of string → string)	optional	Column name to BigQuery type, e.g. `{"Rank": "INTEGER", "created_at": "TIMESTAMP"}`. A destination's `partition.field` must name one of these, and its type is inferred from here.
`table`	string	required	The table's own id, unqualified.

Used by: GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}

`BigQueryTableListResponse`

Field	Type		Description
`page`	integer	nullable	Page number Default: `1`
`per_page`	integer	nullable	Number of items per page Default: `50`
`results`	array of `BigQueryTable`	optional	List of results
`total`	integer	nullable	Total number of pages Default: `0`
`truncated`	boolean	optional	True when the listing hit `BIGQUERY_DISCOVERY_MAX_ITEMS`, so items past it are not reachable by paging. Default: `false`

Used by: GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables

`ValidateQueryRequest`

Field	Type		Description
`query`	string	required	The SQL to check. Standard SQL; legacy SQL is not used.

Used by: POST /rest/beta/bigquery/projects/{project}/validate-query

`ValidateQueryResponse`

The dry run's verdict. Nothing was scanned and nothing was mutated.

A query that will not parse is a legitimate answer here, not an error: this endpoint returns 200 with valid: false.

Field	Type		Description
`error`	string	nullable	BigQuery's explanation when `valid` is false
`schema`	object (map of string → string)	nullable	Columns the query would return, with their types
`statement_type`	string	nullable	`SELECT`, `INSERT`, `DELETE`, … as BigQuery classifies it. Note a valid `DELETE` reports `valid: true` — this endpoint reports what the statement is, it does not refuse writes.
`total_bytes_processed`	integer	nullable	Bytes the query would scan. Use it to size the cost of an uncapped source query before creating the automation.
`valid`	boolean	required	False when BigQuery rejected the SQL

Used by: POST /rest/beta/bigquery/projects/{project}/validate-query

Used by auth

Models used by the auth endpoints, including nested ones. That page also lists every model its operations use.

`Body_auth_token_rest_auth_token_post`

Field	Type		Description
`client_id`	string	required	Your application's client id.
`client_secret`	string	required	Your application's client secret. Never expose it in a browser or mobile client.
`code`	string	required	The single-use authorization code returned to your redirect URI by the authorize step.
`grant_type`	string	required	OAuth2 grant type. Must be `authorization_code`.
`redirect_uri`	string	required	The same redirect URI that was used to obtain `code`. It must match your application's registered URI exactly.

Used by: POST /rest/auth/token

`ExchangedToken`

The token pair returned by the OAuth2 token and refresh endpoints.

Field	Type		Description
`access_token`	string	required	Short-lived bearer token. Send it as `Authorization: Bearer <access_token>` on API calls.
`refresh_token`	string	required	Long-lived token used to obtain a new access token from `POST /rest/auth/refresh` once the access token expires. Store it securely; it is as sensitive as a password.

Used by: POST /rest/auth/refresh, POST /rest/auth/token

`RefreshTokenRequest`

The parameters used when refreshing a token

Field	Type		Description
`client_id`	string	required	Your application's client id.
`client_secret`	string	required	Your application's client secret. Never expose it in a browser or mobile client.
`grant_type`	string	optional	OAuth2 grant type. Must be `refresh_token` for this endpoint. Default: `"refresh_token"`
`refresh_token`	string	required	The refresh token previously issued by `POST /rest/auth/token`.

Used by: POST /rest/auth/refresh

Common (used by 3 or more groups)

`FileType`

Type: one of "gsheets", "xlsx", "csv", "tsv", "folder"

`HTTPValidationError`

Field	Type		Description
`detail`	array of `ValidationError`	optional

`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

`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

`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}

`ValidationError`

Field	Type
`loc`	array of string or integer	required
`msg`	string	required
`type`	string	required