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.
Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says No auth. The permission chip names what the key must hold. See Authentication and scopes, Errors and rate limits and Pagination.
GET/v1/shares/{kind}/{id}
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.
| 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 hold none of the item's view, edit or share permission at its 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 No such item in this workspace.
| 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 Unknown `kind`.
| 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/shares/{kind}/{id}
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.
| 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 do not hold the kind's share permission (`playlist.share`, …) at the item's 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 No such item in this workspace.
| 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 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).
| 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. |
GET/v1/shares/directory
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.
| 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 hold no share permission (`playlist.share`, `media.share`, …) anywhere.
| 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. |