Shares API
Shares endpoints in the Brix REST API for digital signage: 3 operations (GET, PUT). 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.
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}
Auth: Bearer token. Permission: screen.view.
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.
| Parameter | 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. |
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}
Auth: Bearer token. Permission: screen.view.
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.
| Parameter | 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. |
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
Auth: Bearer token. Permission: screen.view.
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.
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.