# Shares

> 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/shares/{kind}/{id}](#get-v1-shares-kind-id)
- [PUT /v1/shares/{kind}/{id}](#put-v1-shares-kind-id)
- [GET /v1/shares/directory](#get-v1-shares-directory)

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

Get a content item's shares

List the share entries for one content item, showing which nodes, users, and roles it is shared with, and at what level. Requires view, edit, or share permission on the item at its home node.

**Notes.**
- Besides the `screen.view` gate, the caller needs the item's view, edit or share permission (`playlist.view`, …) at its location; media is checked at the workspace root.
- A row targets one location (and everything under it), one person or one role; a row with no target shares with every location.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | path | string | yes | `playlist`, `schedule`, `layout`, `creative`, `signage`, `app` or `media`. |
| `id` | path | string | yes | The content item's id. |

```bash
curl "https://api.brixsignage.com/v1/shares/{kind}/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].id` | string |  |
| `data[].targetNodeId` | string \| null |  |
| `data[].targetUserId` | string \| null |  |
| `data[].targetRoleId` | string \| null |  |
| `data[].level` | "disabled" \| "play" \| "play_local" |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You hold none of the item's view, edit or share permission at its location.

Response 404: No such item in this workspace.

Response 422: Unknown `kind`.

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

## PUT /v1/shares/{kind}/{id}

Replace a content item's shares

Replace the entire share set for one content item. Each entry targets exactly one of a node, a user, or a role. Requires the item's own share permission at its home node.

**Notes.**
- Replaces every share of the item in one step. Besides the `screen.view` gate, the caller needs the kind's share permission at the item's location (media: at the workspace root).
- A row targets one location (and everything under it), one person or one role; a row with no target shares with every location.
- The response echoes the request's rows rather than the stored ones.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `kind` | path | string | yes | `playlist`, `schedule`, `layout`, `creative`, `signage`, `app` or `media`. |
| `id` | path | string | yes | The content item's id. |

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `shares` | array of object | yes | The whole new share set (at most 200). An empty array removes every share. |
| `shares[].targetNodeId` | string \| null | no |  |
| `shares[].targetUserId` | string \| null | no |  |
| `shares[].targetRoleId` | string \| null | no |  |
| `shares[].level` | string | yes | `disabled`, `play` or `play_local`; any other value is stored as `play`. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.contentKind` | "playlist" \| "schedule" \| "layout" \| "creative" \| "app" \| "media" \| "signage" |  |
| `data.contentId` | string |  |
| `data.shares` | array of object | The share set as SENT, with duplicate targets collapsed (last one wins): `level` is echoed as sent, not as stored, and there are no row ids (read them with GET). |
| `data.shares[].targetNodeId` | string \| null |  |
| `data.shares[].targetUserId` | string \| null |  |
| `data.shares[].targetRoleId` | string \| null |  |
| `data.shares[].level` | string |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold the kind's share permission (`playlist.share`, …) at the item's location.

Response 404: No such item in this workspace.

Response 422: Unknown `kind`, more than 200 rows, a row with more than one target, or a person or role that is not in this workspace (a person must be one the share directory offers you).

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

## GET /v1/shares/directory

List shareable people and roles

List the people and roles a share can target, including id, display name, and, for roles, colour and member count. Available to anyone holding a share permission on any content, rather than requiring full user directory access. People are listed only from the caller's own workspace: a franchise child workspace sees its own people, never the parent's or another child workspace's. Email is returned only for people the caller can see with the user view permission; otherwise it is null. A role's member count counts only the listed people.

**Notes.**
- Besides the `screen.view` gate, the caller needs at least one share permission somewhere.
- People stop at the child-workspace line: a franchise child workspace sees only its own people, and the parent does not see into a child. `email` needs `user.view` reaching that person, else it is null.

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

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.users` | array of object | People in the workspace the caller shares from (active and invited; never across a franchise child-workspace line). |
| `data.users[].id` | string |  |
| `data.users[].name` | string |  |
| `data.users[].email` | string \| null | Only for people the caller could read with `user.view`; null otherwise. |
| `data.roles` | array of object | Every role in the workspace. |
| `data.roles[].id` | string |  |
| `data.roles[].name` | string |  |
| `data.roles[].color` | string \| null |  |
| `data.roles[].memberCount` | integer | Members among the people listed above. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You hold no share permission (`playlist.share`, `media.share`, …) anywhere.

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