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

# List folders

`GET /api/v1/folders`

## Query parameters

- `cursor` string — Cursor for pagination
- `include` string — Comma-separated list of fields to include (_count, labels, onlySharedWithMe). onlySharedWithMe returns only folders shared with the user, cannot be combined with ownerId or path, and when used with org-scoped API keys requires the userId query parameter. For user-scoped keys (PAT), userId is auto-inferred from the token.
- `labels` string — Comma-separated list of labels to filter by
- `ownerId` string, uuid — Filter by owner user ID
- `pageSize` number, nullable — Number of results per page
- `path` string — Filter by exact path
- `scope` 'organization' | 'restricted' — Filter by share scope
- `sortDirection` 'asc' | 'desc' — Sort direction
- `sortField` 'name' | 'createdAt' | 'updatedAt' | 'favorites' | 'path' — Field to sort by
- `userId` string, uuid — User membership ID. Only used with onlySharedWithMe include field. Required for org-scoped API keys; auto-inferred from the token for user-scoped keys (PAT).

## Response `200`

Paginated list of folders

- FoldersListResponse
  - `pageInfo` object, required — Pagination information
    - `hasNextPage` boolean, required — Whether more results are available
    - `nextCursor` string, nullable, required — Cursor for fetching the next page
    - `pageSize` number, required — Number of results per page
    - `totalRecords` number, required — Total number of records matching the query
  - `records` object[], required — List of folders
    - `_count` object — Count statistics for the folder
      - `documents` number, required — Number of documents in the folder
      - `favorites` number, required — Number of users who have favorited this folder
    - `id` string, uuid, required — Unique folder identifier
    - `labels` string[] — Labels associated with the folder
    - `name` string, required — Name of the folder
    - `ownerId` string, uuid, required — User ID of the folder owner
    - `path` string, required — Full path to the folder
    - `url` string, required — URL to view the folder in the Omni UI.

## Other responses

- `401` — Authentication required
- `404` — Folder not found (when filtering by path)

---

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