Media folders API

Media folders endpoints in the Brix REST API: 6 operations (GET, POST, PATCH, DELETE). Each lists its path, auth, required permission and a curl example.

View as Markdown · For AI agents: the full docs index is at /llms.txt

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, Errors and rate limits and Pagination.

GET /v1/media-folders
POST /v1/media-folders
GET /v1/media-folders/{id}
PATCH /v1/media-folders/{id}
DELETE /v1/media-folders/{id}
POST /v1/media-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/media-folders

Auth: Bearer token. Permission: media.view.

Return the media library's folder tree for this workspace, including each folder's id, name, parent folder, and location.

Parameter	In	Type	Required	Description
`limit`	query	integer	no	Page size. Omit to get every row; pass it to page by `cursor`.
`cursor`	query	string	no	The `nextCursor` of the previous page.
`count`	query	"1"	no	With `limit`: also return `total`.
`usableAt`	query	string	no	Location id: only folders usable at that location.

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

Response 200: Success.

Field	Type	Description
`data`	array of MediaFolder
`data[].id`	string	Media folder id.
`data[].spaceId`	string
`data[].parentId`	string \| null	Parent folder; null = top level.
`data[].name`	string
`data[].nodeId`	string \| null	Home location; null = workspace root.
`data[].createdAt`	string	ISO-8601 timestamp (UTC).
`data[].updatedAt`	string	ISO-8601 timestamp (UTC).
`data[].deletedAt`	string \| null
`nextCursor`	string \| null	Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.
`total`	integer	Total matching rows, when the route computes it.

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

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

POST /v1/media-folders

Auth: Bearer token. Permission: media.create.

Create a folder in the media library. Requires name; parentId and nodeId are optional. Omitting parentId places the folder at the root. Notes. - The 201 body is the row as written, not re-read: columns the create does not set are absent rather than null. GET returns every column.

Request body: application/json

Field	Type	Required	Description
`name`	string	yes
`parentId`	string \| null	no
`nodeId`	string \| null	no	Home location. Default: the caller's own location.

curl -X POST "https://api.brixsignage.com/v1/media-folders" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 201: Success.

Field	Type	Description
`data`	object
`data.id`	string	Media folder id.
`data.spaceId`	string
`data.parentId`	string \| null
`data.name`	string
`data.nodeId`	string \| null
`data.createdAt`	string	ISO-8601 timestamp (UTC).
`data.updatedAt`	string	ISO-8601 timestamp (UTC).
`data.deletedAt`	string \| null

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: The location does not exist.

Response 422: name is missing.

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

GET /v1/media-folders/{id}

Auth: Bearer token. Permission: media.view.

Return one media folder.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media folder id.

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

Response 200: Success.

Field	Type	Description
`data`	MediaFolder	A folder in the media library.
`data.id`	string	Media folder id.
`data.spaceId`	string
`data.parentId`	string \| null	Parent folder; null = top level.
`data.name`	string
`data.nodeId`	string \| null	Home location; null = workspace root.
`data.createdAt`	string	ISO-8601 timestamp (UTC).
`data.updatedAt`	string	ISO-8601 timestamp (UTC).
`data.deletedAt`	string \| null

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

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

PATCH /v1/media-folders/{id}

Auth: Bearer token. Permission: media.edit.

Rename a media folder or move it to a different parent folder or location. Accepts optional name, parentId, and nodeId.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media folder id.

Request body: application/json

Field	Type	Required	Description
`name`	string	no
`parentId`	string \| null	no
`nodeId`	string \| null	no
`baseUpdatedAt`	string	no	The `updatedAt` your edit is based on; 409 with the current row if it moved.

curl -X PATCH "https://api.brixsignage.com/v1/media-folders/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200: Success.

Field	Type	Description
`data`	MediaFolder	A folder in the media library.
`data.id`	string	Media folder id.
`data.spaceId`	string
`data.parentId`	string \| null	Parent folder; null = top level.
`data.name`	string
`data.nodeId`	string \| null	Home location; null = workspace root.
`data.createdAt`	string	ISO-8601 timestamp (UTC).
`data.updatedAt`	string	ISO-8601 timestamp (UTC).
`data.deletedAt`	string \| null

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: No folder with this id.

Response 409: conflict: changed since baseUpdatedAt; the body carries current.

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

DELETE /v1/media-folders/{id}

Auth: Bearer token. Permission: media.delete.

Move a media folder to the recycle bin; it can be restored later. Assets inside the folder are not moved or deleted and keep their existing folder reference.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media folder id.

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

Response 200: Success.

Field	Type	Description
`data`	object
`data.id`	string
`data.deleted`	true

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

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

POST /v1/media-folders/{id}/restore

Auth: Bearer token. Permission: media.delete.

Bring back a deleted media folder so it reappears in the folder tree. Assets inside it keep whatever delete state they already had.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Media folder id.

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

Response 200: Success.

Field	Type	Description
`data`	object
`data.id`	string
`data.restored`	true

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: No folder with this id.

Response 409: not_deleted.

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

GET /v1/media-folders

POST /v1/media-folders

GET /v1/media-folders/{id}

PATCH /v1/media-folders/{id}

DELETE /v1/media-folders/{id}

POST /v1/media-folders/{id}/restore

Connect With Us

Message Received!