GET /v1/roots — Atom Files Developers

← API referenceBrowse & search · API access unavailable

API REFERENCE / BROWSE & SEARCH

`GET` /v1/roots

List the folder roots this caller may enter, not every folder in the account.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Query	`limit`	integer	No	Page size, 1–200; defaults to 100.
Query	`sort`	string (enum)	No	name_asc (default) or modified_desc. Allowed values · closed enum`name_ascmodified_desc`
Query	`cursor`	string	No	Opaque next-page cursor bound to this caller and sort order.

Request example

Example request

GET /v1/roots?limit=100&sort=name_asc
Authorization: Bearer <scoped token>

HTTP status codes

Status	Meaning
`200 OK`	Success response shown below.
`400 Bad Request`	Invalid limit, sort, or pagination cursor.
`401 Unauthorized`	Missing, expired, or invalid credential.
`403 Forbidden`	Credential is valid but lacks the required scope or role.
`410 Gone`	Pagination cursor expired; restart this listing.
`429 Too Many Requests`	Rate limit reached; honor Retry-After when provided.
`503 Service Unavailable`	Service temporarily unavailable; retry safely.

Response fields

Field	Type	Example
`items`	object[]	[2 shown]
`items[].id`	string	folder_private
`items[].type`	string (enum)	folder Allowed values · closed enum`folder`
`items[].name`	string	My files
`items[].root_kind`	string (enum)	owned Allowed values · closed enum`ownedsharedsource`
`items[].modified_at`	string (date-time)	2026-10-20T18:00:00Z
`items[].grant_id`	string \| null	null
`next_cursor`	string \| null	null

Response example

Example response

200 OK
Content-Type: application/json

{
  "items": [
    {
      "id": "folder_private",
      "type": "folder",
      "name": "My files",
      "root_kind": "owned",
      "modified_at": "2026-10-20T18:00:00Z",
      "grant_id": null
    },
    {
      "id": "folder_123",
      "type": "folder",
      "name": "Projects",
      "root_kind": "shared",
      "modified_at": "2026-10-19T18:00:00Z",
      "grant_id": "grant_123"
    }
  ],
  "next_cursor": null
}

How it works

Where browsing starts. GET /v1/roots returns only folders this token can enter: owned roots, shared folders, and accessible connected sources. A shared folder may be deep in its owner’s tree; private ancestors stay hidden. App labels such as PRIVATE, SHARED, and SOURCES are not folder IDs. Open a returned root with GET /v1/folders/{folder_id}/children.

How pages work. Both routes return items and next_cursor. Follow next_cursor until it is null. Keep the same sort while paging (name_asc by default, or modified_desc); changing sort starts a new listing. An item ID breaks ties. Folder children contain files and folders in one sorted list.

What if things change? Browsing is live. For example, if page one ends at M and Zebra is renamed Apple before page two, Apple may be missed because it moved before the cursor. De-duplicate by item ID and refresh after change notifications. Offline or connected-source edits appear only after their metadata syncs.

When to use a snapshot. Use GET /v1/changes/snapshot when starting a sync client that needs a complete metadata inventory. All its pages describe the same point-in-time view of metadata Atom has already indexed; the final page returns a cursor for subsequent changes. This does not lock the tree, include unsynced edits, or capture file bytes. Every request still checks current access, so revocation takes effect even if an older cursor exists.