# Site folders

Folders group site pages and set the path segment of their URL. This section also covers publishing a folder, unpublishing it, moving it to the trash and restoring it.

**Scope:** `landing` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

## Operations

- [List folders](./folders/list.md) — `GET /v1/sites/:id/folders`
- [Create a folder](./folders/create.md) — `POST /v1/sites/:id/folders`
- [Update a folder](./folders/update.md) — `PATCH /v1/sites/:id/folders/:folderId`
- [Move a folder to the trash](./folders/trash.md) — `POST /v1/sites/:id/folders/:folderId/trash`
- [Restore a folder](./folders/restore.md) — `POST /v1/sites/:id/folders/:folderId/restore`
- [Publish a folder](./folders/publication.md) — `POST /v1/sites/:id/folders/:folderId/publication`
- [Unpublish a folder](./folders/unpublish.md) — `POST /v1/sites/:id/folders/:folderId/unpublish`

## Site scope

All methods accept the optional `scope` query parameter: `KNOWLEDGE`, `GROUP` or `MAINPAGE`. Pass it when the site belongs to a knowledge base, a group or the main page. Without it, the folders of such a site are not found and the method responds with `404 ENTITY_NOT_FOUND`.

## Publication and trash

- A new folder is created unpublished.
- Publishing a folder also publishes all of its parent folders up to the site root. The site itself keeps its current state.
- Unpublishing a folder unpublishes the folder and all of its parent folders. Nested folders stay published.
- A folder in the trash keeps its publication flag, and it can be unpublished only after it is restored. Nested folders are not moved to the trash.
- The folder's pages go to the trash together with it. When the folder is restored, they come back unpublished.
- While the parent folder is in the trash, a nested folder cannot be unpublished, and an unpublished nested folder cannot be published: the response is `422 BITRIX_ERROR`.
- The folder list without the `deleted` filter does not show folders in the trash.

## Typical scenario

1. Create a folder — `POST /v1/sites/:id/folders`, the response contains the folder's `data.id`.
2. Create a page in this folder — [`POST /v1/pages`](/docs/entities/pages/create) with the `folderId` field.
3. Publish the page and the folder — `POST /v1/pages/:id/publication` and `POST /v1/sites/:id/folders/:folderId/publication`.

## See also

- [Sites](/docs/entities/sites)
- [Pages](/docs/entities/pages)