---
title: "Update app folder"
method: PUT
path: "/api/app-folders/{item_id}"
---

# Update app folder

`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

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

## Path parameters

- `item_id` string, required: ID of the folder to update. Get it from `id` in [List app folders](/api-reference/list-app-folders).

## Request body

- UpdateAppFolderRequest
  - `name` string: New name, 1 to 100 characters.
  - `position` number: New sort key among folders. Lower values come first.
  - `color` string, nullable: New color, up to 32 characters, or `null` to clear it.
  - `icon` string, nullable: New icon name, up to 64 characters, or `null` to clear it.

## Response `200`

The updated 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`: The request sends `scope`, `app_type`, `owner_id`, `organization_id` or `parent_folder_id`.
- `401`: Missing or invalid credentials.
- `403`: The folder is a workspace folder and you're a viewer or guest, or your token is read-only.
- `404`: `folder_not_found`: the folder doesn't exist in the workspace, or it's another user's personal folder.
- `422`: Validation Error
- `429`: Rate limit exceeded.

## Changes

- **2026-10-11** `80287813ab84`: 1 info
  - the endpoint scheme security `PersonalAccessTokenAuth` was added to the API
- **2026-10-07** `16e7d910d549`: 1 info
  - endpoint added

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

---

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