Ad slots API
Ad slots endpoints in the Brix REST API: 7 operations (GET, POST, PATCH, DELETE, PUT), with auth, permissions and curl examples.
Base URL https://api.brixsignage.com. Send Authorization: Bearer $BRIX_API_KEY unless an operation says No auth. The permission chip names what the key must hold. See Authentication and scopes, Errors and rate limits and Pagination.
GET /v1/ad-slotsPOST /v1/ad-slotsGET /v1/ad-slots/{id}PATCH /v1/ad-slots/{id}DELETE /v1/ad-slots/{id}GET /v1/ad-slots/{id}/impressionsPUT /v1/ad-slots/{id}/secrets
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.
curl "https://api.brixsignage.com/v1/ad-slots" \
-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.
| 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. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| 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. |
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.
curl -X POST "https://api.brixsignage.com/v1/ad-slots" \
-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.
| 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. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| 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/{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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Identifier for id. |
curl "https://api.brixsignage.com/v1/ad-slots/{id}" \
-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.
| 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. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| 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. |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Identifier for id. |
curl -X PATCH "https://api.brixsignage.com/v1/ad-slots/{id}" \
-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.
| 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. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| 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. |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Identifier for id. |
curl -X DELETE "https://api.brixsignage.com/v1/ad-slots/{id}" \
-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.
| 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. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| 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/{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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Identifier for id. |
curl "https://api.brixsignage.com/v1/ad-slots/{id}/impressions" \
-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.
| 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. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| 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. |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Identifier for id. |
curl -X PUT "https://api.brixsignage.com/v1/ad-slots/{id}/secrets" \
-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.
| 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. |
Response 5XX Server error. The body carries a `requestId` to quote to support.
| 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. |