# Content folders

> For AI agents: the full docs index is at https://brixsignage.com/llms.txt, and every page has a markdown twin (add .md to the path).

Base URL `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none or Auth: no API key. The Permission line names what the key must hold. See [Authentication and scopes](https://brixsignage.com/developers/authentication.md), [Errors and rate limits](https://brixsignage.com/developers/errors-and-rate-limits.md) and [Pagination](https://brixsignage.com/developers/pagination.md).

- [GET /v1/content-folders](#get-v1-content-folders)
- [POST /v1/content-folders](#post-v1-content-folders)
- [GET /v1/content-folders/{id}](#get-v1-content-folders-id)
- [PATCH /v1/content-folders/{id}](#patch-v1-content-folders-id)
- [DELETE /v1/content-folders/{id}](#delete-v1-content-folders-id)
- [POST /v1/content-folders/{id}/restore](#post-v1-content-folders-id-restore)

Every 4xx and 5xx response below returns this body:

| Field | Type | Description |
| --- | --- | --- |
| `error` | string | Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, … |
| `message` | string | Human-readable explanation. Safe to show an operator. |
| `requestId` | string | Present on 5xx: quote it to support. |

## GET /v1/content-folders

List content folders

List the folders of the Designs, Playlists and Layouts lists. Set `kind` to `design`, `playlist` or `layout` to get the folders of one list. Without `kind`, the answer contains the folders of each list that you have permission to view.

Auth: Bearer token.

```bash
curl "https://api.brixsignage.com/v1/content-folders" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/content-folders

Create a content folder

Create a folder in the Designs, Playlists or Layouts list. Send `kind` and `name`. Send `parentId` to put the folder inside a different folder; folders can be 4 levels deep. A folder only files items. It does not change who can see an item or what plays on a screen.

Auth: Bearer token.

```bash
curl -X POST "https://api.brixsignage.com/v1/content-folders" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## GET /v1/content-folders/{id}

Get a content folder

Get one folder of the Designs, Playlists or Layouts list. A folder in a different workspace, or in a part of the workspace that you cannot access, returns a not-found error.

Auth: Bearer token.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Identifier for id. |

```bash
curl "https://api.brixsignage.com/v1/content-folders/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## PATCH /v1/content-folders/{id}

Update a content folder

Rename a folder, move it into a different folder, or file items. Send the ids of items of the same kind as the folder in `addItems` to put them in the folder, or in `removeItems` to take them out. You can file at most 500 items in one call. You need edit permission on each item that you file.

Auth: Bearer token.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Identifier for id. |

```bash
curl -X PATCH "https://api.brixsignage.com/v1/content-folders/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## DELETE /v1/content-folders/{id}

Delete a content folder

Move a folder and its subfolders to the recycle bin. The items in them are not deleted; they move up to the parent of the deleted folder. The folder stays in the recycle bin for 30 days.

Auth: Bearer token.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Identifier for id. |

```bash
curl -X DELETE "https://api.brixsignage.com/v1/content-folders/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX: Server error. The body carries a `requestId` to quote to support.

## POST /v1/content-folders/{id}/restore

Restore a deleted content folder

Restore a folder from the recycle bin together with its subfolders. The items that the delete moved up go back into the folder, unless they are in a different folder now.

Auth: Bearer token.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Identifier for id. |

```bash
curl -X POST "https://api.brixsignage.com/v1/content-folders/{id}/restore" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

Response 5XX: Server error. The body carries a `requestId` to quote to support.
