# Ad slots

> 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/ad-slots](#get-v1-ad-slots)
- [POST /v1/ad-slots](#post-v1-ad-slots)
- [GET /v1/ad-slots/{id}](#get-v1-ad-slots-id)
- [PATCH /v1/ad-slots/{id}](#patch-v1-ad-slots-id)
- [DELETE /v1/ad-slots/{id}](#delete-v1-ad-slots-id)
- [GET /v1/ad-slots/{id}/health](#get-v1-ad-slots-id-health)
- [GET /v1/ad-slots/{id}/impressions](#get-v1-ad-slots-id-impressions)
- [PUT /v1/ad-slots/{id}/secrets](#put-v1-ad-slots-id-secrets)
- [POST /v1/ad-slots/{id}/test](#post-v1-ad-slots-id-test)
- [GET /v1/ad-slots/{id}/venues](#get-v1-ad-slots-id-venues)
- [PUT /v1/ad-slots/{id}/venues](#put-v1-ad-slots-id-venues)
- [POST /v1/ad-slots/{id}/venues/import](#post-v1-ad-slots-id-venues-import)

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/ad-slots

List ad slots

List the programmatic ad slots configured in the workspace. Each slot includes its provider, endpoint, venue or device identifiers, and its minimum and maximum duration limits. The exchange credential itself is never included; only the name of the stored credential reference is returned.

**Notes.**
- Newest first; only slots at locations the caller can see. `secretRefs` is always `[]` here: read one slot to see them.

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

```bash
curl "https://api.brixsignage.com/v1/ad-slots" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of AdSlot |  |
| `data[].id` | string |  |
| `data[].spaceId` | string |  |
| `data[].name` | string |  |
| `data[].enabled` | boolean |  |
| `data[].nodeId` | string \| null | Home location; null = workspace root. |
| `data[].createdAt` | string | ISO-8601 timestamp (UTC). |
| `data[].updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data[].config` | AdSlotConfig \| null | Null when the stored settings cannot be read. |
| `data[].secretRefs` | array of string | Secret names that hold a value. Values are never returned. The single-slot reads fill this; the list answers `[]`. |

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/ad-slots

Create an ad slot with a `name` and a `config` object containing `provider`, `endpoint`, `credsRef`, `minSeconds`, `maxSeconds`, `podSeconds`, and `allowAudio`, plus optional `venueId`, `deviceTypeId`, and `nodeId`. The slot is created disabled and cannot request ads until you enable it with a later update.

**Notes.**
- A new slot is always created disabled (`enabled` in the body is ignored), and `secretRefs` is `[]`.

Auth: Bearer token. Permission: `integration.create`.

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Up to 120 characters. |
| `enabled` | boolean | no | Ignored: a new slot is always created disabled. Enable it with an update once its secret is set. |
| `nodeId` | string \| null | no | Home location; you need `integration.create` there. |
| `config` | object | yes |  |
| `config.provider` | "vast" \| "vistar" \| "broadsign" \| "hivestack" | yes |  |
| `config.endpoint` | string | yes |  |
| `config.credsRef` | string | no | The name of the secret (set with `PUT /v1/ad-slots/:id/secrets`) that holds the ad server credential. |
| `config.venueId` | string \| null | no |  |
| `config.deviceTypeId` | string \| null | no |  |
| `config.minSeconds` | integer | no | Shortest ad to accept, 1–300 (default 5). |
| `config.maxSeconds` | integer | no | Longest ad to accept, at least `minSeconds`. |
| `config.podSeconds` | integer | no | Seconds of ads per break, at least `maxSeconds`. |
| `config.allowAudio` | boolean | no |  |
| `config.vistar` | object | no | Vistar settings. Only for `provider` = `vistar`. The endpoint is fixed by `environment`. |
| `config.vistar.environment` | "staging" \| "production" | yes | Which Vistar network the slot talks to. Staging and production use separate credentials. |
| `config.vistar.spots` | integer | yes | Open spots requested per visit to the pod, 1–12. Each spot is one request and at most one ad. |
| `config.vistar.staticSeconds` | integer | yes | Seconds a still image plays, 1–60. |

```bash
curl -X POST "https://api.brixsignage.com/v1/ad-slots" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lobby ads","enabled":true,"config":{"provider":"vast","endpoint":"https://ads.example.com/vast","credsRef":"vastKey"}}'
```

Response 201: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | AdSlot | A slot that fills airtime from a programmatic ad server. |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.name` | string |  |
| `data.enabled` | boolean |  |
| `data.nodeId` | string \| null | Home location; null = workspace root. |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.config` | AdSlotConfig \| null | Null when the stored settings cannot be read. |
| `data.secretRefs` | array of string | Secret names that hold a value. Values are never returned. The single-slot reads fill this; the list answers `[]`. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `integration.create` at the location.

Response 422: `name` missing, or `config` has no provider or endpoint, or the endpoint is not a public http(s) URL.

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

## GET /v1/ad-slots/{id}

Get an ad slot

Retrieve one ad slot, including the names of the credentials stored against it. Credential values are write-only and are never returned by this or any other endpoint.

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

Parameters:

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

```bash
curl "https://api.brixsignage.com/v1/ad-slots/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | AdSlot | A slot that fills airtime from a programmatic ad server. |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.name` | string |  |
| `data.enabled` | boolean |  |
| `data.nodeId` | string \| null | Home location; null = workspace root. |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.config` | AdSlotConfig \| null | Null when the stored settings cannot be read. |
| `data.secretRefs` | array of string | Secret names that hold a value. Values are never returned. The single-slot reads fill this; the list answers `[]`. |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such ad slot in this workspace.

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

## PATCH /v1/ad-slots/{id}

Update an ad slot

Edit an ad slot's name, node, or exchange configuration, or turn ad requesting on and off. Enabling a slot is what allows it to start spending, so this action is recorded in the activity log.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

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

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `enabled` | boolean | no |  |
| `nodeId` | string \| null | no | Move the slot; you need `integration.edit` at the destination too. |
| `config` | object | no | Replaces the settings (missing fields take their defaults). A change to `provider`, `endpoint` or `credsRef` deletes the stored secrets (except for Vistar); set them again with `PUT /v1/ad-slots/:id/secrets`. |
| `config.provider` | "vast" \| "vistar" \| "broadsign" \| "hivestack" | yes |  |
| `config.endpoint` | string | yes |  |
| `config.credsRef` | string | no | The name of the secret (set with `PUT /v1/ad-slots/:id/secrets`) that holds the ad server credential. |
| `config.venueId` | string \| null | no |  |
| `config.deviceTypeId` | string \| null | no |  |
| `config.minSeconds` | integer | no | Shortest ad to accept, 1–300 (default 5). |
| `config.maxSeconds` | integer | no | Longest ad to accept, at least `minSeconds`. |
| `config.podSeconds` | integer | no | Seconds of ads per break, at least `maxSeconds`. |
| `config.allowAudio` | boolean | no |  |
| `config.vistar` | object | no | Vistar settings. Only for `provider` = `vistar`. The endpoint is fixed by `environment`. |
| `config.vistar.environment` | "staging" \| "production" | yes | Which Vistar network the slot talks to. Staging and production use separate credentials. |
| `config.vistar.spots` | integer | yes | Open spots requested per visit to the pod, 1–12. Each spot is one request and at most one ad. |
| `config.vistar.staticSeconds` | integer | yes | Seconds a still image plays, 1–60. |

```bash
curl -X PATCH "https://api.brixsignage.com/v1/ad-slots/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | AdSlot | A slot that fills airtime from a programmatic ad server. |
| `data.id` | string |  |
| `data.spaceId` | string |  |
| `data.name` | string |  |
| `data.enabled` | boolean |  |
| `data.nodeId` | string \| null | Home location; null = workspace root. |
| `data.createdAt` | string | ISO-8601 timestamp (UTC). |
| `data.updatedAt` | string | ISO-8601 timestamp (UTC). |
| `data.config` | AdSlotConfig \| null | Null when the stored settings cannot be read. |
| `data.secretRefs` | array of string | Secret names that hold a value. Values are never returned. The single-slot reads fill this; the list answers `[]`. |

Response 401: Missing, expired or revoked bearer token.

Response 403: You do not hold `integration.edit` at the destination.

Response 404: No such ad slot in this workspace.

Response 409: `conflict`: a `config` change found the slot settings or secrets changed while this request ran. Nothing was saved; read the slot again and resend.

Response 422: An empty `name`, or an invalid `config`.

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

## DELETE /v1/ad-slots/{id}

Delete an ad slot and stop it from requesting ads. Cached creatives and the record of impressions already played are kept, so past playback history remains available after the slot is removed.

**Notes.**
- Answers `{ ok: true }`. The slot is also disabled; its impressions are kept.

Auth: Bearer token. Permission: `integration.delete`.

Parameters:

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

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

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.ok` | true |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such ad slot in this workspace.

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

## GET /v1/ad-slots/{id}/health

Get an ad slot's fill health

Returns fill health for an ad slot over a time window (24 hours by default): ads requested, leased, played, confirmed, expired and not filled, errors, spend, expiry rates, display and confirmation delays, and the screens that requested ads. These are the numbers the ad exchange checks. Available only to workspaces with digital-out-of-home enabled.

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

Parameters:

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

```bash
curl "https://api.brixsignage.com/v1/ad-slots/{id}/health" \
  -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/ad-slots/{id}/impressions

List ad slot impressions

List what an ad slot has actually played, and whether each impression beacon was recorded successfully. Results are returned newest first and the response is capped at 200 records. Use this to reconcile playback against an advertiser's invoice.

**Notes.**
- The newest 200 plays.

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

Parameters:

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

```bash
curl "https://api.brixsignage.com/v1/ad-slots/{id}/impressions" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].id` | string |  |
| `data[].spaceId` | string |  |
| `data[].slotId` | string |  |
| `data[].screenId` | string |  |
| `data[].creativeId` | string | The ad server's creative id. |
| `data[].playKey` | string | A unique key for this play. |
| `data[].playedAt` | string | ISO-8601 timestamp (UTC). |
| `data[].beaconsOk` | integer | Tracking beacons that the ad server accepted. |
| `data[].beaconsFailed` | integer |  |
| `data[].createdAt` | string | ISO-8601 timestamp (UTC). |

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such ad slot in this workspace.

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

## PUT /v1/ad-slots/{id}/secrets

Set ad slot secrets

Store the exchange credential for an ad slot. Send a map of reference names to values; the values are encrypted at rest and merged into any existing credentials. Setting a value to `null` deletes that reference. Only the credential names are ever returned, never the values.

**Notes.**
- Values are encrypted and never returned. Validation errors answer 400, not 422.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

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

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `secrets` | object | yes | Secret name → value (up to 20 names of up to 128 characters; values up to 8192). Null or empty removes that secret; names you do not send are kept. |

```bash
curl -X PUT "https://api.brixsignage.com/v1/ad-slots/{id}/secrets" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.ok` | true |  |
| `data.refs` | array of string | Every secret name that now holds a value. |

Response 400: `too_many_secrets`, `ref_too_long` or `value_too_long`.

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404: No such ad slot in this workspace.

Response 409: The slot settings or secrets changed while this request ran. Nothing was saved; send it again.

Response 429: More than 30 calls a minute.

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

## POST /v1/ad-slots/{id}/test

Test an ad slot's connection

Makes one real ad request for one screen, releases the lease at once and plays nothing, to prove that the credentials and the venue id work. Returns whether the test passed, the reason, and the request with secrets removed. Available only to workspaces with digital-out-of-home enabled.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

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

```bash
curl -X POST "https://api.brixsignage.com/v1/ad-slots/{id}/test" \
  -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/ad-slots/{id}/venues

List ad slot venues

List the screens you can see, each with the Vistar venue id it uses for this ad slot. `venueId` is null for a screen with no venue. Vistar refuses ad requests that have no venue id registered in your Vistar network.

**Notes.**
- One entry for each screen the caller can see. `venueId` is null when the screen has no venue.

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

Parameters:

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

```bash
curl "https://api.brixsignage.com/v1/ad-slots/{id}/venues" \
  -H "Authorization: Bearer $BRIX_API_KEY"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].screenId` | string |  |
| `data[].screenName` | string |  |
| `data[].venueId` | string \| null |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The `dooh` feature is off for this workspace (`feature_disabled`).

Response 404: No such ad slot in this workspace.

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

## PUT /v1/ad-slots/{id}/venues

Set ad slot venues

Set or clear the Vistar venue id of many screens at once. Send a list of `screenId` and `venueId` entries. A `venueId` of null clears the mapping. If any entry is not valid, nothing is saved and the response lists each problem.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

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

Request body: `application/json`

```bash
curl -X PUT "https://api.brixsignage.com/v1/ad-slots/{id}/venues" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.changed` | integer | Screens whose venue is now different. |

Response 401: Missing, expired or revoked bearer token.

Response 403: The `dooh` feature is off for this workspace (`feature_disabled`).

Response 404: No such ad slot in this workspace.

Response 422: An entry has an unknown screen or an invalid venue id. Nothing is saved; `errors` lists each entry.

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

## POST /v1/ad-slots/{id}/venues/import

Import ad slot venues

Set venue ids from CSV text. Each line is `screen,venue_id`, where `screen` is a screen id or an exact screen name. Valid lines are saved. The response gives the number saved and lists each line that was refused, with the reason.

**Notes.**
- Valid lines are saved. Lines with a problem are listed in `errors` and are not saved.

Auth: Bearer token. Permission: `integration.edit`.

Parameters:

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

Request body: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `csv` | string | yes | Lines of `screen,venue_id`. `screen` is a screen id or an exact screen name. A header line is optional. |

```bash
curl -X POST "https://api.brixsignage.com/v1/ad-slots/{id}/venues/import" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"
```

Response 200: Success.

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.applied` | integer |  |
| `data.errors` | array of object |  |
| `data.errors[].line` | integer |  |
| `data.errors[].screen` | string |  |
| `data.errors[].reason` | string |  |

Response 401: Missing, expired or revoked bearer token.

Response 403: The `dooh` feature is off for this workspace (`feature_disabled`).

Response 404: No such ad slot in this workspace.

Response 422: `csv` is missing or too large.

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