# Folder 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/folder-shares/{folderId}](#get-v1-folder-shares-folderid)
- [PUT /v1/folder-shares/{folderId}](#put-v1-folder-shares-folderid)
- [POST /v1/folder-shares/{folderId}/reach](#post-v1-folder-shares-folderid-reach)
- [GET /v1/folder-shares/notices](#get-v1-folder-shares-notices)
- [GET /v1/folder-shares/targets](#get-v1-folder-shares-targets)
- [GET /v1/folder-shares/targets/locations](#get-v1-folder-shares-targets-locations)

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/folder-shares/{folderId}

Get who a folder is shared with

Read who a Files folder is shared with: its own shares (a location, person or role, with `use` or `edit` access), shares inherited from folders above it, and general access. You must be able to edit the folder. A folder in another workspace answers 404.

Auth: Bearer token.

Parameters:

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

```bash
curl "https://api.brixsignage.com/v1/folder-shares/{folderId}" \
  -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.

## PUT /v1/folder-shares/{folderId}

Set who a folder is shared with

Replace who a Files folder is shared with. A location includes its sub-locations, and access is `use` or `edit`. Content already on screens keeps playing when a share is removed. You need permission to share folders and edit rights on this folder.

Auth: Bearer token. Permission: `media-folder.shared`.

Parameters:

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

```bash
curl -X PUT "https://api.brixsignage.com/v1/folder-shares/{folderId}" \
  -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.

## POST /v1/folder-shares/{folderId}/reach

Preview who a folder share reaches

Before saving a share, see who the proposed targets would give access to: a count and up to 100 names, limited to people you are allowed to see. Nothing is saved.

Auth: Bearer token.

Parameters:

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

```bash
curl -X POST "https://api.brixsignage.com/v1/folder-shares/{folderId}/reach" \
  -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.

## GET /v1/folder-shares/notices

List folders recently unshared from you

List folders that were unshared from the caller in the last 30 days. Content already on screens keeps playing, but the files can no longer be picked.

Auth: Bearer token.

```bash
curl "https://api.brixsignage.com/v1/folder-shares/notices" \
  -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.

## GET /v1/folder-shares/targets

Search for folder share targets

Find the people, locations and roles matching `q` that you can share a folder with. Each list is limited to what you are allowed to see.

Auth: Bearer token. Permission: `folder.share`.

```bash
curl "https://api.brixsignage.com/v1/folder-shares/targets" \
  -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.

## GET /v1/folder-shares/targets/locations

List locations to share a folder with

List one level of the location tree for picking a share target. Without `parentId` this is the top level. A location you cannot pick is included with `selectable: false` when it leads to one you can.

Auth: Bearer token.

```bash
curl "https://api.brixsignage.com/v1/folder-shares/targets/locations" \
  -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.