Creatives API
Creatives endpoints in the Brix REST API: 8 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/creativesPOST /v1/creativesGET /v1/creatives/{id}PATCH /v1/creatives/{id}DELETE /v1/creatives/{id}POST /v1/creatives/{id}/restoreGET /v1/creatives/{id}/thumbnailPOST /v1/creatives/bulk-delete
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/creatives
Return the workspace's canvas creatives, including each one's name, stage size, location, and sharing state. The full layout of shapes is not included; use the get-creative operation to retrieve that.
| 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, the number of matching rows. |
usableAt | query | string | no | Location id: only rows usable at that location (homed there, at the workspace root, or shared to it). |
curl "https://api.brixsignage.com/v1/creatives" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | array of Creative | |
data[].id | string | Creative id. |
data[].spaceId | string | |
data[].name | string | |
data[].backgroundUrl | string | null | |
data[].boxes | array of object | The design's boxes (text, image, data-bound fields…), in paint order. |
data[].dataSourceId | string | null | The data source the boxes bind to, if any. |
data[].stage | string | null | Stage preset name. |
data[].stageWidth | integer | null | |
data[].stageHeight | integer | null | |
data[].scenes | array of object | Scenes, for a multi-scene design; often empty. |
data[].touchEnabled | boolean | null | |
data[].tags | array of string | Free-text tags. |
data[].pauseWhileUsed | boolean | null | Hold the playlist while something a tap opened is up. Null = true. |
data[].repeat | object | null | Repeat for each row (beta): plays the design once per row of its data source. Null = off. |
data[].nodeId | string | null | |
data[].approvalState | "draft" | "pending" | "approved" | "rejected" | Review state. Editing an approved row returns it to draft. |
data[].approvedSnapshot | string | null | JSON TEXT of the last approved version (not parsed). |
data[].sourceSignage | any | null | The template it was made from (JSON), if any. |
data[].look | any | null | Accent / Brand Kit / light-dark settings (JSON), if set. |
data[].masterId | string | null | The master template id, for a design made from one. |
data[].shareLockDefault | any | null | Which boxes recipients may edit when shared (JSON), if set. |
data[].shareEditsSkipApproval | boolean | |
data[].templateSource | any | null | The fill-in form behind a design made from a new template (JSON), if any. |
data[].recalledAt | string | null | |
data[].recalledBy | string | null | |
data[].createdAt | string | ISO-8601 timestamp (UTC). |
data[].updatedAt | string | ISO-8601 timestamp (UTC). |
data[].deletedAt | string | null | Always null on these reads: deleted rows are not listed. |
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/creatives
Create a canvas creative. Accepts name and optional boxes, scenes, stageWidth, stageHeight, backgroundUrl, dataSourceId, touchEnabled, nodeId, and masterId. Safe to retry with the same Idempotency-Key header without creating duplicates.
Notes.
- The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example lastSnapshotAt) are absent rather than null. GET returns every column.
- Send an Idempotency-Key header to make a retry safe.
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
backgroundUrl | string | null | no | An unsafe URL scheme is stored as null. |
boxes | array of object | no | The whole box list; each box is checked and filled out with defaults. Default []. |
dataSourceId | string | null | no | A data source in this workspace. |
stage | string | null | no | |
stageWidth | integer | null | no | |
stageHeight | integer | null | no | |
scenes | array of object | no | Default []. |
touchEnabled | boolean | null | no | |
tags | array of string | no | Free-text tags, at most 50. Proof of Play can report on a tag. |
pauseWhileUsed | boolean | null | no | Hold the playlist while something a tap opened is up. Null = true. |
repeat | object | null | no | Repeat for each row (beta): plays the design once per row of its data source, with {{row.column}} values following the row. null turns it off. Answers 403 feature_disabled where the workspace does not have the feature. |
nodeId | string | null | no | Home location. Default: the caller's own location. |
sourceSignage | any | no | |
masterId | string | null | no | The master template it was made from (GET /v1/signage-master-templates). |
shareLockDefault | any | no | Which box fields recipients may edit when it is shared (JSON). |
shareEditsSkipApproval | boolean | no | Recipients' edits air without review. Needs creative.approve. |
look | object | null | no | |
templateSource | object | null | no | The fill-in form behind a design made from a new template (template id, data, look). Editor state only. null clears it. |
curl -X POST "https://api.brixsignage.com/v1/creatives" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json"Response 201: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | Creative id. |
data.spaceId | string | |
data.name | string | |
data.backgroundUrl | string | null | |
data.boxes | array of object | The design's boxes (text, image, data-bound fields…), in paint order. |
data.dataSourceId | string | null | The data source the boxes bind to, if any. |
data.stage | string | null | Stage preset name. |
data.stageWidth | integer | null | |
data.stageHeight | integer | null | |
data.scenes | array of object | Scenes, for a multi-scene design; often empty. |
data.touchEnabled | boolean | null | |
data.tags | array of string | Free-text tags. |
data.pauseWhileUsed | boolean | null | Hold the playlist while something a tap opened is up. Null = true. |
data.repeat | object | null | Repeat for each row (beta): plays the design once per row of its data source. Null = off. |
data.nodeId | string | null | |
data.approvalState | "draft" | "pending" | "approved" | "rejected" | Review state. Editing an approved row returns it to draft. |
data.approvedSnapshot | string | null | JSON TEXT of the last approved version (not parsed). |
data.sourceSignage | any | null | The template it was made from (JSON), if any. |
data.look | any | null | Accent / Brand Kit / light-dark settings (JSON), if set. |
data.masterId | string | null | The master template id, for a design made from one. |
data.shareLockDefault | any | null | Which boxes recipients may edit when shared (JSON), if set. |
data.shareEditsSkipApproval | boolean | |
data.templateSource | any | null | The fill-in form behind a design made from a new template (JSON), if any. |
data.recalledAt | string | null | |
data.recalledBy | string | null | |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
data.deletedAt | string | null | Always null on these reads: deleted rows are not listed. |
Response 401: Missing, expired or revoked bearer token.
Response 403: Setting shareEditsSkipApproval without creative.approve, or a dataSourceId homed where you lack integration.view.
Response 404: dataSourceId names no data source in this workspace.
Response 422: Missing name, invalid JSON, malformed boxes, scenes or look, or a location outside this workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/creatives/{id}
Return one creative in full, including its boxes, scenes, background, any linked data source, and stage dimensions.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Creative id. |
curl "https://api.brixsignage.com/v1/creatives/{id}" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | Creative id. |
data.spaceId | string | |
data.name | string | |
data.backgroundUrl | string | null | |
data.boxes | array of object | The design's boxes (text, image, data-bound fields…), in paint order. |
data.dataSourceId | string | null | The data source the boxes bind to, if any. |
data.stage | string | null | Stage preset name. |
data.stageWidth | integer | null | |
data.stageHeight | integer | null | |
data.scenes | array of object | Scenes, for a multi-scene design; often empty. |
data.touchEnabled | boolean | null | |
data.tags | array of string | Free-text tags. |
data.pauseWhileUsed | boolean | null | Hold the playlist while something a tap opened is up. Null = true. |
data.repeat | object | null | Repeat for each row (beta): plays the design once per row of its data source. Null = off. |
data.nodeId | string | null | |
data.approvalState | "draft" | "pending" | "approved" | "rejected" | Review state. Editing an approved row returns it to draft. |
data.approvedSnapshot | string | null | JSON TEXT of the last approved version (not parsed). |
data.sourceSignage | any | null | The template it was made from (JSON), if any. |
data.look | any | null | Accent / Brand Kit / light-dark settings (JSON), if set. |
data.masterId | string | null | The master template id, for a design made from one. |
data.shareLockDefault | any | null | Which boxes recipients may edit when shared (JSON), if set. |
data.shareEditsSkipApproval | boolean | |
data.templateSource | any | null | The fill-in form behind a design made from a new template (JSON), if any. |
data.recalledAt | string | null | |
data.recalledBy | string | null | |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
data.deletedAt | string | null | Always null on these reads: deleted rows are not listed. |
data.requiresApproval | boolean | The home location requires approval before content airs. |
data.canEditBase | boolean | The caller may edit the design itself (not only its unlocked boxes). |
data.canWaiveApproval | boolean | The caller holds creative.approve at its home location. |
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 such creative in this workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
PATCH /v1/creatives/{id}
Edit a creative. The boxes and scenes fields each replace the entire existing list, so retrieve the creative first and send back the complete array with changes included. If the location requires approval before content goes live, updating the creative resets that approval.
Notes.
- The response is the stored row: it has no requiresApproval, canEditBase or canWaiveApproval (GET has them).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Creative id. |
Request body: application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | |
backgroundUrl | string | null | no | An unsafe URL scheme is stored as null. |
boxes | array of object | no | The whole box list; each box is checked and filled out with defaults. Default []. |
dataSourceId | string | null | no | A data source in this workspace. |
stage | string | null | no | |
stageWidth | integer | null | no | |
stageHeight | integer | null | no | |
scenes | array of object | no | Default []. |
touchEnabled | boolean | null | no | |
tags | array of string | no | Free-text tags, at most 50. Proof of Play can report on a tag. |
pauseWhileUsed | boolean | null | no | Hold the playlist while something a tap opened is up. Null = true. |
repeat | object | null | no | Repeat for each row (beta): plays the design once per row of its data source, with {{row.column}} values following the row. null turns it off. Answers 403 feature_disabled where the workspace does not have the feature. |
nodeId | string | null | no | Home location. Default: the caller's own location. |
sourceSignage | any | no | |
masterId | string | null | no | The master template it was made from (GET /v1/signage-master-templates). |
shareLockDefault | any | no | Which box fields recipients may edit when it is shared (JSON). |
shareEditsSkipApproval | boolean | no | Recipients' edits air without review. Needs creative.approve. |
look | object | null | no | |
templateSource | object | null | no | The fill-in form behind a design made from a new template (template id, data, look). Editor state only. null clears it. |
baseUpdatedAt | string | no | Optimistic concurrency: the updatedAt you read. A stale value is refused with 409 conflict and the current row. |
curl -X PATCH "https://api.brixsignage.com/v1/creatives/{id}" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | Creative | A canvas design (data-bound boxes on a stage). |
data.id | string | Creative id. |
data.spaceId | string | |
data.name | string | |
data.backgroundUrl | string | null | |
data.boxes | array of object | The design's boxes (text, image, data-bound fields…), in paint order. |
data.dataSourceId | string | null | The data source the boxes bind to, if any. |
data.stage | string | null | Stage preset name. |
data.stageWidth | integer | null | |
data.stageHeight | integer | null | |
data.scenes | array of object | Scenes, for a multi-scene design; often empty. |
data.touchEnabled | boolean | null | |
data.tags | array of string | Free-text tags. |
data.pauseWhileUsed | boolean | null | Hold the playlist while something a tap opened is up. Null = true. |
data.repeat | object | null | Repeat for each row (beta): plays the design once per row of its data source. Null = off. |
data.nodeId | string | null | |
data.approvalState | "draft" | "pending" | "approved" | "rejected" | Review state. Editing an approved row returns it to draft. |
data.approvedSnapshot | string | null | JSON TEXT of the last approved version (not parsed). |
data.sourceSignage | any | null | The template it was made from (JSON), if any. |
data.look | any | null | Accent / Brand Kit / light-dark settings (JSON), if set. |
data.masterId | string | null | The master template id, for a design made from one. |
data.shareLockDefault | any | null | Which boxes recipients may edit when shared (JSON), if set. |
data.shareEditsSkipApproval | boolean | |
data.templateSource | any | null | The fill-in form behind a design made from a new template (JSON), if any. |
data.recalledAt | string | null | |
data.recalledBy | string | null | |
data.createdAt | string | ISO-8601 timestamp (UTC). |
data.updatedAt | string | ISO-8601 timestamp (UTC). |
data.deletedAt | string | null | Always null on these reads: deleted rows are not listed. |
Response 401: Missing, expired or revoked bearer token.
Response 403: Moving it to a location where you lack creative.edit, changing shareEditsSkipApproval without creative.approve, or a new dataSourceId homed where you lack integration.view.
Response 404: No such creative (or dataSourceId) in this workspace.
Response 409: conflict: the row changed since baseUpdatedAt; the body carries current.
Response 422: Invalid JSON or malformed boxes, scenes or look.
Response 5XX: Server error. The body carries a requestId to quote to support.
DELETE /v1/creatives/{id}
Move a creative to the recycle bin. If the creative is shared into other locations, the request fails with a 409 error unless the deletion is explicitly confirmed, since deleting a shared creative removes it everywhere it is shared.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Creative id. |
force | query | "true" | no | Delete even when it is shared into other places; the shares go with it. |
curl -X DELETE "https://api.brixsignage.com/v1/creatives/{id}" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200: Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.deleted | true | |
data.sharesRemoved | integer | Shares removed with it. |
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 such creative in this workspace.
Response 409: content_shared: it is shared into other places; shareCount, crossSpaceShares, contentShares say where. Repeat with ?force=true to delete it and those shares.
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/creatives/{id}/restore
Bring back a deleted creative so it returns to the library. The shares removed by the delete come back with it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Creative id. |
curl -X POST "https://api.brixsignage.com/v1/creatives/{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 such creative in this workspace, or it was purged.
Response 409: not_deleted: the creative is not in the recycle bin.
Response 5XX: Server error. The body carries a requestId to quote to support.
GET /v1/creatives/{id}/thumbnail
Return an image of the creative, showing its shapes and pictures along with a representative preview of each content slot, such as a file's poster image, a playlist's first item, or an app's most recent snapshot. Text boxes are not drawn. The image is cached; add ?fresh=1 to bypass the cache after making an edit.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Creative id. |
fresh | query | "1" | no | Skip the cached image and draw it again. |
curl "https://api.brixsignage.com/v1/creatives/{id}/thumbnail" \
-H "Authorization: Bearer $BRIX_API_KEY"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 such creative in this workspace.
Response 5XX: Server error. The body carries a requestId to quote to support.
POST /v1/creatives/bulk-delete
Move up to 500 creatives to the recycle bin in one call. Permission is checked for each one. The answer lists the deleted IDs in ok and the rest in failed, so one failure does not stop the rest.
curl -X POST "https://api.brixsignage.com/v1/creatives/bulk-delete" \
-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.