# Creative overrides

Base URL: `https://api.brixsignage.com`. Send `Authorization: Bearer $BRIX_API_KEY` unless an operation says Auth: none.

## GET /v1/creative-overrides/{creativeId}

Get a creative's overrides at a location

Return the edits a location has made to a creative that was shared with it, the merged result of applying those edits, and any edits that have stopped applying.

Auth: Bearer token. Permission: `creative.view`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `creativeId` | path | string | yes | Creative id: one of yours, or one shared into this workspace. |
| `node` | query | string | no | Location id. Default: the workspace root. |

```bash
curl "https://api.brixsignage.com/v1/creative-overrides/{creativeId}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.creativeId` | string |  |
| `data.nodeId` | string | The location the edits apply at. |
| `data.values` | object | The location's edits: box id → the box fields it changes (for example `{ "price": { "text": "13.00" } }`). |
| `data.overrideId` | string \| null | Id of the stored edits (what an approval request is opened against); null before the first save. |
| `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state of the edits (not of the design). |
| `data.requiresApproval` | boolean | The location requires approval before the edits air. |
| `data.skipsApproval` | boolean | The author waived that review for this design. |
| `data.creative` | OverrideCreative | A creative's design: the boxes and scenes with their settings. |
| `data.creative.id` | string |  |
| `data.creative.nodeId` | string \| null |  |
| `data.creative.name` | string |  |
| `data.creative.backgroundUrl` | string \| null |  |
| `data.creative.boxes` | array of object |  |
| `data.creative.scenes` | array of object |  |
| `data.creative.dataSourceId` | string \| null |  |
| `data.creative.stage` | string | Absent when not set. |
| `data.creative.shareLockDefault` | any \| null |  |
| `data.creative.shareEditsSkipApproval` | boolean |  |
| `data.creative.stageWidth` | integer |  |
| `data.creative.stageHeight` | integer |  |
| `data.creative.touchEnabled` | boolean |  |
| `data.creative.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. |
| `data.creative.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.orphanedBoxIds` | array of string | Edited box ids the design no longer has. |
| `data.sharedFrom` | string \| null | The workspace that owns the design, when it was shared in from another workspace. |
| `data.base` | OverrideCreative | A creative's design: the boxes and scenes with their settings. |
| `data.base.id` | string |  |
| `data.base.nodeId` | string \| null |  |
| `data.base.name` | string |  |
| `data.base.backgroundUrl` | string \| null |  |
| `data.base.boxes` | array of object |  |
| `data.base.scenes` | array of object |  |
| `data.base.dataSourceId` | string \| null |  |
| `data.base.stage` | string | Absent when not set. |
| `data.base.shareLockDefault` | any \| null |  |
| `data.base.shareEditsSkipApproval` | boolean |  |
| `data.base.stageWidth` | integer |  |
| `data.base.stageHeight` | integer |  |
| `data.base.touchEnabled` | boolean |  |
| `data.base.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. |
| `data.base.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.rejectedFields` | array of string | `boxId.field` edits that no longer apply because the author locked the field. |
| `data.updatedAt` | string \| null | When the edits were last saved; null before the first save. |

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: Unknown location, no such creative, or the creative is not usable at that location.

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

## PUT /v1/creative-overrides/{creativeId}

Replace a creative's overrides at a location

Replace a location's edits to a shared creative. If the creative's author has locked a field against editing, the request is rejected with a 422 error for that field.

**Notes.**
- The response has no `sharedFrom`, `base` or `rejectedFields` (GET has them). A save returns approved edits to `draft`.

Auth: Bearer token. Permission: `creative.edit`.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `creativeId` | path | string | yes | Creative id: one of yours, or one shared into this workspace. |
| `node` | query | string | no | Location id. Default: the workspace root. |

Request body (`application/json`):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `values` | object | yes | Every edit to keep, at most 300 boxes. Edits left out are removed. |

```bash
curl -X PUT "https://api.brixsignage.com/v1/creative-overrides/{creativeId}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.creativeId` | string |  |
| `data.nodeId` | string | The location the edits apply at. |
| `data.values` | object | The location's edits: box id → the box fields it changes (for example `{ "price": { "text": "13.00" } }`). |
| `data.overrideId` | string \| null | Id of the stored edits (what an approval request is opened against); null before the first save. |
| `data.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state of the edits (not of the design). |
| `data.requiresApproval` | boolean | The location requires approval before the edits air. |
| `data.skipsApproval` | boolean | The author waived that review for this design. |
| `data.creative` | OverrideCreative | A creative's design: the boxes and scenes with their settings. |
| `data.creative.id` | string |  |
| `data.creative.nodeId` | string \| null |  |
| `data.creative.name` | string |  |
| `data.creative.backgroundUrl` | string \| null |  |
| `data.creative.boxes` | array of object |  |
| `data.creative.scenes` | array of object |  |
| `data.creative.dataSourceId` | string \| null |  |
| `data.creative.stage` | string | Absent when not set. |
| `data.creative.shareLockDefault` | any \| null |  |
| `data.creative.shareEditsSkipApproval` | boolean |  |
| `data.creative.stageWidth` | integer |  |
| `data.creative.stageHeight` | integer |  |
| `data.creative.touchEnabled` | boolean |  |
| `data.creative.approvalState` | "draft" \| "pending" \| "approved" \| "rejected" | Review state. Editing an approved row returns it to `draft`. |
| `data.creative.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.orphanedBoxIds` | array of string | Edited box ids the design no longer has. |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |

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: You lack creative.edit at that location.

| 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: Unknown location, no such creative, or the creative is not usable at that location.

| 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: `validation_error` (bad `values`, more than 300 boxes, unknown box ids in `unknownBoxes`) or `locked` (fields the author locked, in `violations`).

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