# Shared with Me

> 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/shared-with-me](#get-v1-shared-with-me)
- [POST /v1/shared-with-me/{allocationId}/fill](#post-v1-shared-with-me-allocationid-fill)
- [PUT /v1/shared-with-me/{allocationId}/fill](#put-v1-shared-with-me-allocationid-fill)
- [GET /v1/shared-with-me/{allocationId}/source](#get-v1-shared-with-me-allocationid-source)

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/shared-with-me

List airtime shared with me

List airtime slices that other teams have reserved and made available for the caller's team to fill.

**Notes.**
- Only slices the caller can fill are listed. Besides `playlist.view`, the caller needs `playlist.edit` at the location the slice is reserved for.

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

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].allocationId` | string |  |
| `data[].label` | string |  |
| `data[].reservedForNodeId` | string | The location the slice is reserved for. |
| `data[].reservedForName` | string |  |
| `data[].kind` | "percent" \| "every-nth" \| "daypart" | Only `percent` and `every-nth` slices are listed. |
| `data[].value` | number | The share of airtime (a percentage, or every Nth item). |
| `data[].requiresApproval` | boolean |  |
| `data[].sourcePlaylist` | object |  |
| `data[].sourcePlaylist.id` | string |  |
| `data[].sourcePlaylist.name` | string |  |
| `data[].sourcePlaylist.nodeId` | string \| null |  |
| `data[].fill` | object \| null | The playlist that fills the slice; null when none is bound. |

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/shared-with-me/{allocationId}/fill

Create a fill playlist

Create a new playlist and attach it as the fill for an airtime slice reserved for the caller's team.

**Notes.**
- Besides `playlist.view`, the caller needs `playlist.edit` at the location the slice is reserved for.
- The new playlist is empty and is placed at the reserved location.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `allocationId` | path | string | yes | Slice (allocation) id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Default `<location> slice`. |

```bash
curl -X POST "https://api.brixsignage.com/v1/shared-with-me/{allocationId}/fill" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success: A fill playlist is already bound: it is returned (`created: false`) and nothing is created.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.allocationId` | string |  |
| `data.fillPlaylistId` | string |  |
| `data.name` | string |  |
| `data.created` | boolean |  |

Response 201: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.allocationId` | string |  |
| `data.fillPlaylistId` | string |  |
| `data.name` | string |  |
| `data.created` | boolean |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You cannot fill this slice.

Response 404: No such fillable slice in this workspace.

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

## PUT /v1/shared-with-me/{allocationId}/fill

Set the fill playlist

Attach an existing playlist as the fill for an airtime slice reserved for the caller's team. Send `playlistId` as `null` to remove it.

**Notes.**
- Besides `playlist.view`, the caller needs `playlist.edit` at the location the slice is reserved for.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `allocationId` | path | string | yes | Slice (allocation) id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `playlistId` | string \| null | yes | A playlist you can edit; null unbinds. |

```bash
curl -X PUT "https://api.brixsignage.com/v1/shared-with-me/{allocationId}/fill" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.allocationId` | string |  |
| `data.fillPlaylistId` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You cannot fill this slice, or cannot edit that playlist.

Response 404: No such fillable slice, or no such playlist in this workspace.

Response 422: The playlist is the one the slice belongs to.

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

## GET /v1/shared-with-me/{allocationId}/source

Read the playlist a slice belongs to

Get the owner playlist around an airtime slice shared with your team: its name, whether it shuffles, its items in play order (name, kind, thumbnail, duration), and the share itself (kind, value, whether approval is required, and your fill playlist). Read only. Besides `playlist.view`, you need `playlist.edit` at the location the slice is reserved for. Other locations’ shares and the owner’s settings are not returned.

**Notes.**
- Besides `playlist.view`, the caller needs `playlist.edit` at the location the slice is reserved for.
- Read only. Other locations' shares and the owner's settings are not returned.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `allocationId` | path | string | yes | Slice (allocation) id. |

```bash
curl "https://api.brixsignage.com/v1/shared-with-me/{allocationId}/source" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.playlist` | object |  |
| `data.playlist.id` | string |  |
| `data.playlist.name` | string |  |
| `data.playlist.shuffle` | boolean |  |
| `data.items` | array of object | The owner's items in order: what plays around your share. |
| `data.items[].name` | string |  |
| `data.items[].kind` | string |  |
| `data.items[].thumbnailUrl` | string \| null |  |
| `data.items[].durationSec` | number |  |
| `data.share` | object |  |
| `data.share.kind` | "percent" \| "every-nth" \| "daypart" |  |
| `data.share.value` | number |  |
| `data.share.requiresApproval` | boolean |  |
| `data.share.reservedForName` | string |  |
| `data.share.fillPlaylistId` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You cannot fill this slice.

Response 404: No such fillable slice in this workspace.

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