Ad slots API

Ad slots endpoints in the Brix REST API: 12 operations (GET, POST, PATCH, DELETE, PUT). Each lists its path, auth, required permission and a curl example.

View as Markdown · For AI agents: the full docs index is at /llms.txt

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, Errors and rate limits and Pagination.

GET /v1/ad-slots
POST /v1/ad-slots
GET /v1/ad-slots/{id}
PATCH /v1/ad-slots/{id}
DELETE /v1/ad-slots/{id}
GET /v1/ad-slots/{id}/health
GET /v1/ad-slots/{id}/impressions
PUT /v1/ad-slots/{id}/secrets
POST /v1/ad-slots/{id}/test
GET /v1/ad-slots/{id}/venues
PUT /v1/ad-slots/{id}/venues
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

Auth: Bearer token. Permission: integration.view.

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.

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

Auth: Bearer token. Permission: integration.create.

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

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.

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}

Auth: Bearer token. Permission: integration.view.

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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Ad slot id.

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}

Auth: Bearer token. Permission: integration.edit.

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.

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

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}

Auth: Bearer token. Permission: integration.delete.

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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Ad slot id.

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

Auth: Bearer token. Permission: integration.view.

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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Identifier for id.

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

Auth: Bearer token. Permission: integration.view.

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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Ad slot id.

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

Auth: Bearer token. Permission: integration.edit.

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.

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

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

Auth: Bearer token. Permission: integration.edit.

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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Identifier for id.

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

Auth: Bearer token. Permission: integration.view.

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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Ad slot id.

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

Auth: Bearer token. Permission: integration.edit.

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.

Parameter	In	Type	Required	Description
`id`	path	string	yes	Ad slot id.

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

Auth: Bearer token. Permission: integration.edit.

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.

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

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.

GET /v1/ad-slots

POST /v1/ad-slots

GET /v1/ad-slots/{id}

PATCH /v1/ad-slots/{id}

DELETE /v1/ad-slots/{id}

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

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

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

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

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

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

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

Connect With Us

Message Received!