Create a Folder

Create a new folder for organizing files.

Requires a user-scoped API key (u:gcai_...). Folders can be nested by specifying a parent_folder_id.

POST /folders

Create a folder

cURL

curl --request POST \
  --url https://app.gc.ai/api/external/v1/folders \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Q4 Contracts",
  "description": "<string>",
  "parent_folder_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scope": "my-files"
}
'

201

{
  "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>"
}

Authorizations

Authorization · string · header · required

API key for authentication. Format: gcai_xxxxxxxxx

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

Body

application/json

name · string · required

Folder name (min 2 characters)

Minimum string length: 2

Example:

"Q4 Contracts"

description · string

Optional description

parent_folder_id · string<uuid>

Parent folder ID. Mutually exclusive with scope. If both are omitted, creates a top-level folder.

scope · enum<string>

Create the folder at the root of a meta-collection. Mutually exclusive with parent_folder_id. shared-with-me is not valid for create.

Available options: my-files, organization

Example:

"my-files"

Response

201

application/json

Folder created

id · string<uuid> · required

Unique folder identifier

name · string · required

Folder name

description · string | null · 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.

Example:

"/My Files/Contracts"

parent_folder_id · string<uuid> | null · 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