---
title: "Create app folder"
method: POST
path: "/api/app-folders"
---

# Create app folder

`POST /api/app-folders`

## Request

- Base URL: `https://app.base44.com`
- URL: `https://app.base44.com/api/app-folders`
- Auth: HTTP bearer

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Creates a folder for builder apps or agents.

You can change your own personal folders. Workspace folders need the editor role or higher, and any editor can change any workspace folder. A workspace holds up to 500 folders of both kinds, counting every member's personal folders, and a folder can have at most 20 folders above it. Folder names don't have to be unique, so retrying a create that timed out can leave you with two folders.

This is limited to 60 requests per minute, shared with the other endpoints that change folders. A signed-in session has its own limit, and every personal access token for the workspace shares one. Some workspaces have a different limit.

<Note>Call this with a personal access token sent as a Bearer token, or from a signed-in session. A token works on its own workspace's folders. Workspace API keys aren't accepted, and a read-only token is refused.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.</Warning>

## Request body

- CreateAppFolderRequest
  - `name` string, required — Name of the folder, 1 to 100 characters. Names don't have to be unique.
  - `scope` 'workspace' | 'personal', required — `workspace` for a folder every member of the workspace sees, or `personal` for one only you see.
  - `parent_folder_id` string, nullable — 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.
  - `position` number — Sort key among folders. Lower values come first.
  - `color` string, nullable — Color for the folder, up to 32 characters, such as a hex color.
  - `icon` string, nullable — Icon name for the folder, up to 64 characters.
  - `app_type` 'user_app' | 'user_agent', nullable — `user_app` for a folder of builder apps, or `user_agent` for a folder of agents. Defaults to `user_app`.

## Response `200`

The new folder.

- AppFolderSummary
  - `id` string, required — ID of the folder.
  - `name` string, required — Name of the folder.
  - `parent_folder_id` string, nullable, required — ID of the folder this one sits in, or `null` for a top-level folder.
  - `scope` 'workspace' | 'personal', required — `workspace` for a folder every member of the workspace sees, or `personal` for one only you see.
  - `position` number, required — Sort key among folders. Lower values come first.
  - `color` string, nullable — Color set on the folder, or `null` when none is set.
  - `icon` string, nullable — Icon name set on the folder, or `null` when none is set.
  - `app_type` 'user_app' | 'user_agent', nullable — `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.
  - `created_date` string, date-time, required — Time the folder was created, in UTC, as an ISO 8601 timestamp without a time zone offset.

## Other responses

- `400` — `app_type` isn't `user_app` or `user_agent`, the parent has a different `scope` or `app_type` or is another user's personal folder, the folder would have more than 20 folders above it, or the workspace already has 500 folders.
- `401` — Missing or invalid credentials.
- `403` — `scope` is `workspace` and you're a viewer or guest, or your token is read-only.
- `404` — The parent folder doesn't exist.
- `422` — Validation Error
- `429` — Rate limit exceeded.

## Changes

- **2026-10-07** `16e7d910d549` — 1 info
  - endpoint added

[Operation history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/app-folders/post.md)

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/idealspot/apis/base44-app-management-api/revisions/16acfcde4e33?raw)