files

REST API · 5 endpoints

Complete for this group. Each operation below lists its parameters, request body, responses and errors. Every model they use is documented under Models used on this page, so you do not need another page to build a request. Base URL https://dev-api.sheetgo.com; send Authorization: Bearer sg_…. Latest version: https://dev-api.sheetgo.com/rest/reference/files (Markdown).

Conventions for every endpoint. Lists take page (from 1) and per_page (1-100, default 50), and total counts pages, not items. Collection URLs end with /. POST …/run returns 200 when the run is queued; poll GET …/run. Google Sheets use provider: "drive"; column fields take letters ("E"). Error bodies and status codes: api.html#api-errors.

Python recipes. API client helper · Read every page of a list · Find a file and build an automation payload.

Browse and search the storage providers connected to your account — Google Drive, OneDrive, SharePoint and Dropbox — to find the ids you need when building an automation.

Every result carries id, provider and file_type, which is exactly what a source or destination needs, so a result can be used in an automation payload without translation. Folders are returned alongside files; filter with type=folder when you only want containers.

Start at /files/{provider}/roots to discover where browsing can begin: SharePoint sites, Drive shared drives and virtual containers such as Shared with me are only reachable from there. These endpoints are read-only — files are created through the automation payload.

Google Docs are not returned by default. Pass type=gdocs to find a Google Docs file for a document destination's template_id — it is the one type omitted from an unfiltered listing, and it exists on Google Drive only.

Operations

GET/rest/beta/files/{provider}Browse a folder

List the direct contents of one folder, files and folders interleaved.

Parameters

Name	In	Type		Description
`provider`	path	`Provider`	required	Storage provider: drive, onedrive, sharepoint or dropbox
`parent`	query	string	optional	Folder id to list. Defaults to the provider root. Use `/files/{provider}/roots` to discover valid starting points (SharePoint sites, Drive shared drives, Shared with me). Default: `"root"`
`type`	query	string	optional	Comma-separated list of file types to include: `gsheets`, `xlsx`, `csv`, `tsv`, `folder`, `gdocs`. Omit for every supported type except `gdocs`: Google Docs are not returned by default, so request `type=gdocs` to find a document template (Google Drive only). Example: `"gsheets,xlsx"`
`page`	query	integer	optional	Page number, 1-based Default: `1` · Min: `1`
`per_page`	query	integer	optional	Items per page Default: `50` · Min: `1` · Max: `100`

Responses

Status	Meaning	Body
200	Folder contents	`FileListResponse`
401	Authentication failed or token is invalid	—
412	Provider account not connected	—
422	Validation Error	`HTTPValidationError`

Example request

curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/files/PROVIDER" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/files#get-rest-beta-files-provider

GET/rest/beta/files/{provider}/rootsList browsable entry points

Where browsing can start for this provider.

SharePoint ids are site-qualified, so its sites are only reachable through this endpoint. Drive adds its shared drives and virtual containers here. Each entry's id can be passed straight back as parent.

Parameters

Name	In	Type		Description
`provider`	path	`Provider`	required	Storage provider: drive, onedrive, sharepoint or dropbox

Responses

Status	Meaning	Body
200	Entry points	`FileListResponse`
401	Authentication failed or token is invalid	—
412	Provider account not connected	—
422	Validation Error	`HTTPValidationError`

Example request

curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/files/PROVIDER/roots" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/files#get-rest-beta-files-provider-roots

GET/rest/beta/files/{provider}/searchSearch files and folders by name

Search the whole connected account by name.

Results keep the provider's relevance order rather than being sorted alphabetically, so the best match stays on the first page.

Parameters

Name	In	Type		Description
`provider`	path	`Provider`	required	Storage provider: drive, onedrive, sharepoint or dropbox
`q`	query	string	required	Name to search for, across the whole connected account. Drive and SharePoint also accept a pasted file URL and resolve it to that exact item. Min length: `1`
`type`	query	string	optional	Comma-separated list of file types to include: `gsheets`, `xlsx`, `csv`, `tsv`, `folder`, `gdocs`. Omit for every supported type except `gdocs`: Google Docs are not returned by default, so request `type=gdocs` to find a document template (Google Drive only). Example: `"gsheets,xlsx"`
`page`	query	integer	optional	Page number, 1-based Default: `1` · Min: `1`
`per_page`	query	integer	optional	Items per page Default: `50` · Min: `1` · Max: `100`

Responses

Status	Meaning	Body
200	Search results	`FileListResponse`
401	Authentication failed or token is invalid	—
412	Provider account not connected	—
422	Validation Error	`HTTPValidationError`

Example request

curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/files/PROVIDER/search?q=Q" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/files#get-rest-beta-files-provider-search

GET/rest/beta/files/{provider}/{file_id}Get one file or folder

Resolve a single id — useful to validate one before building an automation.

Parameters

Name	In	Type		Description
`provider`	path	`Provider`	required	Storage provider: drive, onedrive, sharepoint or dropbox
`file_id`	path	string	required	Provider file or folder id

Responses

Status	Meaning	Body
200	Item metadata	`FileItem`
401	Authentication failed or token is invalid	—
404	Item not found or not accessible	—
412	Provider account not connected	—
422	Validation Error	`HTTPValidationError`

Example request

curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/files/PROVIDER/FILE_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/files#get-rest-beta-files-provider-file-id

GET/rest/beta/files/{provider}/{file_id}/structureDescribe what is inside a file

Tabs, column letters, named ranges and charts of a spreadsheet.

include=columns returns, per tab, the letter → header map that automation column fields (filter, split, remove_duplicates, left_join, anonymize) need: they take the LETTER (D), not the header (Status).

Cost: this reads the file. Google Sheets and Excel on SharePoint cost a provider read per call; other files (CSV/TSV, and Excel on Drive, Dropbox or OneDrive) are downloaded and parsed, and the first read of a large file takes seconds. Pass tab= and reuse the result: repeat reads of the same file, header_row and tabs are answered from a cache without reopening the file, until it changes.

The ids returned are what a dashboard element needs: tabs[].id is the numeric tab_id (Google Sheets only), charts[].chart_id the chart_id.

Parameters

Name	In	Type		Description
`provider`	path	`Provider`	required	Storage provider: drive, onedrive, sharepoint or dropbox
`file_id`	path	string	required	Provider file id, or a folder id (its newest spreadsheet is read)
`include`	query	string	optional	Comma-separated sections: `tabs`, `columns`, `named_ranges`, `charts`. Default: `tabs,named_ranges,charts` for Google Sheets, `tabs` for Excel/CSV/TSV. `columns` (the letter → header map automation column fields need) is never in the default and implies `tabs`. `named_ranges` and `charts` exist only in Google Sheets.
`tab`	query	string	optional	`columns` for this tab only (by name). Cannot be combined with `all_tabs`.
`all_tabs`	query	boolean	optional	`columns` for every tab. Without it and without `tab`, only the first 10 tabs are read and `columns_truncated` is true. Default: `false`
`header_row`	query	integer	optional	Row holding the headers (1-based). Must match the source's `offset_header`. Default: `1`

Responses

Status	Meaning	Body
200	What is inside the file	`FileStructureResponse`
400	Unknown include value, or invalid tab / all_tabs / header_row	—
401	Authentication failed or token is invalid	—
404	File, folder content or tab not found	—
412	Provider account not connected	—
422	Not a spreadsheet (unsupported_file_type), a section the file cannot have (section_not_available), or a downloaded file above the size limit (file_too_large)	—

Example request

curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/files/PROVIDER/FILE_ID/structure" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/files#get-rest-beta-files-provider-file-id-structure

Models used on this page

Every request and response model referenced above, including nested ones (14). The full catalogue is on api-models.html.

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

`HTTPValidationError`

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

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

`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

`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

`ValidationError`

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