Media folders API

Media folders endpoints in the Brix REST API: 6 operations (GET, POST, PATCH, DELETE), with auth, permissions and curl examples.

View as Markdown

Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says No auth. The permission chip 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

GET/v1/media-folders

Bearer token 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.

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.

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

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.

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

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.

POST/v1/media-folders

Bearer token 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.

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.

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

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.

Response 404 The location does not exist.

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.

Response 422 `name` is missing.

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.

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

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/{id}

Bearer token 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.

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.

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

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.

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

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.

PATCH/v1/media-folders/{id}

Bearer token 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.

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.

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

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.

Response 404 No folder with this id.

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.

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

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.

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

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.

DELETE/v1/media-folders/{id}

Bearer token 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.

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.

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

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.

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

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.

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

Bearer token 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.

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.

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

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.

Response 404 No folder with this id.

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.

Response 409 `not_deleted`.

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.

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

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

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!