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

# List folders

`GET /folders`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/folders`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/folders/get.ts> (a function with typed inputs; its response is checked against the schema)

List all folders accessible to the authenticated user, returned as a flat list with full paths.

Pass `scope` to filter to one of the three top-level meta-collections shown in the GC AI UI:
- `my-files`: folders rooted in the user's personal "My Files" tree
- `shared-with-me`: folders explicitly shared with the user by other users
- `organization`: folders rooted in the organization's "Organization Files" tree

Filtering by `scope` requires a user-scoped API key (`u:gcai_...`).

## Query parameters

- `limit` integer: Max items to return (default 100, max 500)
- `offset` integer, nullable: Number of items to skip (default 0)
- `q` string: Case-insensitive substring search on folder name or description. System-owned collection types (my-files, org-files, etc.) are excluded from results. Composes with `scope`.
- `scope` 'my-files' | 'shared-with-me' | 'organization': Filter folders to a single meta-collection. Requires a user-scoped API key.

## Response `200`

List of folders

- FolderListResponse
  - `folders` Folder[], required
    - `id` string, uuid, required: Unique folder identifier
    - `name` string, required: Folder name
    - `description` string, nullable, required: Folder description, or null if unset
    - `path` string, required: Path through ancestors visible to the requester. Inaccessible ancestors are skipped, so this may not reflect absolute depth. Use `parent_folder_id` to traverse hierarchy.
    - `parent_folder_id` string, uuid, nullable, required: Parent folder ID, or null for root
    - `folder_type` string, required: Folder type (custom, my-files, etc.)
    - `created_at` string, required: ISO 8601 creation timestamp
  - `pagination` Pagination, required
    - `limit` number, required: Page size
    - `offset` number, required: Current offset
    - `has_more` boolean, required: Whether more results exist

## Other responses

- `400`: Invalid scope parameter
- `401`: Missing or malformed API key
- `403`: Scope filter requires a user-scoped API key
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)