Ad slots API

GET/v1/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.

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

Response 200 Success.

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 [].

Request body application/json

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.

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}

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.

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

Response 200 Success.

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}

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.

Request body application/json

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.

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 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.

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

Response 200 Success.

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

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.

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 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.

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

Response 200 Success.

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

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.

Request body application/json

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.

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 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

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.

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 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.

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

Response 200 Success.

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 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.

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.

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

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.

Request body application/json

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.

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.