> ## Documentation Index > Fetch the complete documentation index at: https://docs.qontext.ai/llms.txt > Use this file to discover all available pages before exploring further. # List folders > Lists one folder by `path`, every folder below `path_prefix`, or direct children by `parent_id`. Without a selector it lists root folders. Cursor paginated, never offset. A short page does not mean the end: items the key may not read are dropped after the page is read, so page until `hasMore` is false. ## OpenAPI ````yaml api-reference/public-api.json GET /v1/folders openapi: 3.0.0 info: title: Qontext API description: Read and write the knowledge a workspace has ingested. version: 1.0.0 contact: {} servers: - url: https://api.qontext.ai description: Production security: [] tags: - name: Files description: >- Read and write the files in a workspace. What you read, and what an accepted change goes into, is the live files: the accepted state of the world. A change to a protected file goes to review instead of being accepted automatically, and stays in review until somebody accepts or rejects it. - name: Folders description: >- The tree the files sit in. A folder id survives a rename and a move, and so does every id below it, so ids a client holds stay valid while paths change. - name: Search description: >- Find files by meaning or by a regular expression. Both search the live files, both answer one page of the best matches, and both drop a file this key may not read. paths: /v1/folders: get: tags: - Folders summary: List folders description: >- Lists one folder by `path`, every folder below `path_prefix`, or direct children by `parent_id`. Without a selector it lists root folders. Cursor paginated, never offset. A short page does not mean the end: items the key may not read are dropped after the page is read, so page until `hasMore` is false. operationId: FoldersController_listFolders parameters: - name: limit required: false in: query description: >- Maximum items in one page. A page may come back shorter; read `hasMore`, not the count. schema: minimum: 1 maximum: 1000 default: 100 type: number - name: cursor required: false in: query description: >- A `nextCursor` from an earlier page. Opaque: store and echo it, never parse or construct one. A cursor belongs to the query that issued it, so changing a filter means starting again from the first page; reusing one across filters answers `invalid_cursor` rather than a page from the wrong collection. schema: type: string - name: path required: false in: query description: >- Exact path to a folder. A path naming nothing is an empty collection. The root itself is not addressable here; omit every selector to list root folders. schema: example: /support/policies type: string - name: path_prefix required: false in: query description: >- Every folder below this folder, recursively. A prefix naming nothing is an empty collection. schema: example: /support type: string - name: parent_id required: false in: query description: >- Lists folders directly inside this parent. Omit it to list root folders. schema: example: dir_9f2k1x8b3m7q0v type: string responses: '200': description: A page of folders. Read `hasMore` before stopping. content: application/json: schema: $ref: '#/components/schemas/FolderList' '400': description: >- `invalid_request`: unknown or malformed parameter, see `errors`. `invalid_cursor`: the `cursor` is malformed or was issued for a different query; start again from the first page. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: invalid_request: summary: Invalid request value: type: https://docs.qontext.ai/errors/invalid-request title: Invalid request status: 400 code: invalid_request detail: The request could not be accepted as sent. requestId: 3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b errors: - code: out_of_range pointer: /limit detail: limit must not be greater than 1000 invalid_cursor: summary: Invalid cursor value: type: https://docs.qontext.ai/errors/invalid-cursor title: Invalid cursor status: 400 code: invalid_cursor detail: >- This cursor could not be read. Start again from the first page. requestId: 3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b '401': description: '`unauthenticated`: missing or invalid API key' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: unauthenticated: summary: Unauthenticated value: type: https://docs.qontext.ai/errors/unauthenticated title: Unauthenticated status: 401 code: unauthenticated detail: The API key is missing or not valid. requestId: 3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b '404': description: '`folder_not_found`: no such parent folder readable with this key' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: folder_not_found: summary: Folder not found value: type: https://docs.qontext.ai/errors/folder-not-found title: Folder not found status: 404 code: folder_not_found detail: >- No folder at that path, or none this key is allowed to read. requestId: 3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b '500': description: '`internal_error`: unexpected failure, already reported' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: internal_error: summary: Internal error value: type: https://docs.qontext.ai/errors/internal-error title: Internal error status: 500 code: internal_error detail: An unexpected error occurred. requestId: 3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b '503': description: >- `service_unavailable`: temporarily unreachable. Honour `Retry-After`. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: service_unavailable: summary: Temporarily unavailable value: type: https://docs.qontext.ai/errors/service-unavailable title: Temporarily unavailable status: 503 code: service_unavailable detail: This workspace is temporarily unavailable. requestId: 3f9c2b7e4d1a48c0b6e5f2a19d7c3e8b security: - Authorization: [] - X-API-Key: [] components: schemas: FolderList: type: object properties: object: type: string enum: - list description: Type discriminator. Always `list`. url: type: string example: /v1/files description: >- The collection this page came from, without the query that selected it. hasMore: type: boolean description: >- Whether more items remain. A short page does not mean the end: unreadable items are dropped after the page is read. Page until this is false. nextCursor: type: string nullable: true example: c_9f2k1x8b3m7q0v description: >- Opaque. Pass back as `cursor`. Present whenever `hasMore` is true, `null` on the last page. data: description: The folders on this page. type: array items: $ref: '#/components/schemas/Folder' required: - object - url - hasMore - nextCursor - data Problem: type: object properties: type: type: string example: https://docs.qontext.ai/errors/file-not-found description: >- Stable URI for this kind of failure. Branch on this or on `code`, never on `title` or `detail`. title: type: string example: File not found description: Human label. Not for branching on. status: type: number example: 404 description: Matches the HTTP status. code: type: string example: file_not_found description: Stable machine code. This is what a client branches on. detail: type: string description: >- Human explanation, safe to display. Never a stack trace or engine detail. requestId: type: string description: >- Echoes the `X-Request-Id` response header. One string locates the log line for this call. errors: description: Present when the failure is attributable to specific inputs. type: array items: $ref: '#/components/schemas/FieldError' required: - type - title - status - code - detail - requestId Folder: type: object properties: object: type: string enum: - folder description: Type discriminator. Always `folder`. id: type: string example: dir_9f2k1x8b3m7q0v description: Stable id. Survives a rename or a move. name: type: string example: reports description: Leaf name, without any part of the path. parentId: type: string example: dir_4k1n8p2v5m7q0x nullable: true description: The containing folder, or `null` when this folder sits at the root. parentPath: type: string example: /projects description: Path of the containing folder. `/` at the root. path: type: string example: /projects/reports description: Live folder location. Changes when the folder moves. protected: type: boolean description: >- When true, a change to any file inside this folder goes to review instead of being accepted automatically, however the file itself is flagged. createdAt: type: string format: date-time example: '2026-07-01T09:12:00.000Z' description: When the folder was created. updatedAt: type: string format: date-time example: '2026-08-01T14:03:00.000Z' description: When the folder was last updated. required: - object - id - name - parentId - parentPath - path - protected - createdAt - updatedAt FieldError: type: object properties: code: type: string example: out_of_range description: Stable machine token for what was wrong with this field. pointer: type: string example: /limit description: JSON Pointer to the offending member. detail: type: string example: limit must not be greater than 1000 description: >- Human explanation for this field alone. Branch on `code`, not on this. required: - code - pointer - detail securitySchemes: Authorization: type: http scheme: bearer description: >- Workspace-scoped API key, sent as a bearer token. The recommended header. The workspace is implicit in the key and never appears in a URL. X-API-Key: type: apiKey in: header name: X-API-Key description: >- The same workspace-scoped API key under its original header. Still supported, and still enough on its own. Prefer `Authorization: Bearer` for a new client. ````