Skip to main content
POST
Create app folder

Authorizations

Authorization
string
header
required

Personal access token, sent as Authorization: Bearer <token>.

Body

application/json
name
string
required

Name of the folder, 1 to 100 characters. Names don't have to be unique.

Required string length: 1 - 100
Example:

"Client projects"

scope
enum<string>
required

workspace for a folder every member of the workspace sees, or personal for one only you see.

Available options:
workspace,
personal
Example:

"workspace"

parent_folder_id
string | null

ID of the folder to create this one in, or null for a top-level folder. The parent must have the same scope and app_type, and a personal parent must be yours.

Example:

"68c1f27eb4e7d3005a2c9e0f"

position
number
default:0

Sort key among folders. Lower values come first.

Example:

2

color
string | null

Color for the folder, up to 32 characters, such as a hex color.

Maximum string length: 32
Example:

"#3B82F6"

icon
string | null

Icon name for the folder, up to 64 characters.

Maximum string length: 64
Example:

"briefcase"

app_type
enum<string> | null

user_app for a folder of builder apps, or user_agent for a folder of agents. Defaults to user_app.

Available options:
user_app,
user_agent
Example:

"user_app"

Response

The new folder.

id
string
required

ID of the folder.

Example:

"68c1f2a9b4e7d3005a2c9e11"

name
string
required

Name of the folder.

Example:

"Client projects"

parent_folder_id
string | null
required

ID of the folder this one sits in, or null for a top-level folder.

Example:

"68c1f27eb4e7d3005a2c9e0f"

scope
enum<string>
required

workspace for a folder every member of the workspace sees, or personal for one only you see.

Available options:
workspace,
personal
Example:

"workspace"

position
number
required

Sort key among folders. Lower values come first.

Example:

2

created_date
string<date-time>
required

Time the folder was created, in UTC, as an ISO 8601 timestamp without a time zone offset.

Example:

"2026-08-01T09:15:00"

color
string | null

Color set on the folder, or null when none is set.

Example:

"#3B82F6"

icon
string | null

Icon name set on the folder, or null when none is set.

Example:

"briefcase"

app_type
enum<string> | null

user_app for a folder of builder apps, or user_agent for a folder of agents. Builder app folders created before agent folders existed leave it out.

Available options:
user_app,
user_agent
Example:

"user_app"