Sign in

Update app folder

Changed on

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

Renames a folder, or changes its color, icon or position. Send only the fields you want to change.

A folder's scope, app_type, owner_id and parent_folder_id can't change here, and sending any of them returns a 400.

You can change your own personal folders. Workspace folders need the editor role or higher, and any editor can change any workspace folder. A folder that doesn't exist, or another user's personal folder, returns a 404 with the code folder_not_found.

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>

put/api/app-folders/{item_id}

Request

  • Base URL: https://app.base44.com
  • URL: https://app.base44.com/api/app-folders/{item_id}
  • Auth: HTTP bearer

Path parameters

item_idstring required

ID of the folder to update. Get it from id in List app folders.

Request body

namestring

New name, 1 to 100 characters.

positionnumber

New sort key among folders. Lower values come first.

colorstring nullable

New color, up to 32 characters, or null to clear it.

iconstring nullable

New icon name, up to 64 characters, or null to clear it.

Example request

{
  "name": "Client work",
  "position": 3,
  "color": "#10B981",
  "icon": "folder"
}

Response

The updated folder.

idstring required

ID of the folder.

namestring required

Name of the folder.

parent_folder_idstring 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.

positionnumber required

Sort key among folders. Lower values come first.

colorstring nullable

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

iconstring 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_datestring date-time required

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

Example response

{
  "id": "68c1f2a9b4e7d3005a2c9e11",
  "name": "Client projects",
  "parent_folder_id": "68c1f27eb4e7d3005a2c9e0f",
  "scope": "workspace",
  "position": 2,
  "color": "#3B82F6",
  "icon": "briefcase",
  "app_type": "user_app",
  "created_date": "2026-08-01T09:15:00"
}

Changes