# Cross space 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/cross-space-shares](#get-v1-cross-space-shares)
- [POST /v1/cross-space-shares](#post-v1-cross-space-shares)
- [DELETE /v1/cross-space-shares/{id}](#delete-v1-cross-space-shares-id)
- [POST /v1/cross-space-shares/{id}/copy](#post-v1-cross-space-shares-id-copy)

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/cross-space-shares

List cross-workspace shares

List content this space shares into its child spaces, and content shared with it in turn. A space receiving a share can read it but cannot change or remove it.

**Notes.**
- Lists the shares this workspace RECEIVES (it is the target), not the ones it grants.

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

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].id` | string |  |
| `data[].sourceSpaceId` | string | The workspace that shares. |
| `data[].targetSpaceId` | string | The child workspace that receives. |
| `data[].contentKind` | string | `playlist`, `schedule`, `layout`, `creative`, `media`, … |
| `data[].contentId` | string |  |
| `data[].mode` | "linked" \| "snapshot" | Always `linked` for a new share: the child plays the parent's current version. |
| `data[].lockLevel` | "playlist" \| "items" \| "both" | What the child cannot change. |
| `data[].lockedItemIds` | string | A JSON-ENCODED array of item ids (the stored column), not an array. |
| `data[].grantedBy` | string | The user who shared it; `system` for an API key. |
| `data[].grantedAt` | string | ISO-8601 timestamp (UTC). |
| `data[].createdAt` | string | ISO-8601 timestamp (UTC). |
| `data[].updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data[].deletedAt` | string \| null |  |
| `data[].packShareId` | string \| null | Set when the share comes with a shared FOLDER: the id of that folder's share. Null otherwise. |
| `data[].contentName` | string \| null | Null when the content no longer exists. |
| `data[].sourceSpaceName` | string \| null |  |
| `data[].available` | boolean | False when the shared content was deleted. |
| `data[].thumbnailUrl` | string \| null | The item's picture through the share (`GET /v1/shared-in/{kind}/{id}/thumbnail`). Null for an app, a schedule or a deleted item. |
| `data[].fileKind` | string \| null | For a shared file: its kind (`image`, `video`, `pdf`…), so a Files page can filter it by type. Null for every other kind and for a deleted file. |
| `data[].copyable` | boolean | True when this workspace may make its own copy (`POST /v1/cross-space-shares/{id}/copy`): an item a partner shares live. |
| `data[].items` | integer | A shared folder (`contentKind` `folder`): how many files it brings now. |
| `data[].folders` | array of object | A shared folder: the folder and every folder inside it (the shared folder's own `parentId` is null). |
| `data[].folders[].id` | string |  |
| `data[].folders[].name` | string |  |
| `data[].folders[].parentId` | string \| null |  |
| `data[].folderId` | string \| null | A file that comes with a shared folder: the folder it is in. |

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/cross-space-shares

Share content with a child workspace

Share a playlist, layout, schedule, or creative from this space into a child space. The shared content appears in the child space alongside its own content. Only the space that owns the content can create the share. Requires view permission on shares plus the appropriate permission on the content itself.

**Notes.**
- Besides the `playlist.view` gate, the caller needs the content kind's edit permission at the content's location.

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

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `targetSpaceId` | string | yes | A child workspace of yours. |
| `contentKind` | string | yes |  |
| `contentId` | string | yes |  |
| `lockLevel` | "playlist" \| "items" \| "both" | no | Default `both`. |
| `lockedItemIds` | array of string | no |  |
| `mode` | string | no | Ignored: a share is always `linked`. |

```bash
curl -X POST "https://api.brixsignage.com/v1/cross-space-shares" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success: The content is already shared with that workspace: the existing share is returned.

| Field | Type | Description |
| --- | --- | --- |
| `data` | CrossSpaceShare | Content a parent workspace shares with a child workspace. |
| `data.id` | string |  |
| `data.sourceSpaceId` | string | The workspace that shares. |
| `data.targetSpaceId` | string | The child workspace that receives. |
| `data.contentKind` | string | `playlist`, `schedule`, `layout`, `creative`, `media`, … |
| `data.contentId` | string |  |
| `data.mode` | "linked" \| "snapshot" | Always `linked` for a new share: the child plays the parent's current version. |
| `data.lockLevel` | "playlist" \| "items" \| "both" | What the child cannot change. |
| `data.lockedItemIds` | string | A JSON-ENCODED array of item ids (the stored column), not an array. |
| `data.grantedBy` | string | The user who shared it; `system` for an API key. |
| `data.grantedAt` | string | ISO-8601 timestamp (UTC). |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.deletedAt` | string \| null |  |
| `data.packShareId` | string \| null | Set when the share comes with a shared FOLDER: the id of that folder's share. Null otherwise. |

Response 201: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | CrossSpaceShare | Content a parent workspace shares with a child workspace. |
| `data.id` | string |  |
| `data.sourceSpaceId` | string | The workspace that shares. |
| `data.targetSpaceId` | string | The child workspace that receives. |
| `data.contentKind` | string | `playlist`, `schedule`, `layout`, `creative`, `media`, … |
| `data.contentId` | string |  |
| `data.mode` | "linked" \| "snapshot" | Always `linked` for a new share: the child plays the parent's current version. |
| `data.lockLevel` | "playlist" \| "items" \| "both" | What the child cannot change. |
| `data.lockedItemIds` | string | A JSON-ENCODED array of item ids (the stored column), not an array. |
| `data.grantedBy` | string | The user who shared it; `system` for an API key. |
| `data.grantedAt` | string | ISO-8601 timestamp (UTC). |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.deletedAt` | string \| null |  |
| `data.packShareId` | string \| null | Set when the share comes with a shared FOLDER: the id of that folder's share. Null otherwise. |

Response 401: Missing, expired or revoked bearer token.

Response 403: The target is not a child workspace of yours, or you lack the content kind's edit permission (`playlist.edit`, …) where it lives.

Response 404: No such content in your workspace.

Response 422: `targetSpaceId`, `contentKind` or `contentId` is missing.

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

## DELETE /v1/cross-space-shares/{id}

Revoke a cross-workspace share

Withdraw a share. Only the space that created the share can remove it; the receiving space cannot.

**Notes.**
- Only the sharing workspace can revoke; it needs the content kind's edit permission too.

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

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Share id. |

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.id` | string |  |
| `data.revoked` | true |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: You lack the content kind's edit permission where the content lives.

Response 404: No such share granted by this workspace.

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

## POST /v1/cross-space-shares/{id}/copy

Make your own copy of a shared item

Copy an item that a partner shares with your workspace into your own library, so that you can change it. The copy is a draft and has no link to the original. The share continues: the original plays where you use it, and later changes from the partner reach it. Data sources and sign-in values are not copied. You need create permission for each kind of content that the copy makes. A large copy continues in the background and the answer gives a job id.

Auth: Bearer token.

Parameters:

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Identifier for id. |

```bash
curl -X POST "https://api.brixsignage.com/v1/cross-space-shares/{id}/copy" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 4XX: Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.

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