# Recall

> 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/recall](#get-v1-recall)
- [POST /v1/recall/creative/{id}](#post-v1-recall-creative-id)
- [POST /v1/recall/creative/{id}/restore](#post-v1-recall-creative-id-restore)
- [POST /v1/recall/media/{id}](#post-v1-recall-media-id)
- [POST /v1/recall/media/{id}/restore](#post-v1-recall-media-id-restore)
- [POST /v1/recall/playlist/{id}](#post-v1-recall-playlist-id)
- [POST /v1/recall/playlist/{id}/restore](#post-v1-recall-playlist-id-restore)
- [POST /v1/recall/schedule/{id}](#post-v1-recall-schedule-id)
- [POST /v1/recall/schedule/{id}/restore](#post-v1-recall-schedule-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/recall

List recalled content

Return everything currently held off screens, including its kind, name, when it was recalled, and who recalled it. Since a recall is reversible, this list is the record of what is being withheld and why, so nothing stays off screens indefinitely without anyone knowing. An item is listed only where the caller can view that kind of content at its location. Who recalled it is returned in full only where the caller also holds the user view permission; otherwise only its kind, for example `user` or `staff`.

**Notes.**
- Newest first, not paginated. An item is listed only where the caller holds that kind's view permission (`media.view`, `playlist.view`, …) at its location; a `screen.view`-only key gets an empty list.

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

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data[].id` | string |  |
| `data[].name` | string \| null |  |
| `data[].recalledAt` | string | ISO-8601 timestamp (UTC). |
| `data[].recalledBy` | string \| null | An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`. Without `user.view` at the item's location, only the kind (`user`, `staff`, …). |

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

Recall a creative from all screens

Immediately remove a creative from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.

**Notes.**
- A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The creative's id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data.recalledAt` | string | ISO-8601 timestamp (UTC). |
| `data.recalledBy` | string | Who recalled it. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `creative.edit` where the creative lives.

Response 404: No such creative in this workspace.

Response 409: `already_recalled`: it is already recalled.

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

## POST /v1/recall/creative/{id}/restore

Restore a recalled creative

Put a recalled creative back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The creative's id. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data.recalledAt` | null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `creative.edit` where the creative lives.

Response 404: No such creative in this workspace.

Response 409: `not_recalled`: it is not recalled.

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

## POST /v1/recall/media/{id}

Recall a media file from all screens

Immediately remove a media file from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.

**Notes.**
- A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The media's id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data.recalledAt` | string | ISO-8601 timestamp (UTC). |
| `data.recalledBy` | string | Who recalled it. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `media.edit` where the media lives.

Response 404: No such media in this workspace.

Response 409: `already_recalled`: it is already recalled.

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

## POST /v1/recall/media/{id}/restore

Restore a recalled media file

Put a recalled media file back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The media's id. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data.recalledAt` | null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `media.edit` where the media lives.

Response 404: No such media in this workspace.

Response 409: `not_recalled`: it is not recalled.

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

## POST /v1/recall/playlist/{id}

Recall a playlist from all screens

Immediately remove a playlist from every screen it appears on, without deleting it or changing any other playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.

**Notes.**
- A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The playlist's id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook. |

```bash
curl -X POST "https://api.brixsignage.com/v1/recall/playlist/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data.recalledAt` | string | ISO-8601 timestamp (UTC). |
| `data.recalledBy` | string | Who recalled it. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `playlist.edit` where the playlist lives.

Response 404: No such playlist in this workspace.

Response 409: `already_recalled`: it is already recalled.

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

## POST /v1/recall/playlist/{id}/restore

Restore a recalled playlist

Put a recalled playlist back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The playlist's id. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data.recalledAt` | null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `playlist.edit` where the playlist lives.

Response 404: No such playlist in this workspace.

Response 409: `not_recalled`: it is not recalled.

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

## POST /v1/recall/schedule/{id}

Recall a schedule from all screens

Immediately remove a schedule from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.

**Notes.**
- A flag, not an edit: no playlist, screen or schedule changes, and the item stays in the library. Screens are told at once.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The schedule's id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | no | Why it was recalled. Kept in the activity log and sent with the `content.recalled` webhook. |

```bash
curl -X POST "https://api.brixsignage.com/v1/recall/schedule/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data.recalledAt` | string | ISO-8601 timestamp (UTC). |
| `data.recalledBy` | string | Who recalled it. An actor reference: `user:<id>`, `apikey:<id>`, `staff:<email>`, `partner:<email>` or `system…`. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `schedule.edit` where the schedule lives.

Response 404: No such schedule in this workspace.

Response 409: `already_recalled`: it is already recalled.

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

## POST /v1/recall/schedule/{id}/restore

Restore a recalled schedule

Put a recalled schedule back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | The schedule's id. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.kind` | "media" \| "creative" \| "playlist" \| "schedule" |  |
| `data.recalledAt` | null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `schedule.edit` where the schedule lives.

Response 404: No such schedule in this workspace.

Response 409: `not_recalled`: it is not recalled.

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