← API referenceBrowse & search · API access unavailable
API REFERENCE / BROWSE & SEARCH
GET /v1/folders/{folder_id}
Read one folder’s name, visible parent, revision, and effective access role.
Request fields
| Location | Field | Type | Required | Description |
|---|---|---|---|---|
| Header | Authorization | string | Yes | Credential scoped to the authorized resource. |
| Path | folder_id | string | Yes | Stable Atom folder ID. |
Request example
Example request
GET /v1/folders/folder_123
Authorization: Bearer <scoped token>HTTP status codes
| Status | Meaning |
|---|---|
200 OK | Success response shown below. |
401 Unauthorized | Missing, expired, or invalid credential. |
403 Forbidden | Credential is valid but lacks the required scope or role. |
404 Not Found | Folder does not exist or is not visible. |
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 |
|---|---|---|
id | string | folder_123 |
name | string | Projects |
parent_id | null | null |
revision | string | rev_007 |
access_role | string (enum) | editor Allowed values · closed enum viewereditorowner |
Response example
Example response
200 OK
Content-Type: application/json
{
"id": "folder_123",
"name": "Projects",
"parent_id": null,
"revision": "rev_007",
"access_role": "editor"
}How it works
Use one role rather than a stored list of action flags: viewer can browse and read; editor can also add, edit, and remove items inside the folder; owner can additionally rename, move, or trash the folder and manage sharing. The API derives permitted actions from this role and checks token scopes separately. A folder ID never bypasses a grant. A null parent_id means no parent is visible to this caller; it does not prove the folder is the owner’s top-level folder.