List Folders

GET /v1/folders

List Folders

GET /v1/folders

List folders for the authenticated user. Requires the folders:read role.

Request

Headers

Header	Required	Description
X-API-Key	Yes	Your API key

Query Parameters

Parameter	Type	Required	Description
parent_id	string	No	Filter by parent folder. Omit for root folders.

Example

# List root folders
curl https://api.surfacedocs.dev/v1/folders \
  -H "X-API-Key: sd_live_..."

# List subfolders
curl "https://api.surfacedocs.dev/v1/folders?parent_id=fld_abc123" \
  -H "X-API-Key: sd_live_..."

Response

Status: 200 OK

{
  "folders": [
    {
      "id": "fld_abc123",
      "name": "Engineering",
      "parent_id": null,
      "path": "/Engineering",
      "depth": 0,
      "created_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "fld_def456",
      "name": "Reports",
      "parent_id": null,
      "path": "/Reports",
      "depth": 0,
      "created_at": "2025-01-16T08:00:00Z"
    }
  ]
}