List Folders

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_...).

GET /folders

List folders

cURL

curl --request GET \
  --url https://app.gc.ai/api/external/v1/folders \
  --header 'Authorization: <api-key>'

200

{
  "folders": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>",
      "path": "/My Files/Contracts",
      "parent_folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "folder_type": "<string>",
      "created_at": "<string>"
    }
  ],
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  }
}

Authorizations

Authorization · string · header · required

API key for authentication. Format: gcai_xxxxxxxxx

Create API keys in the GC AI app under Settings → API.

Query Parameters

limit · integer · default: 100

Max items to return (default 100, max 500)

Required range: 1 <= x <= 500

offset · integer | null · default: 0

Number of items to skip (default 0)

Required range: x >= 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.

Example:

"contracts"

scope · enum<string>

Filter folders to a single meta-collection. Requires a user-scoped API key.

Available options: my-files, shared-with-me, organization

Example:

"my-files"

Response

200

application/json

List of folders

folders · object[] · required

Show child attributes

pagination · object · required

Show child attributes