Account API
Account endpoints in the Brix REST API: 44 operations (GET, PUT, POST, PATCH, DELETE), 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/accountGET /v1/account/billing-addressPUT /v1/account/billing-addressPOST /v1/account/billing-modePOST /v1/account/cancelPOST /v1/account/cancel-deletionPATCH /v1/account/contract/renewalGET /v1/account/data-inventoryPOST /v1/account/downgrade-monthlyGET /v1/account/encryption-keyPUT /v1/account/encryption-keyDELETE /v1/account/encryption-keyPOST /v1/account/encryption-key/verifyGET /v1/account/exportGET /v1/account/export/manifestGET /v1/account/export/part/{part}GET /v1/account/invoicesGET /v1/account/invoices/{id}/filePOST /v1/account/invoices/{id}/pay-linkGET /v1/account/invoices/{id}/pdfPOST /v1/account/invoices/pay-all-linkPOST /v1/account/invoices/pay-links-outstandingGET /v1/account/limitsGET /v1/account/me-prefsPOST /v1/account/onboardingDELETE /v1/account/payment-cardPOST /v1/account/payment-card/completePOST /v1/account/payment-card/setupGET /v1/account/payment-methodsPOST /v1/account/payment-methods/{id}/rolePOST /v1/account/payment-methods/manage-urlPATCH /v1/account/payment-optionPATCH /v1/account/prefsPOST /v1/account/reactivateGET /v1/account/retentionPATCH /v1/account/retentionPOST /v1/account/screen-poolPOST /v1/account/screen-pool/estimateDELETE /v1/account/screen-pool/scheduledGET /v1/account/support-accessPATCH /v1/account/support-access/policyPOST /v1/account/support-access/revokePOST /v1/account/upgrade-annualGET /v1/account/upgrade-annual/estimate
GET/v1/account
Returns the workspace plan, subscription status, screen pool size, trial or paid status, and onboarding progress.
**Notes.**
- email, emailVerifiedAt and verificationEmailLastSentAt describe the CALLING user; they are null for an API key.
- On a workspace created before the onboarding step existed, a null prefs.onboardingCompletedAt is filled with the workspace's creation time (and saved).
curl "https://api.brixsignage.com/v1/account" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | Account | |
data.scheduledScreenPool | object | null | A screen plan reduction queued for the renewal. |
data.contract | BillingTerm | null | |
data.id | string | Workspace id (the account id support asks for). |
data.whiteLabel | boolean | A partner bills this workspace; Brix billing does not apply. |
data.status | "active" | "cancel_scheduled" | "paused" | "past_due" | "suspended" | "cancelled" | |
data.pauseUntil | string | null | |
data.cancelEffectiveAt | string | null | |
data.cancelReason | "provider" | "trial_expired" | "voluntary" | "nonpayment" | null | |
data.everPaid | boolean | |
data.deletionRequestedAt | string | null | |
data.billingBanner | BillingBanner | null | |
data.survey | any | The last cancellation survey (`{ reason, competitor, returnLikelihood, comment }`), or null. |
data.prefs | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). |
data.prefs.timeFormat | "12h" | "24h" | |
data.prefs.weekStart | "mon" | "sun" | |
data.prefs.dateFormat | "mdy" | "dmy" | "ymd" | |
data.prefs.tempUnits | "f" | "c" | |
data.prefs.timeZone | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. |
data.prefs.language | string | BCP 47 language tag. |
data.prefs.multinational | boolean | Shows the per-location and per-screen language settings. |
data.prefs.navExtras | array of string | Console pages switched on that the workspace size hides by default. |
data.prefs.appBranding | object | The look of the on-screen apps. |
data.prefs.appBranding.accent | string | |
data.prefs.appBranding.accent2 | string | |
data.prefs.appBranding.theme | "dark" | "light" | |
data.prefs.appBranding.backdrop | "brand" | "wash" | "plain" | "aurora" | "dots" | "grid" | "solid" | |
data.prefs.appBranding.intensity | number | |
data.prefs.audio | object | Default screen volume and a master mute. |
data.prefs.audio.volume | number | 0–100. |
data.prefs.audio.muted | boolean | |
data.prefs.brand | object | |
data.prefs.brand.companyName | string | |
data.prefs.brand.logoUrl | string | |
data.prefs.requireAltText | boolean | |
data.prefs.showScreenLogo | boolean | |
data.prefs.standbyContentKind | string | null | What a screen with nothing to play shows; null = the default card. |
data.prefs.standbyContentId | string | null | |
data.prefs.tier | "simple" | "team" | "enterprise" | Workspace size. It sets console defaults, not access. |
data.prefs.industry | string | null | |
data.prefs.onboardingCompletedAt | string | null | |
data.prefs.setupStep | string | null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). |
data.prefs.orgNameSet | boolean | |
data.prefs.tiers | array of integer | Location tree levels in use. |
data.prefs.tierLabels | object | Custom names for the location tree levels. |
data.prefs.requireTwoFactor | boolean | |
data.prefs.requireSso | boolean | |
data.prefs.requireSsoPending | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. |
data.prefs.requireSsoPendingSince | string | null | |
data.prefs.ai | object | |
data.prefs.ai.enabled | boolean | |
data.prefs.ai.features | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. |
data.prefs.ai.dailyCallLimit | integer | null | |
data.prefs.ai.redactPersonalData | boolean | |
data.prefs.retention | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
data.prefs.retention.offline | number | |
data.prefs.retention.screenshots | number | |
data.prefs.retention.playback | number | |
data.prefs.retention.deviceLogs | number | |
data.prefs.retention.vitals | number | |
data.prefs.retention.replays | number | |
data.prefs.retention.aiEvents | number | |
data.prefs.warehouse | object | Data warehouse feed. Set by Brix; not writable here. |
data.prefs.warehouse.enabled | boolean | |
data.prefs.warehouse.bucketBinding | string | Set by Brix when the data warehouse feed is provisioned. |
data.prefs.warehouse.tables | array of string | |
data.prefs.warehouse.lookbackDays | integer | |
data.prefs.supportAccess | SupportAccessPolicy | |
data.prefs.supportAccess.mode | "open" | "notify" | "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
data.prefs.supportAccess.grantMinutes | integer | How long an approval lasts. |
data.prefs.supportAccess.requestTtlMinutes | integer | How long a request waits for an answer before it expires. |
data.prefs.kioskHasGlobalPin | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. |
data.region | "us" | "eu" | "oc" | "apac" | Where the workspace's data is stored. |
data.billingProvider | "chargebee" | "brix" | `brix`: Brix invoices the account (see `payment`). `chargebee`: a card subscription. |
data.payment | AccountPayment | null | Only when `billingProvider` is `brix`. |
data.subscriptionStatus | string | null | |
data.cadence | "monthly" | "annual" | null | |
data.billableScreens | integer | Screens that count toward the bill now. |
data.licensedScreens | integer | null | Screens bought (the plan quantity or the term's screens). |
data.trialEndsAt | string | null | |
data.nextBillingAt | string | null | |
data.currentTermEndsAt | string | null | |
data.emailVerifiedAt | string | null | The calling user's; null for an API key. |
data.verificationEmailLastSentAt | string | null | |
data.email | string | null | The calling user's email; null for an API key. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/billing-address
Returns the billing address on file with the billing provider: the country used to determine invoice tax, and, for the United States and Canada, the state and postal code. The response includes configured: false when no billing address has been set yet.
curl "https://api.brixsignage.com/v1/account/billing-address" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | object |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/billing-address
Sets the workspace billing address. country is required and validated against the ISO 3166-1 country list. For the United States and Canada, stateCode and zip are also required. This replaces the entire address on file; you cannot update a single field.
**Notes.**
- Answers 400 (not 422) for an invalid address, unlike most validation errors.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
country | string | yes | Country code or name. |
stateCode | string | no | Required for US and Canada. Stored in upper case. |
zip | string | no | Required for US and Canada. |
city | string | no | |
line1 | string | no |
curl -X PUT "https://api.brixsignage.com/v1/account/billing-address" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.configured | true | |
data.address | object | |
data.address.country | string | null | ISO 3166-1 alpha-2. |
data.address.stateCode | string | null | State or province, without the country prefix (`CA`, `ON`). |
data.address.zip | string | null | |
data.address.city | string | null | |
data.address.line1 | string | null | |
data.needsState | boolean |
Response 400 `invalid_country` or `state_required` (400, not 422).
| 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 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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `no_customer`: billing is not set up yet.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/billing-mode
Switches the workspace between automatic card charging (auto) and invoice billing (invoice). Switching to invoice billing requires a signed-in user with a verified work email address, so an API key can only switch to automatic charging.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
mode | "auto" | "invoice" | yes |
curl -X POST "https://api.brixsignage.com/v1/account/billing-mode" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.mode | "auto" | "invoice" |
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 `user_required`: switching to `invoice` needs a signed-in user with a verified work email, so an API key can switch only to `auto`. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `email_unverified`, `work_email_required`, `billing_not_configured`, or `under_contract`.
| 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 422 `mode` is not `auto` or `invoice`.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/cancel
Submits a cancellation request with a reason. Choosing the reason "Seasonal Business" together with a restartDate pauses the account instead of cancelling it. Any other reason schedules cancellation for a fixed number of days after the request. Cancellation can be reversed at any time before it takes effect by calling the reactivate operation.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | yes | Survey answer. `Seasonal Business` pauses the account instead of cancelling it. |
restartDate | string | no | Required for `Seasonal Business`: when the account comes back (future, at most 12 months). |
competitor | string | no | |
returnLikelihood | number | no | |
comment | string | no |
curl -X POST "https://api.brixsignage.com/v1/account/cancel" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | object |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 No such workspace.
| 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 409 `payment_required` (unpaid invoice), `already_cancelled`, or `under_contract` (an agreed term; contact Brix).
| 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 422 `reason` missing, or a bad `restartDate`.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/cancel-deletion
Stops a scheduled permanent deletion of the workspace before it happens. Call this any time before the deletion date to keep the account and its data.
**Notes.**
- The account stays cancelled; reactivate it separately.
curl -X POST "https://api.brixsignage.com/v1/account/cancel-deletion" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.status | "active" | "cancel_scheduled" | "paused" | "past_due" | "suspended" | "cancelled" | |
data.deletionRequestedAt | null |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `not_pending_deletion`.
| 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/account/contract/renewal
Sets whether the workspace's current contract term renews automatically or ends at term expiry. Choosing not to renew voids any unpaid renewal invoice; choosing to renew allows Brix to invoice the next term automatically. Returns 409 if the workspace has no fixed term, and 404 for white-label workspaces, where this setting does not apply. **Notes.** - Turning auto-renew off voids an unpaid renewal invoice.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
renewal | "renew" | "non_renewing" | yes |
curl -X PATCH "https://api.brixsignage.com/v1/account/contract/renewal" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.ok | true | |
data.contract | BillingTerm | An agreed billing term (a fixed number of screens at a fixed rate for a fixed period). |
data.contract.id | string | |
data.contract.status | "active" | "cancelled" | "awaiting_payment" | "ended" | |
data.contract.rail | "chargebee" | "brix" | Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription). |
data.contract.activateOn | "now" | "paid" | |
data.contract.poNumber | string | null | |
data.contract.invoiceNumber | string | null | |
data.contract.invoicePaid | boolean | null | |
data.contract.activatedAt | string | null | |
data.contract.screens | integer | |
data.contract.rateCentsPerScreenMonth | integer | |
data.contract.termMonths | integer | |
data.contract.schedule | "upfront" | "monthly" | "annual" | |
data.contract.collect | "card" | "invoice" | |
data.contract.currency | string | |
data.contract.startsAt | string | Date (YYYY-MM-DD). |
data.contract.endsAt | string | Date (YYYY-MM-DD). |
data.contract.totalCents | integer | |
data.contract.monthlyCents | integer | |
data.contract.termLabel | string | |
data.contract.scheduleLabel | string | |
data.contract.invoiceId | string | null | |
data.contract.notes | string | null | |
data.contract.createdBy | string | null | |
data.contract.prior | object | null | The plan before the term started. |
data.contract.createdAt | string | ISO-8601 timestamp (UTC). |
data.contract.endedAt | string | null | |
data.contract.renewal | "renew" | "non_renewing" | |
data.contract.renewalInvoiceId | string | null | |
data.changed | boolean |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 A workspace billed by a partner.
| 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 409 `no_term` (no agreed term), or a term that cannot change here.
| 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 422 `renewal` is not `renew` or `non_renewing`.
| 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/account/data-inventory
Returns, for every category of data Brix holds about the workspace, what it is, whether it identifies a person, how long it is kept, whether it is included in a data export, and whether it is deleted when the account is closed. Pass ?counts=1 to include a row count for each category.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
counts | query | "1" | no | `1` adds a row count per table (slower). |
curl "https://api.brixsignage.com/v1/account/data-inventory" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.generatedAt | string | ISO-8601 timestamp (UTC). |
data.counted | boolean | |
data.categories | array of object | |
data.categories[].id | string | |
data.categories[].label | string | |
data.categories[].what | string | |
data.categories[].personal | string | |
data.categories[].retention | string | |
data.categories[].rows | integer | null | |
data.categories[].tables | array of object | |
data.categories[].tables[].table | string | |
data.categories[].tables[].rows | integer | null | |
data.categories[].tables[].inExport | boolean | |
data.categories[].tables[].exportNote | string | null | |
data.categories[].tables[].erasedOnClose | boolean | |
data.categories[].tables[].retainedNote | string | null | |
data.categories[].tables[].strippedFields | array of string | |
data.residency | object | null | Where the workspace's data is stored. `database`, `media` and `backups` are internal store names. |
data.notes | array of string |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/downgrade-monthly
Switches the workspace from annual to monthly billing at the end of the current annual term. Nothing is charged or refunded now.
curl -X POST "https://api.brixsignage.com/v1/account/downgrade-monthly" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.cadence | "annual" | Unchanged until the annual term ends. |
data.scheduledCadence | "monthly" |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `no_subscription`, `already_monthly`, or `under_contract`.
| 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 502 The switch could not be scheduled.
| 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/account/encryption-key
Returns whether the workspace can use its own encryption key in Azure Key Vault, what that key covers, its identifier, its status, and the progress of re-encrypting existing data under it.
curl "https://api.brixsignage.com/v1/account/encryption-key" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.available | boolean | Customer-managed keys can be used on this platform. |
data.covers | string | |
data.doesNotCover | string | |
data.key | object | null |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/encryption-key
Enables encryption with the workspace's own key in Azure Key Vault. Brix verifies the key, generates and wraps a data key, and starts re-encrypting existing secrets under it. Every new secret created after this call is protected with the customer's key.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
tenantId | string | yes | Your Microsoft Entra tenant id (a UUID). |
keyId | string | yes | `https://<vault>.vault.azure.net/keys/<name>/<version>`. |
curl -X PUT "https://api.brixsignage.com/v1/account/encryption-key" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 201 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.available | boolean | Customer-managed keys can be used on this platform. |
data.covers | string | |
data.doesNotCover | string | |
data.key | object | null | |
data.firstPass | object | The first re-encryption pass, run inside the request; the rest runs hourly. |
data.firstPass.status | string | |
data.firstPass.remaining | 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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `conflict` (a key is already set; turn it off first) or `key_check_failed`.
| 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 422 Bad `tenantId` or `keyId`.
| 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 503 `not_available` on this platform.
| 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/account/encryption-key
Disables the workspace's customer-managed encryption key. Every secret currently protected by that key is first moved back under the Brix-managed key, so nothing becomes unreadable, and only then is the key record removed. Returns 409 if the customer-managed key can no longer be reached.
**Notes.**
- key is null when the first pass moved every secret back; otherwise it shows disabling until the hourly pass finishes.
curl -X DELETE "https://api.brixsignage.com/v1/account/encryption-key" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.available | boolean | Customer-managed keys can be used on this platform. |
data.covers | string | |
data.doesNotCover | string | |
data.key | object | null | |
data.firstPass | object | The first re-encryption pass, run inside the request; the rest runs hourly. |
data.firstPass.status | string | |
data.firstPass.remaining | 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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 No key is set.
| 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 409 `key_unavailable`: the vault did not answer, so secrets cannot be moved back.
| 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/account/encryption-key/verify
Performs a dry run against the workspace's own encryption key: it wraps and unwraps a random test value to confirm the key still works. Nothing is stored or changed.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
tenantId | string | yes | Your Microsoft Entra tenant id (a UUID). |
keyId | string | yes | `https://<vault>.vault.azure.net/keys/<name>/<version>`. |
curl -X POST "https://api.brixsignage.com/v1/account/encryption-key/verify" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.ok | true |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `key_check_failed`: the vault refused (`kind` says why).
| 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 422 Bad `tenantId` or `keyId`.
| 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 503 `not_available` on this platform.
| 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/account/export
Returns a data export of the workspace as one downloadable file: the workspace record, its members, nine content tables and the last 365 days of activity-log events. Credentials are never included. Because the file holds every member's personal data, it requires permission to edit billing for the whole workspace. Brix does not email or store the export. For every table and the complete activity log, use the export manifest and its parts.
**Notes.**
- No { data } envelope: the body is the export file (Content-Disposition: attachment).
- Credentials are never exported: their columns are kept with null or a [secret; not exported] / [encrypted; not exported] marker.
- generatedBy.kind is user even when an API key made the export (and then userId is absent).
- The complete export (every table, the whole audit log) is GET /v1/account/export/manifest and its parts.
curl "https://api.brixsignage.com/v1/account/export" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
schemaVersion | 1 | |
generatedAt | string | ISO-8601 timestamp (UTC). |
generatedBy | object | Always `user`; `userId` is absent for an API key. |
generatedBy.kind | "user" | |
generatedBy.userId | string | |
workspace | object | The workspace record (every column; the Screen Lock PIN hash replaced by `kioskHasGlobalPin` inside `prefs`). |
people | array of object | |
people[].id | string | |
people[].name | string | |
people[].email | string | |
people[].status | string | |
people[].lastLoginAt | string | null | |
people[].createdAt | string | ISO-8601 timestamp (UTC). |
content | object | Nine content tables, one object per row (all columns). |
content.screens | array of object | |
content.mediaAssets | array of object | |
content.playlists | array of object | |
content.schedules | array of object | |
content.layouts | array of object | |
content.creatives | array of object | |
content.appInstances | array of object | |
content.dataSources | array of object | |
content.banners | array of object | |
auditEvents | array of object | The last 365 days only. |
limits | object | |
limits.auditEvents | string | |
limits.completeness | string |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/export/manifest
Describes the contents of a full data export without downloading it: every table of workspace data with its row count, which tables are excluded from the export and why, and which fields are redacted and why. Use this to confirm what an export will and will not contain before downloading it.
curl "https://api.brixsignage.com/v1/account/export/manifest" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.schemaVersion | integer | |
data.generatedAt | string | ISO-8601 timestamp (UTC). |
data.parts | array of object | |
data.parts[].part | string | Pass to `/export/part/:part`. |
data.parts[].table | string | |
data.parts[].rows | integer | |
data.excluded | array of object | |
data.excluded[].table | string | |
data.excluded[].reason | string | |
data.redactedColumns | array of string | `table.column` values withheld from every part. |
data.notes | array of string |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/export/part/{part}
Downloads one part of a full data export. Results are paged with a cursor rather than an offset, so rows are not skipped or duplicated if data changes while the export is running. Secret values are replaced with a marker rather than removed, so a withheld value can be told apart from one that was never set. Pass ?format=csv to receive the same data as CSV, encoded with a UTF-8 byte-order mark for compatibility with Excel and guarded against spreadsheet formula injection. Use the x-brix-next-cursor response header to fetch the next page.
**Notes.**
- Credentials are never exported: their columns are kept with null or a [secret; not exported] / [encrypted; not exported] marker (the manifest lists them in redactedColumns).
- ?format=csv answers text/csv instead, with the cursor in the X-Brix-Next-Cursor header.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
part | path | string | yes | A `part` from the manifest (a table name). |
cursor | query | string | no | `nextCursor` of the previous page. |
curl "https://api.brixsignage.com/v1/account/export/part/{part}" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | array of object | Rows of the table, all columns (withheld ones marked). |
nextCursor | string | null | Null on the last page. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 No such part.
| 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/account/invoices
Returns the workspace's invoice history, newest first: invoices Brix issued for an agreed term and invoices of the card subscription. The response includes configured: false when billing has not been set up yet.
curl "https://api.brixsignage.com/v1/account/invoices" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.configured | boolean | |
data.invoices | array of object | object | Newest first. Amounts are in currency units, not cents. |
data.reason | string | Present when the card subscription's invoices could not be read. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/invoices/{id}/file
Downloads the PDF file for one invoice belonging to the calling workspace. **Notes.** - For an invoice Brix issued, when the PDF cannot be drawn the route answers 302 to the invoice's web page instead.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Invoice id from the list. |
inline | query | string | no | Any value: `Content-Disposition: inline`. |
curl "https://api.brixsignage.com/v1/account/invoices/{id}/file" \
-H "Authorization: Bearer $BRIX_API_KEY" 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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 Not an invoice of this workspace.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/invoices/{id}/pay-link
Creates a shareable payment link for one invoice, which can be paid by card or ACH bank transfer. The link can optionally be emailed directly, for example to forward to a finance team.
**Notes.**
- For an invoice Brix issued, email is ignored and emailed is always false.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Invoice id from the list. |
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
ttlDays | number | no | Link lifetime in days, 1–180 (clamped). Default 30. |
email | string | no | Also email the link to this address (card subscription invoices only). |
curl -X POST "https://api.brixsignage.com/v1/account/invoices/{id}/pay-link" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.url | string | A web page where anyone with the link can see and pay the invoice. |
data.emailed | boolean |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 Not an invoice of this workspace.
| 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/account/invoices/{id}/pdf
Returns a short-lived download URL for one invoice's PDF. Brix confirms the invoice belongs to the calling workspace before returning the link.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Invoice id (a card subscription invoice). |
inline | query | string | no | Any value: the link opens in the browser instead of downloading. |
curl "https://api.brixsignage.com/v1/account/invoices/{id}/pdf" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.url | string | A short-lived download link. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 Not an invoice of this workspace (invoices Brix issued have no link here; use `/file`).
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/invoices/pay-all-link
Creates one shareable link that lets whoever receives it pay all of the workspace's outstanding invoices at once.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
ttlDays | number | no | Link lifetime in days, 1–180 (clamped). Default 30. |
curl -X POST "https://api.brixsignage.com/v1/account/invoices/pay-all-link" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.url | string | One web page that lists and pays every open invoice. |
data.ttlDays | 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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `billing_not_configured`.
| 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/account/invoices/pay-links-outstanding
Creates a separate hosted payment link for every invoice currently outstanding on the workspace. **Notes.** - Covers the card subscription's invoices only, not invoices Brix issued.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
ttlDays | number | no | Link lifetime in days, 1–180 (clamped). Default 30. |
curl -X POST "https://api.brixsignage.com/v1/account/invoices/pay-links-outstanding" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.links | array of object | |
data.links[].invoiceId | string | |
data.links[].number | string | |
data.links[].amountDue | number | |
data.links[].currencyCode | string | |
data.links[].url | string | |
data.ttlDays | 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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `billing_not_configured`.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/limits
Returns the workspace's API usage limits: the number of requests allowed per minute, the time window, and confirmation that the limit is counted per workspace across all API keys rather than per key. Also returns the RateLimit-* response headers to expect, and the delivery, retry, and retention behavior for webhooks. Use this before building an integration to size your request rate correctly.
curl "https://api.brixsignage.com/v1/account/limits" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.api | object | |
data.api.perMinute | integer | |
data.api.windowSeconds | integer | |
data.api.scope | string | `workspace`: all keys of the workspace share one budget. |
data.api.appliesTo | string | |
data.api.headers | array of string | |
data.api.onBreach | string | |
data.webhooks | object | |
data.webhooks.maxConsecutiveFailures | integer | |
data.webhooks.deliveryLogRetentionDays | integer | |
data.webhooks.delivery | string | |
data.webhooks.retry | string |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/me-prefs
Returns preferences in three layers: workspace (the shared defaults), user (only the values the calling user has changed; empty for an API key), and effective (the merged result to use for display).
**Notes.**
- user is returned as saved: the per-user write does not check its keys or values.
curl "https://api.brixsignage.com/v1/account/me-prefs" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.workspace | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). |
data.workspace.timeFormat | "12h" | "24h" | |
data.workspace.weekStart | "mon" | "sun" | |
data.workspace.dateFormat | "mdy" | "dmy" | "ymd" | |
data.workspace.tempUnits | "f" | "c" | |
data.workspace.timeZone | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. |
data.workspace.language | string | BCP 47 language tag. |
data.workspace.multinational | boolean | Shows the per-location and per-screen language settings. |
data.workspace.navExtras | array of string | Console pages switched on that the workspace size hides by default. |
data.workspace.appBranding | object | The look of the on-screen apps. |
data.workspace.appBranding.accent | string | |
data.workspace.appBranding.accent2 | string | |
data.workspace.appBranding.theme | "dark" | "light" | |
data.workspace.appBranding.backdrop | "brand" | "wash" | "plain" | "aurora" | "dots" | "grid" | "solid" | |
data.workspace.appBranding.intensity | number | |
data.workspace.audio | object | Default screen volume and a master mute. |
data.workspace.audio.volume | number | 0–100. |
data.workspace.audio.muted | boolean | |
data.workspace.brand | object | |
data.workspace.brand.companyName | string | |
data.workspace.brand.logoUrl | string | |
data.workspace.requireAltText | boolean | |
data.workspace.showScreenLogo | boolean | |
data.workspace.standbyContentKind | string | null | What a screen with nothing to play shows; null = the default card. |
data.workspace.standbyContentId | string | null | |
data.workspace.tier | "simple" | "team" | "enterprise" | Workspace size. It sets console defaults, not access. |
data.workspace.industry | string | null | |
data.workspace.onboardingCompletedAt | string | null | |
data.workspace.setupStep | string | null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). |
data.workspace.orgNameSet | boolean | |
data.workspace.tiers | array of integer | Location tree levels in use. |
data.workspace.tierLabels | object | Custom names for the location tree levels. |
data.workspace.requireTwoFactor | boolean | |
data.workspace.requireSso | boolean | |
data.workspace.requireSsoPending | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. |
data.workspace.requireSsoPendingSince | string | null | |
data.workspace.ai | object | |
data.workspace.ai.enabled | boolean | |
data.workspace.ai.features | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. |
data.workspace.ai.dailyCallLimit | integer | null | |
data.workspace.ai.redactPersonalData | boolean | |
data.workspace.retention | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
data.workspace.retention.offline | number | |
data.workspace.retention.screenshots | number | |
data.workspace.retention.playback | number | |
data.workspace.retention.deviceLogs | number | |
data.workspace.retention.vitals | number | |
data.workspace.retention.replays | number | |
data.workspace.retention.aiEvents | number | |
data.workspace.warehouse | object | Data warehouse feed. Set by Brix; not writable here. |
data.workspace.warehouse.enabled | boolean | |
data.workspace.warehouse.bucketBinding | string | Set by Brix when the data warehouse feed is provisioned. |
data.workspace.warehouse.tables | array of string | |
data.workspace.warehouse.lookbackDays | integer | |
data.workspace.supportAccess | SupportAccessPolicy | |
data.workspace.supportAccess.mode | "open" | "notify" | "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
data.workspace.supportAccess.grantMinutes | integer | How long an approval lasts. |
data.workspace.supportAccess.requestTtlMinutes | integer | How long a request waits for an answer before it expires. |
data.workspace.kioskHasGlobalPin | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. |
data.user | object | The calling user's own overrides, as saved. Empty for an API key. |
data.effective | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). |
data.effective.timeFormat | "12h" | "24h" | |
data.effective.weekStart | "mon" | "sun" | |
data.effective.dateFormat | "mdy" | "dmy" | "ymd" | |
data.effective.tempUnits | "f" | "c" | |
data.effective.timeZone | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. |
data.effective.language | string | BCP 47 language tag. |
data.effective.multinational | boolean | Shows the per-location and per-screen language settings. |
data.effective.navExtras | array of string | Console pages switched on that the workspace size hides by default. |
data.effective.appBranding | object | The look of the on-screen apps. |
data.effective.appBranding.accent | string | |
data.effective.appBranding.accent2 | string | |
data.effective.appBranding.theme | "dark" | "light" | |
data.effective.appBranding.backdrop | "brand" | "wash" | "plain" | "aurora" | "dots" | "grid" | "solid" | |
data.effective.appBranding.intensity | number | |
data.effective.audio | object | Default screen volume and a master mute. |
data.effective.audio.volume | number | 0–100. |
data.effective.audio.muted | boolean | |
data.effective.brand | object | |
data.effective.brand.companyName | string | |
data.effective.brand.logoUrl | string | |
data.effective.requireAltText | boolean | |
data.effective.showScreenLogo | boolean | |
data.effective.standbyContentKind | string | null | What a screen with nothing to play shows; null = the default card. |
data.effective.standbyContentId | string | null | |
data.effective.tier | "simple" | "team" | "enterprise" | Workspace size. It sets console defaults, not access. |
data.effective.industry | string | null | |
data.effective.onboardingCompletedAt | string | null | |
data.effective.setupStep | string | null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). |
data.effective.orgNameSet | boolean | |
data.effective.tiers | array of integer | Location tree levels in use. |
data.effective.tierLabels | object | Custom names for the location tree levels. |
data.effective.requireTwoFactor | boolean | |
data.effective.requireSso | boolean | |
data.effective.requireSsoPending | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. |
data.effective.requireSsoPendingSince | string | null | |
data.effective.ai | object | |
data.effective.ai.enabled | boolean | |
data.effective.ai.features | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. |
data.effective.ai.dailyCallLimit | integer | null | |
data.effective.ai.redactPersonalData | boolean | |
data.effective.retention | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
data.effective.retention.offline | number | |
data.effective.retention.screenshots | number | |
data.effective.retention.playback | number | |
data.effective.retention.deviceLogs | number | |
data.effective.retention.vitals | number | |
data.effective.retention.replays | number | |
data.effective.retention.aiEvents | number | |
data.effective.warehouse | object | Data warehouse feed. Set by Brix; not writable here. |
data.effective.warehouse.enabled | boolean | |
data.effective.warehouse.bucketBinding | string | Set by Brix when the data warehouse feed is provisioned. |
data.effective.warehouse.tables | array of string | |
data.effective.warehouse.lookbackDays | integer | |
data.effective.supportAccess | SupportAccessPolicy | |
data.effective.supportAccess.mode | "open" | "notify" | "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
data.effective.supportAccess.grantMinutes | integer | How long an approval lasts. |
data.effective.supportAccess.requestTtlMinutes | integer | How long a request waits for an answer before it expires. |
data.effective.kioskHasGlobalPin | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. |
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. |
POST/v1/account/onboarding
Finishes workspace onboarding in a single call: renames the workspace to the given name, records the industry and complexity tier, marks onboarding as complete, and seeds a starter set of ready-to-play content tailored to the chosen industry. Combining these into one call ensures the completion flag and the seeded content are never out of sync.
**Notes.**
- Every call adds the starter content again; it is not idempotent.
- tier is stored as sent without a check.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
workspaceName | string | no | Renames the workspace and sets the brand company name (cut at 120). |
industry | string | null | no | Industry id (`cafe`, `qsr`, `gym`, …); picks the starter designs. |
tier | "simple" | "team" | "enterprise" | no | |
setupStep | string | no | Walkthrough position to save with the answers. |
curl -X POST "https://api.brixsignage.com/v1/account/onboarding" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.prefs | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). |
data.prefs.timeFormat | "12h" | "24h" | |
data.prefs.weekStart | "mon" | "sun" | |
data.prefs.dateFormat | "mdy" | "dmy" | "ymd" | |
data.prefs.tempUnits | "f" | "c" | |
data.prefs.timeZone | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. |
data.prefs.language | string | BCP 47 language tag. |
data.prefs.multinational | boolean | Shows the per-location and per-screen language settings. |
data.prefs.navExtras | array of string | Console pages switched on that the workspace size hides by default. |
data.prefs.appBranding | object | The look of the on-screen apps. |
data.prefs.appBranding.accent | string | |
data.prefs.appBranding.accent2 | string | |
data.prefs.appBranding.theme | "dark" | "light" | |
data.prefs.appBranding.backdrop | "brand" | "wash" | "plain" | "aurora" | "dots" | "grid" | "solid" | |
data.prefs.appBranding.intensity | number | |
data.prefs.audio | object | Default screen volume and a master mute. |
data.prefs.audio.volume | number | 0–100. |
data.prefs.audio.muted | boolean | |
data.prefs.brand | object | |
data.prefs.brand.companyName | string | |
data.prefs.brand.logoUrl | string | |
data.prefs.requireAltText | boolean | |
data.prefs.showScreenLogo | boolean | |
data.prefs.standbyContentKind | string | null | What a screen with nothing to play shows; null = the default card. |
data.prefs.standbyContentId | string | null | |
data.prefs.tier | "simple" | "team" | "enterprise" | Workspace size. It sets console defaults, not access. |
data.prefs.industry | string | null | |
data.prefs.onboardingCompletedAt | string | null | |
data.prefs.setupStep | string | null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). |
data.prefs.orgNameSet | boolean | |
data.prefs.tiers | array of integer | Location tree levels in use. |
data.prefs.tierLabels | object | Custom names for the location tree levels. |
data.prefs.requireTwoFactor | boolean | |
data.prefs.requireSso | boolean | |
data.prefs.requireSsoPending | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. |
data.prefs.requireSsoPendingSince | string | null | |
data.prefs.ai | object | |
data.prefs.ai.enabled | boolean | |
data.prefs.ai.features | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. |
data.prefs.ai.dailyCallLimit | integer | null | |
data.prefs.ai.redactPersonalData | boolean | |
data.prefs.retention | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
data.prefs.retention.offline | number | |
data.prefs.retention.screenshots | number | |
data.prefs.retention.playback | number | |
data.prefs.retention.deviceLogs | number | |
data.prefs.retention.vitals | number | |
data.prefs.retention.replays | number | |
data.prefs.retention.aiEvents | number | |
data.prefs.warehouse | object | Data warehouse feed. Set by Brix; not writable here. |
data.prefs.warehouse.enabled | boolean | |
data.prefs.warehouse.bucketBinding | string | Set by Brix when the data warehouse feed is provisioned. |
data.prefs.warehouse.tables | array of string | |
data.prefs.warehouse.lookbackDays | integer | |
data.prefs.supportAccess | SupportAccessPolicy | |
data.prefs.supportAccess.mode | "open" | "notify" | "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
data.prefs.supportAccess.grantMinutes | integer | How long an approval lasts. |
data.prefs.supportAccess.requestTtlMinutes | integer | How long a request waits for an answer before it expires. |
data.prefs.kioskHasGlobalPin | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. |
data.seeded | array of object | Starter designs added. |
data.seeded[].id | string | |
data.seeded[].name | string | |
data.library | integer | Starter library items added (photos, a playlist, a schedule, …). 0 when that step failed. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 422 Unknown `industry`.
| 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/account/payment-card
Removes the workspace's saved card. If the payment option was set to card, it reverts to invoice billing.
**Notes.**
- When the payment option was card, it goes back to invoice.
curl -X DELETE "https://api.brixsignage.com/v1/account/payment-card" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.removed | boolean | |
data.payment | AccountPayment | Payment settings of an account that Brix invoices directly. |
data.payment.option | "card" | "invoice" | How issued invoices are paid: charged to the saved card, or paid from the invoice email. |
data.payment.card | object | null | |
data.payment.lastPaid | object | null | The card the last invoice was paid with. |
data.payment.cardAvailable | boolean | Card payment can be set up for this workspace. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 A workspace billed by a partner.
| 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 409 `not_brix_billed`.
| 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/account/payment-card/complete
Saves the card from a finished hosted card-setup session, given its sessionId. Brix re-reads the session from the payment provider and confirms it belongs to the calling workspace, returning 404 otherwise. The same result also happens automatically when the payment provider notifies Brix that the session completed.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
sessionId | string | yes | The `card_session` value from the return URL (`cs_…`). |
curl -X POST "https://api.brixsignage.com/v1/account/payment-card/complete" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.outcome | "saved" | "already_saved" | "incomplete" | |
data.payment | AccountPayment | Payment settings of an account that Brix invoices directly. |
data.payment.option | "card" | "invoice" | How issued invoices are paid: charged to the saved card, or paid from the invoice email. |
data.payment.card | object | null | |
data.payment.lastPaid | object | null | The card the last invoice was paid with. |
data.payment.cardAvailable | boolean | Card payment can be set up for this workspace. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 Not a card session of this workspace.
| 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 409 `not_brix_billed`.
| 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 422 `sessionId` missing or malformed.
| 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 502 The session could not be read.
| 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/account/payment-card/setup
Starts adding or replacing the saved card for a workspace billed directly by Brix. Returns a hosted checkout URL where the card is entered, unless useLastPaid: true is passed and the payment provider already holds a card that was last used to pay this workspace, in which case that card is saved directly. Returns 409 if the workspace is not billed directly by Brix, and 404 for white-label workspaces.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
useLastPaid | boolean | no | Save the card the last invoice was paid with, when that is possible, instead of opening a page. |
curl -X POST "https://api.brixsignage.com/v1/account/payment-card/setup" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | object |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 A workspace billed by a partner.
| 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 409 `not_brix_billed`, or `card_unavailable`.
| 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 502 The card page could not be opened.
| 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/account/payment-methods
Returns the workspace's saved payment methods, including cards and ACH bank accounts. When there are two or more methods and none is the backup, one method that is not the primary is made the backup. **Notes.** - A read that can write: with two or more methods and no backup, the handler makes one non-primary method the backup and records it in the audit log.
curl "https://api.brixsignage.com/v1/account/payment-methods" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.configured | boolean | False when billing is not set up (or could not be read, see `reason`). |
data.sources | array of object | |
data.sources[].id | string | |
data.sources[].type | string | `card`, `bank_account`, or a wallet type (`apple_pay`, `paypal_express_checkout`, …). |
data.sources[].brand | string | null | |
data.sources[].last4 | string | null | |
data.sources[].walletType | string | null | |
data.sources[].gateway | string | null | |
data.sources[].expiryMonth | integer | null | |
data.sources[].expiryYear | integer | null | |
data.sources[].status | string | |
data.sources[].primary | boolean | |
data.sources[].backup | boolean | Charged when the primary fails. |
data.reason | string |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/payment-methods/{id}/role
Sets a saved payment method as the primary or backup method for the workspace.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | Payment method id from the list. |
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
role | "primary" | "backup" | yes |
curl -X POST "https://api.brixsignage.com/v1/account/payment-methods/{id}/role" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.ok | true | |
data.id | string | |
data.role | "primary" | "backup" |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 Not one of this workspace's payment methods.
| 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 409 `billing_not_configured`.
| 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 422 Bad `role`.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/payment-methods/manage-url
Returns a hosted page URL where the workspace can add, replace, or remove a saved card or bank account.
curl -X POST "https://api.brixsignage.com/v1/account/payment-methods/manage-url" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.url | string | A hosted page to add, replace or remove a card or bank account. Open it in a browser. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `billing_not_configured`.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/payment-option
Sets how a workspace billed directly by Brix pays: card or invoice. Choosing card requires a saved card and returns 409 if none exists; every invoice Brix issues is then charged to that card automatically. Returns 409 if the workspace is billed through the billing provider instead, and 404 for white-label workspaces.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
option | "card" | "invoice" | yes |
curl -X PATCH "https://api.brixsignage.com/v1/account/payment-option" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.changed | boolean | |
data.payment | AccountPayment | Payment settings of an account that Brix invoices directly. |
data.payment.option | "card" | "invoice" | How issued invoices are paid: charged to the saved card, or paid from the invoice email. |
data.payment.card | object | null | |
data.payment.lastPaid | object | null | The card the last invoice was paid with. |
data.payment.cardAvailable | boolean | Card payment can be set up for this workspace. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 404 A workspace billed by a partner.
| 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 409 `not_brix_billed`, or `card_required` (save a card first).
| 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 422 Bad `option`.
| 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/account/prefs
Updates workspace-level preferences such as locale, time zone, date and number formats, brand kit, and plan tier. Any field you include is overwritten; fields you omit keep their current value.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
kioskPin | string | null | no | Set (4–8 digits) or clear (null) the workspace Screen Lock PIN. Stored as a hash. |
requireSso | boolean | no | Needs a working single sign-on connection with verified domains; until someone signs in through it, the request is held (`requireSsoPending`). |
requireTwoFactor | boolean | no | Turning it on needs the calling user to have two-factor sign-in set up, so an API key cannot turn it on. |
curl -X PATCH "https://api.brixsignage.com/v1/account/prefs" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"timeFormat":"24h","timeZone":"America/Chicago"}' Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | WorkspacePrefs | Workspace preferences. Every key is present (defaults filled in). |
data.timeFormat | "12h" | "24h" | |
data.weekStart | "mon" | "sun" | |
data.dateFormat | "mdy" | "dmy" | "ymd" | |
data.tempUnits | "f" | "c" | |
data.timeZone | string | IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace. |
data.language | string | BCP 47 language tag. |
data.multinational | boolean | Shows the per-location and per-screen language settings. |
data.navExtras | array of string | Console pages switched on that the workspace size hides by default. |
data.appBranding | object | The look of the on-screen apps. |
data.appBranding.accent | string | |
data.appBranding.accent2 | string | |
data.appBranding.theme | "dark" | "light" | |
data.appBranding.backdrop | "brand" | "wash" | "plain" | "aurora" | "dots" | "grid" | "solid" | |
data.appBranding.intensity | number | |
data.audio | object | Default screen volume and a master mute. |
data.audio.volume | number | 0–100. |
data.audio.muted | boolean | |
data.brand | object | |
data.brand.companyName | string | |
data.brand.logoUrl | string | |
data.requireAltText | boolean | |
data.showScreenLogo | boolean | |
data.standbyContentKind | string | null | What a screen with nothing to play shows; null = the default card. |
data.standbyContentId | string | null | |
data.tier | "simple" | "team" | "enterprise" | Workspace size. It sets console defaults, not access. |
data.industry | string | null | |
data.onboardingCompletedAt | string | null | |
data.setupStep | string | null | Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`). |
data.orgNameSet | boolean | |
data.tiers | array of integer | Location tree levels in use. |
data.tierLabels | object | Custom names for the location tree levels. |
data.requireTwoFactor | boolean | |
data.requireSso | boolean | |
data.requireSsoPending | boolean | Single sign-on was required, and turns on after the first sign-in through the connection. |
data.requireSsoPendingSince | string | null | |
data.ai | object | |
data.ai.enabled | boolean | |
data.ai.features | object | Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`. |
data.ai.dailyCallLimit | integer | null | |
data.ai.redactPersonalData | boolean | |
data.retention | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
data.retention.offline | number | |
data.retention.screenshots | number | |
data.retention.playback | number | |
data.retention.deviceLogs | number | |
data.retention.vitals | number | |
data.retention.replays | number | |
data.retention.aiEvents | number | |
data.warehouse | object | Data warehouse feed. Set by Brix; not writable here. |
data.warehouse.enabled | boolean | |
data.warehouse.bucketBinding | string | Set by Brix when the data warehouse feed is provisioned. |
data.warehouse.tables | array of string | |
data.warehouse.lookbackDays | integer | |
data.supportAccess | SupportAccessPolicy | |
data.supportAccess.mode | "open" | "notify" | "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
data.supportAccess.grantMinutes | integer | How long an approval lasts. |
data.supportAccess.requestTtlMinutes | integer | How long a request waits for an answer before it expires. |
data.kioskHasGlobalPin | boolean | A workspace Screen Lock PIN is set. The PIN and its hash are never returned. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 422 `sso_not_configured`, `two_factor_not_enrolled`, or a PIN that is not 4–8 digits.
| 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/account/reactivate
Reverses a scheduled cancellation, or resumes an account that was paused for seasonal closure.
curl -X POST "https://api.brixsignage.com/v1/account/reactivate" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.status | "active" |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `already_active`, `pending_deletion`, `payment_required`, `payment_method_required`, `not_reactivatable`, or `under_contract`.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/retention
Returns the workspace's data retention schedule: every data stream that can be governed, the retention window currently in effect for it, and the allowed range for that window.
curl "https://api.brixsignage.com/v1/account/retention" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | RetentionSchedule | |
data.policy | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
data.policy.offline | number | |
data.policy.screenshots | number | |
data.policy.playback | number | |
data.policy.deviceLogs | number | |
data.policy.vitals | number | |
data.policy.replays | number | |
data.policy.aiEvents | number | |
data.effective | object | Days kept per stream now. |
data.effective.offline | integer | |
data.effective.screenshots | integer | |
data.effective.playback | integer | |
data.effective.deviceLogs | integer | |
data.effective.vitals | integer | |
data.effective.replays | integer | |
data.effective.aiEvents | integer | |
data.bounds | object | |
data.bounds.offline | object | |
data.bounds.offline.min | integer | |
data.bounds.offline.max | integer | |
data.bounds.offline.platformDefault | integer | |
data.bounds.offline.label | string | |
data.bounds.offline.what | string | |
data.bounds.screenshots | object | |
data.bounds.screenshots.min | integer | |
data.bounds.screenshots.max | integer | |
data.bounds.screenshots.platformDefault | integer | |
data.bounds.screenshots.label | string | |
data.bounds.screenshots.what | string | |
data.bounds.playback | object | |
data.bounds.playback.min | integer | |
data.bounds.playback.max | integer | |
data.bounds.playback.platformDefault | integer | |
data.bounds.playback.label | string | |
data.bounds.playback.what | string | |
data.bounds.deviceLogs | object | |
data.bounds.deviceLogs.min | integer | |
data.bounds.deviceLogs.max | integer | |
data.bounds.deviceLogs.platformDefault | integer | |
data.bounds.deviceLogs.label | string | |
data.bounds.deviceLogs.what | string | |
data.bounds.vitals | object | |
data.bounds.vitals.min | integer | |
data.bounds.vitals.max | integer | |
data.bounds.vitals.platformDefault | integer | |
data.bounds.vitals.label | string | |
data.bounds.vitals.what | string | |
data.bounds.replays | object | |
data.bounds.replays.min | integer | |
data.bounds.replays.max | integer | |
data.bounds.replays.platformDefault | integer | |
data.bounds.replays.label | string | |
data.bounds.replays.what | string | |
data.bounds.aiEvents | object | |
data.bounds.aiEvents.min | integer | |
data.bounds.aiEvents.max | integer | |
data.bounds.aiEvents.platformDefault | integer | |
data.bounds.aiEvents.label | string | |
data.bounds.aiEvents.what | string |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/retention
Sets the retention window, in days, for one or more data streams. Sending null for a stream resets it to the platform default. Values are clamped to the allowed range for each stream.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
offline | number | null | no | |
screenshots | number | null | no | |
playback | number | null | no | |
deviceLogs | number | null | no | |
vitals | number | null | no | |
replays | number | null | no | |
aiEvents | number | null | no |
curl -X PATCH "https://api.brixsignage.com/v1/account/retention" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | RetentionSchedule | |
data.policy | object | Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window. |
data.policy.offline | number | |
data.policy.screenshots | number | |
data.policy.playback | number | |
data.policy.deviceLogs | number | |
data.policy.vitals | number | |
data.policy.replays | number | |
data.policy.aiEvents | number | |
data.effective | object | Days kept per stream now. |
data.effective.offline | integer | |
data.effective.screenshots | integer | |
data.effective.playback | integer | |
data.effective.deviceLogs | integer | |
data.effective.vitals | integer | |
data.effective.replays | integer | |
data.effective.aiEvents | integer | |
data.bounds | object | |
data.bounds.offline | object | |
data.bounds.offline.min | integer | |
data.bounds.offline.max | integer | |
data.bounds.offline.platformDefault | integer | |
data.bounds.offline.label | string | |
data.bounds.offline.what | string | |
data.bounds.screenshots | object | |
data.bounds.screenshots.min | integer | |
data.bounds.screenshots.max | integer | |
data.bounds.screenshots.platformDefault | integer | |
data.bounds.screenshots.label | string | |
data.bounds.screenshots.what | string | |
data.bounds.playback | object | |
data.bounds.playback.min | integer | |
data.bounds.playback.max | integer | |
data.bounds.playback.platformDefault | integer | |
data.bounds.playback.label | string | |
data.bounds.playback.what | string | |
data.bounds.deviceLogs | object | |
data.bounds.deviceLogs.min | integer | |
data.bounds.deviceLogs.max | integer | |
data.bounds.deviceLogs.platformDefault | integer | |
data.bounds.deviceLogs.label | string | |
data.bounds.deviceLogs.what | string | |
data.bounds.vitals | object | |
data.bounds.vitals.min | integer | |
data.bounds.vitals.max | integer | |
data.bounds.vitals.platformDefault | integer | |
data.bounds.vitals.label | string | |
data.bounds.vitals.what | string | |
data.bounds.replays | object | |
data.bounds.replays.min | integer | |
data.bounds.replays.max | integer | |
data.bounds.replays.platformDefault | integer | |
data.bounds.replays.label | string | |
data.bounds.replays.what | string | |
data.bounds.aiEvents | object | |
data.bounds.aiEvents.min | integer | |
data.bounds.aiEvents.max | integer | |
data.bounds.aiEvents.platformDefault | integer | |
data.bounds.aiEvents.label | string | |
data.bounds.aiEvents.what | string |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/screen-pool
Sets how many screens the workspace pays for. An increase is charged now, prorated, to the payment method on file (a very small amount is added to the renewal instead). A reduction on a paid plan takes effect at the renewal and is not refunded; during the free trial a change takes effect at once. You cannot set the plan below the number of screens that are running.
**Notes.**
- An increase is charged now (prorated). A reduction on a paid plan is queued for the renewal and answers scheduled: true; in the trial it changes at once.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
quantity | integer | yes |
curl -X POST "https://api.brixsignage.com/v1/account/screen-pool" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | object |
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 402 `card_declined` or `payment_incomplete`: the plan did not change (or needs our team).
| 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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `screens_in_use` (below the screens running), `no_subscription`, `account_cancelled`, or `under_contract`.
| 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 422 `quantity` is not a whole number from 1 to 10000.
| 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 502 The change could not be made.
| 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/account/screen-pool/estimate
Returns the prorated cost of changing the screen pool before committing to it, including the exact amount that would be charged today and which card would be used. This is read-only and does not change anything; it uses POST rather than GET because the requested quantity must never be cached. **Notes.** - A POST because it takes an argument; it changes nothing.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
quantity | integer | yes |
curl -X POST "https://api.brixsignage.com/v1/account/screen-pool/estimate" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.lines | array of object | Line items of the invoice raised today. |
data.lines[].description | string | |
data.lines[].amount | number | |
data.creditsApplied | number | Credit for the unused part of the current term. |
data.subTotal | number | |
data.amountDueNow | number | Charged now, after credits (currency units, not cents). |
data.currencyCode | string | |
data.nextBillingAt | string | null | |
data.payWith | string | null | The payment method that is charged (`Visa •••• 4242`). |
data.currentQuantity | integer | |
data.newQuantity | integer | |
data.renewalAmount | number | null | What each term costs after the change. |
data.chargedToday | boolean | False when the amount is too small to charge today (it is added to the renewal). |
data.invoiced | boolean | The account pays by invoice; nothing is charged to a card. |
data.decreaseRequiresSupport | false | Always false. Kept for older clients. |
data.scheduledAtRenewal | boolean | A reduction on a paid plan: it takes effect at `renewsAt`. |
data.renewsAt | string | null | |
data.inTrial | boolean | |
data.trialEndsAt | string | null | |
data.minQuantity | integer | The lowest allowed quantity: the screens running now (at least 1). |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `no_subscription`, `account_cancelled`, or `under_contract`.
| 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 422 `quantity` is not a whole number from 1 to 10000.
| 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 502 `estimate_unavailable`.
| 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/account/screen-pool/scheduled
Cancels a screen-pool reduction that is queued to take effect at renewal, keeping the current plan instead. Calling this when nothing is scheduled has no effect. **Notes.** - Succeeds when nothing is queued too.
curl -X DELETE "https://api.brixsignage.com/v1/account/screen-pool/scheduled" \
-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.
| 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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `no_subscription`, `account_cancelled`, or `under_contract`.
| 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 502 The billing provider did not answer; nothing changed.
| 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/account/support-access
Returns the workspace's current Brix support access policy (always allowed, allowed with notification, or approval required), every access request Brix support has raised along with its decision, and every support session opened on the workspace, with any still in progress marked as live.
**Notes.**
- A read that can write: pending requests past their expiry are marked expired first.
curl "https://api.brixsignage.com/v1/account/support-access" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.policy | SupportAccessPolicy | |
data.policy.mode | "open" | "notify" | "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
data.policy.grantMinutes | integer | How long an approval lasts. |
data.policy.requestTtlMinutes | integer | How long a request waits for an answer before it expires. |
data.modes | array of object | |
data.modes[].id | "open" | "notify" | "approve" | |
data.modes[].label | string | |
data.modes[].what | string | |
data.requests | array of object | Newest 100. |
data.requests[].id | string | |
data.requests[].staffEmail | string | The Brix support person who asked. |
data.requests[].reason | string | |
data.requests[].reasonCategory | string | null | |
data.requests[].status | "pending" | "approved" | "denied" | "expired" | "revoked" | |
data.requests[].requestedAt | string | ISO-8601 timestamp (UTC). |
data.requests[].requestExpiresAt | string | ISO-8601 timestamp (UTC). |
data.requests[].decidedAt | string | null | |
data.requests[].decidedByEmail | string | null | |
data.requests[].decidedByName | string | null | |
data.requests[].grantExpiresAt | string | null | |
data.requests[].decisionNote | string | null | |
data.requests[].grantLive | boolean | |
data.sessions | array of object | Times Brix support opened the workspace, newest 100. |
data.sessions[].id | string | |
data.sessions[].staffEmail | string | |
data.sessions[].reason | string | |
data.sessions[].startedAt | string | ISO-8601 timestamp (UTC). |
data.sessions[].endedAt | string | null | |
data.sessions[].expiresAt | string | null | |
data.sessions[].live | boolean | |
data.sessions[].recorded | boolean | The session was screen-recorded. |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/support-access/policy
Sets whether Brix support may open the workspace: always allowed and recorded, allowed but the workspace is notified as it happens, or only with explicit approval for each request.
Request body application/json
| Field | Type | Required | Description |
|---|---|---|---|
mode | "open" | "notify" | "approve" | no | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
grantMinutes | integer | no | How long an approval lasts. |
requestTtlMinutes | integer | no | How long a request waits for an answer before it expires. |
curl -X PATCH "https://api.brixsignage.com/v1/account/support-access/policy" \
-H "Authorization: Bearer $BRIX_API_KEY" \
-H "Content-Type: application/json" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | SupportAccessPolicy | |
data.mode | "open" | "notify" | "approve" | `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request. |
data.grantMinutes | integer | How long an approval lasts. |
data.requestTtlMinutes | integer | How long a request waits for an answer before it expires. |
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 A Brix support session cannot change this. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/support-access/revoke
Immediately withdraws consent for Brix support access: ends every live support session and cancels any outstanding approval, in that order.
curl -X POST "https://api.brixsignage.com/v1/account/support-access/revoke" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.sessionsEnded | integer | |
data.grantsRevoked | 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 A Brix support session cannot do this. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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/account/upgrade-annual
Switches the workspace's monthly subscription to annual, upfront billing. Returns 409 if the workspace is already on annual billing or has no active subscription.
curl -X POST "https://api.brixsignage.com/v1/account/upgrade-annual" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.cadence | "annual" |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `no_subscription`, `under_contract`, or `already_annual`.
| 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 502 The switch failed.
| 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 503 `annual_switch_unavailable`: the switch is not self-serve yet; contact 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. |
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/account/upgrade-annual/estimate
Returns the prorated cost of switching from monthly to annual billing before committing to it, including which card would be charged.
curl "https://api.brixsignage.com/v1/account/upgrade-annual/estimate" \
-H "Authorization: Bearer $BRIX_API_KEY" Response 200 Success.
| Field | Type | Description |
|---|---|---|
data | object | |
data.lines | array of object | Line items of the invoice raised today. |
data.lines[].description | string | |
data.lines[].amount | number | |
data.creditsApplied | number | Credit for the unused part of the current term. |
data.subTotal | number | |
data.amountDueNow | number | Charged now, after credits (currency units, not cents). |
data.currencyCode | string | |
data.nextBillingAt | string | null | |
data.payWith | string | null | The payment method that is charged (`Visa •••• 4242`). |
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 You do not hold the permission for the whole workspace (a grant at one location is not enough).
| 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 409 `no_subscription` or `under_contract`.
| 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 502 `estimate_unavailable`.
| 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. |