# Folders

Managing folders on the Bitrix24 Drive: list contents, create, rename and delete. Folders are stored inside storages and form a nesting tree.

Bitrix24 API: `disk.folder.*`
Scope: `disk`

## Operations

- [Create a folder](./folders/create.md) — `POST /v1/folders`
- [List folder contents](./folders/list.md) — `GET /v1/folders`
- [Get a folder](./folders/get.md) — `GET /v1/folders/:id`
- [Rename a folder](./folders/update.md) — `PATCH /v1/folders/:id`
- [Delete a folder](./folders/delete.md) — `DELETE /v1/folders/:id`
- [Search folders](./folders/search.md) — `POST /v1/folders/search`
- [Folder fields](./folders/fields.md) — `GET /v1/folders/fields`
- [Move a folder](./folders/moveto.md) — `POST /v1/folders/:id/moveto`
- [Copy a folder](./folders/copyto.md) — `POST /v1/folders/:id/copyto`

## Key fields

| Field | Description |
|------|---------|
| `id` | Numeric folder identifier |
| `name` | Folder name. Required on create |
| `parentId` | Parent folder identifier. Required on create and for listing. The storage root folder is given by the `rootFolderId` field in [`GET /v1/storages`](/docs/entities/storages) |
| `storageId` | Storage identifier, from [`GET /v1/storages`](/docs/entities/storages) |
| `type` | Object type — `"folder"` or `"file"` |
| `detailUrl` | Link to the folder in the Bitrix24 interface |
| `createdAt` | Creation date and time in ISO 8601 format |

Full list of fields — [`GET /v1/folders/fields`](./folders/fields.md).

## What to know before working

1. **Field names in the response are camelCase.** The schema maps the original UPPER_SNAKE names to camelCase.
2. **`parentId` is required both for creation and for listing.** `GET /v1/folders` returns the contents of a specific folder. The storage root folder is given by the `rootFolderId` field in [`GET /v1/storages`](/docs/entities/storages).
3. **`GET /v1/folders` returns a mixed list.** The response contains both subfolders (`type: "folder"`) and files (`type: "file"`) at the same time. Files have a different field set — they have `fileId`, `size`, `downloadUrl` and no `realObjectId`. To manage files use the [Files](/docs/entities/files) section. The file card is available via [`GET /v1/files/:id`](/docs/entities/files/get), not `GET /v1/folders/:id`.
4. **The minimum to create is `name` and `parentId`.**
5. **Only the name changes via `PATCH`.** `PATCH /v1/folders/:id` renames a folder. The `parentId` and `code` fields are immutable in the `PATCH` body. To move a folder to a different parent, use [`POST /v1/folders/:id/moveto`](./folders/moveto.md).
6. **Deletion is soft.** `DELETE /v1/folders/:id` marks the folder deleted and moves it to the trash, the folder is not physically erased. Restoring via the API is not supported.

## Typical scenario

1. Get the storage: [`GET /v1/storages`](/docs/entities/storages) — you need `id` and `rootFolderId`.
2. View the root contents: [`GET /v1/folders?parentId=<rootFolderId>`](./folders/list.md).
3. Create a subfolder: [`POST /v1/folders`](./folders/create.md) with `name` and `parentId`.
4. Rename if needed: [`PATCH /v1/folders/:id`](./folders/update.md).
5. Delete: [`DELETE /v1/folders/:id`](./folders/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000. When `limit > 50`, Vibecode runs several requests automatically. The offset is set via `offset` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared for the Vibe API — see [Limits and optimization](/docs/optimization) |

## See also

- [Files](/docs/entities/files)
- [Storages](/docs/entities/storages)
- [Filtering syntax](/docs/filtering)
- [API keys](/docs/keys-auth)
- [Error codes](/docs/errors)