---
title: "List folders"
method: GET
path: "/v1/folders"
tags: ["Folders"]
---

# List folders

`GET /v1/folders`

Retrieve a paginated list of folders within an organization. Supports filtering, sorting, and cursor-based pagination.

The folders endpoint behaves differently based on the type of API key used to authenticate the request:

- **Organization-scoped API keys:** Full access to all folders. Can view any user's restricted folders with `ownerId`. Must provide `ownerId` for `scope=restricted`.
- **Personal Access Tokens (PAT):** Permission-filtered access matching the UI.
   - For `scope=organization` - Returns all organization-shared folders the user can access
   - For `scope=restricted` - Returns only the user's own restricted folders. An `ownerId` is optional; if not provided, it will be auto-inferred and the API will return only the folders belonging to PAT owner.

## Query parameters

- `include` string
- `path` string
- `labels` string[]
- `scope` 'organization' | 'restricted'
- `sortField` 'favorites' | 'name' | 'path'
- `sortDirection` 'asc' | 'desc'
- `cursor` string
- `pageSize` integer
- `ownerId` string, uuid
- `userId` string, uuid

## Response `200`

Paginated folder list

- object
  - `records` Folder[] — Array of folder objects matching the query.
    - `id` string, uuid — Unique identifier for the folder.
    - `name` string — Display name of the folder.
    - `path` string — Full path to the folder.
    - `scope` 'organization' | 'restricted' — Visibility scope of the folder. - `organization` - Organization-wide access - `restricted` - Limited access
    - `owner` object — Information about the folder owner.
      - `id` string — ID of the folder owner.
      - `name` string — Display name of the owner.
    - `labels` string[] — List of labels associated with the folder. Only included when requested via the `include` parameter.
    - `_count` object — Contains count information. Only included when requested via the `include` parameter.
      - `documents` integer — Number of documents contained in the folder.
      - `favorites` integer — Number of users who favorited this folder.
    - `url` string, uri — Direct link to the folder in the Omni UI.
  - `pageInfo` PageInfo — Pagination information for paginated responses.
    - `hasNextPage` boolean — Indicates if there are more records available.
    - `nextCursor` string, nullable — Cursor for the next page of results. `null` if no more results.
    - `pageSize` integer — Number of records per page.
    - `totalRecords` integer — Total number of records matching the query.

## Other responses

- `400` — Bad Request Possible error messages: - `Bad Request: pageSize: Page size must be at least 1` - `Bad Request: ownerId: ownerId is required when scope is 'restricted'` (organization-scoped API keys only) - `Bad Request: sortField: Invalid enum value. Expected 'name' | 'path', received '<invalidField>'` - `Bad Request: include: Invalid value. Expected: _count, labels, onlySharedWithMe, received '<invalidValue>'` - `Bad Request: Invalid path pattern. Only a single wildcard (*) is allowed at the end of the pattern` - `Bad Request: onlySharedWithMe requires userId` - When using `include=onlySharedWithMe` with an Organization API key without providing a `userId` parameter - `Bad Request: onlySharedWithMe cannot be combined with ownerId` - When using `include=onlySharedWithMe` with an `ownerId` parameter - `Bad Request: onlySharedWithMe cannot be combined with path` - When using `include=onlySharedWithMe` with a `path` parameter
- `403` — Forbidden Possible error messages/causes: - Personal Access Tokens (PAT) cannot access other users' restricted folders. - `User-scoped API keys cannot act on behalf of other users` - Operations targeting personal/restricted scope require the user's **Personal content access** setting (`omni_allows_personal_content` system attribute) to be enabled for the user. If not enabled, the API will respond with `403 Forbidden`.
- `404` — Not Found Possible error messages: - `Folder with path <path> does not exist` - `User membership not found`
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)