# files

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.

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

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

Guide: [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md)

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

<a id="get-rest-beta-files-provider"></a>
## GET /rest/beta/files/{provider}

**Browse a folder**

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

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

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `provider` | path | [Provider](https://dev-api.sheetgo.com/rest/reference/models/Provider.md) | yes | Storage provider: drive, onedrive, sharepoint or dropbox |  |
| `parent` | query | string | no | 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, nullable | no | 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). |  |
| `page` | query | integer | no | Page number, 1-based | default: `1`; min: 1 |
| `per_page` | query | integer | no | Items per page | default: `50`; min: 1; max: 100 |

**Responses**

- `200` Folder contents. Schema: [FileListResponse](https://dev-api.sheetgo.com/rest/reference/models/FileListResponse.md)
- `401` Authentication failed or token is invalid
- `412` Provider account not connected
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [FileListResponse](https://dev-api.sheetgo.com/rest/reference/models/FileListResponse.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-files-provider-search"></a>
## GET /rest/beta/files/{provider}/search

**Search 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.

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

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `provider` | path | [Provider](https://dev-api.sheetgo.com/rest/reference/models/Provider.md) | yes | Storage provider: drive, onedrive, sharepoint or dropbox |  |
| `q` | query | string | yes | 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, nullable | no | 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). |  |
| `page` | query | integer | no | Page number, 1-based | default: `1`; min: 1 |
| `per_page` | query | integer | no | Items per page | default: `50`; min: 1; max: 100 |

**Responses**

- `200` Search results. Schema: [FileListResponse](https://dev-api.sheetgo.com/rest/reference/models/FileListResponse.md)
- `401` Authentication failed or token is invalid
- `412` Provider account not connected
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [FileListResponse](https://dev-api.sheetgo.com/rest/reference/models/FileListResponse.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-files-provider-roots"></a>
## GET /rest/beta/files/{provider}/roots

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

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

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `provider` | path | [Provider](https://dev-api.sheetgo.com/rest/reference/models/Provider.md) | yes | Storage provider: drive, onedrive, sharepoint or dropbox |  |

**Responses**

- `200` Entry points. Schema: [FileListResponse](https://dev-api.sheetgo.com/rest/reference/models/FileListResponse.md)
- `401` Authentication failed or token is invalid
- `412` Provider account not connected
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [FileListResponse](https://dev-api.sheetgo.com/rest/reference/models/FileListResponse.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-files-provider-file-id"></a>
## GET /rest/beta/files/{provider}/{file_id}

**Get one file or folder**

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

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

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `provider` | path | [Provider](https://dev-api.sheetgo.com/rest/reference/models/Provider.md) | yes | Storage provider: drive, onedrive, sharepoint or dropbox |  |
| `file_id` | path | string | yes | Provider file or folder id |  |

**Responses**

- `200` Item metadata. Schema: [FileItem](https://dev-api.sheetgo.com/rest/reference/models/FileItem.md)
- `401` Authentication failed or token is invalid
- `404` Item not found or not accessible
- `412` Provider account not connected
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [FileItem](https://dev-api.sheetgo.com/rest/reference/models/FileItem.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-files-provider-file-id-structure"></a>
## GET /rest/beta/files/{provider}/{file_id}/structure

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

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

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `provider` | path | [Provider](https://dev-api.sheetgo.com/rest/reference/models/Provider.md) | yes | Storage provider: drive, onedrive, sharepoint or dropbox |  |
| `file_id` | path | string | yes | Provider file id, or a folder id (its newest spreadsheet is read) |  |
| `include` | query | string | no | 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 | no | `columns` for this tab only (by name). Cannot be combined with `all_tabs`. |  |
| `all_tabs` | query | boolean | no | `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 | no | Row holding the headers (1-based). Must match the source's `offset_header`. | default: `1` |

**Responses**

- `200` What is inside the file. Schema: [FileStructureResponse](https://dev-api.sheetgo.com/rest/reference/models/FileStructureResponse.md)
- `401` Authentication failed or token is invalid
- `400` Unknown include value, or invalid tab / all_tabs / header_row
- `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)

Read next: [FileStructureResponse](https://dev-api.sheetgo.com/rest/reference/models/FileStructureResponse.md).

---

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