---
title: "Replace a content item's shares"
method: PUT
path: "/v1/shares/{kind}/{id}"
tags: ["shares"]
---

# Replace a content item's shares

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

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/shares/{kind}/{id}`
- Auth: HTTP bearer

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.

## Path parameters

- `kind` string, required
- `id` string, required

## Request body

- object
  - `shares` object[], required: The whole new share set (at most 200). An empty array removes every share.
    - `targetNodeId` string, nullable
    - `targetUserId` string, nullable
    - `targetRoleId` string, nullable
    - `level` string, required: `disabled`, `play` or `play_local`; any other value is stored as `play`.

## Response `200`

Success.

- object
  - `data` object, required
    - `contentKind` 'playlist' | 'schedule' | 'layout' | 'creative' | 'app' | 'media' | 'signage', required
    - `contentId` string, required
    - `shares` object[], required: 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).
      - `targetNodeId` string, nullable
      - `targetUserId` string, nullable
      - `targetRoleId` string, nullable
      - `level` string, required

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: You do not hold the kind's share permission (`playlist.share`, …) at the item's location.
- `404`: No such item in this workspace.
- `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).
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)