> ## Documentation Index
> Fetch the complete documentation index at: https://surfacedocs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
# 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**

```json theme={null}
{
  "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"
    }
  ]
}
```