Proof API
Proof endpoints in the Brix REST API for digital signage: 6 operations (GET, POST). Each lists its path, auth, required permission and a curl example.
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/proofGET /v1/proof/eventsGET /v1/proof/exportGET /v1/proof/keysPOST /v1/proof/keys/{keyId}/revokePOST /v1/proof/verify-bundle
GET/v1/proof
Get proof-of-play totals for a date range, broken down by content item and by screen, including digital-out-of-home verification fields. Use the from and to query parameters to set the date range.
Counts what played, where and for how long, over a time window. Only screens the caller can see are counted.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | no | Window start (ISO-8601). Default: the start of the retention window. |
to | query | string | no | Window end (ISO-8601). Default: now. |
screenId | query | string | no | Only this screen. |
curl "https://api.brixsignage.com/v1/proof" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | ProofOfPlayReport | |
data.totals | object | |
data.totals.plays | integer | Successful plays (neither skipped nor failed). |
data.totals.skipped | integer | |
data.totals.failed | integer | |
data.totals.events | integer | Every playback-end event: plays + skipped + failed. |
data.totals.uniqueContent | integer | |
data.totals.screensReporting | integer | |
data.byContent | array of object | Per content, most successful plays first. |
data.byContent[].contentId | string | `unknown` when the player did not report one. |
data.byContent[].contentName | string | Falls back to the id when no name was reported. |
data.byContent[].contentKind | string | `media`, `app`, `creative`, …; `media` for days read from the daily rollup. |
data.byContent[].screenName | string | null | Set only when exactly one screen played it. |
data.byContent[].played | integer | |
data.byContent[].skipped | integer | |
data.byContent[].failed | integer | |
data.byContent[].screenCount | integer | |
data.byContent[].totalDurationSec | integer | |
data.byContent[].firstAt | string | ISO-8601 timestamp (UTC). |
data.byContent[].lastAt | string | ISO-8601 timestamp (UTC). |
data.screens | array of object | Screens that reported in the window, by name. |
data.screens[].id | string | |
data.screens[].name | string | |
data.from | string | ISO-8601 timestamp (UTC). |
data.to | string | ISO-8601 timestamp (UTC). |
data.retentionDays | integer | How far back raw play events exist; older days come from the daily rollup. |
data.truncated | boolean | Always false: the whole window is counted. |
data.fromRollup | boolean | Part of the window was read from the daily rollup. |
Response 401 Missing, expired or revoked bearer token.
| 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 403 The token lacks the permission this operation needs (see `x-brix-permission`).
| 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/proof/events
List individual playback events, one per play, for a date range. The number of events returned is capped. For totals rolled up by content item and screen, use GET /v1/proof instead.
**Notes.**
- rollup sits beside data, outside the usual envelope.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | no | ISO-8601 start (default: the start of the report window). |
to | query | string | no | ISO-8601 end (default: now). |
screenId | query | string | no |
curl "https://api.brixsignage.com/v1/proof/events" \
-H "Authorization: Bearer $BRIX_API_KEY"Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | array of object | One row per play, newest first (at most 2000), from screens the caller can see. |
data[].id | string | |
data[].screenId | string | |
data[].screenName | string | The screen id when the screen no longer exists. |
data[].contentKind | string | `media` when not reported. |
data[].contentId | string | `unknown` when not reported. |
data[].contentName | string | `Unknown content` when not reported. |
data[].startedAt | string | ISO-8601 timestamp (UTC). |
data[].durationSec | integer | |
data[].result | "played" | "skipped" | "failed" | |
data[].reason | string | null | |
rollup | array of object | Daily totals for the part of the range older than the raw-event window; empty when `from` is inside it. |
rollup[].day | string | `YYYY-MM-DD`. |
rollup[].screenId | string | |
rollup[].contentId | string | |
rollup[].plays | integer | |
rollup[].totalDurationMs | integer | |
rollup[].played | integer | |
rollup[].skipped | integer | |
rollup[].failed | integer |
Response 401 Missing, expired or revoked bearer token.
| 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 403 The token lacks the permission this operation needs (see `x-brix-permission`).
| 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/proof/export
Downloads the plays in a date range with the signature and chain status of each play, a summary of counts, a SHA-256 hash of the bundle and a detached server signature. Use from, to and screenId to filter and format=json or format=csv. The newest 5,000 plays are included. Available only to workspaces with digital-out-of-home enabled; other workspaces get 404.
curl "https://api.brixsignage.com/v1/proof/export" \
-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/proof/keys
Lists the proof-of-play signing keys that one screen has registered. screenId is required. Each key shows its key id, when it was first seen, the key it replaced and when it was revoked. Key material is never returned. Available only to workspaces with digital-out-of-home enabled.
curl "https://api.brixsignage.com/v1/proof/keys" \
-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/proof/keys/{keyId}/revoke
Marks one of a screen's signing keys as bad. Send the screenId in the body. From that time, plays signed with the key show as revoked, and the next new key from the screen registers as a replacement. Calling it again has no further effect. The change is recorded in the activity log.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
keyId | path | string | yes | Identifier for keyId. |
curl -X POST "https://api.brixsignage.com/v1/proof/keys/{keyId}/revoke" \
-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/proof/verify-bundle
Checks a downloaded proof-of-play export against the published signing keys: the bundle hash, the server signature, and the device signature and chain of each play. No credential is needed. Requests are rate limited, and a bundle can be at most 8 MB and 5,000 plays.
curl -X POST "https://api.brixsignage.com/v1/proof/verify-bundle"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. |