{ "openapi": "3.1.0", "info": { "title": "Brix API", "version": "1", "summary": "Control plane for Brix digital signage: screens, content, playlists, schedules, casts and emergencies.", "description": "Generated from the route table the API actually mounts\n(`apps/api/routes.snapshot.json`), the description each route is required to\ncarry (`tests/contracts/route-registry.json`), and request/response schemas\n(`apps/api/src/openapi/`). CI enforces all three, so this document cannot list a\nroute that does not exist or omit one that does.\n\n**Schemas.** 337 operations carry request and response schemas\n(`x-brix-schema: verified`). Each is checked in CI against the response the\nreal handler returns — a missing, mistyped or undeclared field fails the build.\nThe remaining operations are route-level only (`x-brix-schema: none`): their\npath, method, permission and purpose are exact, but the shape of `data` is not\nyet modelled, and we would rather say so than publish a schema that validates\nagainst nothing. Objects are open: a new field is not a breaking change.\n\n**Envelope.** Success bodies are `{ \"data\": … }`. Failures are\n`{ \"error\": \"\", \"message\": \"…\" }`, plus `requestId` on a 5xx.\nMany list routes page opt-in (see each operation): pass `?limit=` and\nfollow `nextCursor` via `?cursor=` until it is null.\n\n**Authentication.** `Authorization: Bearer ` with an API key\n(`ak_…`, created in the console under Settings → API & MCP) or a user session. An\nAPI key carries a creator-chosen set of `resource.verb` permissions and may be\npinned to one location's subtree; a key can never be granted a permission its\ncreator does not hold. The permission an operation needs is in\n`x-brix-permission` and in its security requirement.\n\n**Tenancy.** Every request resolves to one workspace. A resource belonging to\nanother tenant returns 404, never 403, so a response never confirms that an\naccount exists.\n\n**Rate limits.** A 429 carries `Retry-After`; a 503 `database_busy` means retry\nafter the `Retry-After` interval." }, "servers": [ { "url": "https://api.brixsignage.com", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, …" }, "message": { "description": "Human-readable explanation. Safe to show an operator.", "type": "string" }, "requestId": { "description": "Present on 5xx: quote it to support.", "type": "string" } }, "required": [ "error" ], "additionalProperties": {}, "description": "Error envelope returned by every failing request." }, "Account": { "type": "object", "properties": { "scheduledScreenPool": { "anyOf": [ { "type": "object", "properties": { "quantity": { "type": "integer" }, "effectiveAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "quantity", "effectiveAt" ] }, { "type": "null" } ], "description": "A screen plan reduction queued for the renewal." }, "contract": { "anyOf": [ { "$ref": "#/components/schemas/BillingTerm" }, { "type": "null" } ] }, "id": { "type": "string", "description": "Workspace id (the account id support asks for)." }, "whiteLabel": { "type": "boolean", "description": "A partner bills this workspace; Brix billing does not apply." }, "status": { "type": "string", "enum": [ "active", "cancel_scheduled", "paused", "past_due", "suspended", "cancelled" ] }, "pauseUntil": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "cancelEffectiveAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string", "enum": [ "provider", "trial_expired", "voluntary", "nonpayment" ] }, { "type": "null" } ] }, "everPaid": { "type": "boolean" }, "deletionRequestedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "billingBanner": { "anyOf": [ { "$ref": "#/components/schemas/BillingBanner" }, { "type": "null" } ] }, "survey": { "description": "The last cancellation survey (`{ reason, competitor, returnLikelihood, comment }`), or null." }, "prefs": { "$ref": "#/components/schemas/WorkspacePrefs" }, "region": { "type": "string", "enum": [ "us", "eu", "oc", "apac" ], "description": "Where the workspace's data is stored." }, "billingProvider": { "type": "string", "enum": [ "chargebee", "brix" ], "description": "`brix`: Brix invoices the account (see `payment`). `chargebee`: a card subscription." }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/AccountPayment" }, { "type": "null" } ], "description": "Only when `billingProvider` is `brix`." }, "subscriptionStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cadence": { "anyOf": [ { "type": "string", "enum": [ "monthly", "annual" ] }, { "type": "null" } ] }, "billableScreens": { "type": "integer", "description": "Screens that count toward the bill now." }, "licensedScreens": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Screens bought (the plan quantity or the term's screens)." }, "trialEndsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "nextBillingAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "currentTermEndsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "The calling user's; null for an API key." }, "verificationEmailLastSentAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The calling user's email; null for an API key." } }, "required": [ "scheduledScreenPool", "contract", "id", "whiteLabel", "status", "pauseUntil", "cancelEffectiveAt", "cancelReason", "everPaid", "deletionRequestedAt", "billingBanner", "survey", "prefs", "region", "billingProvider", "payment", "subscriptionStatus", "cadence", "billableScreens", "licensedScreens", "trialEndsAt", "nextBillingAt", "currentTermEndsAt", "emailVerifiedAt", "verificationEmailLastSentAt", "email" ] }, "AccountPayment": { "type": "object", "properties": { "option": { "type": "string", "enum": [ "card", "invoice" ], "description": "How issued invoices are paid: charged to the saved card, or paid from the invoice email." }, "card": { "anyOf": [ { "type": "object", "properties": { "brand": { "type": "string" }, "last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "savedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "brand", "last4", "expMonth", "expYear", "savedAt" ] }, { "type": "null" } ] }, "lastPaid": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string", "description": "`Visa •••• 5278`." }, "brand": { "type": "string" }, "last4": { "type": "string" }, "invoiceNumber": { "type": "string" }, "paidAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "label", "brand", "last4", "invoiceNumber", "paidAt" ] }, { "type": "null" } ], "description": "The card the last invoice was paid with." }, "cardAvailable": { "type": "boolean", "description": "Card payment can be set up for this workspace." } }, "required": [ "option", "card", "lastPaid", "cardAvailable" ], "description": "Payment settings of an account that Brix invoices directly." }, "Actor": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "key" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "API key id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The key's name." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location the key is pinned to; null = workspace-wide. A pinned key cannot see or create outside that subtree." } }, "required": [ "kind", "id", "name", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "user" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "type": "null" } }, "required": [ "kind", "id", "name", "email", "nodeId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "staff" }, "id": { "type": "string", "description": "`staff:` — Brix support opened the workspace as the customer." }, "name": { "type": "string", "const": "Brix staff" }, "email": { "type": "string" }, "nodeId": { "type": "null" } }, "required": [ "kind", "id", "name", "email", "nodeId" ] } ], "description": "The credential making the call: an API key, a user session, or Brix support." }, "AlertEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Alert event id." }, "code": { "type": "string", "description": "What fired, e.g. `connection-lost`, `display-off`, `storage-critical`." }, "severity": { "type": "string", "description": "`info`, `warning` or `critical`." }, "screenId": { "type": "string" }, "screenName": { "type": "string", "description": "`(unknown screen)` if the screen is gone." }, "message": { "type": "string" }, "nextAction": { "type": "string", "description": "Suggested next step; may be empty." }, "openedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "closedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Null while open." }, "detail": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {} }, { "type": "null" } ], "description": "Structured detail keyed by `kind` (`recovery`, `outage-history`, `network-unstable`, `display-off`), or null." } }, "required": [ "id", "code", "severity", "screenId", "screenName", "message", "nextAction", "openedAt", "closedAt", "detail" ], "description": "One firing of an alert rule against a screen." }, "AlertRule": { "type": "object", "properties": { "id": { "type": "string", "description": "Alert rule id.", "examples": [ "alr_4d5e6f7a8b9c0d1e" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "trigger": { "type": "string", "description": "The first trigger code, e.g. `connection-lost`." }, "config": { "$ref": "#/components/schemas/AlertRuleConfig" }, "enabled": { "type": "boolean" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace root." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "spaceId", "name", "trigger", "config", "enabled", "nodeId", "createdAt", "updatedAt", "deletedAt" ] }, "AlertRuleConfig": { "type": "object", "properties": { "codes": { "description": "Every trigger code the rule watches; the first is also `trigger`.", "type": "array", "items": { "type": "string" } }, "severity": { "type": "string" }, "scopeKind": { "description": "`workspace`, `org_unit`, `location`, `screen_group` or `screen`.", "type": "string" }, "scopeId": { "type": "string" }, "thresholds": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "channels": { "description": "`in-app`, `email`, `webhook`, `teams`.", "type": "array", "items": { "type": "string" } }, "recipients": { "description": "Email addresses, `role:` tokens and webhook URLs. Webhook URLs are Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it.", "type": "array", "items": { "type": "string" } }, "teamsUrls": { "description": "Microsoft Teams workflow URLs for the `teams` channel. Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": {}, "description": "The rule's trigger, scope and delivery settings. Other keys pass through unchanged." }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preview": { "type": "string", "description": "The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential." }, "permissions": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "`resource.action` permissions, or `\"all\"` (every permission, now and later)." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location the key is pinned to (it can act only there and below). Null = workspace-wide." }, "lastUsedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Null = never expires." }, "expired": { "type": "boolean" }, "revokedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set when the key was revoked; a revoked key no longer authenticates." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "name", "preview", "permissions", "nodeId", "lastUsedAt", "expiresAt", "expired", "revokedAt", "createdAt" ], "description": "An API key. The secret is never returned after creation or rotation." }, "AppInstance": { "type": "object", "properties": { "id": { "type": "string", "description": "App instance id.", "examples": [ "app_3c4d5e6f7a8b9c0d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "appKey": { "type": "string", "description": "The app type: a key from `GET /v1/apps/catalog` (`clock`, `weather`, `rss`, …)." }, "name": { "type": "string" }, "config": { "description": "The app's settings (JSON). The keys depend on `appKey`." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace root." }, "lastSnapshotKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Internal key of the last rendered thumbnail." }, "lastSnapshotAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id in the system it was imported from, if imported." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "appKey", "name", "config", "nodeId", "lastSnapshotKey", "lastSnapshotAt", "importSourceId", "createdAt", "updatedAt", "deletedAt" ], "description": "An installed, configured app." }, "ApprovalPolicy": { "type": "object", "properties": { "required": { "type": "boolean" }, "inheritFromParent": { "type": "boolean" }, "escalateUpTiers": { "type": "boolean" }, "allowSharedExemptions": { "type": "boolean" }, "approvers": { "description": "User ids named as approvers.", "type": "array", "items": { "type": "string" } } }, "additionalProperties": {}, "description": "The location's content-approval policy, as stored. New locations inherit `{required:false, inheritFromParent:true, …}`." }, "ApprovalRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Approval request id.", "examples": [ "ar_3c4d5e6f7a8b9c0d" ] }, "contentKind": { "type": "string", "description": "`playlist`, `schedule`, `creative`, `layout`, `creative-override`, `media`, `app`, …" }, "contentId": { "type": "string" }, "contentName": { "type": "string" }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "type": "string", "description": "The content's home location; empty string for the workspace root." }, "nodeName": { "type": "string" }, "requestedByName": { "type": "string" }, "requestedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "type": "array", "items": {}, "description": "What changed since the last approved version: `{kind, label, detail, thumbnailUrl?}` items for kinds the server diffs; for other kinds, whatever the requester sent." }, "state": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "requestedById": { "type": "string", "description": "User id, or `apikey:` for a key." }, "levels": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string" }, "nodeName": { "type": "string" }, "approverIds": { "type": "array", "items": { "type": "string" } }, "approverNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "nodeId", "nodeName", "approverIds", "approverNames" ] }, "description": "The approval chain, one entry per tier." }, "currentLevel": { "type": "integer", "description": "Index into `levels` awaiting a decision while pending." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer" }, "decidedById": { "type": "string" }, "decidedByName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "decidedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "level", "decidedById", "decidedByName", "decidedAt", "note" ] } }, "decidedByName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "decidedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "decisionNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "contentKind", "contentId", "contentName", "thumbnailUrl", "nodeId", "nodeName", "requestedByName", "requestedAt", "note", "changes", "state", "requestedById", "levels", "currentLevel", "decisions", "decidedByName", "decidedAt", "decisionNote" ], "description": "A request to approve content before it can air." }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "workspaceId": { "type": "string" }, "actor": { "type": "string", "description": "`user:`, `apikey:`, `system`, or another internal actor." }, "actorKind": { "type": "string", "enum": [ "user", "api-key", "system" ] }, "actorName": { "type": "string", "description": "The person's or key's name; `System` for the system." }, "actorEmail": { "type": "string", "description": "The person's email; `n/a` for a key; `system@brix` for the system." }, "action": { "type": "string", "description": "What happened, e.g. `screen.renamed`." }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The id of the thing acted on." }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location the event belongs to; null for the workspace." }, "nodeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "at", "workspaceId", "actor", "actorKind", "actorName", "actorEmail", "action", "target", "detail", "nodeId", "nodeName", "ipAddress", "userAgent" ], "description": "One activity log event, with the actor resolved to a name." }, "BillingBanner": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "warning", "critical" ] }, "status": { "type": "string", "enum": [ "past_due", "suspended", "trial_expired", "awaiting_payment", "invoice_dunning" ] }, "headline": { "type": "string" }, "body": { "type": "string" }, "payBy": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "action": { "type": "object", "properties": { "label": { "type": "string" }, "kind": { "type": "string", "const": "pay" } }, "required": [ "label", "kind" ] } }, "required": [ "severity", "status", "headline", "body", "payBy", "action" ] }, "BillingGroup": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "financeContactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "financeContactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where this group's invoices go." }, "chargebeeCustomerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The billing customer linked by Brix; null until linked." }, "chargebeeSubscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription linked by Brix; null until linked." }, "subscriptionStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Net payment terms in days; null = the workspace default." }, "screenCount": { "type": "integer", "description": "Screens billed to this group." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "name", "financeContactName", "financeContactEmail", "chargebeeCustomerId", "chargebeeSubscriptionId", "subscriptionStatus", "paymentTermsDays", "screenCount", "createdAt", "updatedAt" ], "description": "A group of screens billed separately (its own invoice and finance contact)." }, "BillingTerm": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "cancelled", "awaiting_payment", "ended" ] }, "rail": { "type": "string", "enum": [ "chargebee", "brix" ], "description": "Who invoices the term: `brix` (Brix invoices) or `chargebee` (the card subscription)." }, "activateOn": { "type": "string", "enum": [ "now", "paid" ] }, "poNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoicePaid": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "activatedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "screens": { "type": "integer" }, "rateCentsPerScreenMonth": { "type": "integer" }, "termMonths": { "type": "integer" }, "schedule": { "type": "string", "enum": [ "upfront", "monthly", "annual" ] }, "collect": { "type": "string", "enum": [ "card", "invoice" ] }, "currency": { "type": "string" }, "startsAt": { "type": "string", "description": "Date (YYYY-MM-DD)." }, "endsAt": { "type": "string", "description": "Date (YYYY-MM-DD)." }, "totalCents": { "type": "integer" }, "monthlyCents": { "type": "integer" }, "termLabel": { "type": "string" }, "scheduleLabel": { "type": "string" }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "prior": { "anyOf": [ { "type": "object", "properties": { "quantity": { "type": "integer" }, "unitPriceCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "quantity", "unitPriceCents" ] }, { "type": "null" } ], "description": "The plan before the term started." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "endedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "renewal": { "type": "string", "enum": [ "renew", "non_renewing" ] }, "renewalInvoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "status", "rail", "activateOn", "poNumber", "invoiceNumber", "invoicePaid", "activatedAt", "screens", "rateCentsPerScreenMonth", "termMonths", "schedule", "collect", "currency", "startsAt", "endsAt", "totalCents", "monthlyCents", "termLabel", "scheduleLabel", "invoiceId", "notes", "createdBy", "prior", "createdAt", "endedAt", "renewal", "renewalInvoiceId" ], "description": "An agreed billing term (a fixed number of screens at a fixed rate for a fixed period)." }, "Connector": { "type": "object", "properties": { "type": { "type": "string", "description": "The value for a data source's `type` (`http-json`, `csv`, `google-sheets`, …)." }, "label": { "type": "string" }, "category": { "type": "string", "description": "Group the connector is listed under (`generic`, `celebrations`, …)." }, "available": { "type": "boolean", "description": "False for a connector that is listed as coming soon and cannot be used yet." } }, "required": [ "type", "label", "category", "available" ] }, "Creative": { "type": "object", "properties": { "id": { "type": "string", "description": "Creative id.", "examples": [ "cr_4d5e6f7a8b9c0d1e" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "backgroundUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "boxes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "The design's boxes (text, image, data-bound fields…), in paint order." }, "dataSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The data source the boxes bind to, if any." }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stage preset name." }, "stageWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "stageHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "scenes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Scenes, for a multi-scene design; often empty." }, "touchEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state. Editing an approved row returns it to `draft`." }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON TEXT of the last approved version (not parsed)." }, "sourceSignage": { "anyOf": [ {}, { "type": "null" } ], "description": "The template it was made from (JSON), if any." }, "look": { "anyOf": [ {}, { "type": "null" } ], "description": "Accent / Brand Kit / light-dark settings (JSON), if set." }, "masterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The master template id, for a design made from one." }, "shareLockDefault": { "anyOf": [ {}, { "type": "null" } ], "description": "Which boxes recipients may edit when shared (JSON), if set." }, "shareEditsSkipApproval": { "type": "boolean" }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "name", "backgroundUrl", "boxes", "dataSourceId", "stage", "stageWidth", "stageHeight", "scenes", "touchEnabled", "nodeId", "approvalState", "approvedSnapshot", "sourceSignage", "look", "masterId", "shareLockDefault", "shareEditsSkipApproval", "recalledAt", "recalledBy", "createdAt", "updatedAt", "deletedAt" ], "description": "A canvas design (data-bound boxes on a stage)." }, "DataSource": { "type": "object", "properties": { "id": { "type": "string", "description": "Data source id.", "examples": [ "ds_6f7a8b9c0d1e2f3a" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "description": "Connector type (`csv`, `http-json`, `rest`, `google-sheets`, `ical`, …). See `GET /v1/connectors`." }, "config": { "description": "Connector settings with every credential-shaped value (keys, tokens, secrets, passwords) replaced by `••••••••`. Send the mask back unchanged to keep the stored value." }, "cachedData": { "anyOf": [ {}, { "type": "null" } ], "description": "The last successful fetch (JSON), or null before the first sync." }, "connected": { "type": "boolean", "description": "The last sync succeeded." }, "lastSyncedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "syncError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the last sync failed; null when it succeeded." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "spaceId", "name", "type", "config", "cachedData", "connected", "lastSyncedAt", "syncError", "nodeId", "createdAt", "updatedAt" ], "description": "A connected data feed. Credentials are never returned." }, "EmergencyTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "Emergency template id.", "examples": [ "etpl_7a8b9c0d1e2f3a4b" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "headline": { "type": "string" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentKind": { "anyOf": [ { "type": "string", "enum": [ "media", "creative", "playlist", "app" ] }, { "type": "null" } ] }, "contentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scopeKind": { "type": "string", "enum": [ "all", "node", "screens" ] }, "scopeNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location (null = workspace root); permissions are checked here." }, "prestage": { "type": "boolean", "description": "Content is cached on every in-scope screen before any trigger." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "spaceId", "name", "severity", "headline", "body", "contentKind", "contentId", "scopeKind", "scopeNodeId", "nodeId", "prestage", "createdAt", "updatedAt", "deletedAt" ], "description": "A pre-armed emergency recipe." }, "ImportedMedia": { "type": "object", "properties": { "id": { "type": "string", "description": "Media asset id." }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "url": { "type": "string", "description": "`/v1/media//file`." }, "bytes": { "type": "integer" }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean", "const": true }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "string", "description": "JSON-encoded array of strings — NOT decoded here, unlike GET /v1/media." }, "sourceUrl": { "type": "string", "description": "The URL that was imported. Not stored; returned by this route only." }, "autoCaption": { "type": "boolean" }, "captionState": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "null" } ] }, "autoSmartFit": { "type": "boolean" }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "type": "null" } }, "required": [ "id", "spaceId", "name", "kind", "url", "bytes", "checksum", "active", "folderId", "nodeId", "tags", "sourceUrl", "autoCaption", "captionState", "autoSmartFit", "createdAt", "updatedAt", "deletedAt" ], "description": "The row created by an import, before processing settles." }, "Layout": { "type": "object", "properties": { "id": { "type": "string", "description": "Layout id.", "examples": [ "lay_5e6f7a8b9c0d1e2f" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "resolution": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "description": "Design canvas size in pixels." }, "zones": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Zones: geometry, bound content, frame, radius and role. `GET /v1/layouts/{id}/zones` returns the same list." }, "autoFullscreenForVideo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state. Editing an approved row returns it to `draft`." }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON TEXT of the last approved version (not parsed)." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme": { "anyOf": [ {}, { "type": "null" } ], "description": "Brand Kit look (`{ source: \"brand\", mode?, radius? }`), or null for a bare canvas." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." }, "usedByScreenCount": { "type": "integer", "description": "Screens showing this layout now, directly or through a playlist or schedule." } }, "required": [ "id", "spaceId", "name", "resolution", "zones", "autoFullscreenForVideo", "approvalState", "approvedSnapshot", "nodeId", "importSourceId", "theme", "createdAt", "updatedAt", "deletedAt", "usedByScreenCount" ], "description": "A multi-zone layout a screen can show." }, "LayoutZone": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "x": { "type": "number", "description": "Left edge, in layout pixels." }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" }, "locked": { "type": "boolean" }, "contentName": { "description": "Label of the bound content. Absent on the zone a new layout starts with.", "type": "string" }, "content": { "description": "What the zone plays: a media file, playlist, schedule, app, web link or creative (`canvas`).", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "media", "playlist", "schedule", "app", "link", "canvas" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "null" } ] }, "zIndex": { "type": "number" }, "ownerScope": { "type": "string", "enum": [ "workspace", "org_unit", "location" ] }, "ownerNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "frame": { "description": "Paint style on a themed layout.", "type": "string", "enum": [ "bare", "card", "accent", "glass" ] }, "radius": { "description": "Corner radius in layout pixels.", "type": "number" }, "role": { "description": "`logo`: the zone shows the Brand Kit logo instead of content.", "type": "string", "enum": [ "logo" ] } }, "required": [ "id", "name", "x", "y", "w", "h", "locked" ], "additionalProperties": {}, "description": "A zone. Open: a whole-array write (`PUT /v1/layouts/{id}/zones` with `zones`, or `PATCH /v1/layouts/{id}`) stores each zone as sent, so other keys come back too." }, "Location": { "type": "object", "properties": { "id": { "type": "string", "description": "Location (org node) id.", "examples": [ "on_4d5e6f7a8b9c0d1e" ] }, "name": { "type": "string" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent location; null for the workspace root." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your own location code (store number, region code). Unique in the workspace." }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA zone screens here inherit, e.g. `America/Chicago`." }, "tier": { "type": "integer", "description": "Depth: 1 = the workspace root." }, "isSpace": { "type": "boolean", "description": "True for a workspace (Space) boundary: the root, or a franchise child workspace." }, "screenCount": { "type": "integer", "description": "Screens placed directly at this location (not its children)." }, "members": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "userName": { "type": "string" }, "roleId": { "type": "string" }, "roleName": { "type": "string" }, "roleColor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`sso:` when an identity provider granted this; null when granted in Brix." } }, "required": [ "userId", "userName", "roleId", "roleName", "roleColor", "source" ] }, "description": "People granted a role at this location." }, "featureOverrides": { "description": "Owner-set feature overrides, as stored (normally an array)." }, "approval": { "$ref": "#/components/schemas/ApprovalPolicy" }, "billing": { "description": "Owner-set billing metadata as stored, or null." }, "prefs": { "$ref": "#/components/schemas/LocationPrefs" } }, "required": [ "id", "name", "parentId", "externalId", "timezone", "tier", "isSpace", "screenCount", "members", "featureOverrides", "approval", "billing", "prefs" ], "description": "A location in the workspace tree (an org node)." }, "LocationPrefs": { "type": "object", "properties": { "location": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "label", "lat", "lng" ] }, { "type": "null" } ], "description": "Physical place screens here inherit (drives weather and other location-aware apps)." }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "BCP 47 tag screens here inherit, e.g. `de-DE`." }, "defaultContent": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "playlist", "schedule", "creative", "signage", "app", "media", "layout" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, { "type": "null" } ], "description": "What screens here play when they have no content of their own." } }, "required": [ "location", "language", "defaultContent" ], "description": "Inheritable per-location settings (nearest ancestor wins)." }, "ManifestContentBlock": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "creative", "signage", "playlist", "app", "media", "layout" ] } }, "required": [ "kind" ], "additionalProperties": {}, "description": "Resolved content: `kind` plus the fields for that kind (`media`, `playlist` + `items`, `app`, `layout` + `zones`, `creative`, `signage`). The inner shape is the player's format and grows with it." }, "ManifestPreview": { "type": "object", "properties": { "v": { "type": "integer", "description": "Manifest format version." }, "screen": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rotation": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "rotation", "tags" ] }, "generatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "minPlayerVersion": { "type": "string" }, "content": { "$ref": "#/components/schemas/ManifestContentBlock" }, "standbyContent": { "description": "Shown while the panel is outside its operating hours, when set.", "$ref": "#/components/schemas/ManifestContentBlock" }, "screensOff": { "description": "True when the rules say the panel should be off now.", "type": "boolean" }, "operatingWindow": { "description": "Weekly on-hours by weekday key (`mon`…`sun`), or null for always on.", "anyOf": [ { "type": "object", "properties": { "windows": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ] }, { "type": "null" } ] } }, "timeZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "windows", "timeZone" ] }, { "type": "null" } ] }, "proofOfPlay": { "type": "boolean" }, "playbackMode": { "type": "string", "enum": [ "sync", "unsync", "device-time" ] }, "clock": { "type": "object", "properties": { "timeZone": { "type": "string" } }, "required": [ "timeZone" ] }, "language": { "type": "string" }, "location": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "label", "lat", "lng" ] }, { "type": "null" } ] }, "playerSettings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Effective player settings (volume, watermark, download policy, …)." }, "watermarkText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountHold": { "description": "Present when the account is on hold: the screen shows a hold card, not content.", "type": "object", "properties": { "status": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "status", "reason" ] }, "kiosk": { "description": "Screen Lock. The device's PIN material is never returned here — only whether it is set.", "type": "object", "properties": { "enabled": { "type": "boolean" }, "graceSeconds": { "type": "integer" }, "hasPin": { "type": "boolean" }, "hasRecovery": { "type": "boolean" } }, "required": [ "enabled", "graceSeconds", "hasPin", "hasRecovery" ] }, "apkUpdatePolicy": { "type": "object", "properties": { "window": { "type": "boolean" }, "hourLocal": { "type": "integer" }, "forceAfterDays": { "type": "integer" }, "windowMinutes": { "type": "integer" }, "force": { "type": "boolean" } }, "required": [ "window", "hourLocal", "forceAfterDays", "windowMinutes", "force" ] }, "apkUpdate": { "type": "object", "properties": { "version": { "type": "string" }, "url": { "type": "string" }, "sha256": { "type": "string" }, "signature": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "version", "url", "sha256" ] }, "testMode": { "type": "boolean", "const": true }, "testEligible": { "type": "boolean", "const": true }, "fonts": { "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string" }, "url": { "type": "string" }, "weights": { "type": "array", "items": { "type": "integer" } } }, "required": [ "family", "url", "weights" ] } }, "upcomingBlocks": { "description": "The next scheduled changes, so an offline device can pre-load them.", "type": "array", "items": { "type": "object", "properties": { "activatesAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "content": { "$ref": "#/components/schemas/ManifestContentBlock" }, "screensOff": { "type": "boolean" } }, "required": [ "activatesAt", "content" ] } }, "nextRefreshAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "prestagedOverrides": { "description": "Emergency templates pre-loaded on the device.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "emergency", "cast" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "headline": { "type": "string" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "$ref": "#/components/schemas/ManifestContentBlock" }, "triggeredAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "kind", "severity", "headline", "body", "content", "triggeredAt", "expiresAt" ] } }, "cast": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "emergency", "cast" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "headline": { "type": "string" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "$ref": "#/components/schemas/ManifestContentBlock" }, "triggeredAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "kind", "severity", "headline", "body", "content", "triggeredAt", "expiresAt" ] }, "emergency": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "emergency", "cast" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] }, "headline": { "type": "string" }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "$ref": "#/components/schemas/ManifestContentBlock" }, "triggeredAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "kind", "severity", "headline", "body", "content", "triggeredAt", "expiresAt" ] }, "sealed": { "type": "boolean", "const": true }, "brand": { "type": "object", "properties": { "partnerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productName": { "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brandColor": { "type": "string" }, "cmsHost": { "type": "string" }, "supportEmail": { "type": "string" }, "termsUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "privacyUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isWhiteLabel": { "type": "boolean" } }, "required": [ "partnerId", "productName", "logoUrl", "brandColor", "cmsHost", "supportEmail", "termsUrl", "privacyUrl", "isWhiteLabel" ] } }, "required": [ "v", "screen", "generatedAt", "minPlayerVersion", "content", "playbackMode", "language", "location", "playerSettings" ], "description": "What the screen would play: the player manifest, built as the device would receive it." }, "MediaAsset": { "type": "object", "properties": { "id": { "type": "string", "description": "Media asset id.", "examples": [ "med_0c1d2e3f4a5b6c7d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value." }, "url": { "type": "string", "description": "Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address." }, "bytes": { "type": "integer", "description": "Stored size in bytes (0 for links and apps)." }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean", "description": "False when archived." }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "description": "Tags — a JSON array of strings for every row written by the API (decoded from storage; left as the raw text if the stored value is not valid JSON)." }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Video/audio length in seconds." }, "pdfPageCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Animated image loop length." }, "fontFamily": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fontWeights": { "anyOf": [ {}, { "type": "null" } ], "description": "Font assets: the weights in the file (decoded JSON)." }, "state": { "type": "string", "description": "Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, …" }, "stateReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateFault": { "anyOf": [ { "type": "string", "enum": [ "user", "platform" ] }, { "type": "null" } ] }, "stateProgress": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "playableRev": { "type": "integer", "description": "Bumped whenever the playable bytes change." }, "loopState": { "anyOf": [ { "type": "string", "enum": [ "queued", "ready", "failed" ] }, { "type": "null" } ] }, "loopCodecs": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "loopRev": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopRotation": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "masterKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "masterBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "masterProbe": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rendition4k": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "frameLumaMean": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frameLumaVariance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frameEdgeDensity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Plays only from this time." }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Stops playing after this time." }, "autoArchiveOnExpiry": { "type": "boolean" }, "qr": { "anyOf": [ {}, { "type": "null" } ], "description": "QR overlay settings (decoded JSON)." }, "webConfig": { "anyOf": [ {}, { "type": "null" } ], "description": "Web link settings — refresh, zoom, header auth, … (decoded JSON)." }, "replayState": { "anyOf": [ { "type": "string", "enum": [ "healthy", "replay_pending", "replay_failed" ] }, { "type": "null" } ] }, "lastReplayAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastReplaySuccessAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastFailedStep": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lastFailedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "autoCaption": { "type": "boolean" }, "captionTrackKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captionState": { "anyOf": [ { "type": "string", "enum": [ "pending", "ready", "failed" ] }, { "type": "null" } ] }, "showCaptions": { "type": "boolean" }, "audioEnabled": { "type": "boolean" }, "focalRegion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Smart-fit focal region, as stored JSON text." }, "fit": { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ], "description": "How the asset fills a box." }, "autoSmartFit": { "type": "boolean" }, "rotation": { "type": "integer", "description": "Clockwise rotation in degrees." }, "originalFormat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "packageEntry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "packageFiles": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "packageBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace library root." }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "usageCount": { "type": "integer", "description": "Playlists, schedules, layouts, creatives, boards and screens that use this asset." }, "uploadedByName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who uploaded it, from the audit log." }, "uploadSource": { "anyOf": [ { "type": "string", "enum": [ "ui", "api", "mcp" ] }, { "type": "null" } ], "description": "How it was uploaded." } }, "required": [ "id", "spaceId", "name", "kind", "url", "bytes", "checksum", "active", "folderId", "tags", "altText", "thumbnailUrl", "width", "height", "durationSec", "pdfPageCount", "loopDurationMs", "fontFamily", "fontWeights", "state", "stateReason", "stateCode", "stateFault", "stateProgress", "codec", "playableRev", "loopState", "loopCodecs", "loopRev", "loopRotation", "loopBytes", "masterKey", "masterBytes", "masterProbe", "rendition4k", "frameLumaMean", "frameLumaVariance", "frameEdgeDensity", "startsAt", "expiresAt", "autoArchiveOnExpiry", "qr", "webConfig", "replayState", "lastReplayAt", "lastReplaySuccessAt", "lastFailedStep", "lastFailedReason", "autoCaption", "captionTrackKey", "captionState", "showCaptions", "audioEnabled", "focalRegion", "fit", "autoSmartFit", "rotation", "originalFormat", "packageEntry", "packageFiles", "packageBytes", "importSourceId", "nodeId", "recalledAt", "recalledBy", "createdAt", "updatedAt", "deletedAt", "usageCount", "uploadedByName", "uploadSource" ], "description": "A media library item: an uploaded file, a web link, or an app-style asset." }, "MediaAssetDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Media asset id.", "examples": [ "med_0c1d2e3f4a5b6c7d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value." }, "url": { "type": "string", "description": "Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address." }, "bytes": { "type": "integer", "description": "Stored size in bytes (0 for links and apps)." }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean", "description": "False when archived." }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "description": "Tags — a JSON array of strings for every row written by the API (decoded from storage; left as the raw text if the stored value is not valid JSON)." }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Video/audio length in seconds." }, "pdfPageCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Animated image loop length." }, "fontFamily": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fontWeights": { "anyOf": [ {}, { "type": "null" } ], "description": "Font assets: the weights in the file (decoded JSON)." }, "state": { "type": "string", "description": "Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, …" }, "stateReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateFault": { "anyOf": [ { "type": "string", "enum": [ "user", "platform" ] }, { "type": "null" } ] }, "stateProgress": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "playableRev": { "type": "integer", "description": "Bumped whenever the playable bytes change." }, "loopState": { "anyOf": [ { "type": "string", "enum": [ "queued", "ready", "failed" ] }, { "type": "null" } ] }, "loopCodecs": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "loopRev": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopRotation": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "masterKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "masterBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "masterProbe": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rendition4k": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "frameLumaMean": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frameLumaVariance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frameEdgeDensity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Plays only from this time." }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Stops playing after this time." }, "autoArchiveOnExpiry": { "type": "boolean" }, "qr": { "anyOf": [ {}, { "type": "null" } ], "description": "QR overlay settings (decoded JSON)." }, "webConfig": { "anyOf": [ {}, { "type": "null" } ], "description": "Web link settings — refresh, zoom, header auth, … (decoded JSON)." }, "replayState": { "anyOf": [ { "type": "string", "enum": [ "healthy", "replay_pending", "replay_failed" ] }, { "type": "null" } ] }, "lastReplayAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastReplaySuccessAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastFailedStep": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lastFailedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "autoCaption": { "type": "boolean" }, "captionTrackKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captionState": { "anyOf": [ { "type": "string", "enum": [ "pending", "ready", "failed" ] }, { "type": "null" } ] }, "showCaptions": { "type": "boolean" }, "audioEnabled": { "type": "boolean" }, "focalRegion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Smart-fit focal region, as stored JSON text." }, "fit": { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ], "description": "How the asset fills a box." }, "autoSmartFit": { "type": "boolean" }, "rotation": { "type": "integer", "description": "Clockwise rotation in degrees." }, "originalFormat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "packageEntry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "packageFiles": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "packageBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace library root." }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "usageCount": { "type": "integer", "description": "Playlists, schedules, layouts, creatives, boards and screens that use this asset." }, "uploadedByName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Who uploaded it, from the audit log." }, "uploadSource": { "anyOf": [ { "type": "string", "enum": [ "ui", "api", "mcp" ] }, { "type": "null" } ], "description": "How it was uploaded." }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "File format read from the stored bytes (`PNG`, `MP4 (hevc)`), only when the name has no usable extension; otherwise null." } }, "required": [ "id", "spaceId", "name", "kind", "url", "bytes", "checksum", "active", "folderId", "tags", "altText", "thumbnailUrl", "width", "height", "durationSec", "pdfPageCount", "loopDurationMs", "fontFamily", "fontWeights", "state", "stateReason", "stateCode", "stateFault", "stateProgress", "codec", "playableRev", "loopState", "loopCodecs", "loopRev", "loopRotation", "loopBytes", "masterKey", "masterBytes", "masterProbe", "rendition4k", "frameLumaMean", "frameLumaVariance", "frameEdgeDensity", "startsAt", "expiresAt", "autoArchiveOnExpiry", "qr", "webConfig", "replayState", "lastReplayAt", "lastReplaySuccessAt", "lastFailedStep", "lastFailedReason", "autoCaption", "captionTrackKey", "captionState", "showCaptions", "audioEnabled", "focalRegion", "fit", "autoSmartFit", "rotation", "originalFormat", "packageEntry", "packageFiles", "packageBytes", "importSourceId", "nodeId", "recalledAt", "recalledBy", "createdAt", "updatedAt", "deletedAt", "usageCount", "uploadedByName", "uploadSource", "format" ], "description": "One media asset, as GET /v1/media/{id} returns it." }, "MediaAssetUpdated": { "type": "object", "properties": { "id": { "type": "string", "description": "Media asset id.", "examples": [ "med_0c1d2e3f4a5b6c7d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value." }, "url": { "type": "string", "description": "Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address." }, "bytes": { "type": "integer", "description": "Stored size in bytes (0 for links and apps)." }, "checksum": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean", "description": "False when archived." }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "description": "Tags — a JSON array of strings for every row written by the API (decoded from storage; left as the raw text if the stored value is not valid JSON)." }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Video/audio length in seconds." }, "pdfPageCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Animated image loop length." }, "fontFamily": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fontWeights": { "anyOf": [ {}, { "type": "null" } ], "description": "Font assets: the weights in the file (decoded JSON)." }, "state": { "type": "string", "description": "Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, …" }, "stateReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateFault": { "anyOf": [ { "type": "string", "enum": [ "user", "platform" ] }, { "type": "null" } ] }, "stateProgress": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "playableRev": { "type": "integer", "description": "Bumped whenever the playable bytes change." }, "loopState": { "anyOf": [ { "type": "string", "enum": [ "queued", "ready", "failed" ] }, { "type": "null" } ] }, "loopCodecs": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "loopRev": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopRotation": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "loopBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "masterKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "masterBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "masterProbe": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rendition4k": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "frameLumaMean": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frameLumaVariance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frameEdgeDensity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Plays only from this time." }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Stops playing after this time." }, "autoArchiveOnExpiry": { "type": "boolean" }, "qr": { "anyOf": [ {}, { "type": "null" } ], "description": "QR overlay settings (decoded JSON)." }, "webConfig": { "anyOf": [ {}, { "type": "null" } ], "description": "Web link settings — refresh, zoom, header auth, … (decoded JSON)." }, "replayState": { "anyOf": [ { "type": "string", "enum": [ "healthy", "replay_pending", "replay_failed" ] }, { "type": "null" } ] }, "lastReplayAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastReplaySuccessAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastFailedStep": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lastFailedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "autoCaption": { "type": "boolean" }, "captionTrackKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "captionState": { "anyOf": [ { "type": "string", "enum": [ "pending", "ready", "failed" ] }, { "type": "null" } ] }, "showCaptions": { "type": "boolean" }, "audioEnabled": { "type": "boolean" }, "focalRegion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Smart-fit focal region, as stored JSON text." }, "fit": { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ], "description": "How the asset fills a box." }, "autoSmartFit": { "type": "boolean" }, "rotation": { "type": "integer", "description": "Clockwise rotation in degrees." }, "originalFormat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "packageEntry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "packageFiles": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "packageBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace library root." }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "spaceId", "name", "kind", "url", "bytes", "checksum", "active", "folderId", "tags", "altText", "thumbnailUrl", "width", "height", "durationSec", "pdfPageCount", "loopDurationMs", "fontFamily", "fontWeights", "state", "stateReason", "stateCode", "stateFault", "stateProgress", "codec", "playableRev", "loopState", "loopCodecs", "loopRev", "loopRotation", "loopBytes", "masterKey", "masterBytes", "masterProbe", "rendition4k", "frameLumaMean", "frameLumaVariance", "frameEdgeDensity", "startsAt", "expiresAt", "autoArchiveOnExpiry", "qr", "webConfig", "replayState", "lastReplayAt", "lastReplaySuccessAt", "lastFailedStep", "lastFailedReason", "autoCaption", "captionTrackKey", "captionState", "showCaptions", "audioEnabled", "focalRegion", "fit", "autoSmartFit", "rotation", "originalFormat", "packageEntry", "packageFiles", "packageBytes", "importSourceId", "nodeId", "recalledAt", "recalledBy", "createdAt", "updatedAt", "deletedAt" ], "description": "The stored row after a PATCH, without the list-only fields." }, "MediaFolder": { "type": "object", "properties": { "id": { "type": "string", "description": "Media folder id.", "examples": [ "fold_2b3c4d5e6f7a8b9c" ] }, "spaceId": { "type": "string" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parent folder; null = top level." }, "name": { "type": "string" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace root." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "spaceId", "parentId", "name", "nodeId", "createdAt", "updatedAt", "deletedAt" ], "description": "A folder in the media library." }, "MediaUsage": { "type": "object", "properties": { "containers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "playlist", "schedule", "layout", "creative", "signage" ], "description": "`signage` = a signage template (board)." }, "itemCount": { "description": "Playlists only: total items in the playlist.", "type": "integer" } }, "required": [ "id", "name", "kind" ] } }, "screens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "description": "`online`, `offline` or `pairing`." } }, "required": [ "id", "name", "location", "status" ] }, "description": "Active screens showing it now, directly or through one of the containers." }, "lastPlayedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Last completed play reported by a screen; null if never played." } }, "required": [ "containers", "screens", "lastPlayedAt" ] }, "OpenWindow": { "type": "object", "properties": { "start": { "type": "string", "description": "Opening time, `HH:MM` 24-hour, local time." }, "end": { "type": "string", "description": "Closing time, `HH:MM`. An `end` at or before `start` runs past midnight." }, "volume": { "description": "Volume 0–100 while open; absent or null keeps the screen's own.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "brightness": { "description": "Backlight 0–100 while open; absent or null keeps the screen's own.", "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "muted": { "description": "Mute (true) or unmute (false) while open; absent or null keeps the screen's own.", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "start", "end" ] }, "Override": { "type": "object", "properties": { "id": { "type": "string", "description": "Override (cast_… or emg_…) id.", "examples": [ "cast_9f2c4a1b7d3e5f60" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "kind": { "type": "string", "enum": [ "emergency", "cast" ] }, "status": { "type": "string", "enum": [ "active", "cleared", "expired" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ], "description": "Always `info` for a cast." }, "headline": { "type": "string", "description": "An emergency's message; for a cast, the content's name (or \"Cast\")." }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentKind": { "anyOf": [ { "type": "string", "enum": [ "media", "creative", "playlist", "app", "schedule" ] }, { "type": "null" } ] }, "contentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scopeKind": { "type": "string", "enum": [ "all", "node", "screens" ] }, "scopeNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location, when `scopeKind` is `node`." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location the override is attributed to (null = workspace root)." }, "screenCount": { "type": "integer", "description": "Screens targeted, snapshotted when it started." }, "triggeredBy": { "type": "string", "description": "User id, or `system`." }, "triggeredAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Auto-clear time; null = until cleared." }, "clearedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "clearedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "triggeredByName": { "type": "string", "description": "Display name of `triggeredBy`." }, "clearedByName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scopeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location name, `All screens`, or null for a screen list." }, "confirmedCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Active emergencies only: screens confirmed showing it now. Null otherwise." } }, "required": [ "id", "spaceId", "kind", "status", "severity", "headline", "body", "contentKind", "contentId", "scopeKind", "scopeNodeId", "nodeId", "screenCount", "triggeredBy", "triggeredAt", "expiresAt", "clearedBy", "clearedAt", "triggeredByName", "clearedByName", "scopeName", "confirmedCount" ], "description": "A cast or an emergency override." }, "OverrideCreative": { "type": "object", "properties": { "id": { "type": "string" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "backgroundUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "boxes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "scenes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "dataSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "description": "Absent when not set.", "type": "string" }, "shareLockDefault": { "anyOf": [ {}, { "type": "null" } ] }, "shareEditsSkipApproval": { "type": "boolean" }, "stageWidth": { "type": "integer" }, "stageHeight": { "type": "integer" }, "touchEnabled": { "type": "boolean" }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state. Editing an approved row returns it to `draft`." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "nodeId", "name", "backgroundUrl", "boxes", "scenes", "dataSourceId", "shareLockDefault", "shareEditsSkipApproval", "approvalState", "updatedAt" ], "description": "A creative's design: the boxes and scenes with their settings." }, "ParsedFeed": { "type": "object", "properties": { "source": { "type": "object", "properties": { "name": { "type": "string", "description": "The feed's title." }, "handle": { "type": "string", "description": "The feed URL's host." }, "link": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The site link the feed gives." } }, "required": [ "name", "handle", "link" ] }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "description": "Plain-text summary. Can be empty." }, "body": { "type": "string", "description": "Plain-text body; the description when the feed has only one." }, "url": { "type": "string", "description": "The article's link." }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imageCredit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "type": "string", "description": "Empty when the feed names no author." }, "publishedAt": { "type": "string", "description": "A relative phrase made at fetch time (`2 hours ago`, `Yesterday`)." }, "publishedIso": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "The publish time, or null when the feed gives no date that can be read." }, "readTime": { "type": "string", "description": "Reading-time estimate (`1 min read`)." }, "category": { "type": "string", "description": "The first category, or empty." } }, "required": [ "id", "title", "description", "body", "url", "image", "imageCredit", "author", "publishedAt", "publishedIso", "readTime", "category" ] } } }, "required": [ "source", "articles" ] }, "Playlist": { "type": "object", "properties": { "id": { "type": "string", "description": "Playlist id.", "examples": [ "pl_4d5e6f7a8b9c0d1e" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "shuffle": { "type": "boolean" }, "fullscreen": { "type": "boolean" }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plays only from this date (YYYY-MM-DD) or time, stored as sent." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stops after this date (YYYY-MM-DD) or time, stored as sent." }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Only `approved` content airs where the location requires approval." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace root." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "fit": { "anyOf": [ { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ] }, { "type": "null" } ] }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Internal: the approved version, as stored JSON text." }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usedByScreenCount": { "type": "integer" }, "usedByScreens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "Up to 12 screens playing it." }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistAllocation" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistItem" } }, "sharedIn": { "description": "Present when the playlist is outside your locations and was shared in.", "type": "boolean", "const": true } }, "required": [ "id", "spaceId", "name", "description", "shuffle", "fullscreen", "startsAt", "expiresAt", "approvalState", "nodeId", "createdAt", "updatedAt", "deletedAt", "fit", "approvedSnapshot", "importSourceId", "recalledAt", "recalledBy", "usedByScreenCount", "usedByScreens", "allocations", "items" ], "description": "A playlist with its ordered items." }, "PlaylistAllocation": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "ownerKind": { "type": "string", "enum": [ "user", "group", "org-unit" ] }, "ownerId": { "type": "string" }, "ownerName": { "type": "string" }, "kind": { "type": "string", "enum": [ "percent", "every-nth", "daypart" ] }, "value": { "type": "integer" }, "endValue": { "description": "Absent (not null) when unset.", "type": "integer" }, "colorClass": { "type": "string" }, "fillSpaceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fillPlaylistId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unfilledBehavior": { "type": "string", "enum": [ "collapse", "filler", "holding" ] }, "fillerRefKind": { "anyOf": [ { "type": "string", "enum": [ "media", "playlist", "app", "layout" ] }, { "type": "null" } ] }, "fillerRefId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requiresApproval": { "type": "boolean" } }, "required": [ "id", "label", "ownerKind", "ownerId", "ownerName", "kind", "value", "colorClass", "fillSpaceId", "fillPlaylistId", "unfilledBehavior", "fillerRefKind", "fillerRefId", "requiresApproval" ], "description": "An airtime share of the playlist given to a person, group or location." }, "PlaylistCreated": { "type": "object", "properties": { "id": { "type": "string", "description": "Playlist id.", "examples": [ "pl_4d5e6f7a8b9c0d1e" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "shuffle": { "type": "boolean" }, "fullscreen": { "type": "boolean" }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plays only from this date (YYYY-MM-DD) or time, stored as sent." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stops after this date (YYYY-MM-DD) or time, stored as sent." }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Only `approved` content airs where the location requires approval." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace root." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "items": { "maxItems": 0, "type": "array", "items": { "$ref": "#/components/schemas/PlaylistItem" } }, "allocations": { "maxItems": 0, "type": "array", "items": { "$ref": "#/components/schemas/PlaylistAllocation" } } }, "required": [ "id", "spaceId", "name", "description", "shuffle", "fullscreen", "startsAt", "expiresAt", "approvalState", "nodeId", "createdAt", "updatedAt", "deletedAt", "items", "allocations" ], "description": "A new, empty playlist." }, "PlaylistDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Playlist id.", "examples": [ "pl_4d5e6f7a8b9c0d1e" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "shuffle": { "type": "boolean" }, "fullscreen": { "type": "boolean" }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plays only from this date (YYYY-MM-DD) or time, stored as sent." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stops after this date (YYYY-MM-DD) or time, stored as sent." }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Only `approved` content airs where the location requires approval." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace root." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "fit": { "anyOf": [ { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ] }, { "type": "null" } ] }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Internal: the approved version, as stored JSON text." }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usedByScreenCount": { "type": "integer" }, "usedByScreens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "Up to 12 screens playing it." }, "allocations": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistAllocation" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistItem" } }, "sharedIn": { "description": "Present when the playlist is outside your locations and was shared in.", "type": "boolean", "const": true }, "requiresApproval": { "type": "boolean", "description": "The home location requires approval before content airs." }, "resolvedItemCount": { "type": "integer", "description": "Item count with nested playlists expanded." }, "resolvedDurationSec": { "type": "number", "description": "Runtime in seconds with nested playlists expanded." } }, "required": [ "id", "spaceId", "name", "description", "shuffle", "fullscreen", "startsAt", "expiresAt", "approvalState", "nodeId", "createdAt", "updatedAt", "deletedAt", "fit", "approvedSnapshot", "importSourceId", "recalledAt", "recalledBy", "usedByScreenCount", "usedByScreens", "allocations", "items", "requiresApproval", "resolvedItemCount", "resolvedDurationSec" ] }, "PlaylistItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Playlist item id.", "examples": [ "pli_7a8b9c0d1e2f3a4b" ] }, "refKind": { "type": "string", "enum": [ "media", "app", "layout", "playlist" ] }, "refId": { "type": "string", "description": "The media / app instance / layout / playlist id." }, "name": { "type": "string" }, "thumbnailUrl": { "type": "string", "description": "Empty string when there is none." }, "kind": { "type": "string", "description": "The media kind for media items; `app`, `layout` or `playlist` otherwise." }, "nestedItemCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Nested playlists only: its top-level item count." }, "durationMode": { "type": "string", "enum": [ "fixed", "full", "live", "loop", "manual" ] }, "durationSeconds": { "type": "integer", "description": "Dwell in seconds for `fixed`." }, "loopCount": { "type": "integer" }, "loopDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "mediaDurationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fit": { "anyOf": [ { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ] }, { "type": "null" } ], "description": "The item's own fit; null = inherit." }, "assetFit": { "anyOf": [ { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ] }, { "type": "null" } ] }, "assetStartsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assetActive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "fullscreen": { "type": "boolean" }, "withheld": { "anyOf": [ { "type": "string", "enum": [ "expired", "archived", "not-yet" ] }, { "type": "null" } ], "description": "Why a media item is not airing now, or null." }, "allocationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "position": { "type": "integer" } }, "required": [ "id", "refKind", "refId", "name", "thumbnailUrl", "kind", "nestedItemCount", "durationMode", "durationSeconds", "loopCount", "loopDurationMs", "mediaDurationSec", "fit", "assetFit", "assetStartsAt", "assetExpiresAt", "assetActive", "fullscreen", "withheld", "allocationId", "position" ], "description": "One item in a playlist, with its display fields resolved. Items whose content was deleted are left out." }, "PowerPolicy": { "type": "object", "properties": { "id": { "type": "string", "description": "Power policy id.", "examples": [ "ppol_1a2b3c4d5e6f7a8b" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windows": { "$ref": "#/components/schemas/WeeklyWindows" }, "rebootHourLocal": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Hour (0–23, local time) the device restarts each day; null = no scheduled restart." }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA time zone the windows use; null = each screen's own time zone." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads." }, "screenCount": { "type": "integer", "description": "Screens that use this policy." } }, "required": [ "id", "spaceId", "name", "description", "windows", "rebootHourLocal", "timezone", "createdAt", "updatedAt", "deletedAt", "screenCount" ] }, "ProofOfPlayReport": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "plays": { "type": "integer", "description": "Successful plays (neither skipped nor failed)." }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "events": { "type": "integer", "description": "Every playback-end event: plays + skipped + failed." }, "uniqueContent": { "type": "integer" }, "screensReporting": { "type": "integer" } }, "required": [ "plays", "skipped", "failed", "events", "uniqueContent", "screensReporting" ] }, "byContent": { "type": "array", "items": { "type": "object", "properties": { "contentId": { "type": "string", "description": "`unknown` when the player did not report one." }, "contentName": { "type": "string", "description": "Falls back to the id when no name was reported." }, "contentKind": { "type": "string", "description": "`media`, `app`, `creative`, …; `media` for days read from the daily rollup." }, "screenName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set only when exactly one screen played it." }, "played": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "screenCount": { "type": "integer" }, "totalDurationSec": { "type": "integer" }, "firstAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "lastAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "contentId", "contentName", "contentKind", "screenName", "played", "skipped", "failed", "screenCount", "totalDurationSec", "firstAt", "lastAt" ] }, "description": "Per content, most successful plays first." }, "screens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "Screens that reported in the window, by name." }, "from": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "to": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "retentionDays": { "type": "integer", "description": "How far back raw play events exist; older days come from the daily rollup." }, "truncated": { "type": "boolean", "description": "Always false: the whole window is counted." }, "fromRollup": { "type": "boolean", "description": "Part of the window was read from the daily rollup." } }, "required": [ "totals", "byContent", "screens", "from", "to", "retentionDays", "truncated", "fromRollup" ] }, "RetentionSchedule": { "type": "object", "properties": { "policy": { "type": "object", "properties": { "offline": { "type": "number" }, "screenshots": { "type": "number" }, "playback": { "type": "number" }, "deviceLogs": { "type": "number" }, "vitals": { "type": "number" }, "replays": { "type": "number" }, "aiEvents": { "type": "number" } }, "description": "Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window." }, "effective": { "type": "object", "properties": { "offline": { "type": "integer" }, "screenshots": { "type": "integer" }, "playback": { "type": "integer" }, "deviceLogs": { "type": "integer" }, "vitals": { "type": "integer" }, "replays": { "type": "integer" }, "aiEvents": { "type": "integer" } }, "required": [ "offline", "screenshots", "playback", "deviceLogs", "vitals", "replays", "aiEvents" ], "description": "Days kept per stream now." }, "bounds": { "type": "object", "properties": { "offline": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "platformDefault": { "type": "integer" }, "label": { "type": "string" }, "what": { "type": "string" } }, "required": [ "min", "max", "platformDefault", "label", "what" ] }, "screenshots": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "platformDefault": { "type": "integer" }, "label": { "type": "string" }, "what": { "type": "string" } }, "required": [ "min", "max", "platformDefault", "label", "what" ] }, "playback": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "platformDefault": { "type": "integer" }, "label": { "type": "string" }, "what": { "type": "string" } }, "required": [ "min", "max", "platformDefault", "label", "what" ] }, "deviceLogs": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "platformDefault": { "type": "integer" }, "label": { "type": "string" }, "what": { "type": "string" } }, "required": [ "min", "max", "platformDefault", "label", "what" ] }, "vitals": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "platformDefault": { "type": "integer" }, "label": { "type": "string" }, "what": { "type": "string" } }, "required": [ "min", "max", "platformDefault", "label", "what" ] }, "replays": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "platformDefault": { "type": "integer" }, "label": { "type": "string" }, "what": { "type": "string" } }, "required": [ "min", "max", "platformDefault", "label", "what" ] }, "aiEvents": { "type": "object", "properties": { "min": { "type": "integer" }, "max": { "type": "integer" }, "platformDefault": { "type": "integer" }, "label": { "type": "string" }, "what": { "type": "string" } }, "required": [ "min", "max", "platformDefault", "label", "what" ] } }, "required": [ "offline", "screenshots", "playback", "deviceLogs", "vitals", "replays", "aiEvents" ] } }, "required": [ "policy", "effective", "bounds" ] }, "Role": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display style for the role chip." }, "description": { "type": "string", "description": "Empty string when not set." }, "builtIn": { "type": "boolean", "description": "A role that ships with the product. It cannot be deleted, and its permissions, features and scope cannot be changed." }, "permissions": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "`resource.action` permissions, or `\"all\"` (every permission, now and later)." }, "features": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "Feature keys the role unlocks, or `\"all\"`." }, "scope": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "workspace" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "org-units" }, "orgUnitIds": { "type": "array", "items": { "type": "string" }, "description": "The locations (and their subtrees) where the role applies." } }, "required": [ "kind", "orgUnitIds" ] } ], "description": "Where the role applies: the whole workspace, or only the listed locations." }, "character": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A decorative label. Not used for access." }, "memberCount": { "type": "integer", "description": "Role assignments that use this role (one per person per location)." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "name", "color", "description", "builtIn", "permissions", "features", "scope", "character", "memberCount", "createdAt", "updatedAt" ], "description": "A named set of permissions assigned to people at locations." }, "Schedule": { "type": "object", "properties": { "id": { "type": "string", "description": "Schedule id.", "examples": [ "sch_6f7a8b9c0d1e2f3a" ] }, "spaceId": { "type": "string" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location (null = workspace root)." }, "name": { "type": "string" }, "fallbackName": { "type": "string", "description": "Label of the content played between blocks." }, "fallbackMode": { "type": "string", "enum": [ "content", "off" ], "description": "Between blocks: play the fallback content, or turn the screens off." }, "fallbackContentKind": { "anyOf": [ { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ] }, { "type": "null" } ] }, "fallbackContentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "playsSolely": { "type": "boolean" }, "timeBasis": { "type": "string", "enum": [ "device", "cms" ], "description": "Whose clock the block times use: each screen's local time, or the workspace's." }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`YYYY-MM-DD` or ISO-8601; null = no start bound." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set while the schedule is recalled (withheld from every screen)." }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON of the blocks as last approved (approval workflow)." }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usedByScreenCount": { "type": "integer", "description": "Screens assigned this schedule." }, "fallbackContentRef": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, { "type": "null" } ] }, "fallbackThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleBlock" } } }, "required": [ "id", "spaceId", "nodeId", "name", "fallbackName", "fallbackMode", "fallbackContentKind", "fallbackContentId", "playsSolely", "timeBasis", "startsAt", "expiresAt", "approvalState", "createdAt", "updatedAt", "deletedAt", "recalledAt", "recalledBy", "approvedSnapshot", "importSourceId", "usedByScreenCount", "fallbackContentRef", "fallbackThumbnailUrl", "blocks" ], "description": "A schedule with its timed blocks." }, "ScheduleBlock": { "type": "object", "properties": { "id": { "type": "string", "description": "Schedule block id.", "examples": [ "sb_3c4d5e6f7a8b9c0d" ] }, "label": { "type": "string" }, "daysOfWeek": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 }, "description": "0 = Sunday … 6 = Saturday. Empty = every day." }, "startTime": { "type": "string", "description": "24-hour `HH:MM`." }, "endTime": { "type": "string", "description": "24-hour `HH:MM`; `00:00` = midnight. An end before the start wraps overnight." }, "priority": { "type": "integer", "description": "0–1000; higher wins where blocks overlap." }, "startDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`YYYY-MM-DD`, or null for no start bound." }, "endDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "repeatEveryWeeks": { "type": "integer", "description": "1–52." }, "refKind": { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ] }, "refId": { "type": "string" }, "screensOff": { "type": "boolean", "description": "The block turns the screens off instead of playing `ref`." }, "contentName": { "type": "string", "description": "Current name of the content, `Screens off`, or `(missing content)` when the ref no longer resolves." }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "position": { "type": "integer" } }, "required": [ "id", "label", "daysOfWeek", "startTime", "endTime", "priority", "startDate", "endDate", "repeatEveryWeeks", "refKind", "refId", "screensOff", "contentName", "thumbnailUrl", "position" ] }, "Screen": { "type": "object", "properties": { "id": { "type": "string", "description": "Screen id.", "examples": [ "scr_1a2b3c4d5e6f7a8b" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location (org node) the screen belongs to; null = workspace root." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "offline", "pairing" ], "description": "`pairing` = no device has checked in yet." }, "lastSeenAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Last heartbeat or socket ping reply, whichever is later." }, "coreUpdateOfferedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "contentKind": { "anyOf": [ { "type": "string", "enum": [ "playlist", "schedule", "layout", "creative", "app", "media", "signage" ] }, { "type": "null" } ], "description": "What is assigned. Null = nothing assigned." }, "contentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentFit": { "type": "null", "description": "Retired; always null. Fit is set on the content." }, "deactivatedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set while an operator has deactivated the screen." }, "tags": { "type": "array", "items": { "type": "string" } }, "rotation": { "type": "integer", "description": "0, 90, 180 or 270 degrees." }, "rotationCommandedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA time zone; null = inherited." }, "timezoneSource": { "anyOf": [ { "type": "string", "enum": [ "operator", "device" ] }, { "type": "null" } ] }, "operatingHours": { "type": "string", "description": "`default`, or a JSON-encoded weekly window." }, "lastPanelCommand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleScreensOff": { "type": "boolean" }, "displayPowerMode": { "type": "string", "enum": [ "always-on", "follow-schedule", "os-default" ] }, "playbackMode": { "type": "string", "enum": [ "sync", "unsync", "device-time" ] }, "locationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locationLat": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "locationLng": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ipCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipRegion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipLat": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ipLng": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ipTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipGeoAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "playerSettings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Player settings as a JSON-ENCODED string (not an object)." }, "kioskEnabled": { "type": "boolean" }, "kioskPinMode": { "type": "string", "enum": [ "workspace", "custom" ] }, "kioskGraceSeconds": { "type": "integer" }, "activeEmergencyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The live emergency overriding this screen, if any." }, "activeCastId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The live cast overriding this screen, if any." }, "playerVersionHold": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sealed": { "type": "boolean" }, "sealedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "powerPolicyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billingGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom fields as a JSON-ENCODED string." }, "lanSecretAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "When the local-trigger key was last set or rotated. The key itself is never returned." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "label", "lat", "lng" ] }, { "type": "null" } ] }, "deviceClaimed": { "type": "boolean", "description": "Status is `pairing` but a device has claimed it and not yet checked in." }, "nodeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "groupIds": { "type": "array", "items": { "type": "string" }, "description": "Screen groups this screen is in." }, "contentName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentSharedFrom": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the workspace that shared the assigned content in; null when it is this workspace's own." }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Preview of the assigned content." }, "contentAppKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentMediaKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentState": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "state", "reason" ] }, { "type": "null" } ], "description": "Assigned media that is not playable yet (processing, failed, needs_action); null otherwise." }, "contentOrientation": { "anyOf": [ { "type": "string", "enum": [ "portrait", "landscape", "adaptive" ] }, { "type": "null" } ] }, "liveThumbnailAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Capture time of the latest live frame (GET /v1/screens/{id}/live-thumbnail)." }, "liveThumbnailFreshAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "currentContentKind": { "anyOf": [ { "type": "string", "enum": [ "image", "video", "stream" ] }, { "type": "null" } ] }, "currentContentPosterUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emergencyHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "castHeadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "castStartedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "castExpiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "castContentKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "castContentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kioskHasCustomPin": { "type": "boolean" }, "kioskHasRecovery": { "type": "boolean" }, "obscuredSince": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "A system dialog is covering the screen since this time." }, "pixelHealth": { "anyOf": [ { "type": "string", "enum": [ "ok", "frozen", "blank" ] }, { "type": "null" } ] }, "displayOffSince": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "displayOffReason": { "anyOf": [ { "type": "string", "enum": [ "standby", "wrong-input", "disconnected" ] }, { "type": "null" } ] }, "expectedDark": { "type": "object", "properties": { "dark": { "type": "boolean", "description": "True when the rules say the panel should be off now." }, "reason": { "anyOf": [ { "type": "string", "enum": [ "schedule-block", "power-policy", "operating-hours" ] }, { "type": "null" } ] }, "nextOpen": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string" }, "day": { "type": "string" }, "inMinutes": { "type": "number" } }, "required": [ "at", "day", "inMinutes" ] }, { "type": "null" } ] }, "minutesSinceOpen": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "minutesSinceClose": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "dark", "reason", "nextOpen", "minutesSinceOpen", "minutesSinceClose" ] }, "accountHold": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "suspended", "cancelled", "deactivated", "trial_expired" ] }, "reason": { "type": "string" } }, "required": [ "status", "reason" ] }, { "type": "null" } ] }, "outageSummary30d": { "anyOf": [ { "type": "object", "properties": { "windowDays": { "type": "integer" }, "count": { "type": "integer" }, "topCause": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "topCauseShare": { "type": "number" }, "hedgedShare": { "type": "number" }, "lastCause": { "anyOf": [ { "type": "object", "properties": { "cause": { "type": "string", "description": "Outage cause key, e.g. `wifi-dropped`, `power-loss`, `unknown`." }, "confident": { "type": "boolean" } }, "required": [ "cause", "confident" ] }, { "type": "null" } ] }, "lastKnownCause": { "anyOf": [ { "type": "object", "properties": { "cause": { "type": "string", "description": "Outage cause key, e.g. `wifi-dropped`, `power-loss`, `unknown`." }, "confident": { "type": "boolean" } }, "required": [ "cause", "confident" ] }, { "type": "null" } ] }, "insight": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "windowDays", "count", "topCause", "topCauseShare", "hedgedShare", "lastCause", "lastKnownCause", "insight" ] }, { "type": "null" } ] }, "linkFlaps10m": { "description": "Socket link flips in the last ten minutes; present only when > 0 (list and get).", "type": "integer" }, "state": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "The device's last reported state (`updatedAt` plus the heartbeat snapshot). The list returns a lean subset; get and PATCH return it all. Null before the first heartbeat." } }, "required": [ "id", "spaceId", "nodeId", "name", "status", "lastSeenAt", "coreUpdateOfferedAt", "contentKind", "contentId", "contentFit", "deactivatedAt", "tags", "rotation", "rotationCommandedAt", "timezone", "timezoneSource", "operatingHours", "lastPanelCommand", "scheduleScreensOff", "displayPowerMode", "playbackMode", "locationLabel", "locationLat", "locationLng", "ipCity", "ipRegion", "ipCountry", "ipLat", "ipLng", "ipTimezone", "ipGeoAt", "playerSettings", "kioskEnabled", "kioskPinMode", "kioskGraceSeconds", "activeEmergencyId", "activeCastId", "playerVersionHold", "sealed", "sealedAt", "powerPolicyId", "importSourceId", "billingGroupId", "customFields", "lanSecretAt", "createdAt", "updatedAt", "deletedAt", "location", "deviceClaimed", "nodeName", "groupIds", "contentName", "contentSharedFrom", "thumbnailUrl", "contentAppKey", "contentMediaKind", "contentState", "contentOrientation", "liveThumbnailAt", "liveThumbnailFreshAt", "currentContentKind", "currentContentPosterUrl", "emergencyHeadline", "castHeadline", "castStartedAt", "castExpiresAt", "castContentKind", "castContentId", "kioskHasCustomPin", "kioskHasRecovery", "obscuredSince", "pixelHealth", "displayOffSince", "displayOffReason", "expectedDark", "accountHold", "outageSummary30d", "state" ], "description": "A screen, composed with its content, live state and health facts." }, "ScreenDiagnosis": { "type": "object", "properties": { "layer": { "type": "string", "enum": [ "offline", "deactivated", "unassigned", "stick", "resource", "display", "downstream", "healthy" ], "description": "The first layer that explains the problem, checked from the device outward." }, "severity": { "type": "string", "enum": [ "none", "info", "warning", "critical" ] }, "likelyCause": { "type": "string", "description": "One sentence an operator can act on." }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fault": { "anyOf": [ { "type": "string", "enum": [ "platform", "user", "environment" ] }, { "type": "null" } ], "description": "Whose problem it is; null when healthy." }, "guided": { "type": "boolean", "description": "True when `checklist` is a guided fix." }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "code", "label" ] } }, "remedies": { "description": "One-click fixes, when one applies.", "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "reboot", "wake-screen", "restart-app" ], "description": "The command to send with POST /v1/screens/{id}/commands." }, "label": { "type": "string" }, "cost": { "type": "string", "description": "What the remedy interrupts, in words." }, "confirm": { "type": "boolean" } }, "required": [ "kind", "label", "cost", "confirm" ] } }, "prominent": { "type": "boolean", "description": "True when the console shows this as a banner." } }, "required": [ "layer", "severity", "likelyCause", "detail", "fault", "guided", "checklist", "prominent" ], "description": "Why a screen is (or is not) showing what it should." }, "ScreenGroup": { "type": "object", "properties": { "id": { "type": "string", "description": "Screen group id.", "examples": [ "sgrp_7a8b9c0d1e2f3a4b" ] }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screenCount": { "type": "integer", "description": "Members the caller can see." }, "screenIds": { "type": "array", "items": { "type": "string" }, "description": "Member screen ids the caller can see, oldest membership first." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "name", "description", "screenCount", "screenIds", "createdAt", "updatedAt" ], "description": "A named, saved set of screens — the unit for bulk commands and casts." }, "ScreenRow": { "type": "object", "properties": { "id": { "type": "string", "description": "Screen id.", "examples": [ "scr_1a2b3c4d5e6f7a8b" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Location (org node) the screen belongs to; null = workspace root." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "offline", "pairing" ], "description": "`pairing` = no device has checked in yet." }, "lastSeenAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Last heartbeat or socket ping reply, whichever is later." }, "coreUpdateOfferedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "contentKind": { "anyOf": [ { "type": "string", "enum": [ "playlist", "schedule", "layout", "creative", "app", "media", "signage" ] }, { "type": "null" } ], "description": "What is assigned. Null = nothing assigned." }, "contentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentFit": { "type": "null", "description": "Retired; always null. Fit is set on the content." }, "deactivatedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set while an operator has deactivated the screen." }, "rotation": { "type": "integer", "description": "0, 90, 180 or 270 degrees." }, "rotationCommandedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA time zone; null = inherited." }, "timezoneSource": { "anyOf": [ { "type": "string", "enum": [ "operator", "device" ] }, { "type": "null" } ] }, "operatingHours": { "type": "string", "description": "`default`, or a JSON-encoded weekly window." }, "lastPanelCommand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduleScreensOff": { "type": "boolean" }, "displayPowerMode": { "type": "string", "enum": [ "always-on", "follow-schedule", "os-default" ] }, "playbackMode": { "type": "string", "enum": [ "sync", "unsync", "device-time" ] }, "locationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locationLat": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "locationLng": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ipCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipRegion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipCountry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipLat": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ipLng": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ipTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ipGeoAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "playerSettings": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Player settings as a JSON-ENCODED string (not an object)." }, "kioskEnabled": { "type": "boolean" }, "kioskPinMode": { "type": "string", "enum": [ "workspace", "custom" ] }, "kioskGraceSeconds": { "type": "integer" }, "activeEmergencyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The live emergency overriding this screen, if any." }, "activeCastId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The live cast overriding this screen, if any." }, "playerVersionHold": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sealed": { "type": "boolean" }, "sealedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "powerPolicyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billingGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Custom fields as a JSON-ENCODED string." }, "lanSecretAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "When the local-trigger key was last set or rotated. The key itself is never returned." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "tags": { "type": "string", "description": "Tags as a JSON-ENCODED array string (the stored column), not an array." } }, "required": [ "id", "spaceId", "nodeId", "name", "status", "lastSeenAt", "coreUpdateOfferedAt", "contentKind", "contentId", "contentFit", "deactivatedAt", "rotation", "rotationCommandedAt", "timezone", "timezoneSource", "operatingHours", "lastPanelCommand", "scheduleScreensOff", "displayPowerMode", "playbackMode", "locationLabel", "locationLat", "locationLng", "ipCity", "ipRegion", "ipCountry", "ipLat", "ipLng", "ipTimezone", "ipGeoAt", "playerSettings", "kioskEnabled", "kioskPinMode", "kioskGraceSeconds", "activeEmergencyId", "activeCastId", "playerVersionHold", "sealed", "sealedAt", "powerPolicyId", "importSourceId", "billingGroupId", "customFields", "lanSecretAt", "createdAt", "updatedAt", "deletedAt", "tags" ], "description": "A screen as stored, before composition." }, "SerialTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "Serial template id.", "examples": [ "sertpl_2b3c4d5e6f7a8b9c" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text panel model (`Sony Bravia FW-series`)." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace root." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Command id. Kept across edits, so saved buttons that name it keep working." }, "name": { "type": "string" }, "value": { "type": "string", "description": "The command: literal text (`ascii`) or hex digits (`hex`)." }, "encoding": { "type": "string", "enum": [ "ascii", "hex" ] }, "eol": { "type": "string", "enum": [ "none", "cr", "lf", "crlf" ], "description": "Line ending added after the value." }, "hexPreview": { "type": "string", "description": "The exact bytes sent, as spaced hex (`2A 53 0A`)." } }, "required": [ "id", "name", "value", "encoding", "eol", "hexPreview" ] } } }, "required": [ "id", "spaceId", "name", "model", "nodeId", "createdAt", "updatedAt", "items" ], "description": "A saved set of RS232 commands for one panel model." }, "SignageMasterTemplate": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "archetype": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sortOrder": { "type": "integer" }, "format": { "type": "string", "enum": [ "engine", "creative" ], "description": "`engine`: `config` is the template. `creative`: `creative` is a finished design to create a creative from." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write." }, "creative": { "anyOf": [ {}, { "type": "null" } ], "description": "`creative` format: the design (the body `POST /v1/creatives` takes). Null otherwise." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "name", "description", "industry", "archetype", "sortOrder", "format", "config", "creative", "updatedAt" ], "description": "A published template from the Brix catalog." }, "SignageTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "Signage template id.", "examples": [ "sig_8b9c0d1e2f3a4b5c" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "masterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The master template it was copied from, if any." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "name", "config", "nodeId", "masterId", "createdAt", "updatedAt", "deletedAt" ], "description": "A signage template instance in this workspace." }, "SsoClaimMapping": { "type": "object", "properties": { "locationClaim": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The claim whose value names a location (matched to a location's name or Location ID)." }, "rules": { "type": "array", "items": { "type": "object", "properties": { "claim": { "type": "string", "description": "The identity-provider claim to read, e.g. `groups`." }, "match": { "type": "string", "enum": [ "equals", "contains" ] }, "value": { "type": "string" }, "roleId": { "type": "string", "description": "The role to grant when the rule matches." }, "at": { "type": "string", "enum": [ "location", "root", "node" ], "description": "Where to grant it: the location named by `locationClaim`, the workspace root, or the fixed `nodeId`." }, "nodeId": { "description": "The location for an `at: node` rule.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "claim", "match", "value", "roleId", "at" ] } }, "noMatch": { "type": "string", "enum": [ "default", "deny" ], "description": "When no rule matches: give `defaultRoleId` at the root, or refuse the sign-in." } }, "required": [ "locationClaim", "rules", "noMatch" ], "description": "Rules that turn identity-provider claims into a role at a location." }, "SsoConnection": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "vendor": { "type": "string", "description": "Free text; `generic-oidc` when not set." }, "issuer": { "type": "string", "description": "The OpenID Connect issuer URL (`https://`, no trailing slash)." }, "clientId": { "type": "string" }, "clientSecretPreview": { "type": "string", "const": "••••••••", "description": "Always this mask: the client secret is stored encrypted and is never returned." }, "emailDomains": { "type": "string", "description": "Comma-separated, lower-case (a leading `@` and a trailing dot are removed)." }, "domainsVerifiedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "When DNS proved the domains; null until verified. An unverified connection is not offered at sign-in." }, "provenAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "When a sign-in first completed with the current issuer, client and domains; null until then." }, "lastSignInAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "The latest sign-in through this connection. Only the list fills it; create and update answer null." }, "jitProvisioning": { "type": "boolean", "description": "Create a person on their first sign-in." }, "defaultRoleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The role a new person gets at the workspace root when no rule applies." }, "claimMapping": { "anyOf": [ { "$ref": "#/components/schemas/SsoClaimMapping" }, { "type": "null" } ] }, "extraScopes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Scopes requested on top of `openid email profile`, space-separated." }, "lastClaims": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "The claims of the last sign-in (a person's email, name and groups). Null unless the caller also holds `user.view` for the whole workspace." }, "lastClaimsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "redirectUri": { "type": "string", "description": "The redirect URI to register in the identity provider." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "displayName", "vendor", "issuer", "clientId", "clientSecretPreview", "emailDomains", "domainsVerifiedAt", "provenAt", "lastSignInAt", "jitProvisioning", "defaultRoleId", "claimMapping", "extraScopes", "lastClaims", "lastClaimsAt", "enabled", "redirectUri", "createdAt", "updatedAt" ], "description": "An enterprise single sign-on (OpenID Connect) connection." }, "StatusIncident": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "investigating", "identified", "monitoring", "resolved" ] }, "impact": { "type": "string", "enum": [ "degraded", "outage", "none" ] }, "startedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "resolvedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "updates": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "status": { "type": "string", "enum": [ "investigating", "identified", "monitoring", "resolved" ] }, "message": { "type": "string" } }, "required": [ "at", "status", "message" ] }, "description": "Oldest first." }, "screensPlaying": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether screens kept playing during the incident; null when not stated." } }, "required": [ "id", "title", "status", "impact", "startedAt", "resolvedAt", "updates", "screensPlaying" ], "description": "A published incident." }, "SupportAccessPolicy": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "open", "notify", "approve" ], "description": "`open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request." }, "grantMinutes": { "type": "integer", "description": "How long an approval lasts." }, "requestTtlMinutes": { "type": "integer", "description": "How long a request waits for an answer before it expires." } }, "required": [ "mode", "grantMinutes", "requestTtlMinutes" ] }, "UploadedMedia": { "type": "object", "properties": { "id": { "type": "string", "description": "Media asset id.", "examples": [ "med_0c1d2e3f4a5b6c7d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace library root." }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value." }, "url": { "type": "string", "description": "Where the bytes live: a `/v1/media//file` path, an `https` URL, `r2://…`, or (for a web link) the page address." }, "bytes": { "type": "integer", "description": "Stored size in bytes (0 for links and apps)." }, "checksum": { "type": "string", "description": "SHA-256 of the bytes." }, "active": { "type": "boolean", "description": "False when archived." }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Video/audio length in seconds." }, "loopDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Animated image loop length." }, "fontFamily": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fontWeights": { "anyOf": [ { "type": "array", "items": { "type": "integer" } }, { "type": "null" } ], "description": "Font files: the weights in the file." }, "state": { "type": "string", "enum": [ "ready", "failed", "processing", "ready_with_warnings", "needs_action" ] }, "stateReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateFault": { "anyOf": [ { "type": "string", "enum": [ "user", "platform" ] }, { "type": "null" } ] }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "frameLumaMean": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frameLumaVariance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "frameEdgeDensity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "autoCaption": { "type": "boolean" }, "captionState": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "null" } ] }, "autoSmartFit": { "type": "boolean" }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "type": "null" } }, "required": [ "id", "spaceId", "nodeId", "folderId", "name", "kind", "url", "bytes", "checksum", "active", "altText", "width", "height", "durationSec", "loopDurationMs", "fontFamily", "fontWeights", "state", "stateReason", "stateCode", "stateFault", "codec", "frameLumaMean", "frameLumaVariance", "frameEdgeDensity", "autoCaption", "captionState", "autoSmartFit", "createdAt", "updatedAt", "deletedAt" ], "description": "The media row an upload creates, before processing settles." }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "invited", "deactivated" ], "description": "`invited` until the person sets a password or signs in." }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The role of the first entry in `access`; null when the person has no access." }, "scope": { "type": "string", "description": "The location name of the first entry in `access`; `—` when none." }, "loginMethod": { "type": "string", "enum": [ "sso", "passkey", "password" ], "description": "How the person signs in." }, "totpEnabled": { "type": "boolean", "description": "Two-factor authentication with an authenticator app is on." }, "passkeyCount": { "type": "integer" }, "lastLoginAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "access": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "description": "Location id." }, "nodeName": { "type": "string", "description": "Location name; `—` when the location no longer exists." }, "roleId": { "type": "string" }, "roleName": { "type": "string", "description": "Role name; `—` when the role no longer exists." } }, "required": [ "nodeId", "nodeName", "roleId", "roleName" ] }, "description": "Each location the person can access and the role they hold there. Only locations the caller can see are listed." } }, "required": [ "id", "name", "email", "status", "roleId", "scope", "loginMethod", "totpEnabled", "passkeyCount", "lastLoginAt", "access" ], "description": "A person in the workspace." }, "UserSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Session id (not the session token, which is never returned)." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "lastUsedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "userAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The browser or device that signed in." }, "ipAddress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "current": { "type": "boolean", "description": "This is the session making the call (always false for an API key)." } }, "required": [ "id", "createdAt", "lastUsedAt", "expiresAt", "userAgent", "ipAddress", "current" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook delivery id.", "examples": [ "whd_8b9c0d1e2f3a4b5c" ] }, "endpointId": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed", "abandoned" ], "description": "`failed` is retried later; `abandoned` is not retried again." }, "attempts": { "type": "integer" }, "occurredAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "nextAttemptAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "When the next retry is due; null when none is." }, "deliveredAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "responseStatus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "replayOf": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set on a delivery made by a replay: the delivery it resends." }, "payload": { "anyOf": [ { "type": "object", "properties": { "deliveryId": { "type": "string" }, "event": { "type": "string" }, "occurredAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "workspaceId": { "type": "string" }, "attempt": { "type": "integer" }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The event's own fields. A test send carries `{ test: true, note }`." }, "replayOf": { "description": "On a replay: the delivery it resends.", "type": "string" } }, "required": [ "deliveryId", "event", "occurredAt", "workspaceId", "attempt", "data" ], "description": "The JSON body as it was sent to the receiver." }, { "type": "null" } ], "description": "The JSON body as it was sent; null if the stored copy cannot be read." } }, "required": [ "id", "endpointId", "event", "status", "attempts", "occurredAt", "createdAt", "nextAttemptAt", "deliveredAt", "responseStatus", "error", "replayOf", "payload" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint id.", "examples": [ "whe_7a8b9c0d1e2f3a4b" ] }, "url": { "type": "string", "description": "Where deliveries are POSTed." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secretPreview": { "type": "string", "description": "First 8 characters of the signing secret." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event names (see `GET /v1/webhooks/events`)." }, "enabled": { "type": "boolean" }, "autoDisabledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set when repeated failures switched the endpoint off." }, "autoDisabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "consecutiveFailures": { "type": "integer" }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status of the last delivery attempt." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "url", "description", "secretPreview", "events", "enabled", "autoDisabledAt", "autoDisabledReason", "consecutiveFailures", "lastDeliveryAt", "lastStatus", "createdAt", "updatedAt" ], "description": "A customer webhook endpoint. The signing secret is never returned after creation." }, "WeeklyWindows": { "type": "object", "properties": { "mon": { "$ref": "#/components/schemas/OpenWindow" }, "tue": { "$ref": "#/components/schemas/OpenWindow" }, "wed": { "$ref": "#/components/schemas/OpenWindow" }, "thu": { "$ref": "#/components/schemas/OpenWindow" }, "fri": { "$ref": "#/components/schemas/OpenWindow" }, "sat": { "$ref": "#/components/schemas/OpenWindow" }, "sun": { "$ref": "#/components/schemas/OpenWindow" } }, "description": "Open window per weekday (`mon` … `sun`). A day that is absent is closed." }, "WorkspacePrefs": { "type": "object", "properties": { "timeFormat": { "type": "string", "enum": [ "12h", "24h" ] }, "weekStart": { "type": "string", "enum": [ "mon", "sun" ] }, "dateFormat": { "type": "string", "enum": [ "mdy", "dmy", "ymd" ] }, "tempUnits": { "type": "string", "enum": [ "f", "c" ] }, "timeZone": { "type": "string", "description": "IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace." }, "language": { "type": "string", "description": "BCP 47 language tag." }, "multinational": { "type": "boolean", "description": "Shows the per-location and per-screen language settings." }, "navExtras": { "type": "array", "items": { "type": "string" }, "description": "Console pages switched on that the workspace size hides by default." }, "appBranding": { "type": "object", "properties": { "accent": { "type": "string" }, "accent2": { "type": "string" }, "theme": { "type": "string", "enum": [ "dark", "light" ] }, "backdrop": { "type": "string", "enum": [ "brand", "wash", "plain", "aurora", "dots", "grid", "solid" ] }, "intensity": { "type": "number" } }, "required": [ "accent", "accent2", "theme", "backdrop", "intensity" ], "description": "The look of the on-screen apps." }, "audio": { "type": "object", "properties": { "volume": { "type": "number", "description": "0–100." }, "muted": { "type": "boolean" } }, "required": [ "volume", "muted" ], "description": "Default screen volume and a master mute." }, "brand": { "type": "object", "properties": { "companyName": { "type": "string" }, "logoUrl": { "type": "string" } }, "required": [ "companyName", "logoUrl" ] }, "requireAltText": { "type": "boolean" }, "showScreenLogo": { "type": "boolean" }, "standbyContentKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What a screen with nothing to play shows; null = the default card." }, "standbyContentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tier": { "type": "string", "enum": [ "simple", "team", "enterprise" ], "description": "Workspace size. It sets console defaults, not access." }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "onboardingCompletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "setupStep": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`)." }, "orgNameSet": { "type": "boolean" }, "tiers": { "type": "array", "items": { "type": "integer" }, "description": "Location tree levels in use." }, "tierLabels": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Custom names for the location tree levels." }, "requireTwoFactor": { "type": "boolean" }, "requireSso": { "type": "boolean" }, "requireSsoPending": { "type": "boolean", "description": "Single sign-on was required, and turns on after the first sign-in through the connection." }, "requireSsoPendingSince": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "ai": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "features": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean" }, "description": "Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`." }, "dailyCallLimit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "redactPersonalData": { "type": "boolean" } }, "required": [ "enabled", "features", "dailyCallLimit", "redactPersonalData" ] }, "retention": { "type": "object", "properties": { "offline": { "type": "number" }, "screenshots": { "type": "number" }, "playback": { "type": "number" }, "deviceLogs": { "type": "number" }, "vitals": { "type": "number" }, "replays": { "type": "number" }, "aiEvents": { "type": "number" } }, "description": "Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window." }, "warehouse": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "bucketBinding": { "type": "string", "description": "Set by Brix when the data warehouse feed is provisioned." }, "tables": { "type": "array", "items": { "type": "string" } }, "lookbackDays": { "type": "integer" } }, "required": [ "enabled", "bucketBinding", "tables", "lookbackDays" ], "description": "Data warehouse feed. Set by Brix; not writable here." }, "supportAccess": { "$ref": "#/components/schemas/SupportAccessPolicy" }, "kioskHasGlobalPin": { "type": "boolean", "description": "A workspace Screen Lock PIN is set. The PIN and its hash are never returned." } }, "required": [ "timeFormat", "weekStart", "dateFormat", "tempUnits", "timeZone", "language", "multinational", "navExtras", "appBranding", "audio", "brand", "requireAltText", "showScreenLogo", "standbyContentKind", "standbyContentId", "tier", "industry", "onboardingCompletedAt", "setupStep", "orgNameSet", "tiers", "tierLabels", "requireTwoFactor", "requireSso", "requireSsoPending", "requireSsoPendingSince", "ai", "retention", "warehouse", "supportAccess", "kioskHasGlobalPin" ], "description": "Workspace preferences. Every key is present (defaults filled in)." }, "WorkspaceRef": { "type": "object", "properties": { "id": { "type": "string", "description": "Workspace id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Workspace name; null only if the workspace row is missing." } }, "required": [ "id", "name" ] } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "account" }, { "name": "ad-slots" }, { "name": "ai" }, { "name": "alert-channels" }, { "name": "alert-events" }, { "name": "alert-rules" }, { "name": "api-keys" }, { "name": "app-instances" }, { "name": "approvals" }, { "name": "apps" }, { "name": "audit" }, { "name": "banners" }, { "name": "billing-groups" }, { "name": "casts" }, { "name": "celebration-entries" }, { "name": "connected-apps" }, { "name": "connectors" }, { "name": "contact" }, { "name": "creative-overrides" }, { "name": "creatives" }, { "name": "cross-space-shares" }, { "name": "data-sources" }, { "name": "device-preassignments" }, { "name": "email-health" }, { "name": "emergencies" }, { "name": "emergency-templates" }, { "name": "feature-flags" }, { "name": "feeds" }, { "name": "gdpr" }, { "name": "import" }, { "name": "interactions" }, { "name": "layouts" }, { "name": "link-preview" }, { "name": "me" }, { "name": "media" }, { "name": "media-folders" }, { "name": "media-sync" }, { "name": "oauth" }, { "name": "org-nodes" }, { "name": "platform-banners" }, { "name": "playlists" }, { "name": "power-policies" }, { "name": "proof" }, { "name": "recall" }, { "name": "recycle-bin" }, { "name": "roles" }, { "name": "schedules" }, { "name": "screen-groups" }, { "name": "screens" }, { "name": "screenshots" }, { "name": "search" }, { "name": "serial-templates" }, { "name": "shared-with-me" }, { "name": "shares" }, { "name": "signage-master-templates" }, { "name": "signage-templates" }, { "name": "social" }, { "name": "social-accounts" }, { "name": "sso-connections" }, { "name": "status" }, { "name": "uptime" }, { "name": "users" }, { "name": "web-recorder" }, { "name": "webhooks" }, { "name": "workspace" } ], "paths": { "/v1/account": { "get": { "operationId": "getAccount", "tags": [ "account" ], "summary": "Get account overview", "description": "Returns the workspace plan, subscription status, screen pool size, trial or paid status, and onboarding progress.\n\n**Notes.**\n- `email`, `emailVerifiedAt` and `verificationEmailLastSentAt` describe the CALLING user; they are null for an API key.\n- On a workspace created before the onboarding step existed, a null `prefs.onboardingCompletedAt` is filled with the workspace's creation time (and saved).", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "x-brix-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)." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Account" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] } }, "/v1/account/billing-address": { "get": { "operationId": "getAccountBillingAddress", "tags": [ "account" ], "summary": "Get billing address", "description": "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.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "address": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2." }, "stateCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province, without the country prefix (`CA`, `ON`)." }, "zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "stateCode", "zip", "city", "line1" ] }, "needsState": { "type": "boolean", "description": "The country needs a state and postal code (US, Canada)." } }, "required": [ "configured", "address", "needsState" ] }, { "type": "object", "properties": { "configured": { "type": "boolean", "const": false }, "address": { "type": "null" }, "reason": { "description": "Present when the address could not be read.", "type": "string" } }, "required": [ "configured", "address" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] }, "put": { "operationId": "replaceAccountBillingAddress", "tags": [ "account" ], "summary": "Set billing address", "description": "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.\n\n**Notes.**\n- Answers 400 (not 422) for an invalid address, unlike most validation errors.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Answers 400 (not 422) for an invalid address, unlike most validation errors." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "description": "Country code or name." }, "stateCode": { "description": "Required for US and Canada. Stored in upper case.", "type": "string" }, "zip": { "description": "Required for US and Canada.", "type": "string" }, "city": { "type": "string" }, "line1": { "type": "string" } }, "required": [ "country" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "configured": { "type": "boolean", "const": true }, "address": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2." }, "stateCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or province, without the country prefix (`CA`, `ON`)." }, "zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "stateCode", "zip", "city", "line1" ] }, "needsState": { "type": "boolean" } }, "required": [ "configured", "address", "needsState" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`invalid_country` or `state_required` (400, not 422).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`no_customer`: billing is not set up yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/billing-mode": { "post": { "operationId": "createAccountBillingMode", "tags": [ "account" ], "summary": "Switch billing mode", "description": "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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "invoice" ] } }, "required": [ "mode" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "auto", "invoice" ] } }, "required": [ "mode" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`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).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`email_unverified`, `work_email_required`, `billing_not_configured`, or `under_contract`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`mode` is not `auto` or `invoice`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/cancel": { "post": { "operationId": "cancelAccount", "tags": [ "account" ], "summary": "Cancel subscription", "description": "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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Survey answer. `Seasonal Business` pauses the account instead of cancelling it." }, "restartDate": { "description": "Required for `Seasonal Business`: when the account comes back (future, at most 12 months).", "type": "string" }, "competitor": { "type": "string" }, "returnLikelihood": { "type": "number" }, "comment": { "type": "string" } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "cancel_scheduled" }, "cancelEffectiveAt": { "type": "string", "description": "30 days from now." } }, "required": [ "status", "cancelEffectiveAt" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "paused" }, "pauseUntil": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "status", "pauseUntil" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`payment_required` (unpaid invoice), `already_cancelled`, or `under_contract` (an agreed term; contact Brix).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`reason` missing, or a bad `restartDate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/cancel-deletion": { "post": { "operationId": "createAccountCancelDeletion", "tags": [ "account" ], "summary": "Cancel pending account deletion", "description": "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.\n\n**Notes.**\n- The account stays `cancelled`; reactivate it separately.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The account stays `cancelled`; reactivate it separately." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "cancel_scheduled", "paused", "past_due", "suspended", "cancelled" ] }, "deletionRequestedAt": { "type": "null" } }, "required": [ "status", "deletionRequestedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_pending_deletion`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/contract/renewal": { "patch": { "operationId": "updateAccountContractRenewal", "tags": [ "account" ], "summary": "Set contract auto-renewal", "description": "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.\n\n**Notes.**\n- Turning auto-renew off voids an unpaid renewal invoice.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Turning auto-renew off voids an unpaid renewal invoice." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "renewal": { "type": "string", "enum": [ "renew", "non_renewing" ] } }, "required": [ "renewal" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "contract": { "$ref": "#/components/schemas/BillingTerm" }, "changed": { "type": "boolean" } }, "required": [ "ok", "contract", "changed" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "A workspace billed by a partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`no_term` (no agreed term), or a term that cannot change here.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`renewal` is not `renew` or `non_renewing`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/data-inventory": { "get": { "operationId": "getAccountDataInventory", "tags": [ "account" ], "summary": "Get data inventory", "description": "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.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "parameters": [ { "name": "counts", "in": "query", "required": false, "schema": { "type": "string", "const": "1" }, "description": "`1` adds a row count per table (slower)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "counted": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "what": { "type": "string" }, "personal": { "type": "string" }, "retention": { "type": "string" }, "rows": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "tables": { "type": "array", "items": { "type": "object", "properties": { "table": { "type": "string" }, "rows": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "inExport": { "type": "boolean" }, "exportNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "erasedOnClose": { "type": "boolean" }, "retainedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "strippedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "table", "rows", "inExport", "exportNote", "erasedOnClose", "retainedNote", "strippedFields" ] } } }, "required": [ "id", "label", "what", "personal", "retention", "rows", "tables" ] } }, "residency": { "anyOf": [ { "type": "object", "properties": { "region": { "type": "string" }, "label": { "type": "string" }, "database": { "type": "string" }, "media": { "type": "string" }, "backups": { "type": "string" } }, "required": [ "region", "label", "database", "media", "backups" ] }, { "type": "null" } ], "description": "Where the workspace's data is stored. `database`, `media` and `backups` are internal store names." }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "generatedAt", "counted", "categories", "residency", "notes" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] } }, "/v1/account/downgrade-monthly": { "post": { "operationId": "createAccountDowngradeMonthly", "tags": [ "account" ], "summary": "Switch to monthly billing", "description": "Switches the workspace from annual to monthly billing at the end of the current annual term. Nothing is charged or refunded now.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cadence": { "type": "string", "const": "annual", "description": "Unchanged until the annual term ends." }, "scheduledCadence": { "type": "string", "const": "monthly" } }, "required": [ "cadence", "scheduledCadence" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`no_subscription`, `already_monthly`, or `under_contract`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The switch could not be scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/encryption-key": { "delete": { "operationId": "deleteAccountEncryptionKey", "tags": [ "account" ], "summary": "Disable customer-managed key", "description": "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.\n\n**Notes.**\n- `key` is null when the first pass moved every secret back; otherwise it shows `disabling` until the hourly pass finishes.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "x-brix-notes": [ "`key` is null when the first pass moved every secret back; otherwise it shows `disabling` until the hourly pass finishes." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Customer-managed keys can be used on this platform." }, "covers": { "type": "string" }, "doesNotCover": { "type": "string" }, "key": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string", "const": "azure-key-vault" }, "tenantId": { "type": "string" }, "keyId": { "type": "string", "description": "The key identifier in the vault (a URL). Not key material." }, "status": { "type": "string", "enum": [ "error", "pending", "active", "disabling" ] }, "reencryptDone": { "type": "integer" }, "reencryptTotal": { "type": "integer" }, "lastUnwrapAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "createdBy": { "type": "string", "description": "User id, or `api-key`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "wrappedKeyPreview": { "type": "string", "description": "The first characters of the wrapped data key, to tell keys apart. Unusable without your key." } }, "required": [ "provider", "tenantId", "keyId", "status", "reencryptDone", "reencryptTotal", "lastUnwrapAt", "lastError", "verifiedAt", "createdBy", "createdAt", "updatedAt", "wrappedKeyPreview" ] }, { "type": "null" } ] }, "firstPass": { "type": "object", "properties": { "status": { "type": "string" }, "remaining": { "type": "integer" } }, "required": [ "status", "remaining" ], "description": "The first re-encryption pass, run inside the request; the rest runs hourly." } }, "required": [ "available", "covers", "doesNotCover", "key", "firstPass" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No key is set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`key_unavailable`: the vault did not answer, so secrets cannot be moved back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] }, "get": { "operationId": "getAccountEncryptionKey", "tags": [ "account" ], "summary": "Get encryption key status", "description": "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.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Customer-managed keys can be used on this platform." }, "covers": { "type": "string" }, "doesNotCover": { "type": "string" }, "key": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string", "const": "azure-key-vault" }, "tenantId": { "type": "string" }, "keyId": { "type": "string", "description": "The key identifier in the vault (a URL). Not key material." }, "status": { "type": "string", "enum": [ "error", "pending", "active", "disabling" ] }, "reencryptDone": { "type": "integer" }, "reencryptTotal": { "type": "integer" }, "lastUnwrapAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "createdBy": { "type": "string", "description": "User id, or `api-key`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "wrappedKeyPreview": { "type": "string", "description": "The first characters of the wrapped data key, to tell keys apart. Unusable without your key." } }, "required": [ "provider", "tenantId", "keyId", "status", "reencryptDone", "reencryptTotal", "lastUnwrapAt", "lastError", "verifiedAt", "createdBy", "createdAt", "updatedAt", "wrappedKeyPreview" ] }, { "type": "null" } ] } }, "required": [ "available", "covers", "doesNotCover", "key" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] }, "put": { "operationId": "replaceAccountEncryptionKey", "tags": [ "account" ], "summary": "Enable customer-managed key", "description": "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.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "Your Microsoft Entra tenant id (a UUID)." }, "keyId": { "type": "string", "description": "`https://.vault.azure.net/keys//`." } }, "required": [ "tenantId", "keyId" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Customer-managed keys can be used on this platform." }, "covers": { "type": "string" }, "doesNotCover": { "type": "string" }, "key": { "anyOf": [ { "type": "object", "properties": { "provider": { "type": "string", "const": "azure-key-vault" }, "tenantId": { "type": "string" }, "keyId": { "type": "string", "description": "The key identifier in the vault (a URL). Not key material." }, "status": { "type": "string", "enum": [ "error", "pending", "active", "disabling" ] }, "reencryptDone": { "type": "integer" }, "reencryptTotal": { "type": "integer" }, "lastUnwrapAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "verifiedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "createdBy": { "type": "string", "description": "User id, or `api-key`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "wrappedKeyPreview": { "type": "string", "description": "The first characters of the wrapped data key, to tell keys apart. Unusable without your key." } }, "required": [ "provider", "tenantId", "keyId", "status", "reencryptDone", "reencryptTotal", "lastUnwrapAt", "lastError", "verifiedAt", "createdBy", "createdAt", "updatedAt", "wrappedKeyPreview" ] }, { "type": "null" } ] }, "firstPass": { "type": "object", "properties": { "status": { "type": "string" }, "remaining": { "type": "integer" } }, "required": [ "status", "remaining" ], "description": "The first re-encryption pass, run inside the request; the rest runs hourly." } }, "required": [ "available", "covers", "doesNotCover", "key", "firstPass" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict` (a key is already set; turn it off first) or `key_check_failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bad `tenantId` or `keyId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`not_available` on this platform.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/account/encryption-key/verify": { "post": { "operationId": "verifyAccountEncryptionKey", "tags": [ "account" ], "summary": "Verify encryption key", "description": "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.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "Your Microsoft Entra tenant id (a UUID)." }, "keyId": { "type": "string", "description": "`https://.vault.azure.net/keys//`." } }, "required": [ "tenantId", "keyId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`key_check_failed`: the vault refused (`kind` says why).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bad `tenantId` or `keyId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`not_available` on this platform.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/account/export": { "get": { "operationId": "exportAccount", "tags": [ "account" ], "summary": "Download full data export", "description": "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.\n\n**Notes.**\n- No `{ data }` envelope: the body is the export file (`Content-Disposition: attachment`).\n- Credentials are never exported: their columns are kept with `null` or a `[secret; not exported]` / `[encrypted; not exported]` marker.\n- `generatedBy.kind` is `user` even when an API key made the export (and then `userId` is absent).\n- The complete export (every table, the whole audit log) is `GET /v1/account/export/manifest` and its parts.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-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." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "generatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "generatedBy": { "type": "object", "properties": { "kind": { "type": "string", "const": "user" }, "userId": { "type": "string" } }, "required": [ "kind" ], "description": "Always `user`; `userId` is absent for an API key." }, "workspace": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The workspace record (every column; the Screen Lock PIN hash replaced by `kioskHasGlobalPin` inside `prefs`)." }, "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string" }, "lastLoginAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "name", "email", "status", "lastLoginAt", "createdAt" ] } }, "content": { "type": "object", "properties": { "screens": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "mediaAssets": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "playlists": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "schedules": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "layouts": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "creatives": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "appInstances": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "dataSources": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "banners": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "screens", "mediaAssets", "playlists", "schedules", "layouts", "creatives", "appInstances", "dataSources", "banners" ], "description": "Nine content tables, one object per row (all columns)." }, "auditEvents": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "The last 365 days only." }, "limits": { "type": "object", "properties": { "auditEvents": { "type": "string" }, "completeness": { "type": "string" } }, "required": [ "auditEvents", "completeness" ] } }, "required": [ "schemaVersion", "generatedAt", "generatedBy", "workspace", "people", "content", "auditEvents", "limits" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/export/manifest": { "get": { "operationId": "getAccountExportManifest", "tags": [ "account" ], "summary": "Get export manifest", "description": "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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "schemaVersion": { "type": "integer" }, "generatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "parts": { "type": "array", "items": { "type": "object", "properties": { "part": { "type": "string", "description": "Pass to `/export/part/:part`." }, "table": { "type": "string" }, "rows": { "type": "integer" } }, "required": [ "part", "table", "rows" ] } }, "excluded": { "type": "array", "items": { "type": "object", "properties": { "table": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "table", "reason" ] } }, "redactedColumns": { "type": "array", "items": { "type": "string" }, "description": "`table.column` values withheld from every part." }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "schemaVersion", "generatedAt", "parts", "excluded", "redactedColumns", "notes" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/export/part/{part}": { "get": { "operationId": "getAccountExportPart", "tags": [ "account" ], "summary": "Download one export part", "description": "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.\n\n**Notes.**\n- 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`).\n- `?format=csv` answers `text/csv` instead, with the cursor in the `X-Brix-Next-Cursor` header.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-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." ], "parameters": [ { "name": "part", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A `part` from the manifest (a table name).", "example": "screens" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Rows of the table, all columns (withheld ones marked)." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null on the last page." } }, "required": [ "data", "nextCursor" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such part.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/invoices": { "get": { "operationId": "listAccountInvoices", "tags": [ "account" ], "summary": "List invoices", "description": "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.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "configured": { "type": "boolean" }, "invoices": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "brix", "description": "An invoice Brix issued (an agreed term)." }, "id": { "type": "string" }, "number": { "type": "string" }, "date": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "total": { "type": "number" }, "amountDue": { "type": "number" }, "currencyCode": { "type": "string" }, "status": { "type": "string", "description": "`payment_due`, `paid`, `voided`, …" }, "paidWith": { "type": "null" }, "poNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "source", "id", "number", "date", "total", "amountDue", "currencyCode", "status", "paidWith", "poNumber", "dueDate" ] }, { "type": "object", "properties": { "source": { "type": "string", "const": "chargebee", "description": "An invoice of the card subscription." }, "id": { "type": "string" }, "number": { "type": "string" }, "date": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "total": { "type": "number" }, "amountDue": { "type": "number" }, "currencyCode": { "type": "string" }, "status": { "type": "string" }, "paidWith": { "description": "`Visa •••• 4242`; null when unpaid or not paid by card.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "txnIds": { "description": "Payment transaction ids.", "type": "array", "items": { "type": "string" } }, "subscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "id", "number", "date", "total", "amountDue", "currencyCode", "status" ] } ] }, "description": "Newest first. Amounts are in currency units, not cents." }, "reason": { "description": "Present when the card subscription's invoices could not be read.", "type": "string" } }, "required": [ "configured", "invoices" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] } }, "/v1/account/invoices/{id}/file": { "get": { "operationId": "getAccountInvoiceFile", "tags": [ "account" ], "summary": "Download invoice file", "description": "Downloads the PDF file for one invoice belonging to the calling workspace.\n\n**Notes.**\n- For an invoice Brix issued, when the PDF cannot be drawn the route answers 302 to the invoice's web page instead.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "x-brix-notes": [ "For an invoice Brix issued, when the PDF cannot be drawn the route answers 302 to the invoice's web page instead." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id from the list.", "example": "binv_7a8b9c0d1e2f3a4b" }, { "name": "inline", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Any value: `Content-Disposition: inline`." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not an invoice of this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] } }, "/v1/account/invoices/{id}/pay-link": { "post": { "operationId": "createAccountInvoicePayLink", "tags": [ "account" ], "summary": "Create invoice pay link", "description": "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.\n\n**Notes.**\n- For an invoice Brix issued, `email` is ignored and `emailed` is always false.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "For an invoice Brix issued, `email` is ignored and `emailed` is always false." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id from the list.", "example": "binv_7a8b9c0d1e2f3a4b" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttlDays": { "description": "Link lifetime in days, 1–180 (clamped). Default 30.", "type": "number" }, "email": { "description": "Also email the link to this address (card subscription invoices only).", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "A web page where anyone with the link can see and pay the invoice." }, "emailed": { "type": "boolean" } }, "required": [ "url", "emailed" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not an invoice of this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/invoices/{id}/pdf": { "get": { "operationId": "getAccountInvoicePdf", "tags": [ "account" ], "summary": "Get invoice PDF link", "description": "Returns a short-lived download URL for one invoice's PDF. Brix confirms the invoice belongs to the calling workspace before returning the link.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Invoice id (a card subscription invoice).", "example": "1043" }, { "name": "inline", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Any value: the link opens in the browser instead of downloading." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "A short-lived download link." } }, "required": [ "url" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not an invoice of this workspace (invoices Brix issued have no link here; use `/file`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] } }, "/v1/account/invoices/pay-all-link": { "post": { "operationId": "createAccountInvoicePayAllLink", "tags": [ "account" ], "summary": "Create pay-all link", "description": "Creates one shareable link that lets whoever receives it pay all of the workspace's outstanding invoices at once.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttlDays": { "description": "Link lifetime in days, 1–180 (clamped). Default 30.", "type": "number" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "One web page that lists and pays every open invoice." }, "ttlDays": { "type": "integer" } }, "required": [ "url", "ttlDays" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`billing_not_configured`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/invoices/pay-links-outstanding": { "post": { "operationId": "createAccountInvoicePayLinksOutstanding", "tags": [ "account" ], "summary": "Create links for outstanding invoices", "description": "Creates a separate hosted payment link for every invoice currently outstanding on the workspace.\n\n**Notes.**\n- Covers the card subscription's invoices only, not invoices Brix issued.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Covers the card subscription's invoices only, not invoices Brix issued." ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttlDays": { "description": "Link lifetime in days, 1–180 (clamped). Default 30.", "type": "number" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "number": { "type": "string" }, "amountDue": { "type": "number" }, "currencyCode": { "type": "string" }, "url": { "type": "string" } }, "required": [ "invoiceId", "number", "amountDue", "currencyCode", "url" ] } }, "ttlDays": { "type": "integer" } }, "required": [ "links", "ttlDays" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`billing_not_configured`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/limits": { "get": { "operationId": "listAccountLimits", "tags": [ "account" ], "summary": "Get API limits", "description": "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.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "api": { "type": "object", "properties": { "perMinute": { "type": "integer" }, "windowSeconds": { "type": "integer" }, "scope": { "type": "string", "description": "`workspace`: all keys of the workspace share one budget." }, "appliesTo": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "onBreach": { "type": "string" } }, "required": [ "perMinute", "windowSeconds", "scope", "appliesTo", "headers", "onBreach" ] }, "webhooks": { "type": "object", "properties": { "maxConsecutiveFailures": { "type": "integer" }, "deliveryLogRetentionDays": { "type": "integer" }, "delivery": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "maxConsecutiveFailures", "deliveryLogRetentionDays", "delivery", "retry" ] } }, "required": [ "api", "webhooks" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] } }, "/v1/account/me-prefs": { "get": { "operationId": "listAccountMePrefs", "tags": [ "account" ], "summary": "Get my preferences", "description": "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).\n\n**Notes.**\n- `user` is returned as saved: the per-user write does not check its keys or values.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "x-brix-notes": [ "`user` is returned as saved: the per-user write does not check its keys or values." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/WorkspacePrefs" }, "user": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The calling user's own overrides, as saved. Empty for an API key." }, "effective": { "description": "The workspace preferences with the user's overrides applied.", "$ref": "#/components/schemas/WorkspacePrefs" } }, "required": [ "workspace", "user", "effective" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] } }, "/v1/account/onboarding": { "post": { "operationId": "createAccountOnboarding", "tags": [ "account" ], "summary": "Complete onboarding", "description": "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.\n\n**Notes.**\n- Every call adds the starter content again; it is not idempotent.\n- `tier` is stored as sent without a check.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Every call adds the starter content again; it is not idempotent.", "`tier` is stored as sent without a check." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceName": { "description": "Renames the workspace and sets the brand company name (cut at 120).", "type": "string" }, "industry": { "description": "Industry id (`cafe`, `qsr`, `gym`, …); picks the starter designs.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tier": { "type": "string", "enum": [ "simple", "team", "enterprise" ] }, "setupStep": { "description": "Walkthrough position to save with the answers.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "prefs": { "$ref": "#/components/schemas/WorkspacePrefs" }, "seeded": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "Starter designs added." }, "library": { "type": "integer", "description": "Starter library items added (photos, a playlist, a schedule, …). 0 when that step failed." } }, "required": [ "prefs", "seeded", "library" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unknown `industry`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/payment-card": { "delete": { "operationId": "deleteAccountPaymentCard", "tags": [ "account" ], "summary": "Remove saved card", "description": "Removes the workspace's saved card. If the payment option was set to card, it reverts to invoice billing.\n\n**Notes.**\n- When the payment option was `card`, it goes back to `invoice`.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "When the payment option was `card`, it goes back to `invoice`." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "removed": { "type": "boolean" }, "payment": { "$ref": "#/components/schemas/AccountPayment" } }, "required": [ "removed", "payment" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "A workspace billed by a partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_brix_billed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/payment-card/complete": { "post": { "operationId": "completeAccountPaymentCard", "tags": [ "account" ], "summary": "Complete card setup", "description": "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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "The `card_session` value from the return URL (`cs_…`)." } }, "required": [ "sessionId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "saved", "already_saved", "incomplete" ] }, "payment": { "$ref": "#/components/schemas/AccountPayment" } }, "required": [ "outcome", "payment" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not a card session of this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_brix_billed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`sessionId` missing or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The session could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/payment-card/setup": { "post": { "operationId": "createAccountPaymentCardSetup", "tags": [ "account" ], "summary": "Start card setup", "description": "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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "useLastPaid": { "description": "Save the card the last invoice was paid with, when that is possible, instead of opening a page.", "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "saved": { "type": "boolean", "const": true }, "payment": { "$ref": "#/components/schemas/AccountPayment" } }, "required": [ "saved", "payment" ] }, { "type": "object", "properties": { "saved": { "type": "boolean", "const": false }, "url": { "type": "string", "description": "A hosted card page. After it, call `/payment-card/complete` with the `card_session` from the return URL." } }, "required": [ "saved", "url" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "A workspace billed by a partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_brix_billed`, or `card_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The card page could not be opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/payment-methods": { "get": { "operationId": "listAccountPaymentMethods", "tags": [ "account" ], "summary": "List payment methods", "description": "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.\n\n**Notes.**\n- 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.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "x-brix-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." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "False when billing is not set up (or could not be read, see `reason`)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "description": "`card`, `bank_account`, or a wallet type (`apple_pay`, `paypal_express_checkout`, …)." }, "brand": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "walletType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gateway": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiryMonth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "expiryYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "type": "string" }, "primary": { "type": "boolean" }, "backup": { "type": "boolean", "description": "Charged when the primary fails." } }, "required": [ "id", "type", "brand", "last4", "walletType", "gateway", "expiryMonth", "expiryYear", "status", "primary", "backup" ] } }, "reason": { "type": "string" } }, "required": [ "configured", "sources" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] } }, "/v1/account/payment-methods/{id}/role": { "post": { "operationId": "createAccountPaymentMethodRole", "tags": [ "account" ], "summary": "Set payment method role", "description": "Sets a saved payment method as the primary or backup method for the workspace.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Payment method id from the list.", "example": "pm_card_1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "primary", "backup" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "id": { "type": "string" }, "role": { "type": "string", "enum": [ "primary", "backup" ] } }, "required": [ "ok", "id", "role" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not one of this workspace's payment methods.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`billing_not_configured`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bad `role`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/payment-methods/manage-url": { "post": { "operationId": "createAccountPaymentMethodManageUrl", "tags": [ "account" ], "summary": "Get payment methods management link", "description": "Returns a hosted page URL where the workspace can add, replace, or remove a saved card or bank account.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "A hosted page to add, replace or remove a card or bank account. Open it in a browser." } }, "required": [ "url" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`billing_not_configured`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/payment-option": { "patch": { "operationId": "updateAccountPaymentOption", "tags": [ "account" ], "summary": "Set payment option", "description": "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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "option": { "type": "string", "enum": [ "card", "invoice" ] } }, "required": [ "option" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "changed": { "type": "boolean" }, "payment": { "$ref": "#/components/schemas/AccountPayment" } }, "required": [ "changed", "payment" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "A workspace billed by a partner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_brix_billed`, or `card_required` (save a card first).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bad `option`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/prefs": { "patch": { "operationId": "updateAccountPref", "tags": [ "account" ], "summary": "Update workspace preferences", "description": "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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kioskPin": { "description": "Set (4–8 digits) or clear (null) the workspace Screen Lock PIN. Stored as a hash.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requireSso": { "description": "Needs a working single sign-on connection with verified domains; until someone signs in through it, the request is held (`requireSsoPending`).", "type": "boolean" }, "requireTwoFactor": { "description": "Turning it on needs the calling user to have two-factor sign-in set up, so an API key cannot turn it on.", "type": "boolean" } }, "additionalProperties": {}, "description": "Any `WorkspacePrefs` keys to change; omitted keys keep their value. `supportAccess`, `retention`, `warehouse` and the PIN hash are ignored here (they have their own routes, or are set by Brix)." }, "example": { "timeFormat": "24h", "timeZone": "America/Chicago" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspacePrefs" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`sso_not_configured`, `two_factor_not_enrolled`, or a PIN that is not 4–8 digits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/reactivate": { "post": { "operationId": "createAccountReactivate", "tags": [ "account" ], "summary": "Reactivate account", "description": "Reverses a scheduled cancellation, or resumes an account that was paused for seasonal closure.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "active" } }, "required": [ "status" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`already_active`, `pending_deletion`, `payment_required`, `payment_method_required`, `not_reactivatable`, or `under_contract`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/retention": { "get": { "operationId": "getAccountRetention", "tags": [ "account" ], "summary": "Get retention settings", "description": "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.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RetentionSchedule" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] }, "patch": { "operationId": "updateAccountRetention", "tags": [ "account" ], "summary": "Set retention window", "description": "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.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "offline": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "screenshots": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "playback": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "deviceLogs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "vitals": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "replays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "aiEvents": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "description": "Days per stream; a value outside the stream's bounds is clamped; null returns the stream to the platform window." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RetentionSchedule" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/account/screen-pool": { "post": { "operationId": "createAccountScreenPool", "tags": [ "account" ], "summary": "Buy screen licences", "description": "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.\n\n**Notes.**\n- 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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-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." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "quantity" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "quantity": { "type": "integer", "description": "Screens billed now (unchanged until the renewal)." }, "previousQuantity": { "type": "integer" }, "invoiceId": { "type": "null" }, "amountPaid": { "type": "null" }, "banked": { "type": "boolean", "const": false }, "scheduled": { "type": "boolean", "const": true, "description": "A reduction on a paid plan, queued for the renewal." }, "scheduledQuantity": { "type": "integer" }, "effectiveAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "quantity", "previousQuantity", "invoiceId", "amountPaid", "banked", "scheduled", "scheduledQuantity", "effectiveAt" ] }, { "type": "object", "properties": { "quantity": { "type": "integer" }, "previousQuantity": { "type": "integer" }, "invoiceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amountPaid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "banked": { "type": "boolean", "description": "The part-period charge was too small to charge today; it is added to the renewal." }, "invoiced": { "type": "boolean", "description": "An invoice-billed account: an invoice was raised, not charged." }, "trial": { "type": "boolean", "description": "In the free trial: nothing was invoiced." }, "amountDue": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "quantity", "previousQuantity", "invoiceId", "amountPaid", "banked", "invoiced", "trial", "amountDue" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`card_declined` or `payment_incomplete`: the plan did not change (or needs our team).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`screens_in_use` (below the screens running), `no_subscription`, `account_cancelled`, or `under_contract`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`quantity` is not a whole number from 1 to 10000.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The change could not be made.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/screen-pool/estimate": { "post": { "operationId": "createAccountScreenPoolEstimate", "tags": [ "account" ], "summary": "Estimate screen-pool change", "description": "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.\n\n**Notes.**\n- A POST because it takes an argument; it changes nothing.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "x-brix-notes": [ "A POST because it takes an argument; it changes nothing." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "quantity" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "description", "amount" ] }, "description": "Line items of the invoice raised today." }, "creditsApplied": { "type": "number", "description": "Credit for the unused part of the current term." }, "subTotal": { "type": "number" }, "amountDueNow": { "type": "number", "description": "Charged now, after credits (currency units, not cents)." }, "currencyCode": { "type": "string" }, "nextBillingAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "payWith": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The payment method that is charged (`Visa •••• 4242`)." }, "currentQuantity": { "type": "integer" }, "newQuantity": { "type": "integer" }, "renewalAmount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "What each term costs after the change." }, "chargedToday": { "type": "boolean", "description": "False when the amount is too small to charge today (it is added to the renewal)." }, "invoiced": { "type": "boolean", "description": "The account pays by invoice; nothing is charged to a card." }, "decreaseRequiresSupport": { "type": "boolean", "const": false, "description": "Always false. Kept for older clients." }, "scheduledAtRenewal": { "type": "boolean", "description": "A reduction on a paid plan: it takes effect at `renewsAt`." }, "renewsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "inTrial": { "type": "boolean" }, "trialEndsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "minQuantity": { "type": "integer", "description": "The lowest allowed quantity: the screens running now (at least 1)." } }, "required": [ "lines", "creditsApplied", "subTotal", "amountDueNow", "currencyCode", "nextBillingAt", "payWith", "currentQuantity", "newQuantity", "renewalAmount", "chargedToday", "invoiced", "decreaseRequiresSupport", "scheduledAtRenewal", "renewsAt", "inTrial", "trialEndsAt", "minQuantity" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`no_subscription`, `account_cancelled`, or `under_contract`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`quantity` is not a whole number from 1 to 10000.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`estimate_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] } }, "/v1/account/screen-pool/scheduled": { "delete": { "operationId": "deleteAccountScreenPoolScheduled", "tags": [ "account" ], "summary": "Cancel scheduled screen-pool change", "description": "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.\n\n**Notes.**\n- Succeeds when nothing is queued too.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Succeeds when nothing is queued too." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`no_subscription`, `account_cancelled`, or `under_contract`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The billing provider did not answer; nothing changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/support-access": { "get": { "operationId": "getAccountSupportAccess", "tags": [ "account" ], "summary": "Get support access status", "description": "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.\n\n**Notes.**\n- A read that can write: pending requests past their expiry are marked `expired` first.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "x-brix-notes": [ "A read that can write: pending requests past their expiry are marked `expired` first." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/SupportAccessPolicy" }, "modes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "open", "notify", "approve" ] }, "label": { "type": "string" }, "what": { "type": "string" } }, "required": [ "id", "label", "what" ] } }, "requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "staffEmail": { "type": "string", "description": "The Brix support person who asked." }, "reason": { "type": "string" }, "reasonCategory": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "approved", "denied", "expired", "revoked" ] }, "requestedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "requestExpiresAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "decidedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "decidedByEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "decidedByName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "grantExpiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "decisionNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "grantLive": { "type": "boolean" } }, "required": [ "id", "staffEmail", "reason", "reasonCategory", "status", "requestedAt", "requestExpiresAt", "decidedAt", "decidedByEmail", "decidedByName", "grantExpiresAt", "decisionNote", "grantLive" ] }, "description": "Newest 100." }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "staffEmail": { "type": "string" }, "reason": { "type": "string" }, "startedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "endedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "live": { "type": "boolean" }, "recorded": { "type": "boolean", "description": "The session was screen-recorded." } }, "required": [ "id", "staffEmail", "reason", "startedAt", "endedAt", "expiresAt", "live", "recorded" ] }, "description": "Times Brix support opened the workspace, newest 100." } }, "required": [ "policy", "modes", "requests", "sessions" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] } }, "/v1/account/support-access/policy": { "patch": { "operationId": "updateAccountSupportAccessPolicy", "tags": [ "account" ], "summary": "Set support access policy", "description": "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.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "open", "notify", "approve" ], "description": "`open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request." }, "grantMinutes": { "type": "integer", "description": "How long an approval lasts." }, "requestTtlMinutes": { "type": "integer", "description": "How long a request waits for an answer before it expires." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SupportAccessPolicy" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "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).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/account/support-access/revoke": { "post": { "operationId": "createAccountSupportAccessRevoke", "tags": [ "account" ], "summary": "Revoke support access", "description": "Immediately withdraws consent for Brix support access: ends every live support session and cancels any outstanding approval, in that order.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sessionsEnded": { "type": "integer" }, "grantsRevoked": { "type": "integer" } }, "required": [ "sessionsEnded", "grantsRevoked" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "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).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/account/upgrade-annual": { "post": { "operationId": "createAccountUpgradeAnnual", "tags": [ "account" ], "summary": "Switch to annual billing", "description": "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.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cadence": { "type": "string", "const": "annual" } }, "required": [ "cadence" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`no_subscription`, `under_contract`, or `already_annual`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The switch failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`annual_switch_unavailable`: the switch is not self-serve yet; contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/account/upgrade-annual/estimate": { "get": { "operationId": "getAccountUpgradeAnnualEstimate", "tags": [ "account" ], "summary": "Estimate annual upgrade cost", "description": "Returns the prorated cost of switching from monthly to annual billing before committing to it, including which card would be charged.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "description", "amount" ] }, "description": "Line items of the invoice raised today." }, "creditsApplied": { "type": "number", "description": "Credit for the unused part of the current term." }, "subTotal": { "type": "number" }, "amountDueNow": { "type": "number", "description": "Charged now, after credits (currency units, not cents)." }, "currencyCode": { "type": "string" }, "nextBillingAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "payWith": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The payment method that is charged (`Visa •••• 4242`)." } }, "required": [ "lines", "creditsApplied", "subTotal", "amountDueNow", "currencyCode", "nextBillingAt", "payWith" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`no_subscription` or `under_contract`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`estimate_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] } }, "/v1/ad-slots": { "get": { "operationId": "listAdSlots", "tags": [ "ad-slots" ], "summary": "List ad slots", "description": "List the programmatic ad slots configured in the workspace. Each slot includes its provider, endpoint, venue or device identifiers, and its minimum and maximum duration limits. The exchange credential itself is never included; only the name of the stored credential reference is returned.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "post": { "operationId": "createAdSlot", "tags": [ "ad-slots" ], "summary": "Create an ad slot", "description": "Create an ad slot with a `name` and a `config` object containing `provider`, `endpoint`, `credsRef`, `minSeconds`, `maxSeconds`, `podSeconds`, and `allowAudio`, plus optional `venueId`, `deviceTypeId`, and `nodeId`. The slot is created disabled and cannot request ads until you enable it with a later update.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/ad-slots/{id}": { "delete": { "operationId": "deleteAdSlot", "tags": [ "ad-slots" ], "summary": "Delete an ad slot", "description": "Delete an ad slot and stop it from requesting ads. Cached creatives and the record of impressions already played are kept, so past playback history remains available after the slot is removed.", "x-brix-permission": "integration.delete", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.delete" ] } ] }, "get": { "operationId": "getAdSlot", "tags": [ "ad-slots" ], "summary": "Get an ad slot", "description": "Retrieve one ad slot, including the names of the credentials stored against it. Credential values are write-only and are never returned by this or any other endpoint.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "patch": { "operationId": "updateAdSlot", "tags": [ "ad-slots" ], "summary": "Update an ad slot", "description": "Edit an ad slot's name, node, or exchange configuration, or turn ad requesting on and off. Enabling a slot is what allows it to start spending, so this action is recorded in the activity log.", "x-brix-permission": "integration.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/ad-slots/{id}/impressions": { "get": { "operationId": "listAdSlotImpressions", "tags": [ "ad-slots" ], "summary": "List an ad slot's impressions", "description": "List what an ad slot has actually played, and whether each impression beacon was recorded successfully. Results are returned newest first and the response is capped at 200 records. Use this to reconcile playback against an advertiser's invoice.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] } }, "/v1/ad-slots/{id}/secrets": { "put": { "operationId": "replaceAdSlotSecret", "tags": [ "ad-slots" ], "summary": "Set an ad slot's credentials", "description": "Store the exchange credential for an ad slot. Send a map of reference names to values; the values are encrypted at rest and merged into any existing credentials. Setting a value to `null` deletes that reference. Only the credential names are ever returned, never the values.", "x-brix-permission": "integration.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/ai/events": { "get": { "operationId": "listAiEvents", "tags": [ "ai" ], "summary": "List AI activity events", "description": "Return the workspace's record of every AI-powered call it made, including the feature, model, outcome, actor, duration, and number of redactions. Calls that were refused, for example because the feature is disabled or a usage limit was reached, also appear as entries, since a blocked request is only evidenced by a record of the refusal. The prompt and output text are never stored. Only events at locations where the caller holds the audit log view permission are returned, as in the audit log. The actor is returned in full only where the caller also holds the user view permission; otherwise only its kind, for example user or staff. Results are paginated and can be filtered by feature, outcome, and a starting point in time; a page can hold fewer entries than the limit.", "x-brix-permission": "audit-log.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "audit-log.view" ] } ] } }, "/v1/ai/events.csv": { "get": { "operationId": "getAiEventsCsv", "tags": [ "ai" ], "summary": "Export AI activity events as CSV", "description": "Return the same AI activity data as a CSV file, suitable for sharing or importing elsewhere. It applies the same filters, the same location scope and the same actor rule as the JSON list, so the export always matches what the list view shows.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/ai/models": { "get": { "operationId": "listAiModels", "tags": [ "ai" ], "summary": "List AI models in use", "description": "Return which AI model powers each AI feature, when it was adopted, what it replaced, and the safe-use guidance shown to users at the point of use. This reflects the exact configuration currently enforced, so it cannot drift out of step with actual behavior.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/ai/summary": { "get": { "operationId": "getAiSummary", "tags": [ "ai" ], "summary": "Summarize AI activity", "description": "Return counts of AI calls grouped by feature, model, and outcome over a time window that defaults to 30 days. Totals separate calls that ran successfully, calls that failed, and calls that were refused due to policy or usage limits, so a refusal is never confused with a failure. Only calls at locations where the caller holds the audit log view permission are counted.", "x-brix-permission": "audit-log.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "audit-log.view" ] } ] } }, "/v1/alert-channels/teams/test": { "post": { "operationId": "testAlertChannelTeam", "tags": [ "alert-channels" ], "summary": "Send a test Microsoft Teams alert", "description": "Send a sample alert card to a Microsoft Teams webhook to confirm it is configured correctly. Provide the webhook `url` in the request body; it must be a Microsoft Teams Workflow URL. The response returns `ok`, `status`, and an optional `message`, and never includes the URL you sent. This operation is rate-limited to 10 requests per minute.\n\nA refusal from Microsoft Teams is NOT an HTTP error: the answer is 200 with `ok: false` and a `message` to show.", "x-brix-permission": "alert-rule.create", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "A Microsoft Teams workflow URL, or the masked URL a saved rule shows (then send `ruleId` too)." }, "ruleId": { "description": "With a masked `url`: the rule whose saved URL to use.", "type": "string" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "status": { "type": "integer", "description": "HTTP status Microsoft Teams answered with; 0 when it did not answer." }, "message": { "type": "string", "description": "What went wrong, in words to show an operator." } }, "required": [ "ok", "status", "message" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "status": { "type": "integer" } }, "required": [ "ok", "status" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The URL is not a Microsoft Teams workflow URL, or a masked URL matches no URL saved on `ruleId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 10 calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "alert-rule.create" ] } ] } }, "/v1/alert-events": { "get": { "operationId": "listAlertEvents", "tags": [ "alert-events" ], "summary": "List alert events", "description": "List alerts that have fired against your screens, each combined with the screen's name. This endpoint is read-only: alerts open automatically when a condition is detected and close automatically on recovery. Only currently open alerts are returned, as a limited list, so a long history does not push them out.\n\nOpen events (up to 300, newest first) followed by recently closed ones (up to 300). Not paginated.\n\n**Notes.**\n- The route-registry description names `alert-rule.view`, but the route is gated by `screen.view`; `screen.view` is what a key needs.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The route-registry description names `alert-rule.view`, but the route is gated by `screen.view`; `screen.view` is what a key needs." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertEvent" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/alert-events/{id}/close": { "post": { "operationId": "closeAlertEvent", "tags": [ "alert-events" ], "summary": "Close an alert event", "description": "Manually close an alert event before it would close automatically on recovery. Access is checked against the screen where the alert fired.\n\n**Notes.**\n- The route-registry description names `alert-rule.edit`, but the route is gated by `screen.edit` at the event's location.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The route-registry description names `alert-rule.edit`, but the route is gated by `screen.edit` at the event's location." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alert event id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AlertEvent" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`already_closed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/alert-rules": { "get": { "operationId": "listAlertRules", "tags": [ "alert-rules" ], "summary": "List alert rules", "description": "List the alert rules configured for your workspace. Each rule includes its name, trigger, scope configuration, and whether it is enabled. Results are limited to the organization nodes you have access to. Microsoft Teams workflow URLs in `config.teamsUrls` and web addresses in `config.recipients` are credentials, so the response shows them masked: the host and the last four characters, for example `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`.", "x-brix-permission": "alert-rule.view", "x-brix-schema": "verified", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Page size. Omit to get every row; pass it to page by `cursor`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRule" } }, "nextCursor": { "description": "Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "description": "Total matching rows, when the route computes it.", "type": "integer" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "alert-rule.view" ] } ] }, "post": { "operationId": "createAlertRule", "tags": [ "alert-rules" ], "summary": "Create an alert rule", "description": "Create an alert rule with a `name`, `trigger`, optional `config`, optional `enabled` flag, and optional `nodeId`. If the scope named in `config` does not resolve to an existing target, the request is refused rather than saved. A Microsoft Teams channel is also refused unless `config.teamsUrls` contains at least one valid Microsoft Teams Workflow HTTPS URL. The response shows each URL masked.\n\n**Notes.**\n- The 201 body is the row as written, not re-read: `nodeId` is absent when the create did not set one.", "x-brix-permission": "alert-rule.create", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the row as written, not re-read: `nodeId` is absent when the create did not set one." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "trigger": { "type": "string" }, "config": { "$ref": "#/components/schemas/AlertRuleConfig" }, "enabled": { "type": "boolean" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "trigger" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Alert rule id.", "examples": [ "alr_4d5e6f7a8b9c0d1e" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "trigger": { "type": "string", "description": "The first trigger code, e.g. `connection-lost`." }, "config": { "$ref": "#/components/schemas/AlertRuleConfig" }, "enabled": { "type": "boolean" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "spaceId", "name", "trigger", "config", "enabled", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The location does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` or `trigger` is missing, the scope target does not exist, or a Microsoft Teams URL is not a workflow URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "alert-rule.create" ] } ] } }, "/v1/alert-rules/{id}": { "delete": { "operationId": "deleteAlertRule", "tags": [ "alert-rules" ], "summary": "Delete an alert rule", "description": "Delete an alert rule. It moves to the recycle bin and stops firing immediately.", "x-brix-permission": "alert-rule.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alert rule id.", "example": "alr_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such alert rule in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "alert-rule.delete" ] } ] }, "get": { "operationId": "getAlertRule", "tags": [ "alert-rules" ], "summary": "Get an alert rule", "description": "Get one alert rule, including its full trigger configuration. Access is limited to the organization nodes you can see. Microsoft Teams workflow URLs in `config.teamsUrls` and web addresses in `config.recipients` are credentials, so the response shows them masked: the host and the last four characters, for example `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`.", "x-brix-permission": "alert-rule.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alert rule id.", "example": "alr_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AlertRule" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "alert-rule.view" ] } ] }, "patch": { "operationId": "updateAlertRule", "tags": [ "alert-rules" ], "summary": "Update an alert rule", "description": "Update an alert rule's `name`, `trigger`, `config`, `enabled` flag, or `nodeId`. The same scope validation used when creating a rule applies here. To keep a saved URL, send its masked value back unchanged. To replace it, send the new URL. A masked value that matches no saved URL is refused.", "x-brix-permission": "alert-rule.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alert rule id.", "example": "alr_4d5e6f7a8b9c0d1e" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "trigger": { "type": "string" }, "config": { "$ref": "#/components/schemas/AlertRuleConfig" }, "enabled": { "type": "boolean" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseUpdatedAt": { "description": "The `updatedAt` your edit is based on; 409 with the current row if it moved.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AlertRule" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No rule with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: changed since `baseUpdatedAt`; the body carries `current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The scope target does not exist, a Microsoft Teams URL is not a workflow URL, or a masked URL matches no saved URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "alert-rule.edit" ] } ] } }, "/v1/alert-rules/{id}/restore": { "post": { "operationId": "restoreAlertRule", "tags": [ "alert-rules" ], "summary": "Restore a deleted alert rule", "description": "Restore an alert rule that was deleted within the last 30 days. The rule resumes firing once restored.", "x-brix-permission": "alert-rule.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Alert rule id.", "example": "alr_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such alert rule in this workspace, or it was purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: the rule is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "alert-rule.delete" ] } ] } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "tags": [ "api-keys" ], "summary": "List API keys", "description": "Returns the workspace's API keys: name, assigned permissions, the location the key is pinned to (if any), and when each was created and last used. Key secrets are never returned. A key is listed only where the caller holds the API key view permission at the key's location; a workspace-wide key needs that permission for the whole workspace.\n\n**Notes.**\n- Not paginated. Revoked keys are listed too (`revokedAt` set).", "x-brix-permission": "api-key.view", "x-brix-schema": "verified", "x-brix-notes": [ "Not paginated. Revoked keys are listed too (`revokedAt` set)." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "api-key.view" ] } ] }, "post": { "operationId": "createApiKey", "tags": [ "api-keys" ], "summary": "Create API key", "description": "Creates a new API key. Provide `name`, `permissions` (a list of `resource.action` strings, or `\"all\"`), and an optional `nodeId` to restrict the key to one location and everything beneath it. The raw key secret is returned exactly once, in this response; only its hash is stored afterward, so it cannot be retrieved again.", "x-brix-permission": "api-key.create", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "permissions": { "description": "You must hold each one where the key applies. Default `[]` (a key that can do nothing).", "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] }, "nodeId": { "description": "Pin the key to this location. Omit for a workspace-wide key, which needs its permissions workspace-wide.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresInDays": { "description": "Days until the key stops working (at most 3650). Omit, null or 0 = never expires.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "name" ] }, "example": { "name": "Menu board sync", "permissions": [ "screen.view", "media.create" ], "expiresInDays": 365 } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preview": { "type": "string", "description": "The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential." }, "permissions": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "`resource.action` permissions, or `\"all\"` (every permission, now and later)." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location the key is pinned to (it can act only there and below). Null = workspace-wide." }, "lastUsedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Null = never expires." }, "expired": { "type": "boolean" }, "revokedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set when the key was revoked; a revoked key no longer authenticates." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "secret": { "type": "string", "description": "The full key. Shown ONLY in this response; store it now. Send it as `Authorization: Bearer `." } }, "required": [ "id", "name", "preview", "permissions", "nodeId", "lastUsedAt", "expiresAt", "expired", "revokedAt", "createdAt", "secret" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold every permission you grant, or not at the key's location (a workspace-wide key needs them workspace-wide). Also refused for a Brix support session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` missing, `expiresInDays` over 3650 or not a number, or `nodeId` not a location of this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "api-key.create" ] } ] } }, "/v1/api-keys/{id}": { "delete": { "operationId": "deleteApiKey", "tags": [ "api-keys" ], "summary": "Revoke API key", "description": "Revokes an API key immediately, so it can no longer be used. You must hold the permission to delete keys at or above the location the key is pinned to, not merely somewhere else in the workspace.\n\n**Notes.**\n- The key stays in the list with `revokedAt` set. Revoking a key again answers 200 and moves `revokedAt` to now.", "x-brix-permission": "api-key.delete", "x-brix-schema": "verified", "x-brix-notes": [ "The key stays in the list with `revokedAt` set. Revoking a key again answers 200 and moves `revokedAt` to now." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "API key id.", "example": "ak_7a8b9c0d1e2f3a4b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "type": "boolean", "const": true } }, "required": [ "id", "revoked" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You lack `api-key.delete` at the key's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such key in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "api-key.delete" ] } ] } }, "/v1/api-keys/{id}/rotate": { "post": { "operationId": "rotateApiKey", "tags": [ "api-keys" ], "summary": "Rotate API key", "description": "Replaces an API key's secret with a new one, invalidating the old secret immediately. The new secret is returned exactly once, in this response. You must hold the permission to create keys at or above the location the key is pinned to.\n\n**Notes.**\n- The key keeps its id, name, permissions, location and expiry; `lastUsedAt` is reset to null. An expired key can be rotated and stays expired.", "x-brix-permission": "api-key.create", "x-brix-schema": "verified", "x-brix-notes": [ "The key keeps its id, name, permissions, location and expiry; `lastUsedAt` is reset to null. An expired key can be rotated and stays expired." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "API key id.", "example": "ak_7a8b9c0d1e2f3a4b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "preview": { "type": "string", "description": "The first characters of the key (`ak_us_live_Ab3x`), to recognise it. Not usable as a credential." }, "permissions": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "`resource.action` permissions, or `\"all\"` (every permission, now and later)." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location the key is pinned to (it can act only there and below). Null = workspace-wide." }, "lastUsedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Null = never expires." }, "expired": { "type": "boolean" }, "revokedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set when the key was revoked; a revoked key no longer authenticates." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "secret": { "type": "string", "description": "The full key. Shown ONLY in this response; store it now. Send it as `Authorization: Bearer `." } }, "required": [ "id", "name", "preview", "permissions", "nodeId", "lastUsedAt", "expiresAt", "expired", "revokedAt", "createdAt", "secret" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key holds permissions you cannot grant at its location, you lack `api-key.create` there, or a Brix support session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such key in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`revoked`: a revoked key cannot be rotated; create a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "api-key.create" ] } ] } }, "/v1/app-instances": { "get": { "operationId": "listAppInstances", "tags": [ "app-instances" ], "summary": "List app instances", "description": "List every app configured in the workspace, including its id, `appKey`, name, configuration, and node. This is the data behind the My apps grid.", "x-brix-permission": "app-instance.view", "x-brix-schema": "verified", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Page size. Omit to get every row; pass it to page by `cursor`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "With `limit`: also return `total`, the number of matching rows." }, { "name": "usableAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location id: only rows usable at that location (homed there, at the workspace root, or shared to it)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AppInstance" } }, "nextCursor": { "description": "Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "description": "Total matching rows, when the route computes it.", "type": "integer" } }, "required": [ "data" ] }, "example": { "data": [ { "id": "app_3c4d5e6f7a8b9c0d", "spaceId": "space_1a2b3c4d5e6f7a8b", "appKey": "clock", "name": "Lobby clock", "config": { "format": "24h" }, "nodeId": null, "lastSnapshotKey": null, "lastSnapshotAt": null, "importSourceId": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null } ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.view" ] } ] }, "post": { "operationId": "createAppInstance", "tags": [ "app-instances" ], "summary": "Create an app instance", "description": "Configure an app for the workspace with an `appKey`, `name`, and optional `config` and `nodeId`. `appKey` must match one of the apps offered by the store; list the available keys first with GET /v1/apps/catalog.\n\n**Notes.**\n- The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.", "x-brix-permission": "app-instance.create", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appKey": { "type": "string", "description": "A key from `GET /v1/apps/catalog`. An unknown key is refused (422 `unknown_app`)." }, "name": { "type": "string" }, "config": { "description": "The app's settings: a JSON object, or the same as a JSON string. Default `{}`.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "appKey", "name" ] }, "example": { "appKey": "clock", "name": "Lobby clock", "config": { "format": "24h" } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "App instance id.", "examples": [ "app_3c4d5e6f7a8b9c0d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "appKey": { "type": "string", "description": "The app type: a key from `GET /v1/apps/catalog` (`clock`, `weather`, `rss`, …)." }, "name": { "type": "string" }, "config": { "description": "The app's settings (JSON). The keys depend on `appKey`." }, "nodeId": { "description": "Home location, when one was set or derived.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSnapshotKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSnapshotAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "appKey", "name", "config", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "app_3c4d5e6f7a8b9c0d", "spaceId": "space_1a2b3c4d5e6f7a8b", "appKey": "clock", "name": "Lobby clock", "config": { "format": "24h" }, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null } } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing `appKey`/`name`, invalid JSON config, unknown app (`unknown_app`), or a location outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.create" ] } ] } }, "/v1/app-instances/{id}": { "delete": { "operationId": "deleteAppInstance", "tags": [ "app-instances" ], "summary": "Delete an app instance", "description": "Delete a configured app instance. Screens and playlists that reference it stop showing it.", "x-brix-permission": "app-instance.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "App instance id.", "example": "app_3c4d5e6f7a8b9c0d" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Delete even when it is shared into other places; the shares go with it." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "sharesRemoved": { "type": "integer", "description": "Shares removed with it." } }, "required": [ "id", "deleted", "sharesRemoved" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such app instance in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.delete" ] } ] }, "get": { "operationId": "getAppInstance", "tags": [ "app-instances" ], "summary": "Get an app instance", "description": "Retrieve one configured app instance, including its full configuration.", "x-brix-permission": "app-instance.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "App instance id.", "example": "app_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppInstance" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such app instance in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.view" ] } ] }, "patch": { "operationId": "updateAppInstance", "tags": [ "app-instances" ], "summary": "Update an app instance", "description": "Edit a configured app's name, configuration, or node. `config` replaces the entire configuration, so read the current value first before submitting changes.", "x-brix-permission": "app-instance.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "App instance id.", "example": "app_3c4d5e6f7a8b9c0d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "appKey": { "type": "string", "description": "A key from `GET /v1/apps/catalog`. An unknown key is refused (422 `unknown_app`)." }, "name": { "type": "string" }, "config": { "description": "The app's settings: a JSON object, or the same as a JSON string. Default `{}`.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseUpdatedAt": { "description": "Optimistic concurrency: the `updatedAt` you read. A stale value is refused with 409 `conflict` and the `current` row.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AppInstance" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such app instance in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the row changed since `baseUpdatedAt`; the body carries `current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON config or unknown app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.edit" ] } ] } }, "/v1/app-instances/{id}/duplicate": { "post": { "operationId": "duplicateAppInstance", "tags": [ "app-instances" ], "summary": "Duplicate an app instance", "description": "Create a copy of a configured app instance, including its configuration and home node, named \" copy\". Use this to reuse a tuned configuration instead of re-entering it. Requires permission to create app instances at the source instance's node.\n\n**Notes.**\n- The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.", "x-brix-permission": "app-instance.create", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "App instance id.", "example": "app_3c4d5e6f7a8b9c0d" } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "App instance id.", "examples": [ "app_3c4d5e6f7a8b9c0d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "appKey": { "type": "string", "description": "The app type: a key from `GET /v1/apps/catalog` (`clock`, `weather`, `rss`, …)." }, "name": { "type": "string" }, "config": { "description": "The app's settings (JSON). The keys depend on `appKey`." }, "nodeId": { "description": "Home location, when one was set or derived.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSnapshotKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSnapshotAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "appKey", "name", "config", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such app instance in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.create" ] } ] } }, "/v1/app-instances/{id}/restore": { "post": { "operationId": "restoreAppInstance", "tags": [ "app-instances" ], "summary": "Restore a deleted app instance", "description": "Restore an app instance that was deleted within the last 30 days. The shares removed by the delete come back. Playlist items removed by the delete do not come back; add the app to those playlists again.", "x-brix-permission": "app-instance.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "App instance id.", "example": "app_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such app instance in this workspace, or it was purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: it is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.delete" ] } ] } }, "/v1/app-instances/{id}/thumbnail": { "get": { "operationId": "getAppInstanceThumbnail", "tags": [ "app-instances" ], "summary": "Get an app instance thumbnail", "description": "Retrieve a shared preview image of an app instance. The same image is reused everywhere the app is previewed, so it loads quickly. Add `?fresh=1` to force a new image to be generated after a configuration change.\n\n**Notes.**\n- A cached image is `image/jpeg`. When there is none yet, the answer is a neutral `image/svg+xml` placeholder (header `x-brix-cache: pending`, not cached) while the image is drawn in the background; fetch it again shortly.", "x-brix-permission": "app-instance.view", "x-brix-schema": "verified", "x-brix-notes": [ "A cached image is `image/jpeg`. When there is none yet, the answer is a neutral `image/svg+xml` placeholder (header `x-brix-cache: pending`, not cached) while the image is drawn in the background; fetch it again shortly." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "App instance id.", "example": "app_3c4d5e6f7a8b9c0d" }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Skip the cached image and draw it again." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such app instance in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`browser_unavailable`: images cannot be drawn in this environment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.view" ] } ] } }, "/v1/approvals": { "get": { "operationId": "listApprovals", "tags": [ "approvals" ], "summary": "List approval requests", "description": "List approval requests the caller is allowed to see, newest first. Use `?state=` to narrow the list to requests still awaiting a decision. The response is capped because approval history only grows over time.\n\nNewest first. The route needs `screen.view`, but each request is listed only if the caller can also view (or approve) that content kind at its location — e.g. `playlist.view` for a playlist. A `screen.view`-only key gets an empty list.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "description": "Only requests in this state (`pending` = the inbox)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "At most this many (default and max 500)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRequest" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "post": { "operationId": "createApproval", "tags": [ "approvals" ], "summary": "Request approval for content", "description": "Open an approval request for a piece of content. The authenticated caller becomes the requester. Decide the request with POST /v1/approvals/:id/decide, or cancel it with POST /v1/approvals/:id/withdraw.\n\n**Notes.**\n- The request goes to the content's own location; a `nodeId` in the body is ignored. The content's review state becomes `pending`.\n- The requester is the caller (`apikey:` for a key).", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The request goes to the content's own location; a `nodeId` in the body is ignored. The content's review state becomes `pending`.", "The requester is the caller (`apikey:` for a key)." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentKind": { "type": "string", "description": "`playlist`, `schedule`, `creative`, `layout`, `media`, `app`, …" }, "contentId": { "type": "string" }, "contentName": { "type": "string" }, "note": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "changes": { "description": "Used only for content kinds the server does not compare itself.", "type": "array", "items": {} } }, "required": [ "contentKind", "contentId", "contentName" ] }, "example": { "contentKind": "playlist", "contentId": "pl_2b3c4d5e6f7a8b9c", "contentName": "Lobby Loop", "note": "New spring menu" } } } }, "responses": { "200": { "description": "Success: A request for this content is already pending: that request is returned and nothing is created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } }, "required": [ "data" ] } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The content is approved, and you do not hold its approve permission (`playlist.approve`, …) at its location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such content, or it is at a location where you do not hold `screen.view`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`contentKind`, `contentId` or `contentName` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/approvals/{id}": { "get": { "operationId": "getApproval", "tags": [ "approvals" ], "summary": "Get an approval request", "description": "Retrieve one approval request. If the request falls outside what you are allowed to see, this returns 404 rather than 403, so its existence is not revealed.\n\n**Notes.**\n- Besides `screen.view`, the caller must be able to view or approve the content kind at its location (e.g. `playlist.view`); otherwise 404.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Besides `screen.view`, the caller must be able to view or approve the content kind at its location (e.g. `playlist.view`); otherwise 404." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Approval request id.", "example": "ar_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such request, or you cannot view (or approve) that kind of content at its location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/approvals/{id}/decide": { "post": { "operationId": "decideApproval", "tags": [ "approvals" ], "summary": "Approve or reject content", "description": "Approve or reject a pending approval request. A reason is required when rejecting. The decision is applied to the underlying content's approval status.\n\nDecides the CURRENT level of the chain. Approving the last level lets the content air; approving an earlier level passes it to the next. Besides `screen.view`, the caller must be a named approver for the level or hold the content kind's approve permission (`playlist.approve`, `schedule.approve`, …) at the level's location.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Approval request id.", "example": "ar_3c4d5e6f7a8b9c0d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "decisionNote": { "description": "Required to reject.", "type": "string" } }, "required": [ "decision" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not eligible to decide this level, or `self_approval` (another approver exists).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`already_decided`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bad `decision`, or a rejection without `decisionNote`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/approvals/{id}/withdraw": { "post": { "operationId": "withdrawApproval", "tags": [ "approvals" ], "summary": "Withdraw an approval request", "description": "Cancel your own pending approval request. The content it was attached to returns to draft status.\n\n**Notes.**\n- The content's review state goes back to `draft`.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The content's review state goes back to `draft`." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Approval request id.", "example": "ar_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You are not the requester, and not an approver for the current level.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`already_decided`: the request is no longer pending.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/apps/{key}/render": { "get": { "operationId": "renderApp", "tags": [ "apps" ], "summary": "Render a catalog app", "description": "Get the rendered HTML for one app from the app catalog. This is the same output used by the player and by the content management system preview.", "x-brix-schema": "none", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for key." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/apps/catalog": { "get": { "operationId": "listAppCatalog", "tags": [ "apps" ], "summary": "List the apps this workspace can add", "description": "List the apps available to your workspace, including which ones are currently visible for your account to add.", "x-brix-permission": "app-instance.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The `appKey` to create an instance with." }, "status": { "type": "string", "enum": [ "alpha", "beta", "ga", "deprecated" ] }, "visible": { "type": "boolean", "description": "True when this workspace can add it: enabled and GA, or alpha/beta with early access." } }, "required": [ "key", "status", "visible" ] } } }, "required": [ "apps" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.view" ] } ] } }, "/v1/apps/counter/{token}": { "get": { "operationId": "getAppCounter", "tags": [ "apps" ], "summary": "Get a live counter value", "description": "Get the current value of a live counter app, such as Now Serving or Goal Tracker. Access is controlled by the `token` in the URL rather than by an API key; anyone with the token can read the value.", "x-brix-schema": "none", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for token." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] }, "post": { "operationId": "postAppCounter", "tags": [ "apps" ], "summary": "Update a live counter value", "description": "Set or adjust the value of a live counter app. Provide either an absolute value or a relative change, and the resulting value is clamped between 0 and 999999. Access is controlled by the `token` in the URL rather than by an API key.", "x-brix-schema": "none", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for token." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/apps/counter/{token}/control": { "get": { "operationId": "getAppCounterControl", "tags": [ "apps" ], "summary": "Get the counter control page", "description": "Get an HTML page with simple controls for adjusting a live counter from a phone. The page submits its changes back to the counter endpoint. Access is controlled by the `token` in the URL.", "x-brix-schema": "none", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for token." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/audit": { "get": { "operationId": "getAudit", "tags": [ "audit" ], "summary": "List activity log events", "description": "Returns the workspace's append-only activity log, newest first, with each event's actor shown by name rather than raw id, whether the actor was a person, an API key, or the system. Page with `limit` and `cursor`; `nextCursor` sits beside `data`. There are no filters: use the export for a time window. A caller limited to some locations sees only the events at those locations.\n\n**Notes.**\n- Newest first. There are no filters: page with `cursor`.\n- A caller limited to some locations sees only events at those locations, so a page can hold fewer than `limit` events while `nextCursor` is still set.", "x-brix-permission": "audit-log.view", "x-brix-schema": "verified", "x-brix-notes": [ "Newest first. There are no filters: page with `cursor`.", "A caller limited to some locations sees only events at those locations, so a page can hold fewer than `limit` events while `nextCursor` is still set." ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page size (default 200, max 500)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`nextCursor` of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `cursor` for the next (older) page; null on the last page." } }, "required": [ "data", "nextCursor" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "audit-log.view" ] } ] }, "post": { "operationId": "createAudit", "tags": [ "audit" ], "summary": "Add activity log event", "description": "Appends one client event to the workspace's activity log, for example that a help panel was opened. The `action` must be in the `cms.` namespace, so only events of that kind can be added this way. The actor is always the caller, never taken from the request body. The activity log is append-only: events can be added but never updated or deleted. Limited to 120 events a minute.\n\n**Notes.**\n- Needs only `audit-log.view`. The actor is always the caller; `ipAddress` and `userAgent` come from the request.", "x-brix-permission": "audit-log.view", "x-brix-schema": "verified", "x-brix-notes": [ "Needs only `audit-log.view`. The actor is always the caller; `ipAddress` and `userAgent` come from the request." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "Must be in the `cms.` namespace: `cms.` then lower-case letters, digits, `.`, `_` or `-` (up to 122 more characters)." }, "target": { "type": "string" }, "detail": { "type": "string" }, "nodeId": { "description": "A location you can see.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "action" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuditEvent" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`action` is missing or outside the `cms.` namespace, or `nodeId` is not a location you can see.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 events a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "audit-log.view" ] } ] } }, "/v1/audit/export": { "get": { "operationId": "exportAudit", "tags": [ "audit" ], "summary": "Export activity log feed", "description": "Returns the activity log as a feed suitable for a log collector or SIEM tool. Unlike the regular activity log listing, results are returned oldest first, so a collector can page forward from a saved position without missing or re-reading events. Returns newline-delimited JSON by default; pass `?format=json` for a human-readable array. Use the `from` and `to` parameters for a half-open time window, and the `x-brix-next-cursor` and `x-brix-has-more` response headers to page through results.\n\n**Notes.**\n- Oldest first. The default body is NDJSON: one `AuditEvent` object per line. The next-page cursor is in the `X-Brix-Next-Cursor` header (empty on the last page) and `X-Brix-Has-More` is `1` or `0`.\n- With `format=json` the body is JSON: `{ data: AuditEvent[], nextCursor: string | null }`.", "x-brix-permission": "audit-log.view", "x-brix-schema": "verified", "x-brix-notes": [ "Oldest first. The default body is NDJSON: one `AuditEvent` object per line. The next-page cursor is in the `X-Brix-Next-Cursor` header (empty on the last page) and `X-Brix-Has-More` is `1` or `0`.", "With `format=json` the body is JSON: `{ data: AuditEvent[], nextCursor: string | null }`." ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page size (default 500, max 1000)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `X-Brix-Next-Cursor` header (or `nextCursor`) of the previous page." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO-8601; events at or after this time." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO-8601; events before this time." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json" ] }, "description": "`json` answers `{ data: AuditEvent[], nextCursor }` instead of NDJSON." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "application/x-ndjson": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`from` or `to` is not an ISO-8601 timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "audit-log.view" ] } ] } }, "/v1/audit/integrity": { "get": { "operationId": "getAuditIntegrity", "tags": [ "audit" ], "summary": "Get activity log integrity chain", "description": "Returns the tamper-evidence chain for the workspace's activity log: a digest to record for later comparison, and the daily checkpoints behind it. Each complete UTC day of events is combined into one checkpoint linked to the day before. The current, still-open day is deliberately not yet included, since a checkpoint over data still being written would have to be recalculated.", "x-brix-permission": "audit-log.view", "x-brix-schema": "verified", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 400 }, "description": "Checkpoints to return, newest first (default 90, max 400)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "latestDigest": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The value to record. Null before the first day is covered." }, "coveredThrough": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "The end of the last covered day." }, "canonicalVersion": { "type": "string", "description": "The version of the row encoding the hashes use." }, "note": { "type": "string" }, "checkpoints": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer" }, "periodStart": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "periodEnd": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "rowCount": { "type": "integer" }, "firstEventId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastEventId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merkleRoot": { "type": "string" }, "prevDigest": { "type": "string", "description": "The previous checkpoint's digest, or `genesis`." }, "digest": { "type": "string" } }, "required": [ "seq", "periodStart", "periodEnd", "rowCount", "firstEventId", "lastEventId", "merkleRoot", "prevDigest", "digest" ] } } }, "required": [ "latestDigest", "coveredThrough", "canonicalVersion", "note", "checkpoints" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "audit-log.view" ] } ] } }, "/v1/audit/integrity/verify": { "post": { "operationId": "verifyAuditIntegrity", "tags": [ "audit" ], "summary": "Verify activity log integrity", "description": "Re-reads every event behind the integrity chain and recomputes it, to prove the activity log has not been altered since a digest was recorded. Returns HTTP 200 with `ok: false` when verification fails, rather than an error status, so a monitoring script can distinguish \"the log was altered\" from \"the check itself failed\". This is rate-limited because it re-reads the full log.\n\n**Notes.**\n- Answers 200 with `ok: false` when verification fails.", "x-brix-permission": "audit-log.view", "x-brix-schema": "verified", "x-brix-notes": [ "Answers 200 with `ok: false` when verification fails." ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "Checkpoints to check, newest first (default 90).", "type": "integer" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "checkpoints": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "seq": { "type": "integer" }, "periodStart": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "periodEnd": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "storedRowCount": { "type": "integer" }, "actualRowCount": { "type": "integer" }, "recomputedRoot": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rootMatches": { "type": "boolean" }, "digestMatches": { "type": "boolean" }, "chainIntact": { "type": "boolean" }, "ok": { "type": "boolean" } }, "required": [ "id", "seq", "periodStart", "periodEnd", "storedRowCount", "actualRowCount", "recomputedRoot", "rootMatches", "digestMatches", "chainIntact", "ok" ] } }, "ok": { "type": "boolean", "description": "False when any checkpoint failed: the log was changed." }, "latestDigest": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "checkpoints", "ok", "latestDigest" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 10 checks in 5 minutes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "audit-log.view" ] } ] } }, "/v1/banners": { "get": { "operationId": "listBanners", "tags": [ "banners" ], "summary": "List announcement banners", "description": "List the announcement banners this workspace has created for display inside the content management system, including each banner's title, body, tone, audience, and active state.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "post": { "operationId": "createBanner", "tags": [ "banners" ], "summary": "Create an announcement banner", "description": "Create an announcement banner with a `title` and optional `body`, `tone`, `audience`, and `active` state. `tone` defaults to \"info\" when not specified.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/banners/{id}": { "delete": { "operationId": "deleteBanner", "tags": [ "banners" ], "summary": "Delete an announcement banner", "description": "Delete an announcement banner.", "x-brix-permission": "integration.delete", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.delete" ] } ] }, "get": { "operationId": "getBanner", "tags": [ "banners" ], "summary": "Get an announcement banner", "description": "Retrieve one announcement banner.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "patch": { "operationId": "updateBanner", "tags": [ "banners" ], "summary": "Update an announcement banner", "description": "Edit an announcement banner's title, body, tone, audience, or active state.", "x-brix-permission": "integration.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/banners/{id}/restore": { "post": { "operationId": "restoreBanner", "tags": [ "banners" ], "summary": "Restore a deleted banner", "description": "Restore a previously deleted announcement banner so it is active again.", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/billing-groups": { "get": { "operationId": "listBillingGroups", "tags": [ "billing-groups" ], "summary": "List billing groups", "description": "Returns the workspace's billing groups (who pays for which screens), each with its current count of billable screens.\n\n**Notes.**\n- Sorted by name; not paginated. Unlike the single read, list rows have no `createdAt` / `updatedAt`.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "x-brix-notes": [ "Sorted by name; not paginated. Unlike the single read, list rows have no `createdAt` / `updatedAt`." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "financeContactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "financeContactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where this group's invoices go." }, "chargebeeCustomerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The billing customer linked by Brix; null until linked." }, "chargebeeSubscriptionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The subscription linked by Brix; null until linked." }, "subscriptionStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Net payment terms in days; null = the workspace default." }, "screenCount": { "type": "integer", "description": "Screens billed to this group." } }, "required": [ "id", "name", "financeContactName", "financeContactEmail", "chargebeeCustomerId", "chargebeeSubscriptionId", "subscriptionStatus", "paymentTermsDays", "screenCount" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] }, "post": { "operationId": "createBillingGroup", "tags": [ "billing-groups" ], "summary": "Create billing group", "description": "Creates a billing group with a name and finance contact. Connecting it to an account with the billing provider is a separate step; one is never created automatically here.\n\n**Notes.**\n- The group bills nothing until Brix links it to a billing account.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The group bills nothing until Brix links it to a billing account." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "financeContactName": { "type": "string" }, "financeContactEmail": { "description": "Stored in lower case.", "type": "string" }, "paymentTermsDays": { "description": "Net terms in days; rounded. Not range-checked on create.", "type": "number" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillingGroup" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/billing-groups/{id}": { "delete": { "operationId": "deleteBillingGroup", "tags": [ "billing-groups" ], "summary": "Delete billing group", "description": "Soft-deletes a billing group. Returns 409 if any screens are still billed to it; move or remove those screens first.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Billing group id.", "example": "bgrp_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`group_in_use`: screens still bill to it; move them first (`PATCH /v1/screens/:id` `billingGroupId`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] }, "get": { "operationId": "getBillingGroup", "tags": [ "billing-groups" ], "summary": "Get billing group", "description": "Returns one billing group by id.", "x-brix-permission": "billing.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Billing group id.", "example": "bgrp_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillingGroup" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such group in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.view" ] } ] }, "patch": { "operationId": "updateBillingGroup", "tags": [ "billing-groups" ], "summary": "Update billing group", "description": "Updates a billing group's name, finance contact, or invoice terms.\n\n**Notes.**\n- `paymentTermsDays` is range-checked here (1–365) but not on create.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "`paymentTermsDays` is range-checked here (1–365) but not on create." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Billing group id.", "example": "bgrp_5e6f7a8b9c0d1e2f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "financeContactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "financeContactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "description": "1–365, or null to use the workspace default.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BillingGroup" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Empty `name`, or `paymentTermsDays` outside 1–365.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/billing-groups/{id}/screens": { "post": { "operationId": "createBillingGroupScreen", "tags": [ "billing-groups" ], "summary": "Assign screens to billing group", "description": "Assigns a batch of screens to a billing group. This updates the destination group, every group the screens are moving from, and the workspace subscription, so screen counts and billing stay in sync.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Billing group id.", "example": "bgrp_5e6f7a8b9c0d1e2f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "screenIds": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Up to 500 are read; more are ignored. Ids that are not live screens are skipped." } }, "required": [ "screenIds" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "assigned": { "type": "integer", "description": "Screens moved into the group." }, "skipped": { "type": "integer", "description": "Ids not moved (unknown, or already in the group)." }, "screenCount": { "type": "integer" } }, "required": [ "id", "assigned", "skipped", "screenCount" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You lack `billing.edit` at one of the screens' locations (the response names them in `screenIds`); nothing changes. Also: You do not hold the permission for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such group, or none of the ids is a live screen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`screenIds` missing or empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/casts": { "get": { "operationId": "listCasts", "tags": [ "casts" ], "summary": "List casts", "description": "List casts, which are timed content takeovers, newest first. Use `?status=active` to filter to casts currently on air, and `?limit` (up to 500, default 200) to bound the number of results. Cast history is kept indefinitely.", "x-brix-permission": "screen.cast", "x-brix-schema": "verified", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "cleared", "expired" ] }, "description": "Only casts in this state." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "At most this many, newest first (default 200, max 500)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Override" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "cast_9f2c4a1b7d3e5f60", "spaceId": "space_1a2b3c4d5e6f7a8b", "kind": "cast", "status": "active", "severity": "info", "headline": "Friday lunch special", "body": null, "contentKind": "media", "contentId": "med_0c1d2e3f4a5b6c7d", "scopeKind": "screens", "scopeNodeId": null, "nodeId": null, "screenCount": 2, "triggeredBy": "usr_5e6f7a8b9c0d1e2f", "triggeredAt": "2026-09-28T11:30:00.000Z", "expiresAt": "2026-09-28T13:30:00.000Z", "clearedBy": null, "clearedAt": null, "triggeredByName": "Sam Rivera", "clearedByName": null, "scopeName": null, "confirmedCount": null } ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.cast" ] } ] }, "post": { "operationId": "castContent", "tags": [ "casts" ], "summary": "Cast content to screens", "description": "Put content on air across a set of screens for a period of time, after which the screens automatically revert to their normal content. Send `contentKind` (media, playlist, app, creative, or schedule), `contentId`, `scopeKind`, and optionally `scopeNodeId`, `screenIds`, and `expiresAt`. `scopeKind` accepts all, node, or screens and defaults to all: a request sent with no scope casts to every screen the caller can reach. An active emergency override takes priority over a cast, and the cast resumes automatically once the emergency is cleared.\n\nPuts one piece of content on the chosen screens now, above their schedule, until it expires or is cleared. An emergency still pre-empts a cast.", "x-brix-permission": "screen.cast", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentKind": { "type": "string", "enum": [ "media", "playlist", "app", "creative", "schedule" ], "description": "What kind of thing `contentId` names." }, "contentId": { "type": "string", "description": "The media, playlist, app instance, creative or schedule to put on air." }, "contentName": { "description": "Label for the cast (shown in the console). Defaults to \"Cast\".", "type": "string" }, "scopeKind": { "description": "Which screens: every screen you can reach (`all`), one location's subtree (`node`), or a list (`screens`). **Defaults to `all`: omit it and the cast goes to EVERY screen you can reach.**", "type": "string", "enum": [ "all", "node", "screens" ] }, "scopeNodeId": { "description": "Location id, with `scopeKind: node`.", "type": "string" }, "screenIds": { "description": "Screen ids, with `scopeKind: screens`.", "type": "array", "items": { "type": "string" } }, "expiresAt": { "description": "When the cast ends by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.", "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "required": [ "contentKind", "contentId" ] }, "example": { "contentKind": "media", "contentId": "med_0c1d2e3f4a5b6c7d", "contentName": "Friday lunch special", "scopeKind": "screens", "screenIds": [ "scr_1a2b3c4d5e6f7a8b", "scr_2b3c4d5e6f7a8b9c" ], "expiresAt": "2026-09-28T13:30:00.000Z" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Override" } }, "required": [ "data" ] }, "example": { "data": { "id": "cast_9f2c4a1b7d3e5f60", "spaceId": "space_1a2b3c4d5e6f7a8b", "kind": "cast", "status": "active", "severity": "info", "headline": "Friday lunch special", "body": null, "contentKind": "media", "contentId": "med_0c1d2e3f4a5b6c7d", "scopeKind": "screens", "scopeNodeId": null, "nodeId": null, "screenCount": 2, "triggeredBy": "usr_5e6f7a8b9c0d1e2f", "triggeredAt": "2026-09-28T11:30:00.000Z", "expiresAt": "2026-09-28T13:30:00.000Z", "clearedBy": null, "clearedAt": null, "triggeredByName": "Sam Rivera", "clearedByName": null, "scopeName": null, "confirmedCount": null } } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not shared to one or more target locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The content does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid body, the scope matched no screens you can reach (`no_screens`), or the content cannot play (empty playlist, unprocessed media).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.cast" ] } ] } }, "/v1/casts/{id}/clear": { "post": { "operationId": "endCast", "tags": [ "casts" ], "summary": "End a cast", "description": "End a cast immediately and return its screens to their scheduled content.\n\nEnds an active cast; its screens return to their scheduled content immediately.", "x-brix-permission": "screen.cast", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast id.", "example": "cast_9f2c4a1b7d3e5f60" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Override" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such cast in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`already_inactive`: the cast is already cleared or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.cast" ] } ] } }, "/v1/celebration-entries": { "get": { "operationId": "listCelebrationEntries", "tags": [ "celebration-entries" ], "summary": "List celebration entries", "description": "Return the roster of birthdays, anniversaries, and other occasions that the Celebrations app displays.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "post": { "operationId": "createCelebrationEntry", "tags": [ "celebration-entries" ], "summary": "Create a celebration entry", "description": "Add an entry to the celebration roster. Requires name; also accepts occasionType, occasionMonth, occasionDay, occasionYear, photoUrl, department, title, location, customMessage, sourceId, and externalId, all optional.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/celebration-entries/{id}": { "delete": { "operationId": "deleteCelebrationEntry", "tags": [ "celebration-entries" ], "summary": "Delete a celebration entry", "description": "Remove an entry from the celebration roster. The entry moves to the recycle bin and can be brought back with the restore operation.", "x-brix-permission": "integration.delete", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.delete" ] } ] }, "get": { "operationId": "getCelebrationEntry", "tags": [ "celebration-entries" ], "summary": "Get a celebration entry", "description": "Return one entry from the celebration roster.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "patch": { "operationId": "updateCelebrationEntry", "tags": [ "celebration-entries" ], "summary": "Update a celebration entry", "description": "Edit one entry in the celebration roster. Accepts any of the fields used when creating an entry.", "x-brix-permission": "integration.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/celebration-entries/{id}/restore": { "post": { "operationId": "restoreCelebrationEntry", "tags": [ "celebration-entries" ], "summary": "Restore a celebration entry", "description": "Bring back a deleted celebration entry so it appears again in the celebration app's roster.", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connected-apps": { "get": { "operationId": "listConnectedApps", "tags": [ "connected-apps" ], "summary": "List connected apps", "description": "Returns the AI assistants and other MCP clients that people in this workspace connected with OAuth: the client, who connected it, its permissions, the location it is pinned to, and when it was last used. You see a connection only where you hold the permission to view API keys at its location.\n\n**Notes.**\n- Newest first. Only connections whose location the caller can see with `api-key.view` are listed.", "x-brix-permission": "api-key.view", "x-brix-schema": "verified", "x-brix-notes": [ "Newest first. Only connections whose location the caller can see with `api-key.view` are listed." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Connection id." }, "clientId": { "type": "string" }, "clientName": { "type": "string", "description": "The app's name, as it registered." }, "redirectHost": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The host the app signs in through." }, "connectedBy": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ], "description": "The person who approved it; null if they no longer exist." }, "permissions": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location the connection is limited to; null for the whole workspace." }, "lastUsedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "connectedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "clientId", "clientName", "redirectHost", "connectedBy", "permissions", "nodeId", "lastUsedAt", "connectedAt" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "api-key.view" ] } ] } }, "/v1/connected-apps/{id}": { "delete": { "operationId": "deleteConnectedApp", "tags": [ "connected-apps" ], "summary": "Disconnect connected app", "description": "Disconnects an app that was connected with OAuth. Its access stops immediately. You must hold the permission to delete API keys at the location the connection is pinned to.\n\n**Notes.**\n- Answers the same for a connection that was already revoked.", "x-brix-permission": "api-key.delete", "x-brix-schema": "verified", "x-brix-notes": [ "Answers the same for a connection that was already revoked." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Connection id.", "example": "oag_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "type": "boolean", "const": true } }, "required": [ "id", "revoked" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold `api-key.delete` where the connection is limited to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "api-key.delete" ] } ] } }, "/v1/connectors": { "get": { "operationId": "listConnectors", "tags": [ "connectors" ], "summary": "List connector types", "description": "List the data-source connector types: the `type` to use when you create a data source, its label and category, and whether it is available yet.", "x-brix-permission": "integration.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] } }, "/v1/connectors/probe": { "post": { "operationId": "createConnectorProbe", "tags": [ "connectors" ], "summary": "Test a connector URL", "description": "Test whether the platform can reach a given endpoint, behind the Test connection action used before creating a data source. The request is made from the server rather than the browser. Requests to private or internal network addresses are blocked.\n\nSends a GET to the URL from the server and returns the status and the start of the body. Rate limited to 20 calls a minute.\n\n**Notes.**\n- A URL that cannot be reached is not an HTTP error: the answer is 200 with `ok: false`, `status: 0` and `error`.\n- A blocked private or internal address answers 400 with the `{ data: { ok: false, status: 0, error } }` body, not the usual error body.", "x-brix-permission": "integration.create", "x-brix-schema": "verified", "x-brix-notes": [ "A URL that cannot be reached is not an HTTP error: the answer is 200 with `ok: false`, `status: 0` and `error`.", "A blocked private or internal address answers 400 with the `{ data: { ok: false, status: 0, error } }` body, not the usual error body." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "An http(s) URL on the public internet." }, "token": { "description": "Sent as `Authorization: Bearer `. Not stored.", "type": "string" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status the URL answered with." }, "ok": { "type": "boolean", "description": "The status was 2xx." }, "contentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sample": { "type": "string", "description": "The first 4000 characters of the response body." }, "truncated": { "type": "boolean", "description": "The body was longer than `sample`." } }, "required": [ "status", "ok", "contentType", "sample", "truncated" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "status": { "type": "number", "const": 0 }, "error": { "type": "string", "description": "Why the request did not complete (network failure, timeout, or a blocked address)." } }, "required": [ "ok", "status", "error" ] } ] } }, "required": [ "data" ] } } } }, "400": { "description": "`bad_request`: the URL is not http(s). A private or internal address also answers 400, with the `data` body (`ok: false`, `status: 0`, `error`) instead of an error body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 20 calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/contact": { "get": { "operationId": "getContact", "tags": [ "contact" ], "summary": "List support messages", "description": "Returns messages sent to Brix through the contact endpoint, newest first, up to a capped number of results. A caller with `screen.view` for the whole workspace gets all of the workspace's messages. Any other caller gets only the messages they sent.\n\n**Notes.**\n- Newest first, at most 200. A caller without `screen.view` for the whole workspace gets only the messages sent from their own email address, so an API key limited to a location always gets an empty list.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Newest first, at most 200. A caller without `screen.view` for the whole workspace gets only the messages sent from their own email address, so an API key limited to a location always gets an empty list." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "fromEmail": { "type": "string", "description": "The sender: a person's email, or the key's contact address." }, "subject": { "type": "string" }, "message": { "type": "string" }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The `source` tag the sender set, else the `sourcePath`." }, "emailSent": { "type": "boolean", "description": "The message reached the support inbox by email." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "spaceId", "fromEmail", "subject", "message", "source", "emailSent", "createdAt" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "post": { "operationId": "createContact", "tags": [ "contact" ], "summary": "Send support message", "description": "Sends a message to Brix, for example through a \"Send message / report a problem\" dialog. Provide `subject` and `message`, and optionally `source` and `sourcePath` to indicate where the message was sent from. The sender is always the caller (the signed-in person or the API key), never taken from the request body. Limited to 10 requests per minute.\n\n**Notes.**\n- The sender is always the caller; an `email` field in the body is ignored.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The sender is always the caller; an `email` field in the body is ignored." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 200, "description": "Trimmed; 1–200 characters." }, "message": { "type": "string", "maxLength": 5000, "description": "Trimmed; 1–5000 characters." }, "source": { "description": "A tag for where the message came from (cut at 500 characters).", "type": "string" }, "sourcePath": { "description": "The page the sender was on (cut at 500 characters).", "type": "string" } }, "required": [ "subject", "message" ] }, "example": { "subject": "Screen will not pair", "message": "The lobby screen shows a pairing code that does not work.", "source": "api" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "emailSent": { "type": "boolean" }, "closeNoted": { "type": "boolean", "description": "The message was also added to the workspace's record in the Brix customer system." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "`email_not_sent`, `close_note_failed`. The message is stored either way." } }, "required": [ "id", "emailSent", "closeNoted", "warnings" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The workspace or the sender could not be resolved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`subject` or `message` is empty or too long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 10 messages a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/creative-overrides/{creativeId}": { "get": { "operationId": "getCreativeOverride", "tags": [ "creative-overrides" ], "summary": "Get a creative's overrides at a location", "description": "Return the edits a location has made to a creative that was shared with it, the merged result of applying those edits, and any edits that have stopped applying.", "x-brix-permission": "creative.view", "x-brix-schema": "verified", "parameters": [ { "name": "creativeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Creative id: one of yours, or one shared into this workspace.", "example": "cr_4d5e6f7a8b9c0d1e" }, { "name": "node", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location id. Default: the workspace root." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "creativeId": { "type": "string" }, "nodeId": { "type": "string", "description": "The location the edits apply at." }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "The location's edits: box id → the box fields it changes (for example `{ \"price\": { \"text\": \"13.00\" } }`)." }, "overrideId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the stored edits (what an approval request is opened against); null before the first save." }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state of the edits (not of the design)." }, "requiresApproval": { "type": "boolean", "description": "The location requires approval before the edits air." }, "skipsApproval": { "type": "boolean", "description": "The author waived that review for this design." }, "creative": { "description": "The design with the edits applied: what the screens play.", "$ref": "#/components/schemas/OverrideCreative" }, "orphanedBoxIds": { "type": "array", "items": { "type": "string" }, "description": "Edited box ids the design no longer has." }, "sharedFrom": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The workspace that owns the design, when it was shared in from another workspace." }, "base": { "description": "The design without the edits.", "$ref": "#/components/schemas/OverrideCreative" }, "rejectedFields": { "type": "array", "items": { "type": "string" }, "description": "`boxId.field` edits that no longer apply because the author locked the field." }, "updatedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "When the edits were last saved; null before the first save." } }, "required": [ "creativeId", "nodeId", "values", "overrideId", "approvalState", "requiresApproval", "skipsApproval", "creative", "orphanedBoxIds", "sharedFrom", "base", "rejectedFields", "updatedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown location, no such creative, or the creative is not usable at that location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.view" ] } ] }, "put": { "operationId": "replaceCreativeOverride", "tags": [ "creative-overrides" ], "summary": "Replace a creative's overrides at a location", "description": "Replace a location's edits to a shared creative. If the creative's author has locked a field against editing, the request is rejected with a 422 error for that field.\n\n**Notes.**\n- The response has no `sharedFrom`, `base` or `rejectedFields` (GET has them). A save returns approved edits to `draft`.", "x-brix-permission": "creative.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The response has no `sharedFrom`, `base` or `rejectedFields` (GET has them). A save returns approved edits to `draft`." ], "parameters": [ { "name": "creativeId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Creative id: one of yours, or one shared into this workspace.", "example": "cr_4d5e6f7a8b9c0d1e" }, { "name": "node", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location id. Default: the workspace root." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Every edit to keep, at most 300 boxes. Edits left out are removed." } }, "required": [ "values" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "creativeId": { "type": "string" }, "nodeId": { "type": "string", "description": "The location the edits apply at." }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "The location's edits: box id → the box fields it changes (for example `{ \"price\": { \"text\": \"13.00\" } }`)." }, "overrideId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Id of the stored edits (what an approval request is opened against); null before the first save." }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state of the edits (not of the design)." }, "requiresApproval": { "type": "boolean", "description": "The location requires approval before the edits air." }, "skipsApproval": { "type": "boolean", "description": "The author waived that review for this design." }, "creative": { "description": "The design with the edits applied: what the screens play.", "$ref": "#/components/schemas/OverrideCreative" }, "orphanedBoxIds": { "type": "array", "items": { "type": "string" }, "description": "Edited box ids the design no longer has." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "creativeId", "nodeId", "values", "overrideId", "approvalState", "requiresApproval", "skipsApproval", "creative", "orphanedBoxIds", "updatedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You lack creative.edit at that location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown location, no such creative, or the creative is not usable at that location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`validation_error` (bad `values`, more than 300 boxes, unknown box ids in `unknownBoxes`) or `locked` (fields the author locked, in `violations`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.edit" ] } ] } }, "/v1/creatives": { "get": { "operationId": "listCreatives", "tags": [ "creatives" ], "summary": "List creatives", "description": "Return the workspace's canvas creatives, including each one's name, stage size, location, and sharing state. The full layout of shapes is not included; use the get-creative operation to retrieve that.", "x-brix-permission": "creative.view", "x-brix-schema": "verified", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Page size. Omit to get every row; pass it to page by `cursor`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "With `limit`: also return `total`, the number of matching rows." }, { "name": "usableAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location id: only rows usable at that location (homed there, at the workspace root, or shared to it)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Creative" } }, "nextCursor": { "description": "Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "description": "Total matching rows, when the route computes it.", "type": "integer" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.view" ] } ] }, "post": { "operationId": "createCreative", "tags": [ "creatives" ], "summary": "Create a creative", "description": "Create a canvas creative. Accepts name and optional boxes, scenes, stageWidth, stageHeight, backgroundUrl, dataSourceId, touchEnabled, nodeId, and masterId. Safe to retry with the same Idempotency-Key header without creating duplicates.\n\n**Notes.**\n- The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.\n- Send an `Idempotency-Key` header to make a retry safe.", "x-brix-permission": "creative.create", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.", "Send an `Idempotency-Key` header to make a retry safe." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "backgroundUrl": { "description": "An unsafe URL scheme is stored as null.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "boxes": { "description": "The whole box list; each box is checked and filled out with defaults. Default `[]`.", "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "dataSourceId": { "description": "A data source in this workspace.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "stageHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "scenes": { "description": "Default `[]`.", "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "touchEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceSignage": {}, "masterId": { "description": "The master template it was made from (`GET /v1/signage-master-templates`).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shareLockDefault": { "description": "Which box fields recipients may edit when it is shared (JSON)." }, "shareEditsSkipApproval": { "description": "Recipients' edits air without review. Needs `creative.approve`.", "type": "boolean" }, "look": { "anyOf": [ { "type": "object", "properties": { "design": { "type": "string", "enum": [ "brix-sidebar", "brix-header", "brix-cinema", "brix-welcome" ] }, "source": { "type": "string", "enum": [ "brand", "custom" ] }, "style": { "type": "string", "enum": [ "flat", "panels", "deep" ] }, "accent": { "description": "`#rrggbb`.", "type": "string" }, "accent2": { "description": "`#rrggbb`.", "type": "string" }, "mode": { "type": "string", "enum": [ "dark", "light" ] } }, "required": [ "design", "source", "style" ], "description": "Look of a Brix Template design. `null` clears it." }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Creative id.", "examples": [ "cr_4d5e6f7a8b9c0d1e" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "backgroundUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "boxes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "The design's boxes (text, image, data-bound fields…), in paint order." }, "dataSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The data source the boxes bind to, if any." }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stage preset name." }, "stageWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "stageHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "scenes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Scenes, for a multi-scene design; often empty." }, "touchEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state. Editing an approved row returns it to `draft`." }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON TEXT of the last approved version (not parsed)." }, "sourceSignage": { "anyOf": [ {}, { "type": "null" } ], "description": "The template it was made from (JSON), if any." }, "look": { "anyOf": [ {}, { "type": "null" } ], "description": "Accent / Brand Kit / light-dark settings (JSON), if set." }, "masterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The master template id, for a design made from one." }, "shareLockDefault": { "anyOf": [ {}, { "type": "null" } ], "description": "Which boxes recipients may edit when shared (JSON), if set." }, "shareEditsSkipApproval": { "type": "boolean" }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "name", "boxes", "scenes", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Setting `shareEditsSkipApproval` without `creative.approve`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`dataSourceId` names no data source in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing name, invalid JSON, malformed boxes, scenes or look, or a location outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.create" ] } ] } }, "/v1/creatives/{id}": { "delete": { "operationId": "deleteCreative", "tags": [ "creatives" ], "summary": "Delete a creative", "description": "Move a creative to the recycle bin. If the creative is shared into other locations, the request fails with a 409 error unless the deletion is explicitly confirmed, since deleting a shared creative removes it everywhere it is shared.", "x-brix-permission": "creative.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Creative id.", "example": "cr_4d5e6f7a8b9c0d1e" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Delete even when it is shared into other places; the shares go with it." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "sharesRemoved": { "type": "integer", "description": "Shares removed with it." } }, "required": [ "id", "deleted", "sharesRemoved" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such creative in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.delete" ] } ] }, "get": { "operationId": "getCreative", "tags": [ "creatives" ], "summary": "Get a creative", "description": "Return one creative in full, including its boxes, scenes, background, any linked data source, and stage dimensions.", "x-brix-permission": "creative.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Creative id.", "example": "cr_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Creative id.", "examples": [ "cr_4d5e6f7a8b9c0d1e" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "backgroundUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "boxes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "The design's boxes (text, image, data-bound fields…), in paint order." }, "dataSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The data source the boxes bind to, if any." }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stage preset name." }, "stageWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "stageHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "scenes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Scenes, for a multi-scene design; often empty." }, "touchEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state. Editing an approved row returns it to `draft`." }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON TEXT of the last approved version (not parsed)." }, "sourceSignage": { "anyOf": [ {}, { "type": "null" } ], "description": "The template it was made from (JSON), if any." }, "look": { "anyOf": [ {}, { "type": "null" } ], "description": "Accent / Brand Kit / light-dark settings (JSON), if set." }, "masterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The master template id, for a design made from one." }, "shareLockDefault": { "anyOf": [ {}, { "type": "null" } ], "description": "Which boxes recipients may edit when shared (JSON), if set." }, "shareEditsSkipApproval": { "type": "boolean" }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." }, "requiresApproval": { "type": "boolean", "description": "The home location requires approval before content airs." }, "canEditBase": { "type": "boolean", "description": "The caller may edit the design itself (not only its unlocked boxes)." }, "canWaiveApproval": { "type": "boolean", "description": "The caller holds `creative.approve` at its home location." } }, "required": [ "id", "spaceId", "name", "backgroundUrl", "boxes", "dataSourceId", "stage", "stageWidth", "stageHeight", "scenes", "touchEnabled", "nodeId", "approvalState", "approvedSnapshot", "sourceSignage", "look", "masterId", "shareLockDefault", "shareEditsSkipApproval", "recalledAt", "recalledBy", "createdAt", "updatedAt", "deletedAt", "requiresApproval", "canEditBase", "canWaiveApproval" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such creative in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.view" ] } ] }, "patch": { "operationId": "updateCreative", "tags": [ "creatives" ], "summary": "Update a creative", "description": "Edit a creative. The boxes and scenes fields each replace the entire existing list, so retrieve the creative first and send back the complete array with changes included. If the location requires approval before content goes live, updating the creative resets that approval.\n\n**Notes.**\n- The response is the stored row: it has no `requiresApproval`, `canEditBase` or `canWaiveApproval` (GET has them).", "x-brix-permission": "creative.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The response is the stored row: it has no `requiresApproval`, `canEditBase` or `canWaiveApproval` (GET has them)." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Creative id.", "example": "cr_4d5e6f7a8b9c0d1e" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "backgroundUrl": { "description": "An unsafe URL scheme is stored as null.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "boxes": { "description": "The whole box list; each box is checked and filled out with defaults. Default `[]`.", "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "dataSourceId": { "description": "A data source in this workspace.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stageWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "stageHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "scenes": { "description": "Default `[]`.", "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "touchEnabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceSignage": {}, "masterId": { "description": "The master template it was made from (`GET /v1/signage-master-templates`).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shareLockDefault": { "description": "Which box fields recipients may edit when it is shared (JSON)." }, "shareEditsSkipApproval": { "description": "Recipients' edits air without review. Needs `creative.approve`.", "type": "boolean" }, "look": { "anyOf": [ { "type": "object", "properties": { "design": { "type": "string", "enum": [ "brix-sidebar", "brix-header", "brix-cinema", "brix-welcome" ] }, "source": { "type": "string", "enum": [ "brand", "custom" ] }, "style": { "type": "string", "enum": [ "flat", "panels", "deep" ] }, "accent": { "description": "`#rrggbb`.", "type": "string" }, "accent2": { "description": "`#rrggbb`.", "type": "string" }, "mode": { "type": "string", "enum": [ "dark", "light" ] } }, "required": [ "design", "source", "style" ], "description": "Look of a Brix Template design. `null` clears it." }, { "type": "null" } ] }, "baseUpdatedAt": { "description": "Optimistic concurrency: the `updatedAt` you read. A stale value is refused with 409 `conflict` and the `current` row.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Creative" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Moving it to a location where you lack creative.edit, or changing `shareEditsSkipApproval` without `creative.approve`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such creative (or `dataSourceId`) in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the row changed since `baseUpdatedAt`; the body carries `current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON or malformed boxes, scenes or look.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.edit" ] } ] } }, "/v1/creatives/{id}/restore": { "post": { "operationId": "restoreCreative", "tags": [ "creatives" ], "summary": "Restore a creative", "description": "Bring back a deleted creative so it returns to the library. The shares removed by the delete come back with it.", "x-brix-permission": "creative.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Creative id.", "example": "cr_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such creative in this workspace, or it was purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: the creative is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.delete" ] } ] } }, "/v1/creatives/{id}/thumbnail": { "get": { "operationId": "getCreativeThumbnail", "tags": [ "creatives" ], "summary": "Get a creative's thumbnail", "description": "Return an image of the creative, showing its shapes and pictures along with a representative preview of each content slot, such as a file's poster image, a playlist's first item, or an app's most recent snapshot. Text boxes are not drawn. The image is cached; add ?fresh=1 to bypass the cache after making an edit.", "x-brix-permission": "creative.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Creative id.", "example": "cr_4d5e6f7a8b9c0d1e" }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Skip the cached image and draw it again." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such creative in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.view" ] } ] } }, "/v1/cross-space-shares": { "get": { "operationId": "listCrossSpaceShares", "tags": [ "cross-space-shares" ], "summary": "List cross-space shares", "description": "List content this space shares into its child spaces, and content shared with it in turn. A space receiving a share can read it but cannot change or remove it.", "x-brix-permission": "playlist.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.view" ] } ] }, "post": { "operationId": "createCrossSpaceShare", "tags": [ "cross-space-shares" ], "summary": "Share content into a child space", "description": "Share a playlist, layout, schedule, or creative from this space into a child space. The shared content appears in the child space alongside its own content. Only the space that owns the content can create the share. Requires view permission on shares plus the appropriate permission on the content itself.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cross-space-shares/{id}": { "delete": { "operationId": "deleteCrossSpaceShare", "tags": [ "cross-space-shares" ], "summary": "Remove a cross-space share", "description": "Withdraw a share. Only the space that created the share can remove it; the receiving space cannot.", "x-brix-permission": "playlist.view", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.view" ] } ] } }, "/v1/data-sources": { "get": { "operationId": "listDataSources", "tags": [ "data-sources" ], "summary": "List data sources", "description": "List the data feeds, such as spreadsheets, APIs, and other connectors, that creatives and apps can connect to. Credentials are encrypted at rest and are never returned.\n\n**Notes.**\n- Not paginated: every data source you can see comes back in one response (no `?limit`/`?cursor`, unlike the app instance, creative and layout lists).", "x-brix-permission": "integration.view", "x-brix-schema": "verified", "x-brix-notes": [ "Not paginated: every data source you can see comes back in one response (no `?limit`/`?cursor`, unlike the app instance, creative and layout lists)." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataSource" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "post": { "operationId": "createDataSource", "tags": [ "data-sources" ], "summary": "Create a data source", "description": "Connect a data feed with a `name`, a connector `type`, a `config`, and an optional `nodeId`. Any credentials included in `config` are encrypted at rest. Test the configuration first with POST /v1/data-sources/test before creating it.\n\n**Notes.**\n- Gated by `integration.edit`, not `integration.create`.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Gated by `integration.edit`, not `integration.create`." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "description": "Connector type from `GET /v1/connectors`. The value is not checked here: an unknown type fails at the first sync." }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`." }, "nodeId": { "description": "Home location; null or absent = workspace root. The key needs the permission there.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "type" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DataSource" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` or `type` is missing, or `invalid_node`: the location is not in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/data-sources/{id}": { "delete": { "operationId": "deleteDataSource", "tags": [ "data-sources" ], "summary": "Delete a data source", "description": "Delete a data source. It can be restored later with POST /v1/data-sources/:id/restore. Creatives connected to it display their fallback values while it is deleted.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Data source id.", "example": "ds_6f7a8b9c0d1e2f3a" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such data source in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] }, "get": { "operationId": "getDataSource", "tags": [ "data-sources" ], "summary": "Get a data source", "description": "Retrieve one data source, including its connector configuration, the time of its last sync, and its row schema. Secret values are redacted.", "x-brix-permission": "integration.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Data source id.", "example": "ds_6f7a8b9c0d1e2f3a" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DataSource" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such data source in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "patch": { "operationId": "updateDataSource", "tags": [ "data-sources" ], "summary": "Update a data source", "description": "Edit a data source's name, connector configuration, or node.\n\nSend `••••••••` back for a credential to keep the stored value. To point the source at a different address or connector type, enter the credential again.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Data source id.", "example": "ds_6f7a8b9c0d1e2f3a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "description": "A change of type needs `config` with the credentials entered again.", "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`." }, "nodeId": { "description": "Move it; the key needs `integration.edit` at the destination too.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DataSource" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No `integration.edit` at the destination location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such data source in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`credential_reentry_required`: the change moves a masked credential to a new address or connector type (`fields` names what moved); or `invalid_node`: the destination is not in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/data-sources/{id}/restore": { "post": { "operationId": "restoreDataSource", "tags": [ "data-sources" ], "summary": "Restore a deleted data source", "description": "Restore a deleted data source connector. Apps and creatives connected to it begin receiving fresh data again the next time their content refreshes.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Data source id.", "example": "ds_6f7a8b9c0d1e2f3a" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such data source in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: the data source is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/data-sources/{id}/sync": { "post": { "operationId": "syncDataSource", "tags": [ "data-sources" ], "summary": "Sync a data source now", "description": "Pull fresh data for one data source immediately instead of waiting for its regular schedule.\n\nRuns the connector once and caches the result. A connector failure is NOT an HTTP error: the answer is 200 with `synced: false` and the reason.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Data source id.", "example": "ds_6f7a8b9c0d1e2f3a" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "synced": { "type": "boolean", "const": true } }, "required": [ "id", "synced" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "synced": { "type": "boolean", "const": false }, "error": { "type": "string", "description": "Why the connector failed. Also stored as the source's `syncError`." } }, "required": [ "id", "synced", "error" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such data source in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/data-sources/refresh-all": { "post": { "operationId": "refreshAllDataSources", "tags": [ "data-sources" ], "summary": "Sync every data source", "description": "Pull fresh data for every data source in the workspace immediately. This action is rate-limited to 5 requests per minute.\n\nSyncs, one after another, every data source the caller may edit. Rate limited to 5 calls a minute.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "integer" }, "ok": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "total", "ok", "failed" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 5 calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/data-sources/sheets-methods": { "get": { "operationId": "listDataSourceSheetsMethods", "tags": [ "data-sources" ], "summary": "List Google Sheets sharing methods", "description": "List the ways a Google Sheet can be shared with the platform, and the address to share it with. The response may include `publicLink`, `serviceAccount`, and `oauth`, depending on what the platform supports; a method is listed only if it is actually available. `serviceAccount` is not a secret; it is the address you enter into Google's Share dialog.", "x-brix-permission": "integration.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "publicLink": { "type": "boolean", "const": true, "description": "A sheet shared as \"anyone with the link\" always works." }, "serviceAccount": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The address to share a private sheet with; null when this method is not available." }, "oauth": { "type": "boolean", "description": "A private sheet can be picked by signing in with Google." } }, "required": [ "publicLink", "serviceAccount", "oauth" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] } }, "/v1/data-sources/test": { "post": { "operationId": "testDataSource", "tags": [ "data-sources" ], "summary": "Test a data source config", "description": "Validate a connector configuration without saving it. Returns `{ ok: true, preview }` on success or `{ ok: false, error }` on failure, so a misconfigured feed can be caught before it is created.\n\nRuns the connector once with a config that is not saved. A connector failure is NOT an HTTP error: the answer is 200 with `ok: false` and the reason. Rate limited to 20 calls a minute.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Connector settings (JSON). The keys depend on `type`. Credentials are encrypted at rest and every later read shows them as `••••••••`." } }, "required": [ "type" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "preview": { "type": "string", "description": "The fetched data as JSON text, cut to 2000 characters." } }, "required": [ "ok", "preview" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "type": "string", "description": "Why the connector failed, or that no connector has this `type`." } }, "required": [ "ok", "error" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 20 calls in a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/device-preassignments": { "get": { "operationId": "listDevicePreassignments", "tags": [ "device-preassignments" ], "summary": "List pre-assigned devices", "description": "List devices pre-assigned to locations in your workspace. Each entry shows the end of the device serial number, the location, the screen name, and whether the device is still waiting to be claimed or has already been claimed. Results are limited to the organization nodes you can see.\n\n**Notes.**\n- Carries `available` beside `data`.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Carries `available` beside `data`." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "serialHint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The last 4 characters of the serial. The full serial is not stored." }, "nodeId": { "type": "string" }, "locationName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The location's own id (its Location ID), when set." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "waiting", "claimed" ] }, "claimedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "claimedScreenId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "serialHint", "nodeId", "locationName", "locationId", "name", "status", "claimedAt", "claimedScreenId", "createdAt" ] } }, "available": { "type": "boolean", "description": "False when the workspace's data region does not support pre-assignment yet (`data` is then empty)." } }, "required": [ "data", "available" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "post": { "operationId": "createDevicePreassignment", "tags": [ "device-preassignments" ], "summary": "Pre-assign devices to locations", "description": "Pre-assign device serial numbers to locations, identified by Location ID or `nodeId`, so each device pairs automatically into its assigned location the first time it is plugged in. Submit up to 1000 rows in one request; all rows are validated before any are saved. Re-uploading the same rows is safe and does not create duplicates, and `dryRun` validates rows without saving them. A serial number already assigned to another workspace is refused with a conflict error, and the action is recorded in the activity log.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "serial": { "type": "string", "description": "The device serial number." }, "locationId": { "description": "The location's Location ID (case-insensitive). Give this or `nodeId`.", "type": "string" }, "nodeId": { "type": "string" }, "name": { "description": "Screen name; default: the location name and the serial's last 4 characters.", "type": "string" } }, "required": [ "serial" ] } }, "dryRun": { "description": "True: check and report, change nothing (answers 200).", "type": "boolean" } }, "required": [ "rows" ] } } } }, "responses": { "200": { "description": "Success: a dry run (`dryRun: true`): the same report, nothing changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "counts": { "type": "object", "properties": { "claimed": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" } }, "required": [ "claimed", "created", "updated", "unchanged" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "serial": { "type": "string", "description": "The serial's last 4 characters." }, "outcome": { "type": "string", "enum": [ "claimed", "created", "updated", "unchanged" ] }, "nodeId": { "type": "string" }, "locationName": { "type": "string" }, "locationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" } }, "required": [ "index", "serial", "outcome", "nodeId", "locationName", "locationId", "name" ] } } }, "required": [ "dryRun", "counts", "rows" ] } }, "required": [ "data" ] } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "dryRun": { "type": "boolean" }, "counts": { "type": "object", "properties": { "claimed": { "type": "integer" }, "created": { "type": "integer" }, "updated": { "type": "integer" }, "unchanged": { "type": "integer" } }, "required": [ "claimed", "created", "updated", "unchanged" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "serial": { "type": "string", "description": "The serial's last 4 characters." }, "outcome": { "type": "string", "enum": [ "claimed", "created", "updated", "unchanged" ] }, "nodeId": { "type": "string" }, "locationName": { "type": "string" }, "locationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" } }, "required": [ "index", "serial", "outcome", "nodeId", "locationName", "locationId", "name" ] } } }, "required": [ "dryRun", "counts", "rows" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A serial is held by another workspace, or the data region does not support pre-assignment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No rows, too many rows, or a row is invalid; `data.errors` lists each by `index` and `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/device-preassignments/{id}": { "delete": { "operationId": "deleteDevicePreassignment", "tags": [ "device-preassignments" ], "summary": "Cancel a device pre-assignment", "description": "Cancel a pending device pre-assignment. If the device has already been claimed and turned into a screen, that screen is not affected. The action is recorded in the activity log.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pre-assignment id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/email-health/events": { "get": { "operationId": "listEmailHealthEvents", "tags": [ "email-health" ], "summary": "Get email delivery events", "description": "Returns recent email delivery events for one address, such as deliveries, bounces, and complaints, for use in a per-user delivery history view.\n\n**Notes.**\n- The newest 50 events. A caller limited to some locations sees only the addresses of people they can see.", "x-brix-permission": "user.view", "x-brix-schema": "verified", "x-brix-notes": [ "The newest 50 events. A caller limited to some locations sees only the addresses of people they can see." ], "parameters": [ { "name": "recipient", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only events for this address (case-insensitive)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "recipient": { "type": "string" }, "eventType": { "type": "string", "description": "`delivered`, `bounced`, `complained`, `delivery_delayed`, `sent`, …" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occurredAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "recipient", "eventType", "reason", "occurredAt" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.view" ] } ] } }, "/v1/email-health/failing": { "get": { "operationId": "getEmailHealthFailing", "tags": [ "email-health" ], "summary": "List users with failing email", "description": "Returns the users in the workspace whose email address is currently bouncing or has been marked as spam, so an admin can see who Brix currently cannot reach by email.\n\n**Notes.**\n- Active people only, limited to the people the caller can see.", "x-brix-permission": "user.view", "x-brix-schema": "verified", "x-brix-notes": [ "Active people only, limited to the people the caller can see." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "User id." }, "name": { "type": "string" }, "email": { "type": "string" }, "failingAt": { "type": "string", "description": "When delivery started to fail." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "failingAt", "reason" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.view" ] } ] } }, "/v1/emergencies": { "get": { "operationId": "listEmergencies", "tags": [ "emergencies" ], "summary": "List emergency overrides", "description": "List emergency overrides, newest first. Use `?status=active` to filter to overrides currently taking over screens.", "x-brix-permission": "emergency-override.view", "x-brix-schema": "verified", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "cleared", "expired" ] }, "description": "Only overrides in this state." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "At most this many, newest first (default 200, max 500)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Override" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "emg_4d5e6f7a8b9c0d1e", "spaceId": "space_1a2b3c4d5e6f7a8b", "kind": "emergency", "status": "active", "severity": "critical", "headline": "Evacuate the building now", "body": "Use the nearest exit. Do not use the lifts.", "contentKind": null, "contentId": null, "scopeKind": "all", "scopeNodeId": null, "nodeId": null, "screenCount": 42, "triggeredBy": "usr_5e6f7a8b9c0d1e2f", "triggeredAt": "2026-09-28T11:30:00.000Z", "expiresAt": null, "clearedBy": null, "clearedAt": null, "triggeredByName": "Sam Rivera", "clearedByName": null, "scopeName": "All screens", "confirmedCount": 0 } ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.view" ] } ] }, "post": { "operationId": "triggerEmergency", "tags": [ "emergencies" ], "summary": "Trigger an emergency takeover", "description": "Trigger an emergency takeover across a set of screens. An emergency takes the highest priority and layers over each screen's normal content, so clearing it restores exactly what was playing before.\n\nTakes over the chosen screens now, above every schedule and cast, until cleared or expired. Clearing restores exactly what was playing.\n\n**Notes.**\n- The route is gated by `emergency-override.create`; the route registry's description names `emergency-override.trigger`, which is not a permission the API checks.", "x-brix-permission": "emergency-override.create", "x-brix-schema": "verified", "x-brix-notes": [ "The route is gated by `emergency-override.create`; the route registry's description names `emergency-override.trigger`, which is not a permission the API checks." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "headline": { "type": "string", "description": "The message on every targeted screen. Required, non-blank." }, "body": { "description": "Optional second line.", "type": "string" }, "severity": { "description": "Default `critical`.", "type": "string", "enum": [ "info", "warning", "critical" ] }, "contentKind": { "description": "Attach content to show under the banner. Needs `contentId`.", "type": "string", "enum": [ "media", "creative" ] }, "contentId": { "description": "The media or creative id. Needs `contentKind`.", "type": "string" }, "scopeKind": { "description": "Which screens: every screen you can reach (`all`), one location's subtree (`node`), or a list (`screens`). **Defaults to `all`: omit it and the emergency goes to EVERY screen you can reach.**", "type": "string", "enum": [ "all", "node", "screens" ] }, "scopeNodeId": { "description": "Location id, with `scopeKind: node`.", "type": "string" }, "screenIds": { "description": "Screen ids, with `scopeKind: screens`.", "type": "array", "items": { "type": "string" } }, "expiresAt": { "description": "When it clears by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.", "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "required": [ "headline" ] }, "example": { "headline": "Evacuate the building now", "body": "Use the nearest exit. Do not use the lifts.", "severity": "critical", "scopeKind": "all" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Override" } }, "required": [ "data" ] }, "example": { "data": { "id": "emg_4d5e6f7a8b9c0d1e", "spaceId": "space_1a2b3c4d5e6f7a8b", "kind": "emergency", "status": "active", "severity": "critical", "headline": "Evacuate the building now", "body": "Use the nearest exit. Do not use the lifts.", "contentKind": null, "contentId": null, "scopeKind": "all", "scopeNodeId": null, "nodeId": null, "screenCount": 42, "triggeredBy": "usr_5e6f7a8b9c0d1e2f", "triggeredAt": "2026-09-28T11:30:00.000Z", "expiresAt": null, "clearedBy": null, "clearedAt": null, "triggeredByName": "Sam Rivera", "clearedByName": null, "scopeName": "All screens", "confirmedCount": 0 } } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not shared to one or more target locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The content does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing headline, a half content pointer, a bad `expiresAt`, no reachable screens (`no_screens`), or content that cannot play (`content_unplayable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.create" ] } ] } }, "/v1/emergencies/{id}": { "get": { "operationId": "getEmergency", "tags": [ "emergencies" ], "summary": "Get an emergency override", "description": "Retrieve one emergency override, including its scope, content, and expiry.", "x-brix-permission": "emergency-override.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Emergency id.", "example": "emg_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Override" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such emergency in this workspace (or outside your locations).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.view" ] } ] } }, "/v1/emergencies/{id}/clear": { "post": { "operationId": "clearEmergency", "tags": [ "emergencies" ], "summary": "Clear an emergency override", "description": "Clear an active emergency override. This releases its screens back to their normal content, and the action is recorded in the activity log.", "x-brix-permission": "emergency-override.create", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Emergency id.", "example": "emg_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Override" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such emergency in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`already_inactive`: already cleared or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.create" ] } ] } }, "/v1/emergencies/from-template/{templateId}": { "post": { "operationId": "triggerEmergencyTemplate", "tags": [ "emergencies" ], "summary": "Trigger an emergency from a template", "description": "Trigger an emergency using a stored template. Any scope or expiry sent with the request overrides the template's defaults.\n\nFires a stored template. Scope and expiry given here override the template's defaults. Send `{}` to use the template as stored.", "x-brix-permission": "emergency-override.create", "x-brix-schema": "verified", "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Emergency template id.", "example": "etpl_7a8b9c0d1e2f3a4b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scopeKind": { "description": "Which screens: every screen you can reach (`all`), one location's subtree (`node`), or a list (`screens`). **Defaults to `all`: omit it and the emergency goes to EVERY screen you can reach.**", "type": "string", "enum": [ "all", "node", "screens" ] }, "scopeNodeId": { "description": "Location id, with `scopeKind: node`.", "type": "string" }, "screenIds": { "description": "Screen ids, with `scopeKind: screens`.", "type": "array", "items": { "type": "string" } }, "expiresAt": { "description": "When it clears by itself: ISO-8601 or epoch milliseconds. Omit or null to run until cleared.", "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "description": "Trigger-time overrides. Omitted scope fields fall back to the template's own scope." } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Override" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the template's content is not shared to one or more target locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such template, or its content is gone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bad `expiresAt`, no reachable screens (`no_screens`), or content that cannot play.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.create" ] } ] } }, "/v1/emergency-templates": { "get": { "operationId": "listEmergencyTemplates", "tags": [ "emergency-templates" ], "summary": "List emergency templates", "description": "List pre-configured emergency recipes, such as Lockdown, Severe weather, or Fire drill, used for one-click triggering. A template with `prestage` set to true has its content cached on every screen in scope in advance, before it is ever triggered.", "x-brix-permission": "emergency-override.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmergencyTemplate" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.view" ] } ] }, "post": { "operationId": "createEmergencyTemplate", "tags": [ "emergency-templates" ], "summary": "Create an emergency template", "description": "Create a reusable emergency recipe with a `name`, `contentKind`, `contentId`, `scope`, `severity`, and an optional `prestage` flag. Trigger it later with POST /v1/emergencies/from-template/:templateId.", "x-brix-permission": "emergency-override.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Default \"Untitled template\".", "type": "string" }, "headline": { "description": "Default \"Emergency\".", "type": "string" }, "body": { "type": "string" }, "severity": { "description": "Default `critical`.", "type": "string", "enum": [ "info", "warning", "critical" ] }, "contentKind": { "type": "string", "enum": [ "media", "creative", "playlist", "app" ] }, "contentId": { "type": "string" }, "scopeKind": { "description": "Default `all`.", "type": "string", "enum": [ "all", "node", "screens" ] }, "scopeNodeId": { "description": "Required with `scopeKind: node`.", "type": "string" }, "nodeId": { "description": "Home location. Default: the API key's location, else the workspace root.", "type": "string" }, "prestage": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmergencyTemplate" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing `emergency-override.edit` at the home or scope location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The content or a location does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A content kind outside media/creative/playlist/app, a half content pointer, or `scopeKind: node` without `scopeNodeId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.edit" ] } ] } }, "/v1/emergency-templates/{id}": { "delete": { "operationId": "deleteEmergencyTemplate", "tags": [ "emergency-templates" ], "summary": "Delete an emergency template", "description": "Delete an emergency template. Emergencies already triggered from it are unaffected.", "x-brix-permission": "emergency-override.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.edit" ] } ] }, "patch": { "operationId": "updateEmergencyTemplate", "tags": [ "emergency-templates" ], "summary": "Update an emergency template", "description": "Edit an emergency template's content, scope, severity, or prestaging setting.", "x-brix-permission": "emergency-override.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "emergency-override.edit" ] } ] } }, "/v1/feature-flags": { "get": { "operationId": "listFeatureFlags", "tags": [ "feature-flags" ], "summary": "Get feature flags", "description": "Returns the platform feature flags resolved for this workspace. A workspace-specific override replaces the global default for that flag; both sit on top of the plan tier's default.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "flags": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean" }, "description": "Flag name → on or off. Only flags with a platform default or a workspace override are listed." } }, "required": [ "flags" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "patch": { "operationId": "updateFeatureFlag", "tags": [ "feature-flags" ], "summary": "Set feature flag override", "description": "Sets or clears (with `null`) a workspace-level feature flag override. The change is stored server-side, so it takes effect for every user, device, and screen in the workspace.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flagName": { "type": "string", "description": "A feature key, e.g. `approvals`, `sync-groups`, `proof-of-play`." }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "On or off for this workspace; null removes the override." } }, "required": [ "flagName", "enabled" ] }, "example": { "flagName": "approvals", "enabled": true } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "flagName": { "type": "string" }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "flagName", "enabled" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold `billing.edit` for the whole workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`flagName` is missing or not a known feature, or `enabled` is not a boolean or null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/feeds/discover": { "get": { "operationId": "getFeedDiscover", "tags": [ "feeds" ], "summary": "Discover feed URLs from a site", "description": "Find public RSS, Atom, or JSON feed URLs published by a given site URL.", "x-brix-permission": "app-instance.create", "x-brix-schema": "verified", "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "A feed URL or a web page URL." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pageUrl": { "type": "string", "description": "The URL after redirects." }, "pageTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The page's ``; null when the URL is itself a feed." }, "feeds": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The feed's absolute URL." }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "rss", "atom", "json" ] } }, "required": [ "url", "title", "type" ] }, "description": "Feeds found. Empty when the page names none." } }, "required": [ "pageUrl", "pageTitle", "feeds" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The page is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`url` is missing or not a usable URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The site did not answer, or answered with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "app-instance.create" ] } ] } }, "/v1/feeds/fetch": { "get": { "operationId": "getFeedFetch", "tags": [ "feeds" ], "summary": "Fetch and parse a feed", "description": "Fetch an RSS, Atom, or JSON feed and return its articles as normalized JSON. Results are cached for five minutes.\n\nNeeds no credential: the RSS app on the screen calls it. Limited to 120 calls a minute from one IP address.\n\n**Notes.**\n- `fetchedAt` is a top-level key beside `data`, not inside it.\n- Cached for 5 minutes (`Cache-Control: public, max-age=60, s-maxage=300`).", "x-brix-schema": "verified", "x-brix-notes": [ "`fetchedAt` is a top-level key beside `data`, not inside it.", "Cached for 5 minutes (`Cache-Control: public, max-age=60, s-maxage=300`)." ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The feed URL (RSS, Atom or JSON Feed). A web page URL also works when the site has a feed at a usual path (`/feed`, `/rss.xml`)." }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With `translate=1`: translate the article text to this language (BCP 47)." }, { "name": "translate", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ParsedFeed" }, "fetchedAt": { "type": "string", "description": "When the feed was fetched. It is beside `data`, not in it." } }, "required": [ "data", "fetchedAt" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The feed is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`url` is missing, or no feed was found at it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 120 calls in a minute from this IP address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The site did not answer, or answered with an error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/gdpr/erase": { "post": { "operationId": "createGdprErase", "tags": [ "gdpr" ], "summary": "Erase user under GDPR", "description": "Permanently anonymizes a user's profile and deletes their associated personal data, including linked identities, passkeys, sessions, and pending email verifications, to satisfy a right-to-be-forgotten request. You cannot erase your own account or the last remaining account owner. Only an account owner can do this to an owner, and you cannot do it to a person who holds a permission you do not hold. An API key is never an owner.\n\n**Notes.**\n- Irreversible. Unlike `POST /v1/users/:id/erase`, the person does not have to be deactivated first.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Irreversible. Unlike `POST /v1/users/:id/erase`, the person does not have to be deactivated first." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" } }, "required": [ "userId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "userId": { "type": "string" }, "erased": { "type": "boolean", "const": true } }, "required": [ "userId", "erased" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Also `owner_required` or `outranked`: the person is an owner, or holds a permission you do not hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such person in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cant_erase_self` or `last_owner`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`userId` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/gdpr/export": { "get": { "operationId": "exportGdpr", "tags": [ "gdpr" ], "summary": "Export user data (GDPR)", "description": "Assembles a data subject access request export for the whole workspace: every person, screen and piece of content, and the last 365 days of the activity log, as one JSON file with secret values withheld. The key or person must have `billing.edit` for the whole workspace. Each table is capped; `complete` is false when one was cut.\n\n**Notes.**\n- Exports the whole workspace, not one person: every person, screen and piece of content, and the last 365 days of the activity log.\n- No `{ data }` envelope: the body is the export file (`Content-Disposition: attachment`).\n- Credentials are never exported: their columns are kept with `null` or a `[secret; not exported]` / `[encrypted; not exported]` marker.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Exports the whole workspace, not one person: every person, screen and piece of content, and the last 365 days of the activity log.", "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." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "generatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "subject": { "type": "object", "properties": { "spaceId": { "type": "string", "description": "The workspace exported." }, "requestedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null for an API key." } }, "required": [ "spaceId", "requestedByUserId" ] }, "limits": { "type": "object", "properties": { "perTable": { "type": "integer", "description": "At most this many rows per table." }, "auditEvents": { "type": "integer", "description": "At most this many activity log events." }, "auditWindowDays": { "type": "integer", "description": "Activity log events from this many days back." } }, "required": [ "perTable", "auditEvents", "auditWindowDays" ] }, "truncated": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean", "const": true }, "description": "The tables cut at the limit; empty when none." }, "complete": { "type": "boolean", "description": "False when a table was cut at the limit." }, "tables": { "type": "object", "properties": { "workspace": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "The workspace record, every column (the Screen Lock PIN hash replaced by `kioskHasGlobalPin` inside `prefs`)." }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "lastLoginAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "title", "phone", "status", "lastLoginAt", "emailVerifiedAt", "createdAt", "updatedAt", "deletedAt" ] } }, "screens": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Every column; credentials withheld, and `kioskHasCustomPin` / `kioskHasRecovery` added." }, "media": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "playlists": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "schedules": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "layouts": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "creatives": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "appInstances": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "dataSources": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "`config` is `[encrypted; not exported]` (or null)." }, "banners": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "auditEvents": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Newest first." } }, "required": [ "workspace", "users", "screens", "media", "playlists", "schedules", "layouts", "creatives", "appInstances", "dataSources", "banners", "auditEvents" ] } }, "required": [ "schemaVersion", "generatedAt", "subject", "limits", "truncated", "complete", "tables" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] }, "post": { "operationId": "exportGdpr2", "tags": [ "gdpr" ], "summary": "Export user data (GDPR)", "description": "Same as the GET version of this operation: assembles a data subject access request export for the whole workspace as one JSON file, with secret values withheld. The key or person must have `billing.edit` for the whole workspace. Takes no request body.\n\n**Notes.**\n- Exports the whole workspace, not one person: every person, screen and piece of content, and the last 365 days of the activity log.\n- No `{ data }` envelope: the body is the export file (`Content-Disposition: attachment`).\n- Credentials are never exported: their columns are kept with `null` or a `[secret; not exported]` / `[encrypted; not exported]` marker.\n- Takes no body; the same export as the GET.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Exports the whole workspace, not one person: every person, screen and piece of content, and the last 365 days of the activity log.", "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.", "Takes no body; the same export as the GET." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "generatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "subject": { "type": "object", "properties": { "spaceId": { "type": "string", "description": "The workspace exported." }, "requestedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Null for an API key." } }, "required": [ "spaceId", "requestedByUserId" ] }, "limits": { "type": "object", "properties": { "perTable": { "type": "integer", "description": "At most this many rows per table." }, "auditEvents": { "type": "integer", "description": "At most this many activity log events." }, "auditWindowDays": { "type": "integer", "description": "Activity log events from this many days back." } }, "required": [ "perTable", "auditEvents", "auditWindowDays" ] }, "truncated": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "boolean", "const": true }, "description": "The tables cut at the limit; empty when none." }, "complete": { "type": "boolean", "description": "False when a table was cut at the limit." }, "tables": { "type": "object", "properties": { "workspace": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "The workspace record, every column (the Screen Lock PIN hash replaced by `kioskHasGlobalPin` inside `prefs`)." }, "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "lastLoginAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "name", "email", "title", "phone", "status", "lastLoginAt", "emailVerifiedAt", "createdAt", "updatedAt", "deletedAt" ] } }, "screens": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Every column; credentials withheld, and `kioskHasCustomPin` / `kioskHasRecovery` added." }, "media": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "playlists": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "schedules": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "layouts": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "creatives": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "appInstances": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "dataSources": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "`config` is `[encrypted; not exported]` (or null)." }, "banners": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "auditEvents": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Newest first." } }, "required": [ "workspace", "users", "screens", "media", "playlists", "schedules", "layouts", "creatives", "appInstances", "dataSources", "banners", "auditEvents" ] } }, "required": [ "schemaVersion", "generatedAt", "subject", "limits", "truncated", "complete", "tables" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } }, "/v1/import/bundle": { "post": { "operationId": "createImportBundle", "tags": [ "import" ], "summary": "Import bundle", "description": "Performs a bulk import from a multipart upload containing a manifest JSON file and a zip of media files. In one operation, this creates the location tree, media library, playlists, and screens (initially unpaired) described by the manifest. Physical screens are paired into these pre-created entries later. Requires the import-create permission on the API key.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/import/upload-urls": { "post": { "operationId": "createImportUploadUrl", "tags": [ "import" ], "summary": "Create import upload slots", "description": "Creates up to 500 upload slots for a large-scale import. Each slot returns a URL you upload file bytes to directly and in parallel, and your import manifest then references the file by its `uploadId`. Use this instead of a single bundle upload when importing 10,000 or more files, since a single request cannot hold that much data.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/import/zm-originals": { "post": { "operationId": "createImportZmOriginal", "tags": [ "import" ], "summary": "Import original media from Zeetaminds", "description": "Fetches a Zeetaminds account's original media files, which cannot normally be downloaded directly by a browser, into this workspace's pending upload slots. Processes files in batches and reports a per-file result. Widget and layout items have no underlying file and are reported as skipped. Only affects the workspace that owns the calling API key.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/interactions": { "get": { "operationId": "listInteractions", "tags": [ "interactions" ], "summary": "List interaction events", "description": "List engagement events from your screens, such as on-screen taps, QR code scans, presenter joins, and form submissions.\n\n**Notes.**\n- Newest first, at most 1000, from screens at locations the caller can see.", "x-brix-permission": "playback-log.view", "x-brix-schema": "verified", "x-brix-notes": [ "Newest first, at most 1000, from screens at locations the caller can see." ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO-8601 start (default: 7 days ago)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO-8601 end (default: now)." }, { "name": "screenId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "screenId": { "type": "string" }, "screenName": { "type": "string", "description": "The screen id when the screen no longer exists." }, "at": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "kind": { "type": "string", "enum": [ "touch", "qr-scan", "screenshare-join", "form-submit" ] }, "detail": { "type": "string", "description": "A short human-readable summary." } }, "required": [ "id", "screenId", "screenName", "at", "kind", "detail" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playback-log.view" ] } ] } }, "/v1/layouts": { "get": { "operationId": "listLayouts", "tags": [ "layouts" ], "summary": "List layouts", "description": "List the workspace's multi-zone layouts, including each layout's name, resolution, and zone count.", "x-brix-permission": "layout.view", "x-brix-schema": "verified", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Page size. Omit to get every row; pass it to page by `cursor`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "With `limit`: also return `total`, the number of matching rows." }, { "name": "usableAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location id: only rows usable at that location (homed there, at the workspace root, or shared to it)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Layout" } }, "nextCursor": { "description": "Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "description": "Total matching rows, when the route computes it.", "type": "integer" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.view" ] } ] }, "post": { "operationId": "createLayout", "tags": [ "layouts" ], "summary": "Create a layout", "description": "Create a multi-zone layout with a `name` and optional `resolution`, `zones`, `autoFullscreenForVideo`, `nodeId`, and `theme`. Setting `theme` to `{ source: \"brand\", mode?, radius? }` paints the layout using the workspace Brand Kit; omit it or set it to `null` for a plain canvas. Each zone can also carry a frame style (bare, card, accent, or glass), a corner radius in pixels, and a role of \"logo\" for a zone that shows the Brand Kit logo without needing its own content.\n\n**Notes.**\n- The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.\n- The 201 body has no `usedByScreenCount`.", "x-brix-permission": "layout.create", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.", "The 201 body has no `usedByScreenCount`." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "resolution": { "description": "Canvas size in pixels. Default 1920 x 1080.", "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ] }, "zones": { "description": "The whole zone list. Default: one full-canvas zone named Main.", "type": "array", "items": { "$ref": "#/components/schemas/LayoutZone" } }, "autoFullscreenForVideo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "brand" }, "mode": { "type": "string", "enum": [ "dark", "light" ] }, "radius": { "type": "number", "minimum": 0 }, "wash": { "type": "string", "enum": [ "corner", "none" ] } }, "required": [ "source" ], "description": "Paint the layout in the workspace Brand Kit. `null` = a plain canvas." }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Layout id.", "examples": [ "lay_5e6f7a8b9c0d1e2f" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "resolution": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "description": "Design canvas size in pixels." }, "zones": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Zones: geometry, bound content, frame, radius and role. `GET /v1/layouts/{id}/zones` returns the same list." }, "autoFullscreenForVideo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "approvalState": { "description": "Absent: the create does not set it (it is `draft`).", "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme": { "anyOf": [ {}, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "name", "resolution", "zones", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: zone content that is not usable at the layout's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing name, invalid JSON, a bad theme or zone paint, zone content that does not exist or loops, or a location outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.create" ] } ] } }, "/v1/layouts/{id}": { "delete": { "operationId": "deleteLayout", "tags": [ "layouts" ], "summary": "Delete a layout", "description": "Delete a layout. This fails with 409 `content_shared` if the layout is actively shared into other spaces; pass `?force=true` to delete it anyway.", "x-brix-permission": "layout.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Delete even when it is shared into other places; the shares go with it." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "sharesRemoved": { "type": "integer", "description": "Shares removed with it." } }, "required": [ "id", "deleted", "sharesRemoved" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.delete" ] } ] }, "get": { "operationId": "getLayout", "tags": [ "layouts" ], "summary": "Get a layout", "description": "Retrieve one layout, including its zone geometry with each zone's content assignment and frame, radius, and role styling, its theme (the Brand Kit look, or null), and its video-fullscreen behaviour.", "x-brix-permission": "layout.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Layout id.", "examples": [ "lay_5e6f7a8b9c0d1e2f" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "resolution": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "description": "Design canvas size in pixels." }, "zones": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Zones: geometry, bound content, frame, radius and role. `GET /v1/layouts/{id}/zones` returns the same list." }, "autoFullscreenForVideo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state. Editing an approved row returns it to `draft`." }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON TEXT of the last approved version (not parsed)." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme": { "anyOf": [ {}, { "type": "null" } ], "description": "Brand Kit look (`{ source: \"brand\", mode?, radius? }`), or null for a bare canvas." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." }, "usedByScreenCount": { "type": "integer", "description": "Screens showing this layout now, directly or through a playlist or schedule." }, "requiresApproval": { "type": "boolean", "description": "The home location requires approval before content airs." } }, "required": [ "id", "spaceId", "name", "resolution", "zones", "autoFullscreenForVideo", "approvalState", "approvedSnapshot", "nodeId", "importSourceId", "theme", "createdAt", "updatedAt", "deletedAt", "usedByScreenCount", "requiresApproval" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.view" ] } ] }, "patch": { "operationId": "updateLayout", "tags": [ "layouts" ], "summary": "Update a layout", "description": "Edit a layout's name, resolution, zones, `autoFullscreenForVideo`, node, or theme. Setting `theme` to `{ source: \"brand\", mode?, radius? }` turns the Brand Kit look on, and `null` turns it off. Zones accept a frame style (bare, card, accent, or glass), a radius, and a role of \"logo\". An invalid theme, or an unrecognized frame or role, returns 422.\n\n**Notes.**\n- The response is the stored row: it has no `usedByScreenCount` or `requiresApproval` (GET has them).", "x-brix-permission": "layout.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The response is the stored row: it has no `usedByScreenCount` or `requiresApproval` (GET has them)." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "resolution": { "description": "Canvas size in pixels. Default 1920 x 1080.", "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ] }, "zones": { "description": "The whole zone list. Default: one full-canvas zone named Main.", "type": "array", "items": { "$ref": "#/components/schemas/LayoutZone" } }, "autoFullscreenForVideo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "brand" }, "mode": { "type": "string", "enum": [ "dark", "light" ] }, "radius": { "type": "number", "minimum": 0 }, "wash": { "type": "string", "enum": [ "corner", "none" ] } }, "required": [ "source" ], "description": "Paint the layout in the workspace Brand Kit. `null` = a plain canvas." }, { "type": "null" } ] }, "baseUpdatedAt": { "description": "Optimistic concurrency: the `updatedAt` you read. A stale value is refused with 409 `conflict` and the `current` row.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Layout id.", "examples": [ "lay_5e6f7a8b9c0d1e2f" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "resolution": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "w", "h" ], "description": "Design canvas size in pixels." }, "zones": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "description": "Zones: geometry, bound content, frame, radius and role. `GET /v1/layouts/{id}/zones` returns the same list." }, "autoFullscreenForVideo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ], "description": "Review state. Editing an approved row returns it to `draft`." }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON TEXT of the last approved version (not parsed)." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme": { "anyOf": [ {}, { "type": "null" } ], "description": "Brand Kit look (`{ source: \"brand\", mode?, radius? }`), or null for a bare canvas." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "name", "resolution", "zones", "autoFullscreenForVideo", "approvalState", "approvedSnapshot", "nodeId", "importSourceId", "theme", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Moving it to a location where you lack layout.edit, or zone content that is not usable there (`not_shared`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the row changed since `baseUpdatedAt`; the body carries `current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON, a bad theme or zone paint, zone content that does not exist or loops back into this layout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.edit" ] } ] } }, "/v1/layouts/{id}/restore": { "post": { "operationId": "restoreLayout", "tags": [ "layouts" ], "summary": "Restore a deleted layout", "description": "Restore a deleted layout so it returns to the layout library.", "x-brix-permission": "layout.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout in this workspace, or it was purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: the layout is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.delete" ] } ] } }, "/v1/layouts/{id}/thumbnail": { "get": { "operationId": "getLayoutThumbnail", "tags": [ "layouts" ], "summary": "Get a layout thumbnail", "description": "Retrieve a preview image of a layout, showing each zone at its real position filled with a still of its content. The same image is used everywhere the layout is previewed. Add `?fresh=1` to regenerate it after an edit.", "x-brix-permission": "layout.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" }, { "name": "fresh", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Skip the cached image and draw it again." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "image/svg+xml": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.view" ] } ] } }, "/v1/layouts/{id}/zones": { "get": { "operationId": "listLayoutZones", "tags": [ "layouts" ], "summary": "List a layout's zones", "description": "List a layout's zones, including the content attached to each one.", "x-brix-permission": "layout.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutZone" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.view" ] } ] }, "post": { "operationId": "createLayoutZone", "tags": [ "layouts" ], "summary": "Add a zone to a layout", "description": "Add one zone to a layout, specifying its geometry, the content attached to it, and, on a themed layout, its frame (bare, card, accent, or glass), radius, and role. A zone with role \"logo\" does not need content of its own.\n\n**Notes.**\n- Editing zones returns an approved layout to `draft` where approval is required.", "x-brix-permission": "layout.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Editing zones returns an approved layout to `draft` where approval is required." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Default `Zone <n>`.", "type": "string" }, "x": { "description": "Default 0.", "type": "number" }, "y": { "description": "Default 0.", "type": "number" }, "w": { "description": "Default 480.", "type": "number" }, "h": { "description": "Default 270.", "type": "number" }, "locked": { "type": "boolean" }, "contentName": { "type": "string" }, "content": { "description": "What the zone plays. It must exist in this workspace, be usable at the layout's location, and not contain this layout.", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "media", "playlist", "schedule", "app", "link", "canvas" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id" ] }, { "type": "null" } ] }, "ownerScope": { "type": "string", "enum": [ "workspace", "org_unit", "location" ] }, "ownerNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "frame": { "type": "string", "enum": [ "bare", "card", "accent", "glass" ] }, "radius": { "type": "number", "minimum": 0 }, "role": { "type": "string", "enum": [ "logo" ] } } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Layout id." }, "zones": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutZone" }, "description": "Every zone, in paint order." }, "zone": { "description": "The new zone.", "$ref": "#/components/schemas/LayoutZone" } }, "required": [ "id", "zones", "zone" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not usable at the layout's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout (or zone) in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the layout changed during the write three times running; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A bad frame, radius or role, content that does not exist, or zone content that plays this layout again (a loop).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.edit" ] } ] }, "put": { "operationId": "replaceLayoutZone", "tags": [ "layouts" ], "summary": "Replace a layout's zones", "description": "Replace a layout's entire set of zones in one call. Send every zone you want to keep, including each zone's frame, radius, and role on a themed layout; a zone sent without those becomes a plain, unframed zone.\n\nSend `zones` to replace the whole list, or `zoneIds` (every current zone id, once) to reorder it.\n\n**Notes.**\n- `zones` is stored as sent: keys the API does not know are kept and returned.", "x-brix-permission": "layout.edit", "x-brix-schema": "verified", "x-brix-notes": [ "`zones` is stored as sent: keys the API does not know are kept and returned." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "zones": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutZone" }, "description": "The new zone list, stored as sent." } }, "required": [ "zones" ] }, { "type": "object", "properties": { "zoneIds": { "type": "array", "items": { "type": "string" }, "description": "Every current zone id, in the new paint order." } }, "required": [ "zoneIds" ] } ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Layout id." }, "zones": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutZone" }, "description": "Every zone, in paint order." } }, "required": [ "id", "zones" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not usable at the layout's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout (or zone) in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the layout changed during the write three times running; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`zoneIds` that are not every zone exactly once, neither `zones` nor `zoneIds`, or a bad or looping zone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.edit" ] } ] } }, "/v1/layouts/{id}/zones/{zoneId}": { "delete": { "operationId": "deleteLayoutZone", "tags": [ "layouts" ], "summary": "Delete a layout zone", "description": "Remove one zone from a layout.", "x-brix-permission": "layout.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" }, { "name": "zoneId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Zone id.", "example": "zn_9c0d1e2f3a4b5c6d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Layout id." }, "zones": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutZone" }, "description": "Every zone, in paint order." } }, "required": [ "id", "zones" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout or zone in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the layout changed during the write three times running; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.edit" ] } ] }, "patch": { "operationId": "updateLayoutZone", "tags": [ "layouts" ], "summary": "Update a layout zone", "description": "Edit one zone's geometry, attached content, or, on a themed layout, its frame, radius, or role. Send `null` for any of those to clear it. Rejects a change that would create a loop back into the same layout.", "x-brix-permission": "layout.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Layout id.", "example": "lay_5e6f7a8b9c0d1e2f" }, { "name": "zoneId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Zone id.", "example": "zn_9c0d1e2f3a4b5c6d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Default `Zone <n>`.", "type": "string" }, "x": { "description": "Default 0.", "type": "number" }, "y": { "description": "Default 0.", "type": "number" }, "w": { "description": "Default 480.", "type": "number" }, "h": { "description": "Default 270.", "type": "number" }, "locked": { "type": "boolean" }, "contentName": { "type": "string" }, "content": { "description": "What the zone plays. It must exist in this workspace, be usable at the layout's location, and not contain this layout.", "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "media", "playlist", "schedule", "app", "link", "canvas" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id" ] }, { "type": "null" } ] }, "ownerScope": { "type": "string", "enum": [ "workspace", "org_unit", "location" ] }, "ownerNodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "frame": { "description": "`null` removes it.", "anyOf": [ { "type": "string", "enum": [ "bare", "card", "accent", "glass" ] }, { "type": "null" } ] }, "radius": { "description": "`null` removes it.", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "role": { "description": "`null` removes it.", "anyOf": [ { "type": "string", "enum": [ "logo" ] }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Layout id." }, "zones": { "type": "array", "items": { "$ref": "#/components/schemas/LayoutZone" }, "description": "Every zone, in paint order." }, "zone": { "description": "The zone as saved.", "$ref": "#/components/schemas/LayoutZone" } }, "required": [ "id", "zones", "zone" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not usable at the layout's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such layout (or zone) in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the layout changed during the write three times running; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A bad frame, radius or role, content that does not exist, or zone content that plays this layout again (a loop).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "layout.edit" ] } ] } }, "/v1/link-preview": { "get": { "operationId": "getLinkPreview", "tags": [ "link-preview" ], "summary": "Preview a link", "description": "Return a title, description, and preview image for a URL, using an optional width parameter to size the image. The request is fetched and validated server-side, since a browser cannot fetch most sites directly, and results are cached.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/me": { "get": { "operationId": "getMe", "tags": [ "me" ], "summary": "Describe the calling credential", "description": "Returns who is calling and what they are allowed to do: whether the caller is a signed-in person, an API key, or Brix support; the location an API key is pinned to, if any; the workspace; and the caller's full set of permissions.\n\nWho is calling (API key, user, or Brix support), which workspace the call resolves to, and the permissions held. Call it first when a request is refused: `actor.nodeId` shows a key pinned to one location.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "actor": { "$ref": "#/components/schemas/Actor" }, "workspace": { "$ref": "#/components/schemas/WorkspaceRef" }, "permissions": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ], "description": "`all` for an owner-style credential, else every `resource.verb` held anywhere in the workspace. A planning hint: node-scoped checks still run on each call." } }, "required": [ "actor", "workspace", "permissions" ] } }, "required": [ "data" ] }, "example": { "data": { "actor": { "kind": "key", "id": "key_6f7a8b9c0d1e2f3a", "name": "Menu board sync", "nodeId": null }, "workspace": { "id": "space_1a2b3c4d5e6f7a8b", "name": "Riverside Coffee" }, "permissions": [ "screen.view", "screen.cast", "media.view", "media.create" ] } } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/media": { "get": { "operationId": "listMedia", "tags": [ "media" ], "summary": "List media", "description": "Return the media library: images, videos, PDFs, presentations, fonts, web links, and app-backed assets. Use limit and cursor to page through results, count=1 to include a total count, search to search by name or tag, and the comma-separated kind, state, and folderId parameters to filter. Paging is optional but recommended, since a library can hold thousands of items.\n\nWithout `limit`, every visible asset comes back unordered and without `nextCursor`. With `limit`, rows are newest first.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Case-insensitive match on name or tags." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated kinds, e.g. `image,video`." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated processing states." }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated folder ids." }, { "name": "usableAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location id: only assets that may play there (own, root library, or shared in)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Page size (max 500). Omit to get every row." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "With `limit`: also return `total`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaAsset" } }, "nextCursor": { "description": "Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "description": "Total matching rows, when the route computes it.", "type": "integer" } }, "required": [ "data" ] }, "example": { "data": [ { "id": "med_0c1d2e3f4a5b6c7d", "spaceId": "space_1a2b3c4d5e6f7a8b", "name": "lunch-special.jpg", "kind": "image", "url": "/v1/media/med_0c1d2e3f4a5b6c7d/file", "bytes": 482113, "checksum": null, "active": true, "folderId": null, "tags": [ "menu", "lunch" ], "altText": "Grilled chicken wrap with fries", "thumbnailUrl": null, "width": 1920, "height": 1080, "durationSec": null, "pdfPageCount": null, "loopDurationMs": null, "fontFamily": null, "fontWeights": null, "state": "ready", "stateReason": null, "stateCode": null, "stateFault": null, "stateProgress": null, "codec": null, "playableRev": 0, "loopState": null, "loopCodecs": null, "loopRev": null, "loopRotation": null, "loopBytes": null, "masterKey": null, "masterBytes": null, "masterProbe": null, "rendition4k": null, "frameLumaMean": null, "frameLumaVariance": null, "frameEdgeDensity": null, "startsAt": null, "expiresAt": null, "autoArchiveOnExpiry": false, "qr": null, "webConfig": null, "replayState": null, "lastReplayAt": null, "lastReplaySuccessAt": null, "lastFailedStep": null, "lastFailedReason": null, "autoCaption": false, "captionTrackKey": null, "captionState": null, "showCaptions": true, "audioEnabled": false, "focalRegion": null, "fit": "contain", "autoSmartFit": true, "rotation": 0, "originalFormat": null, "packageEntry": null, "packageFiles": null, "packageBytes": null, "importSourceId": null, "nodeId": null, "recalledAt": null, "recalledBy": null, "createdAt": "2026-09-20T10:15:00.000Z", "updatedAt": "2026-09-20T10:15:00.000Z", "deletedAt": null, "usageCount": 2, "uploadedByName": "Sam Rivera", "uploadSource": "ui" } ], "nextCursor": null, "total": 1 } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] }, "post": { "operationId": "createMedia", "tags": [ "media" ], "summary": "Create a media item", "description": "Create a media asset record for a file whose bytes are already stored elsewhere, by providing name, kind, and url. This creates only the metadata record; to upload new file bytes, use POST /v1/media/upload, PUT /v1/media/upload/:uploadId, or POST /v1/media/import-url instead.\n\n**Notes.**\n- The 201 body is the row as written, not re-read: columns the create does not set are absent rather than null. GET returns every column.\n- Use this for links (web pages, streams, dashboards). To add a FILE, use POST /v1/media/upload, the multipart upload, or POST /v1/media/import-url.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the row as written, not re-read: columns the create does not set are absent rather than null. GET returns every column.", "Use this for links (web pages, streams, dashboards). To add a FILE, use POST /v1/media/upload, the multipart upload, or POST /v1/media/import-url." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "pdf", "powerpoint", "web", "dashboard", "weather", "rss", "clock", "qr", "menu", "directory", "donor-wall", "hall-of-fame", "birthday-board", "recognition", "wayfinding", "check-in", "emergency", "touch-kiosk", "package", "font" ] }, "url": { "type": "string", "description": "An https URL, a /v1/ path, or (for a web link) the page address. Private and internal network addresses are refused." }, "active": { "type": "boolean" }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "autoArchiveOnExpiry": { "type": "boolean" }, "qr": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "webConfig": { "description": "Web link settings (refresh, zoom, …).", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "audioEnabled": { "type": "boolean" }, "fit": { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ] } }, "required": [ "name", "kind", "url" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Media asset id.", "examples": [ "med_0c1d2e3f4a5b6c7d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value." }, "url": { "type": "string", "description": "Where the bytes live: a `/v1/media/<id>/file` path, an `https` URL, `r2://…`, or (for a web link) the page address." }, "bytes": { "type": "integer", "description": "Stored size in bytes (0 for links and apps)." }, "active": { "type": "boolean", "description": "False when archived." }, "tags": { "description": "Tags — a JSON array of strings for every row written by the API (decoded from storage; left as the raw text if the stored value is not valid JSON)." }, "state": { "type": "string", "description": "Processing state: `ready`, `processing`, `ready_with_warnings`, `blocked`, …" }, "autoArchiveOnExpiry": { "type": "boolean" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace library root." }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Video/audio length in seconds." }, "startsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Plays only from this time." }, "expiresAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Stops playing after this time." }, "qr": { "anyOf": [ {}, { "type": "null" } ], "description": "QR overlay settings (decoded JSON)." }, "webConfig": { "anyOf": [ {}, { "type": "null" } ], "description": "Web link settings — refresh, zoom, header auth, … (decoded JSON)." }, "audioEnabled": { "type": "boolean" }, "fit": { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ], "description": "How the asset fills a box." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "type": "null" } }, "required": [ "id", "spaceId", "name", "kind", "url", "bytes", "active", "tags", "state", "autoArchiveOnExpiry", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`fit` is not a known value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The folder or location does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name`, `kind` or `url` is missing, or `kind` is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media-folders": { "get": { "operationId": "listMediaFolders", "tags": [ "media-folders" ], "summary": "List media folders", "description": "Return the media library's folder tree for this workspace, including each folder's id, name, parent folder, and location.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Page size. Omit to get every row; pass it to page by `cursor`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "With `limit`: also return `total`." }, { "name": "usableAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location id: only folders usable at that location." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MediaFolder" } }, "nextCursor": { "description": "Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "description": "Total matching rows, when the route computes it.", "type": "integer" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] }, "post": { "operationId": "createMediaFolder", "tags": [ "media-folders" ], "summary": "Create a media folder", "description": "Create a folder in the media library. Requires name; parentId and nodeId are optional. Omitting parentId places the folder at the root.\n\n**Notes.**\n- The 201 body is the row as written, not re-read: columns the create does not set are absent rather than null. GET returns every column.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the row as written, not re-read: columns the create does not set are absent rather than null. GET returns every column." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Media folder id.", "examples": [ "fold_2b3c4d5e6f7a8b9c" ] }, "spaceId": { "type": "string" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "spaceId", "name", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The location does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media-folders/{id}": { "delete": { "operationId": "deleteMediaFolder", "tags": [ "media-folders" ], "summary": "Delete a media folder", "description": "Move a media folder to the recycle bin; it can be restored later. Assets inside the folder are not moved or deleted and keep their existing folder reference.", "x-brix-permission": "media.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media folder id.", "example": "fold_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.delete" ] } ] }, "get": { "operationId": "getMediaFolder", "tags": [ "media-folders" ], "summary": "Get a media folder", "description": "Return one media folder.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media folder id.", "example": "fold_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MediaFolder" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] }, "patch": { "operationId": "updateMediaFolder", "tags": [ "media-folders" ], "summary": "Update a media folder", "description": "Rename a media folder or move it to a different parent folder or location. Accepts optional name, parentId, and nodeId.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media folder id.", "example": "fold_2b3c4d5e6f7a8b9c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "parentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseUpdatedAt": { "description": "The `updatedAt` your edit is based on; 409 with the current row if it moved.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MediaFolder" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No folder with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: changed since `baseUpdatedAt`; the body carries `current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media-folders/{id}/restore": { "post": { "operationId": "restoreMediaFolder", "tags": [ "media-folders" ], "summary": "Restore a deleted media folder", "description": "Bring back a deleted media folder so it reappears in the folder tree. Assets inside it keep whatever delete state they already had.", "x-brix-permission": "media.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media folder id.", "example": "fold_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No folder with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.delete" ] } ] } }, "/v1/media-sync": { "get": { "operationId": "listMediaSync", "tags": [ "media-sync" ], "summary": "List synced folders", "description": "Return the workspace's synced folders, including the remote path, the destination folder in Brix, the connected account, sync status, the last error, the last check time, and the number of files synced. Only folders connected at locations where the caller holds the integration view permission are returned.", "x-brix-permission": "integration.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string", "description": "`onedrive` or `sharepoint`." }, "remotePath": { "type": "string" }, "folderId": { "type": "string", "description": "The library folder the files land in." }, "folderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountConnected": { "type": "boolean", "description": "False when the connected account was removed: syncing stops until it is connected again." }, "status": { "type": "string", "enum": [ "ok", "error", "paused" ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSyncAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "itemsSynced": { "type": "integer" }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "provider", "remotePath", "folderId", "folderName", "accountLabel", "accountConnected", "status", "lastError", "lastSyncAt", "itemsSynced", "createdAt", "updatedAt" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] } }, "/v1/media-sync/{id}": { "delete": { "operationId": "deleteMediaSync", "tags": [ "media-sync" ], "summary": "Stop syncing a folder", "description": "Stop following a remote folder. The sync source is removed, but files already imported are not affected. This action is recorded in the activity log.\n\n**Notes.**\n- The files already synced stay in the library.", "x-brix-permission": "integration.delete", "x-brix-schema": "verified", "x-brix-notes": [ "The files already synced stay in the library." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Synced folder id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.delete" ] } ] } }, "/v1/media-sync/{id}/sync": { "post": { "operationId": "syncMediaSync", "tags": [ "media-sync" ], "summary": "Sync a folder now", "description": "Trigger an immediate sync of one connected folder, bounded to a fixed number of files for the run, and return a summary of what happened. This action is recorded in the activity log.\n\n**Notes.**\n- A failed run still answers 200: read `error`.", "x-brix-permission": "integration.create", "x-brix-schema": "verified", "x-brix-notes": [ "A failed run still answers 200: read `error`." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Synced folder id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "imported": { "type": "integer" }, "updated": { "type": "integer" }, "removed": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" }, "caughtUp": { "type": "boolean", "description": "False when more changes remain for the next run." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the run stopped, in words; null when it did not." } }, "required": [ "imported", "updated", "removed", "skipped", "failed", "caughtUp", "error" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No synced folder with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/media/{id}": { "delete": { "operationId": "deleteMedia", "tags": [ "media" ], "summary": "Delete a media asset", "description": "Move a media asset to the recycle bin. Playlists and screens that reference it show a gap where the asset was until it is restored or replaced.\n\nMoves the asset to the recycle bin (restorable for 30 days) and removes it from every playlist. Screens casting it return to their schedule.", "x-brix-permission": "media.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Delete even when it is shared into other places." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "sharesRemoved": { "type": "integer", "description": "Shares removed with it." } }, "required": [ "id", "deleted", "sharesRemoved" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such asset in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`content_shared`: the item is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.delete" ] } ] }, "get": { "operationId": "getMedia", "tags": [ "media" ], "summary": "Get a media asset", "description": "Return one media asset with its full details, including kind, url, dimensions, duration, tags, folder, play window, and web configuration.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MediaAssetDetail" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such asset in this workspace (or it is in the recycle bin).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] }, "patch": { "operationId": "updateMedia", "tags": [ "media" ], "summary": "Update a media asset", "description": "Edit a media asset. Accepts name, altText, tags, folderId, node, play-window fields (startsAt, expiresAt, autoArchiveOnExpiry), audioEnabled, a QR code overlay, and web configuration. Changing the URL of a web-kind asset re-checks it to make sure it is safe to fetch.\n\nSend only the fields to change. `state` and `bytes` are set by processing and ignored here.\n\n**Notes.**\n- The response is the stored row, not the GET shape: it has no `usageCount`, `uploadedByName` or `uploadSource`.\n- An invalid `fit` answers 400 with only `error` (no `message`); every other validation failure is 422 `validation_error`.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The response is the stored row, not the GET shape: it has no `usageCount`, `uploadedByName` or `uploadSource`.", "An invalid `fit` answers 400 with only `error` (no `message`); every other validation failure is 422 `validation_error`." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "video", "audio", "pdf", "powerpoint", "web", "dashboard", "weather", "rss", "clock", "qr", "menu", "directory", "donor-wall", "hall-of-fame", "birthday-board", "recognition", "wayfinding", "check-in", "emergency", "touch-kiosk", "package", "font" ] }, "url": { "description": "An https URL, a /v1/ path or a data:image URI; for a web link, the page address (private and internal network addresses are refused).", "type": "string" }, "active": { "description": "False archives the asset.", "type": "boolean" }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "autoArchiveOnExpiry": { "type": "boolean" }, "qr": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "webConfig": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "nodeId": { "description": "Move to another location (needs media.edit there).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "audioEnabled": { "type": "boolean" }, "fit": { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ] }, "baseUpdatedAt": { "description": "The `updatedAt` your edit is based on. When set and the row has moved since, the write is refused with 409 and the current row.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MediaAssetUpdated" } }, "required": [ "data" ] } } } }, "400": { "description": "`fit` is not one of contain, cover, fill, blur-fill.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Moving it to a location where you lack media.edit, or attaching an SSO connection without settings.edit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such asset in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: `baseUpdatedAt` is stale; the body carries `current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid kind, URL, folder or location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/captions": { "get": { "operationId": "listMediaCaptions", "tags": [ "media" ], "summary": "Get a video's captions", "description": "Return a video's caption track as WebVTT. Add ?lang= to request a machine-translated version, for example ?lang=es for Spanish. This URL is stable, so it can be referenced directly by a player.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Two- or three-letter language code: a machine translation of the track (default: the original)." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "text/vtt": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id, or it has no captions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 reads a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] }, "post": { "operationId": "createMediaCaption", "tags": [ "media" ], "summary": "Generate captions for a video", "description": "Automatically generate a caption track for a video from its audio and attach it to the asset. To upload a caption file instead, use the caption upload operation. To show or hide an existing caption track, use the caption visibility operation.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "key": { "type": "string", "description": "Storage path of the caption track." }, "state": { "type": "string", "const": "ready" } }, "required": [ "ok", "key", "state" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`wrong_kind`: not a video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id, or no bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Over 40 MB: send the audio to /captions/transcribe instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`transcription_failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/captions/transcribe": { "post": { "operationId": "transcribeMediaCaption", "tags": [ "media" ], "summary": "Generate captions from a video's audio", "description": "Convert a short audio clip, extracted from a video as 16 kHz mono WAV, into a caption track. Use this instead of the standard caption-generation operation when the full video file is too large to process directly.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The video's audio track (e.g. 16 kHz mono WAV), at most 20 MB." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "key": { "type": "string", "description": "Storage path of the caption track." }, "state": { "type": "string", "const": "ready" } }, "required": [ "ok", "key", "state" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`wrong_kind`: not a video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Over 20 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Empty body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`transcription_failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/captions/upload": { "post": { "operationId": "uploadMediaCaption", "tags": [ "media" ], "summary": "Upload a caption file", "description": "Attach a caption file to a video. SRT files are converted to WebVTT; WebVTT files are stored as-is. This is the alternative to automatic caption generation.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "requestBody": { "required": true, "content": { "text/vtt": { "schema": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "A .vtt or .srt caption file, at most 5 MB." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "key": { "type": "string", "description": "Storage path of the caption track." }, "state": { "type": "string", "const": "ready" } }, "required": [ "ok", "key", "state" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`wrong_kind`: not a video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Over 5 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Not a .vtt or .srt track.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Empty body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/captions/visibility": { "post": { "operationId": "createMediaCaptionVisibility", "tags": [ "media" ], "summary": "Show or hide a video's captions", "description": "Turn a video's caption track on or off for playback. Hiding the track keeps it in storage so it can be shown again later. If no caption track exists yet, the response indicates that one must be generated first.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "show": { "description": "True shows captions; anything else hides them.", "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "hidden", "ready", "needs_audio" ], "description": "`needs_audio`: shown, but the video has no caption track yet." } }, "required": [ "state" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`wrong_kind`: not a video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/delta": { "get": { "operationId": "getMediaDelta", "tags": [ "media" ], "summary": "Check for a media delta download", "description": "Used by playback devices to check whether their cached copy of a file is current. The caller sends the checksum of its cached copy and receives either the data needed to update it, or a flag indicating no partial update is available along with a URL to download the full file.\n\n**Notes.**\n- Reserved: delta downloads are not offered yet, so this always answers `deltaAvailable: false`.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "x-brix-notes": [ "Reserved: delta downloads are not offered yet, so this always answers `deltaAvailable: false`." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deltaAvailable": { "type": "boolean", "const": false }, "downloadUrl": { "type": "null" } }, "required": [ "deltaAvailable", "downloadUrl" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] } }, "/v1/media/{id}/file": { "get": { "operationId": "getMediaFile", "tags": [ "media" ], "summary": "Download a media file", "description": "Stream the media asset's file bytes. Supports HTTP Range requests for partial downloads.\n\n**Notes.**\n- HTML, SVG and script files are served as `application/octet-stream` attachments, never inline.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "x-brix-notes": [ "HTML, SVG and script files are served as `application/octet-stream` attachments, never inline." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" }, { "name": "w", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Images: resize to this width (a thumbnail)." }, { "name": "h", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Images: resize to this height." }, { "name": "fit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cover", "contain", "scale-down", "crop", "pad" ] }, "description": "How a resized copy fits `w` × `h` (default `cover`)." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id, or the file is not in storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] } }, "/v1/media/{id}/focal-region": { "post": { "operationId": "createMediaFocalRegion", "tags": [ "media" ], "summary": "Detect an image's focal region", "description": "Detect the main subject of an image and cache its position as a normalized x, y, width, and height. This lets the image be cropped around its subject when shown in a differently shaped area, instead of being cropped from the center.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "region": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "x", "y", "w", "h" ] }, { "type": "null" } ], "description": "Fractions (0–1) of the image. Null when nothing stood out; the stored region is then unchanged." } }, "required": [ "region" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`wrong_kind`: not an image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id, or no bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Over 32 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/playback-quality": { "get": { "operationId": "getMediaPlaybackQuality", "tags": [ "media" ], "summary": "Get a video's playback quality", "description": "Return dropped-frame data reported by screens that have played this video, used to flag videos that are not playing smoothly. A null health value means the asset has not been measured yet, not that it is playing well.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "health": { "anyOf": [ { "type": "object", "properties": { "strugglingScreens": { "type": "integer" }, "screensReporting": { "type": "integer" }, "worstDropPct": { "type": "number" }, "videoWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "videoHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "strugglingScreens", "screensReporting", "worstDropPct", "videoWidth", "videoHeight" ] }, { "type": "null" } ], "description": "Null until a screen reports on this video." }, "stutterDropPct": { "type": "number", "description": "Dropped-frame percentage above which a screen counts as struggling." }, "minSamplesToWarn": { "type": "integer" }, "screens": { "type": "array", "items": { "type": "object", "properties": { "screenId": { "type": "string" }, "worstDropPct": { "type": "number" }, "meanDropPct": { "type": "number" }, "samples": { "type": "integer" }, "videoWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "videoHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lastSeenAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "screenId", "worstDropPct", "meanDropPct", "samples", "videoWidth", "videoHeight", "lastSeenAt" ] } } }, "required": [ "health", "stutterDropPct", "minSamplesToWarn", "screens" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] } }, "/v1/media/{id}/poster": { "get": { "operationId": "getMediaPoster", "tags": [ "media" ], "summary": "Get a media poster image", "description": "Return the poster image attached to a media asset, used as its thumbnail for videos and PDFs.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" }, { "name": "w", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Resize to this width." }, { "name": "h", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Resize to this height." }, { "name": "fit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cover", "contain", "scale-down", "crop", "pad" ] } } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id, or it has no poster.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] }, "post": { "operationId": "createMediaPoster", "tags": [ "media" ], "summary": "Set or generate a media poster", "description": "Attach a poster image to a media asset, used as its thumbnail. The file must be an image and no larger than 4 MB.\n\n**Notes.**\n- With `?generate=1` the body is `{ thumbnailUrl, generated }` and no request body is read.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "x-brix-notes": [ "With `?generate=1` the body is `{ thumbnailUrl, generated }` and no request body is read." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" }, { "name": "generate", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "`1`: generate the poster from the media itself (send no body)." } ], "requestBody": { "required": false, "content": { "image/*": { "schema": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The poster image (at most 4 MB). Omit it with `?generate=1`." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "thumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "generated": { "type": "boolean", "description": "False when no poster could be made (the previous one is kept)." } }, "required": [ "thumbnailUrl", "generated" ] }, { "type": "object", "properties": { "thumbnailUrl": { "type": "string" } }, "required": [ "thumbnailUrl" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Over 4 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Not a recognised image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Empty body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/render": { "post": { "operationId": "renderMedia", "tags": [ "media" ], "summary": "Render a web link now", "description": "Capture and store a screenshot of a web or link asset. If screenshot rendering is not available for this workspace, the response reports that it is not configured rather than failing.\n\n**Notes.**\n- Usually queued (`queued: true`); the frame is then at GET /v1/media/{id}/render-frame.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Usually queued (`queued: true`); the frame is then at GET /v1/media/{id}/render-frame." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "queued": { "type": "boolean", "const": true } }, "required": [ "ok", "queued" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "key": { "type": "string" } }, "required": [ "ok", "key" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 renders a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The render failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/render-frame": { "get": { "operationId": "getMediaRenderFrame", "tags": [ "media" ], "summary": "Get a web link's latest render", "description": "Return the most recent screenshot generated for a web or link asset by the render operation.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id, or the link has not been rendered yet (a render is then queued).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] } }, "/v1/media/{id}/render-source": { "get": { "operationId": "getMediaRenderSource", "tags": [ "media" ], "summary": "Stream source bytes for poster rendering", "description": "Read-only byte stream used to generate a video's poster image, with support for partial (Range) reads. Access is scoped to a single media asset and workspace and expires after two minutes. This is not a general-purpose way to download or stream media; use the media file operation for that.", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/media/{id}/restore": { "post": { "operationId": "restoreMedia", "tags": [ "media" ], "summary": "Restore a deleted media item", "description": "Bring back a deleted media asset. Any playlist or screen still referencing it resumes rendering it.", "x-brix-permission": "media.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: it is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.delete" ] } ] } }, "/v1/media/{id}/rotate": { "post": { "operationId": "rotateMedia", "tags": [ "media" ], "summary": "Rotate a photo or video", "description": "Rotate a photo or video 90, 180, or 270 degrees clockwise. This rewrites the stored file rather than only changing how it is displayed, since playback devices cannot rotate video at display time. Images are rotated immediately; video rotation is queued, and the asset keeps playing its current version until the rotated file is ready.\n\n**Notes.**\n- Photos rotate now (`rotated`); videos are re-encoded in the background (`queued`).", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Photos rotate now (`rotated`); videos are re-encoded in the background (`queued`)." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "degrees": { "anyOf": [ { "type": "number", "const": 90 }, { "type": "number", "const": 180 }, { "type": "number", "const": 270 } ], "description": "Clockwise." } }, "required": [ "degrees" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "outcome": { "type": "string", "const": "rotated" }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "rotation": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 90 }, { "type": "number", "const": 180 }, { "type": "number", "const": 270 } ] } }, "required": [ "ok", "outcome", "width", "height", "rotation" ] }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "outcome": { "type": "string", "const": "queued" }, "rotation": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 90 }, { "type": "number", "const": 180 }, { "type": "number", "const": 270 } ] } }, "required": [ "ok", "outcome", "rotation" ] } ] } }, "required": [ "data" ] } } } }, "400": { "description": "`degrees` is not 90, 180 or 270, or the item is not a photo or video.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id, or its bytes are gone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A rotation is already running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The image service failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Rotation is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/suggest": { "post": { "operationId": "suggestMedia", "tags": [ "media" ], "summary": "Suggest alt text and tags for an image", "description": "Analyze an image asset and return suggested altText and tags. This only returns suggestions; it does not save them, so use the update-media-asset operation to accept them. Only images are supported. If this feature is temporarily unavailable, the response returns empty values rather than failing.\n\n**Notes.**\n- Suggestions only: nothing is saved.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Suggestions only: nothing is saved." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "altText", "tags" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`wrong_kind`: not an image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id, or no bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Over 32 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/{id}/usage": { "get": { "operationId": "getMediaUsage", "tags": [ "media" ], "summary": "Show where a media asset is used", "description": "Return where a media asset is used, across playlists, creatives, and layouts, along with when it was last played.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MediaUsage" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such asset in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] } }, "/v1/media/{id}/web-secrets": { "put": { "operationId": "replaceMediaWebSecret", "tags": [ "media" ], "summary": "Set a web link's secrets", "description": "Store credentials, such as authentication tokens or login passwords, for a web asset. Values are encrypted at rest and write-only: send an object mapping reference names to values, where a null value deletes that reference. Only the reference names, never the values, can be read back later. This merges with any existing secrets rather than replacing them.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Media asset id.", "example": "med_0c1d2e3f4a5b6c7d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secrets": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": "Secret name → value (at most 50, values ≤ 8192 characters). `null` or `\"\"` removes one; names not sent are kept." } }, "required": [ "secrets" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "refs": { "type": "array", "items": { "type": "string" }, "description": "The secret NAMES now stored. Values are never returned." } }, "required": [ "ok", "refs" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Too many secrets, or a name or value too long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No media with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/backfill-avif": { "post": { "operationId": "createMediaBackfillAvif", "tags": [ "media" ], "summary": "Convert AVIF images", "description": "Convert this workspace's existing AVIF image assets to JPEG.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer" }, "after": { "description": "`nextAfter` of the previous run.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "scanned": { "type": "integer" }, "transcoded": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "type": "string", "enum": [ "source_gone", "undecodable", "service_error", "binding_absent", "transcoded", "already_done", "not_avif" ] } }, "required": [ "id", "name", "result" ] } }, "nextAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass as `after` to continue; null when done." } }, "required": [ "scanned", "transcoded", "rows", "nextAfter" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 10 runs a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`binding_absent`: image conversion is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/backfill-codec-warnings": { "post": { "operationId": "createMediaBackfillCodecWarning", "tags": [ "media" ], "summary": "Re-check codec warnings", "description": "Recompute codec-compatibility warnings for this workspace's video assets under the current compatibility rules, and clear any outdated re-export warnings. Safe to run more than once.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "scanned": { "type": "integer" }, "cleared": { "type": "integer" } }, "required": [ "scanned", "cleared" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 10 runs a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/backfill-heic": { "post": { "operationId": "createMediaBackfillHeic", "tags": [ "media" ], "summary": "Convert HEIC images", "description": "Convert this workspace's existing HEIC image assets to JPEG so they display correctly on devices that cannot decode HEIC. Safe to run more than once, and applies only to your own workspace. Returns a 503 error if the conversion feature is temporarily unavailable.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer" }, "after": { "description": "`nextAfter` of the previous run.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "scanned": { "type": "integer" }, "transcoded": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "result": { "type": "string", "enum": [ "source_gone", "undecodable", "service_error", "binding_absent", "transcoded", "already_done", "not_heic" ] } }, "required": [ "id", "name", "result" ] } }, "nextAfter": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "scanned", "transcoded", "rows", "nextAfter" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 10 runs a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`binding_absent`: HEIC conversion is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/backfill-video-metadata": { "post": { "operationId": "createMediaBackfillVideoMetadata", "tags": [ "media" ], "summary": "Fill in missing video details", "description": "Scan this workspace's existing video files to fill in missing width, height, and duration values, and correct codec information that was guessed from the filename. Also updates the codec-compatibility warning where applicable.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "description": "Most videos to read this run.", "type": "integer" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "scanned": { "type": "integer" }, "updated": { "type": "integer" }, "reclassified": { "type": "integer" } }, "required": [ "scanned", "updated", "reclassified" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 10 runs a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/import-url": { "post": { "operationId": "importMediaFromUrl", "tags": [ "media" ], "summary": "Import media from a URL", "description": "Import a file from a remote URL into the media library. The API fetches the file server-side, checking that the URL does not point to a disallowed destination, stores its bytes, and creates the media asset record. This is the same path used by the upload_media_from_url tool.\n\nFetches a public http(s) URL into the library. SVG is refused.\n\n**Notes.**\n- The response is the row as built for insert, not the GET shape: `tags` is a JSON string (not an array), `sourceUrl` is present but not stored, and most columns (state, fit, width, …) are absent. Read GET /v1/media/{id} for the settled asset.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "x-brix-notes": [ "The response is the row as built for insert, not the GET shape: `tags` is a JSON string (not an array), `sourceUrl` is present but not stored, and most columns (state, fit, width, …) are absent. Read GET /v1/media/{id} for the settled asset." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Public http(s) address of the file." }, "name": { "description": "Display name; defaults to the file name in the URL.", "type": "string" }, "folderId": { "type": "string" }, "nodeId": { "description": "Home location; defaults to your own.", "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "autoCaption": { "description": "Videos: generate captions.", "type": "boolean" }, "autoSmartFit": { "description": "Images: detect a focal region (default true).", "type": "boolean" } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ImportedMedia" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`too_large`: the file is over the size limit for its kind.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_type`: SVG or an unknown content type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing or non-http URL, a blocked address (`url_blocked`), or an unknown folder or location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`fetch_failed` / `source_status`: the source did not answer with the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media/moderate": { "post": { "operationId": "moderateMedia", "tags": [ "media" ], "summary": "Check text for unsafe content", "description": "Run a safety classifier over a piece of user-submitted text, such as banner copy or a message board post, and return its verdict. This operation only classifies the text; it does not store it.", "x-brix-permission": "media.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string" } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "flagged": { "type": "boolean" }, "reason": { "description": "Present when flagged.", "type": "string" }, "checked": { "type": "boolean", "description": "False when the check could not run (the text is then not flagged)." } }, "required": [ "flagged", "checked" ] } }, "required": [ "data" ] } } } }, "400": { "description": "`text` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/media/stats": { "get": { "operationId": "listMediaStats", "tags": [ "media" ], "summary": "Get media library statistics", "description": "Return summary counts for the media library in one response: total assets, unused assets, and a count per folder. Use this instead of listing all media when only summary counts are needed.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "total": { "type": "integer" }, "unused": { "type": "integer", "description": "Items used nowhere." }, "folders": { "type": "array", "items": { "type": "object", "properties": { "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "count": { "type": "integer" } }, "required": [ "folderId", "count" ] }, "description": "Items per folder; `folderId` null = not in a folder." } }, "required": [ "total", "unused", "folders" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] } }, "/v1/media/upload": { "post": { "operationId": "uploadMedia", "tags": [ "media" ], "summary": "Upload a media file", "description": "Upload a file in a single request using multipart form data. Accepts form fields file (required), and optional name, nodeId, and folderId. This stores the file and creates the media asset record in one step, and is safe to retry with the same Idempotency-Key header. For large files or programmatic clients, minting an upload URL and then uploading with PUT is usually simpler.\n\n**Notes.**\n- Form fields other than `file` are strings, as multipart sends them.\n- For files over ~100 MB use the multipart upload.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "x-brix-notes": [ "Form fields other than `file` are strings, as multipart sends them.", "For files over ~100 MB use the multipart upload." ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The file. SVG is refused." }, "name": { "description": "Display name; default the file name.", "type": "string" }, "nodeId": { "description": "Home location; default the caller's own.", "type": "string" }, "folderId": { "type": "string" }, "alt": { "description": "Alt text.", "type": "string" }, "decorative": { "description": "`1`: the image is decorative (empty alt text).", "type": "string", "enum": [ "1" ] }, "autoCaption": { "description": "Videos: `1` generates captions.", "type": "string", "enum": [ "1" ] }, "autoSmartFit": { "description": "Images: `0` skips focal-region detection (default on).", "type": "string", "enum": [ "0", "1" ] }, "durationSec": { "description": "Videos: length in seconds, when the client measured it.", "type": "string" }, "loopDurationMs": { "description": "Animated images: loop length.", "type": "string" }, "width": { "type": "string" }, "height": { "type": "string" }, "codec": { "type": "string" }, "codecString": { "type": "string" }, "fps": { "type": "string" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UploadedMedia" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The folder or location does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The file is over the limit for its kind (images 250 MB, video 2 GB, documents 100 MB, fonts 10 MB).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "SVG, or a type the library does not take.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`file` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media/upload/{uploadId}": { "put": { "operationId": "replaceMediaUpload", "tags": [ "media" ], "summary": "Upload bytes to a minted upload URL", "description": "Upload the raw file bytes for a previously created upload slot. Send the file as the request body and set the Content-Type header to match the file's type. After uploading, finalize the upload to create the media asset record.\n\n**Notes.**\n- This stores the bytes for a bulk import; the import itself creates the media rows.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "x-brix-notes": [ "This stores the bytes for a bulk import; the import itself creates the media rows." ], "parameters": [ { "name": "uploadId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "An `upl_…` id from POST /v1/import/upload-urls." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The file bytes. Send the file's real `content-type` when you know it." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "uploadId": { "type": "string" }, "bytes": { "type": "integer" } }, "required": [ "uploadId", "bytes" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No mint with this id in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Over 500 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "SVG.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Empty body or a malformed id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media/upload/multipart/{id}": { "get": { "operationId": "getMediaUploadMultipart", "tags": [ "media" ], "summary": "Get a multipart upload's progress", "description": "Return the state of an in-progress multipart upload, including the file's name, size, kind, part size, and every part already received, each with its part number, ETag, and size. Use this to resume an interrupted upload from the last completed part instead of starting over. Returns 404 if the upload belongs to another workspace, has already finished, or has expired.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The upload's media id, from `POST /v1/media/upload/multipart/create`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "kind": { "type": "string" }, "sizeBytes": { "type": "integer" }, "partSize": { "type": "integer" }, "masterOf": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "parts": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer" }, "etag": { "type": "string" }, "size": { "type": "integer" } }, "required": [ "partNumber", "etag", "size" ] }, "description": "Parts already stored: resume from the first missing one." } }, "required": [ "id", "name", "contentType", "kind", "sizeBytes", "partSize", "masterOf", "createdAt", "parts" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media/upload/multipart/{id}/abort": { "post": { "operationId": "abortMediaUploadMultipart", "tags": [ "media" ], "summary": "Cancel a multipart upload", "description": "Cancel an in-progress multipart upload and discard any parts already received. Safe to call more than once.\n\n**Notes.**\n- Answers `aborted: true` also when there was nothing to cancel.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "x-brix-notes": [ "Answers `aborted: true` also when there was nothing to cancel." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The upload's media id, from `POST /v1/media/upload/multipart/create`." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "aborted": { "type": "boolean", "const": true } }, "required": [ "aborted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media/upload/multipart/{id}/complete": { "post": { "operationId": "completeMediaUploadMultipart", "tags": [ "media" ], "summary": "Complete a multipart upload", "description": "Finalize a multipart upload by sending the list of uploaded parts, each with partNumber and etag. If the list is left empty, the server completes the upload using the parts it already has on record, so a client resuming an interrupted upload does not need to know every part's ETag. This creates the media asset record; video files are automatically queued for processing.\n\n**Notes.**\n- For a master upload (`masterOf`) the body is `{ id, masterKey, masterBytes }`; otherwise it is the new media row.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "x-brix-notes": [ "For a master upload (`masterOf`) the body is `{ id, masterKey, masterBytes }`; otherwise it is the new media row." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The upload's media id, from `POST /v1/media/upload/multipart/create`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer" }, "etag": { "type": "string" } }, "required": [ "partNumber", "etag" ] } } }, "required": [ "parts" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Media asset id.", "examples": [ "med_0c1d2e3f4a5b6c7d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace library root." }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Media kind: image, video, audio, pdf, powerpoint, web, dashboard, weather, rss, clock, qr, menu, directory, donor-wall, hall-of-fame, birthday-board, recognition, wayfinding, check-in, emergency, touch-kiosk, package, font. Free text in storage, so a very old row may carry another value." }, "url": { "type": "string", "description": "Where the bytes live: a `/v1/media/<id>/file` path, an `https` URL, `r2://…`, or (for a web link) the page address." }, "bytes": { "type": "integer", "description": "Stored size in bytes (0 for links and apps)." }, "active": { "type": "boolean", "description": "False when archived." }, "altText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Video/audio length in seconds." }, "loopDurationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Animated image loop length." }, "state": { "type": "string", "enum": [ "ready", "failed", "processing", "ready_with_warnings", "needs_action" ] }, "stateReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stateFault": { "anyOf": [ { "type": "string", "enum": [ "user", "platform" ] }, { "type": "null" } ] }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "autoCaption": { "type": "boolean" }, "captionState": { "type": "null" }, "autoSmartFit": { "type": "boolean" }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "type": "null" } }, "required": [ "id", "spaceId", "nodeId", "folderId", "name", "kind", "url", "bytes", "active", "altText", "width", "height", "durationSec", "loopDurationMs", "state", "stateReason", "stateCode", "stateFault", "codec", "autoCaption", "captionState", "autoSmartFit", "importSourceId", "createdAt", "updatedAt", "deletedAt" ] }, { "type": "object", "properties": { "id": { "type": "string", "description": "The asset the master was attached to (`masterOf`)." }, "masterKey": { "type": "string" }, "masterBytes": { "type": "integer" } }, "required": [ "id", "masterKey", "masterBytes" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A part is missing or does not match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No parts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media/upload/multipart/{id}/part/{partNumber}": { "put": { "operationId": "replaceMediaUploadMultipartPart", "tags": [ "media" ], "summary": "Upload one part of a multipart upload", "description": "Upload one part of a file for an in-progress multipart upload, identified by its part number. Returns the part's ETag, which is needed to complete the upload. Returns 404 if the upload belongs to another workspace.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The upload's media id, from `POST /v1/media/upload/multipart/create`." }, { "name": "partNumber", "in": "path", "required": true, "schema": { "type": "string" }, "description": "1-based part number." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The part's bytes." } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "partNumber": { "type": "integer" }, "etag": { "type": "string", "description": "Send it back in `complete`." } }, "required": [ "partNumber", "etag" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such upload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The part is larger than `partSize`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Bad part number or empty part.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media/upload/multipart/create": { "post": { "operationId": "createMediaUploadMultipartCreate", "tags": [ "media" ], "summary": "Start a multipart upload", "description": "Begin a multipart upload for large files, such as multi-gigabyte videos, that are too large for a single request. Validates the file kind and checks its size against the limit allowed for that kind. Returns an upload id and the part size to use for subsequent part uploads.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "contentType": { "description": "The file's media type; decides the kind.", "type": "string" }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0 }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "alt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "decorative": { "type": "boolean" }, "loopDurationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codecString": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "masterOf": { "description": "An existing video's id: upload a high-resolution master for it instead of a new asset.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "importSourceId": { "description": "Your own id for the file. If a live asset already has it, the answer is 200 with `exists: true`.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "sizeBytes" ] } } } }, "responses": { "200": { "description": "Success: `importSourceId` matched a live asset: `{ id, exists: true }`, nothing started.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "The upload id (and the media id it will become)." }, "partSize": { "type": "integer", "description": "Send parts of exactly this size (the last may be smaller)." } }, "required": [ "id", "partSize" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "exists": { "type": "boolean", "const": true } }, "required": [ "id", "exists" ] } ] } }, "required": [ "data" ] } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "The upload id (and the media id it will become)." }, "partSize": { "type": "integer", "description": "Send parts of exactly this size (the last may be smaller)." } }, "required": [ "id", "partSize" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "exists": { "type": "boolean", "const": true } }, "required": [ "id", "exists" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`sizeBytes` is over the limit for the kind.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "SVG.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unknown file type, or `sizeBytes` missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/media/upload/package": { "post": { "operationId": "createMediaUploadPackage", "tags": [ "media" ], "summary": "Upload an HTML5 package", "description": "Upload a zipped HTML5 package as a media asset, using multipart form data with fields file (required), and optional name, nodeId, and folderId. The archive is validated, expanded into storage, and its entry page is identified automatically.", "x-brix-permission": "media.create", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentEncoding": "binary", "description": "The .zip. It must hold an entry page (`index.html`)." }, "name": { "description": "Display name; default the file name.", "type": "string" }, "nodeId": { "description": "Home location; default the caller's own.", "type": "string" }, "folderId": { "type": "string" } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Media asset id.", "examples": [ "med_0c1d2e3f4a5b6c7d" ] }, "spaceId": { "type": "string", "description": "Workspace id." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location; null = workspace library root." }, "folderId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "kind": { "type": "string", "const": "package" }, "url": { "type": "string", "description": "Where the bytes live: a `/v1/media/<id>/file` path, an `https` URL, `r2://…`, or (for a web link) the page address." }, "bytes": { "type": "integer", "description": "Stored size in bytes (0 for links and apps)." }, "checksum": { "type": "string", "description": "SHA-256 of the .zip." }, "active": { "type": "boolean", "description": "False when archived." }, "packageEntry": { "type": "string", "description": "The entry page found in the archive, e.g. `index.html`." }, "packageFiles": { "type": "integer", "description": "Files in the archive." }, "packageBytes": { "type": "integer", "description": "Expanded size of the archive, in bytes." }, "state": { "type": "string", "const": "ready" }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "type": "null" } }, "required": [ "id", "spaceId", "nodeId", "folderId", "name", "kind", "url", "bytes", "checksum", "active", "packageEntry", "packageFiles", "packageBytes", "state", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The folder or location does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The .zip, or its expanded contents, is over the limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`file` is missing, the .zip cannot be read, or a file in it is refused (unsafe path, type not allowed, no entry page).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.create" ] } ] } }, "/v1/oauth/authorize": { "get": { "operationId": "getOauthAuthorize", "tags": [ "oauth" ], "summary": "Start OAuth authorization", "description": "The OAuth 2.1 authorization endpoint for apps that connect to the MCP endpoint. It checks the client, the exact redirect URI, the PKCE challenge (S256) and that `resource` is the MCP URL, then redirects the browser to the Brix consent screen, where a person approves the connection. Errors are shown on the consent screen, never sent to the client's redirect URI. This endpoint is rate-limited per IP address.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth/register": { "post": { "operationId": "createOauthRegister", "tags": [ "oauth" ], "summary": "Register OAuth client", "description": "Registers a public OAuth client (dynamic client registration, RFC 7591) that uses PKCE and no client secret. Redirect URIs must use https, or http on the local computer. A registered client belongs to no workspace and can do nothing until a person approves a connection. This endpoint is rate-limited per IP address.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth/revoke": { "post": { "operationId": "createOauthRevoke", "tags": [ "oauth" ], "summary": "Revoke OAuth token", "description": "Revokes a refresh token or an MCP access token (RFC 7009). This ends the whole connection: every access token of that connection stops working on its next request. Always answers 200.", "x-brix-permission": "oauth-app.revoked", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/oauth/token": { "post": { "operationId": "createOauthToken", "tags": [ "oauth" ], "summary": "Get OAuth access token", "description": "Exchanges an API key for an OAuth 2.0 access token using the client-credentials grant: `client_id` is the API key's id and `client_secret` is the key's secret. The returned token is a reference to the key rather than a copy of its permissions, so revoking the key immediately invalidates every token issued from it, and any permission change takes effect on the token's next use without needing a refresh. Responses follow the OAuth specification, including `invalid_client` on an authentication failure and `unsupported_grant_type` for an unsupported grant. This endpoint is rate-limited per IP address.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/org-nodes": { "get": { "operationId": "listLocations", "tags": [ "org-nodes" ], "summary": "List locations", "description": "Returns the workspace's location tree, for example districts, regions, sites, and departments, with each location's path and member count.\n\nEvery location in the workspace tree the caller may see (not paginated). Build the tree from `parentId`.", "x-brix-permission": "org-unit.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "on_4d5e6f7a8b9c0d1e", "name": "Chicago Loop", "parentId": "space_1a2b3c4d5e6f7a8b", "externalId": "STORE-0142", "timezone": "America/Chicago", "tier": 2, "isSpace": false, "screenCount": 6, "members": [ { "userId": "usr_5e6f7a8b9c0d1e2f", "userName": "Sam Rivera", "roleId": "role_0a1b2c3d4e5f6a7b", "roleName": "Store manager", "roleColor": null, "source": null } ], "featureOverrides": [], "approval": { "required": false, "inheritFromParent": true, "escalateUpTiers": false, "allowSharedExemptions": false, "approvers": [] }, "billing": null, "prefs": { "location": { "label": "Chicago Loop", "lat": 41.8837, "lng": -87.6289 }, "language": null, "defaultContent": null } } ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "org-unit.view" ] } ] }, "post": { "operationId": "createLocation", "tags": [ "org-nodes" ], "summary": "Create a location", "description": "Creates a new location under a parent location. Provide `name`, `parentId`, and an optional `kind`. To create many locations at once, use the bulk-create operation instead.", "x-brix-permission": "org-unit.create", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Location name." }, "parentId": { "description": "Parent location; omit to place it directly under the workspace root.", "type": "string" }, "externalId": { "description": "Your own location code; must be unique in the workspace.", "type": "string" }, "timezone": { "description": "IANA zone, e.g. `Europe/London`.", "type": "string" }, "approval": { "description": "Owner-only when it opts out of inheritance or names approvers (403 otherwise); ignored from anyone else.", "$ref": "#/components/schemas/ApprovalPolicy" }, "isSpace": { "description": "Owner-only: create a child workspace (franchise).", "type": "boolean" }, "billingOwnerNodeId": { "description": "With `isSpace`: the ancestor workspace that pays.", "type": "string" }, "screenLimit": { "description": "Owner-only, advisory.", "type": "integer", "minimum": 0 }, "tier": { "description": "Owner-only. Defaults to 2.", "type": "integer" }, "billing": { "description": "Owner-only." }, "featureOverrides": { "description": "Owner-only." } }, "required": [ "name" ] }, "example": { "name": "Chicago Loop", "parentId": "on_0a1b2c3d4e5f6a7b", "externalId": "STORE-0142", "timezone": "America/Chicago" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Location" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "An owner-only field was set (`isSpace`, `billing`, `featureOverrides`, `tier`, `screenLimit`, or a non-inheriting approval policy).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`location_id_taken`: another location already uses this `externalId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` missing, invalid `externalId`, or `parentId` not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "org-unit.create" ] } ] } }, "/v1/org-nodes/{id}": { "delete": { "operationId": "deleteOrgNode", "tags": [ "org-nodes" ], "summary": "Delete location", "description": "Soft-deletes a location. Everything at that location, including screens, content and folders, is transferred to its parent location first, so nothing is left orphaned. Role assignments at the location are removed, so the same rule as removing a role assignment applies: only an account owner can remove an owner's assignment. The root location and any location with active child locations cannot be deleted.\n\n**Notes.**\n- Screens and content move to the parent. The people placed here lose their role at this location.", "x-brix-permission": "org-unit.delete", "x-brix-schema": "verified", "x-brix-notes": [ "Screens and content move to the parent. The people placed here lose their role at this location." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Location (org node) id.", "example": "on_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "transferredTo": { "type": "string", "description": "The parent location that received this location's screens and content." } }, "required": [ "id", "deleted", "transferredTo" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold `org-unit.delete` there, or a person placed there outranks you (`owner_required`, `outranked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such location in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`protected` (the workspace root), `has_children` (move or delete the child locations first), or `last_owner`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "A franchise workspace's own subscription could not be ended; nothing was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "org-unit.delete" ] } ] }, "get": { "operationId": "getLocation", "tags": [ "org-nodes" ], "summary": "Get a location", "description": "Returns one location, including its path, parent, and settings.", "x-brix-permission": "org-unit.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Location (org node) id.", "example": "on_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Location" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such location in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "org-unit.view" ] } ] }, "patch": { "operationId": "updateLocation", "tags": [ "org-nodes" ], "summary": "Update a location", "description": "Updates a location's name, parent location, approval configuration, or preferences. Moving a location to a new parent updates the path of every location beneath it.\n\nRename, re-code, move, or change inheritable settings. Only the fields sent change.", "x-brix-permission": "org-unit.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Location (org node) id.", "example": "on_4d5e6f7a8b9c0d1e" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "parentId": { "description": "Move under another location (null = the workspace root).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "description": "IANA zone, or null/empty to inherit.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tier": { "type": "integer" }, "prefs": { "description": "Per-key: a value sets it, null clears it back to inherit, absent keeps it.", "type": "object", "properties": { "location": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "lat": { "type": "number", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "minimum": -180, "maximum": 180 } }, "required": [ "label", "lat", "lng" ] }, { "type": "null" } ] }, "language": { "description": "BCP 47 tag, or null to inherit.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultContent": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "playlist", "schedule", "creative", "signage", "app", "media", "layout" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, { "type": "null" } ] } } }, "approval": { "$ref": "#/components/schemas/ApprovalPolicy" }, "approvalBase": { "description": "Compare-and-set: the policy you last read. 409 if it changed since.", "$ref": "#/components/schemas/ApprovalPolicy" }, "billing": { "description": "Owner-only." }, "featureOverrides": { "description": "Owner-only." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Location" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Owner-only field, or a move you lack permission for at the destination.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such location in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`externalId` already used, or `approvalBase` no longer matches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid field (a malformed `prefs`, moving a location under itself, unplayable default content).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "org-unit.edit" ] } ] } }, "/v1/org-nodes/{id}/members": { "get": { "operationId": "listOrgNodeMembers", "tags": [ "org-nodes" ], "summary": "List location members", "description": "Returns the people directly assigned a role at this specific location, including the id of each role assignment. This id is needed to remove a membership, and is not included in the general roster listing.\n\n**Notes.**\n- Only the roles granted at this location, not those inherited from a parent.", "x-brix-permission": "user.view", "x-brix-schema": "verified", "x-brix-notes": [ "Only the roles granted at this location, not those inherited from a parent." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Location (org node) id.", "example": "on_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Membership id." }, "userId": { "type": "string" }, "userName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "roleId": { "type": "string" }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "roleColor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "userId", "userName", "roleId", "roleName", "roleColor" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold `user.view` at this location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such location in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.view" ] } ] }, "post": { "operationId": "createOrgNodeMember", "tags": [ "org-nodes" ], "summary": "Assign role at location", "description": "Grants a person a role at this location. Provide `userId` and `roleId`. You cannot grant a role carrying permissions you do not hold yourself at that location.\n\n**Notes.**\n- The 201 body is the membership row as written.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the membership row as written." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Location (org node) id.", "example": "on_4d5e6f7a8b9c0d1e" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "roleId": { "type": "string" } }, "required": [ "userId", "roleId" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Membership id." }, "spaceId": { "type": "string" }, "nodeId": { "type": "string" }, "userId": { "type": "string" }, "roleId": { "type": "string" }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "spaceId", "nodeId", "userId", "roleId", "createdAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The role holds permissions you do not hold, or you cannot grant them at this location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such location, person or role in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`userId` or `roleId` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/org-nodes/{id}/members/{memberId}": { "delete": { "operationId": "deleteOrgNodeMember", "tags": [ "org-nodes" ], "summary": "Remove role assignment", "description": "Removes one person's role assignment at this location. Only an account owner can remove the assignment of a person who is an owner at this location, and you cannot remove an assignment that carries a permission you do not hold here. An API key is never an owner. Refuses the request if it would leave the workspace without any account owner.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Location (org node) id.", "example": "on_4d5e6f7a8b9c0d1e" }, { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Membership id (from the member list).", "example": "memb_6f7a8b9c0d1e2f3a" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "removed": { "type": "boolean", "const": true } }, "required": [ "id", "removed" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold `user.edit` here, or the person outranks you (`owner_required`, `outranked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such location or membership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`last_owner`: this is the last owner of the workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/org-nodes/bulk": { "post": { "operationId": "createOrgNodeBulk", "tags": [ "org-nodes" ], "summary": "Bulk-create locations", "description": "Creates up to 200 locations in a single call, for example to paste in a full location list at fleet setup. Send `parentId` and either a list of `names` or a list of `units`, each with a name and an optional time zone, town, Location ID and parent Location ID, so one list can hold regions and the stores under them. Empty or repeated names, and Location IDs already in use, are skipped, so the same list can safely be submitted again. Requires the create-location permission at the parent location.\n\n**Notes.**\n- Idempotent: sending the same list again creates nothing new and lists every row in `skipped`.", "x-brix-permission": "org-unit.create", "x-brix-schema": "verified", "x-brix-notes": [ "Idempotent: sending the same list again creates nothing new and lists every row in `skipped`." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parentId": { "type": "string", "description": "The location the new ones go under (unless a row names its own parent)." }, "names": { "description": "Location names. Use this or `units`.", "type": "array", "items": { "type": "string" } }, "units": { "description": "One row per location (up to 200). Use this or `names`.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "timezone": { "description": "IANA zone.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "description": "A town or city (with coordinates, or looked up from `label`).", "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "label" ] }, { "type": "null" } ] }, "externalId": { "description": "Your own location code.", "type": "string" }, "parentExternalId": { "description": "The location code of this row's parent: an earlier row, or an existing location.", "type": "string" } }, "required": [ "name" ] } } }, "required": [ "parentId" ] }, "example": { "parentId": "on_0a1b2c3d4e5f6a7b", "units": [ { "name": "Chicago Loop", "timezone": "America/Chicago", "externalId": "STORE-0142" } ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "created": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "skipped": { "type": "array", "items": { "type": "string" }, "description": "Names skipped: empty, repeated, or already a location there (or a Location ID already in use)." }, "locationsSkipped": { "type": "array", "items": { "type": "string" }, "description": "Names created without a town or city, because the one given could not be found." } }, "required": [ "created", "skipped", "locationsSkipped" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold `org-unit.create` at the parent location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`parentId` missing or not found, no rows, more than 200 rows, an invalid Location ID or time zone, or a parent that is a separate workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "org-unit.create" ] } ] } }, "/v1/platform-banners": { "get": { "operationId": "listPlatformBanners", "tags": [ "platform-banners" ], "summary": "List platform banners", "description": "List notices shown at the top of every page in the content management system. Returns every active, non-deleted notice for this workspace; apply the display window and the audience yourself. Notices a signed-in person has already dismissed are left out for that person, so an API key gets every notice.\n\n**Notes.**\n- Every active notice is returned, whatever its display window; filter on `startsAt`, `endsAt` and `audience` yourself. Notices for another account are never returned.\n- Dismissing a notice needs a signed-in person, so an API key always gets the notices a person may have dismissed.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Every active notice is returned, whatever its display window; filter on `startsAt`, `endsAt` and `audience` yourself. Notices for another account are never returned.", "Dismissing a notice needs a signed-in person, so an API key always gets the notices a person may have dismissed." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tone": { "type": "string", "enum": [ "info", "success", "warning", "promo" ] }, "title": { "type": "string" }, "message": { "type": "string" }, "cta": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } }, "required": [ "label", "href" ] }, { "type": "null" } ], "description": "A call-to-action link, or null." }, "dismissible": { "type": "boolean" }, "audience": { "type": "object", "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "additionalProperties": {}, "description": "Who the notice is for: `everyone`, `role`, `tier`, `min-online-screens` or `account`. Apply the audience and the display window yourself." }, "startsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "tone", "title", "message", "cta", "dismissible", "audience", "startsAt", "endsAt", "active", "createdAt" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/playlists": { "get": { "operationId": "listPlaylists", "tags": [ "playlists" ], "summary": "List playlists", "description": "List every playlist in the workspace, including its items and a summary of its dayparting rules.\n\nEvery playlist you can see, each with its items. Not paginated.", "x-brix-permission": "playlist.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Playlist" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.view" ] } ] }, "post": { "operationId": "createPlaylist", "tags": [ "playlists" ], "summary": "Create a playlist", "description": "Create a playlist with a `name` and an optional `nodeId` and other fields. Safe to retry with an idempotency key, to protect against duplicate creation from a double-click.\n\nCreates an empty playlist. Add items with POST /v1/playlists/{id}/items. Send an `Idempotency-Key` header to make a retry safe.\n\n**Notes.**\n- The create response is the new row plus empty `items` and `allocations`; it omits `fit`, `usedByScreenCount`, `usedByScreens` and the other columns that GET returns.", "x-brix-permission": "playlist.create", "x-brix-schema": "verified", "x-brix-notes": [ "The create response is the new row plus empty `items` and `allocations`; it omits `fit`, `usedByScreenCount`, `usedByScreens` and the other columns that GET returns." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "shuffle": { "type": "boolean" }, "fullscreen": { "type": "boolean" }, "startsAt": { "description": "YYYY-MM-DD or ISO-8601.", "type": "string" }, "expiresAt": { "description": "YYYY-MM-DD or ISO-8601.", "type": "string" }, "nodeId": { "description": "Home location; defaults to your own.", "type": "string" } }, "required": [ "name" ] }, "example": { "name": "Lunch menu", "description": "Weekday 11:00-14:00", "shuffle": false } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlaylistCreated" } }, "required": [ "data" ] }, "example": { "data": { "id": "pl_4d5e6f7a8b9c0d1e", "spaceId": "space_1a2b3c4d5e6f7a8b", "name": "Lunch menu", "description": "Weekday 11:00-14:00", "shuffle": false, "fullscreen": false, "startsAt": null, "expiresAt": null, "approvalState": "approved", "nodeId": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null, "items": [], "allocations": [] } } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing name, an unparsable date, or an unknown location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.create" ] } ] } }, "/v1/playlists/{id}": { "delete": { "operationId": "deletePlaylist", "tags": [ "playlists" ], "summary": "Delete a playlist", "description": "Delete a playlist to the recycle bin. Screens assigned to it fall back to their default content. Fails with 409 if the playlist is shared into other spaces, unless the deletion is forced.\n\nMoves the playlist to the recycle bin (restorable for 30 days).", "x-brix-permission": "playlist.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Delete even when it is shared into other places." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "sharesRemoved": { "type": "integer" } }, "required": [ "id", "deleted", "sharesRemoved" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`content_shared`: the item is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.delete" ] } ] }, "get": { "operationId": "getPlaylist", "tags": [ "playlists" ], "summary": "Get a playlist", "description": "Retrieve one playlist with its ordered items, including each item's reference kind and id, duration, and rules.", "x-brix-permission": "playlist.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlaylistDetail" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.view" ] } ] }, "patch": { "operationId": "updatePlaylist", "tags": [ "playlists" ], "summary": "Update a playlist", "description": "Edit a playlist's own fields, such as name, node, shuffle, and transition settings. Items are managed through the separate /items routes.\n\nSend only the fields to change. A playback change to an approved playlist returns it to `draft` where approval is required.\n\n**Notes.**\n- Fields of the wrong type are ignored rather than refused (for example `name: 5`).", "x-brix-permission": "playlist.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Fields of the wrong type are ignored rather than refused (for example `name: 5`)." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "shuffle": { "type": "boolean" }, "fullscreen": { "type": "boolean" }, "fit": { "anyOf": [ { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ] }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "description": "Move to another location (needs playlist.edit there).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseUpdatedAt": { "description": "The `updatedAt` your edit is based on; a stale value answers 409 with `current`.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playlist" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Moving it to a location where you lack playlist.edit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: `baseUpdatedAt` is stale; the body carries `current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An unparsable date or an unknown location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.edit" ] } ] } }, "/v1/playlists/{id}/allocations": { "put": { "operationId": "replacePlaylistAllocation", "tags": [ "playlists" ], "summary": "Set playlist allocations", "description": "Set a playlist's allocations: shares of its airtime given to a person, a group or a location (a percent, every nth play, or a time of day). This replaces the whole set; allocations you leave out are removed.\n\n**Notes.**\n- An out-of-range `value` is 400 `validation_error`; every other validation failure is 422.\n- Rows with an unknown `ownerKind` or `kind` are dropped without an error.\n- A missing or malformed body is treated as an empty list, which removes every allocation.\n- The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it.", "x-brix-permission": "playlist.edit", "x-brix-schema": "verified", "x-brix-notes": [ "An out-of-range `value` is 400 `validation_error`; every other validation failure is 422.", "Rows with an unknown `ownerKind` or `kind` are dropped without an error.", "A missing or malformed body is treated as an empty list, which removes every allocation.", "The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allocations": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Keep this id: one of the playlist's current allocations, or a new id of 6-64 URL-safe characters. Otherwise a new id is made.", "type": "string" }, "label": { "type": "string" }, "ownerKind": { "type": "string", "enum": [ "user", "group", "org-unit" ], "description": "Who gets the share. `org-unit` = a location (`ownerId` is its node id)." }, "ownerId": { "type": "string" }, "ownerName": { "type": "string" }, "kind": { "type": "string", "enum": [ "percent", "every-nth", "daypart" ] }, "value": { "type": "integer", "description": "`percent` 0-100, `every-nth` 1-100, `daypart` 0-1439 (the minute of the day it opens)." }, "endValue": { "description": "`daypart`: the minute of the day it closes.", "type": "number" }, "colorClass": { "type": "string" }, "fillSpaceId": { "description": "A child workspace that fills the share; null = this workspace.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "unfilledBehavior": { "description": "What plays while the share is not filled. Default `collapse`.", "type": "string", "enum": [ "collapse", "filler", "holding" ] }, "fillerRefKind": { "description": "With `filler`: the kind of the filler content.", "type": "string", "enum": [ "media", "playlist", "app", "layout" ] }, "fillerRefId": { "type": "string" }, "requiresApproval": { "description": "What the recipient puts in the share must be approved first.", "type": "boolean" } }, "required": [ "ownerKind", "ownerId", "kind", "value" ] }, "description": "The whole set, at most 200. Allocations left out are removed." } }, "required": [ "allocations" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playlist" } }, "required": [ "data" ] } } } }, "400": { "description": "`validation_error`: a `value` outside its kind's range or not a whole number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "More than 200 allocations, a location that is not in this workspace (`invalid_node`), or percent shares that would give away more than 99% on some screen.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.edit" ] } ] } }, "/v1/playlists/{id}/duplicate": { "post": { "operationId": "duplicatePlaylist", "tags": [ "playlists" ], "summary": "Duplicate a playlist", "description": "Create a deep copy of a playlist, including its settings, share-of-voice allocations (fill assignments reset), and ordered items, named \"<name> copy\" and unique within the space. The copy starts as a draft with no assignment. Requires permission to create playlists at the source playlist's home node.", "x-brix-permission": "playlist.create", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playlist" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.create" ] } ] } }, "/v1/playlists/{id}/items": { "post": { "operationId": "addPlaylistItem", "tags": [ "playlists" ], "summary": "Add an item to a playlist", "description": "Append one item to a playlist with `refKind`, `refId`, and an optional `durationSec` and other fields. Rejects references from another space, and rejects any nesting that would create a loop, such as a playlist referencing a layout zone that contains the same playlist, with a clear error rather than failing silently.\n\nAppends one item. A video or audio file defaults to playing its full length, an animated image to one loop, anything else to 10 seconds. Returns the whole playlist.\n\n**Notes.**\n- `position` is accepted and ignored.\n- The returned `approvalState` is the value from before the edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it.", "x-brix-permission": "playlist.edit", "x-brix-schema": "verified", "x-brix-notes": [ "`position` is accepted and ignored.", "The returned `approvalState` is the value from before the edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refKind": { "type": "string", "enum": [ "media", "app", "layout", "playlist" ] }, "refId": { "type": "string", "minLength": 1 }, "durationMode": { "type": "string", "enum": [ "fixed", "full", "live", "loop", "manual" ] }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "loopCount": { "type": "number" }, "fit": { "description": "contain, cover, fill or blur-fill; anything else means inherit.", "type": "string" }, "fullscreen": { "type": "boolean" }, "position": { "description": "Accepted but ignored: the item is always appended. Reorder with PUT /v1/playlists/{id}/items.", "type": "number" }, "allocationId": { "type": "string" } }, "required": [ "refKind", "refId" ], "description": "Unknown fields are refused." } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playlist" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not available at the playlist's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist, or the referenced content is not in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid body, a playlist loop, a layout with unbound zones, or an unknown allocation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.edit" ] } ] }, "put": { "operationId": "reorderPlaylistItems", "tags": [ "playlists" ], "summary": "Reorder a playlist's items", "description": "Replace a playlist's entire item list in one call. Send the full array of items in the order you want; the same reference and loop validation applies as when adding a single item.\n\nSets the order of the items: `itemIds[0]` plays first. Unknown ids are skipped. It does not add or remove items. Returns the whole playlist.\n\n**Notes.**\n- Items left out of `itemIds` keep their old position number, so two items can share a position. Send every item id.\n- A missing or malformed body is treated as an empty list, not refused.", "x-brix-permission": "playlist.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Items left out of `itemIds` keep their old position number, so two items can share a position. Send every item id.", "A missing or malformed body is treated as an empty list, not refused." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "type": "array", "items": { "type": "string" }, "description": "Item ids in the new order." } }, "required": [ "itemIds" ] }, "example": { "itemIds": [ "pli_7a8b9c0d1e2f3a4b", "pli_1e2f3a4b5c6d7e8f" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playlist" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.edit" ] } ] } }, "/v1/playlists/{id}/items/{itemId}": { "delete": { "operationId": "deletePlaylistItem", "tags": [ "playlists" ], "summary": "Remove a playlist item", "description": "Remove one item from a playlist. The remaining items keep their existing order.\n\nRemoves the item and closes the gap in the positions. Returns the whole playlist.\n\n**Notes.**\n- An unknown `itemId` is not refused: nothing is removed and the answer is 200 with the playlist.\n- The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it.", "x-brix-permission": "playlist.edit", "x-brix-schema": "verified", "x-brix-notes": [ "An unknown `itemId` is not refused: nothing is removed and the answer is 200 with the playlist.", "The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist item id.", "example": "pli_7a8b9c0d1e2f3a4b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playlist" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.edit" ] } ] }, "patch": { "operationId": "updatePlaylistItem", "tags": [ "playlists" ], "summary": "Update a playlist item", "description": "Edit one playlist item's duration, loop count, fit, full-screen setting, screen tag rules or allocation. `refKind` and `refId` cannot be changed on an existing item; delete it and add a new item to point at different content.\n\n**Notes.**\n- An unknown `itemId` is not refused: nothing changes and the answer is 200 with the playlist.\n- `targetTags` and `excludeTags` are stored but not returned on the items.\n- Fields of the wrong type are ignored rather than refused.\n- The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it.", "x-brix-permission": "playlist.edit", "x-brix-schema": "verified", "x-brix-notes": [ "An unknown `itemId` is not refused: nothing changes and the answer is 200 with the playlist.", "`targetTags` and `excludeTags` are stored but not returned on the items.", "Fields of the wrong type are ignored rather than refused.", "The returned playlist row (`updatedAt`, `approvalState`) is the one read before this edit; an approved playlist is returned to `draft` in storage by this call. Re-read with GET to see it." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist item id.", "example": "pli_7a8b9c0d1e2f3a4b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "durationMode": { "type": "string", "enum": [ "fixed", "full", "live", "loop", "manual" ] }, "durationSeconds": { "description": "Dwell for `fixed`, rounded and clamped to 1 second through 24 hours.", "type": "number" }, "loopCount": { "description": "Plays per turn for `loop`; rounded.", "type": "number", "minimum": 1 }, "fit": { "description": "The item's own fit; `null` = follow the file's fit.", "anyOf": [ { "type": "string", "enum": [ "contain", "cover", "fill", "blur-fill" ] }, { "type": "null" } ] }, "fullscreen": { "description": "Take over the whole screen, over any layout.", "type": "boolean" }, "targetTags": { "description": "Play only on screens with one of these tags. `null` or `[]` clears the rule.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "excludeTags": { "description": "Never play on screens with one of these tags. `null` or `[]` clears the rule.", "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "allocationId": { "description": "Put the item in one of this playlist's allocations; `null` = the base rotation.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Playlist" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`allocationId` is not one of this playlist's allocations, or nothing to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.edit" ] } ] } }, "/v1/playlists/{id}/restore": { "post": { "operationId": "restorePlaylist", "tags": [ "playlists" ], "summary": "Restore a deleted playlist", "description": "Restore a deleted playlist so its items and ordering return to the playlist library.", "x-brix-permission": "playlist.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace, or it was purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: the playlist is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.delete" ] } ] } }, "/v1/playlists/{id}/share-readiness": { "get": { "operationId": "getPlaylistShareReadiness", "tags": [ "playlists" ], "summary": "Get playlist share readiness", "description": "For a playlist's airtime reserved for other teams, list who at each location can fill their share, and the narrowest role that would let them do so.\n\n**Notes.**\n- `requiredPermissions` is absent when `locations` is empty.", "x-brix-permission": "playlist.view", "x-brix-schema": "verified", "x-brix-notes": [ "`requiredPermissions` is absent when `locations` is empty." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Playlist id.", "example": "pl_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string" }, "nodeName": { "type": "string" }, "canFill": { "type": "boolean", "description": "Somebody at the location can fill the share now." }, "fillerCount": { "type": "integer" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "userId", "name", "email" ] }, "description": "People at the location who cannot fill it yet." }, "roleId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The narrowest existing role that would let them fill it." }, "roleName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mayGrant": { "type": "boolean", "description": "The caller may give that role at that location." } }, "required": [ "nodeId", "nodeName", "canFill", "fillerCount", "candidates", "roleId", "roleName", "mayGrant" ] }, "description": "One per location that holds a percent share of this playlist." }, "requiredPermissions": { "description": "The permissions filling a share needs. Absent when no location holds a share.", "type": "array", "items": { "type": "string" } } }, "required": [ "locations" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such playlist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.view" ] } ] } }, "/v1/power-policies": { "get": { "operationId": "listPowerPolicies", "tags": [ "power-policies" ], "summary": "List power policies", "description": "List the power policies configured for your workspace. Each policy defines an open and close window for the screens using it.\n\n**Notes.**\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Needs the permission at the workspace root: a location-scoped key is refused." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PowerPolicy" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "ppol_1a2b3c4d5e6f7a8b", "spaceId": "space_1a2b3c4d5e6f7a8b", "name": "Store hours", "description": "Open 8 to 22", "windows": { "mon": { "start": "08:00", "end": "22:00" }, "tue": { "start": "08:00", "end": "22:00", "volume": 40 } }, "rebootHourLocal": 4, "timezone": "Europe/London", "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null, "screenCount": 12 } ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "post": { "operationId": "createPowerPolicy", "tags": [ "power-policies" ], "summary": "Create a power policy", "description": "Create a named power policy that defines when screens using it should power on and off.\n\n**Notes.**\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Needs the permission at the workspace root: a location-scoped key is refused." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Default on create: `Untitled policy`.", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windows": { "type": "object", "properties": { "mon": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "tue": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "wed": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "thu": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "fri": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "sat": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "sun": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] } }, "description": "Open window per weekday. `null` or an absent day is closed. A malformed day is dropped (closed), not refused." }, "rebootHourLocal": { "description": "0–23; rounded and clamped. Null (or a value that is not a number) turns the restart off.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "timezone": { "description": "IANA time zone (`Europe/London`). An unknown zone is refused with 422.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PowerPolicy" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unknown `timezone`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/power-policies/{id}": { "get": { "operationId": "getPowerPolicy", "tags": [ "power-policies" ], "summary": "Get a power policy", "description": "Get one power policy by its ID.\n\n**Notes.**\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Needs the permission at the workspace root: a location-scoped key is refused." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Power policy id.", "example": "ppol_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PowerPolicy" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such power policy in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "patch": { "operationId": "updatePowerPolicy", "tags": [ "power-policies" ], "summary": "Update a power policy", "description": "Update a power policy's open and close windows, reboot hour, time zone, or name.\n\n**Notes.**\n- `screenCount` in this response is always 0; read the policy to get the real count.\n- An empty `name` keeps the current name.\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "`screenCount` in this response is always 0; read the policy to get the real count.", "An empty `name` keeps the current name.", "Needs the permission at the workspace root: a location-scoped key is refused." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Power policy id.", "example": "ppol_1a2b3c4d5e6f7a8b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Default on create: `Untitled policy`.", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windows": { "type": "object", "properties": { "mon": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "tue": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "wed": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "thu": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "fri": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "sat": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] }, "sun": { "anyOf": [ { "$ref": "#/components/schemas/OpenWindow" }, { "type": "null" } ] } }, "description": "Open window per weekday. `null` or an absent day is closed. A malformed day is dropped (closed), not refused." }, "rebootHourLocal": { "description": "0–23; rounded and clamped. Null (or a value that is not a number) turns the restart off.", "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "timezone": { "description": "IANA time zone (`Europe/London`). An unknown zone is refused with 422.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PowerPolicy" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such power policy in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unknown `timezone`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/power-policies/{id}/delete": { "post": { "operationId": "createPowerPolicyDelete", "tags": [ "power-policies" ], "summary": "Delete a power policy", "description": "Delete a power policy. Screens that use it go back to their own operating hours. A deleted policy cannot be restored.\n\n**Notes.**\n- A POST to `/delete`, not `DELETE`. Screens that use the policy keep the link and use their own operating hours until they get another policy. There is no restore route.\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "A POST to `/delete`, not `DELETE`. Screens that use the policy keep the link and use their own operating hours until they get another policy. There is no restore route.", "Needs the permission at the workspace root: a location-scoped key is refused." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Power policy id.", "example": "ppol_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such power policy in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/proof": { "get": { "operationId": "getProofOfPlay", "tags": [ "proof" ], "summary": "Get a proof-of-play report", "description": "Get proof-of-play totals for a date range, broken down by content item and by screen, including digital-out-of-home verification fields. Use the `from` and `to` query parameters to set the date range.\n\nCounts what played, where and for how long, over a time window. Only screens the caller can see are counted.", "x-brix-permission": "playback-log.view", "x-brix-schema": "verified", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window start (ISO-8601). Default: the start of the retention window." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window end (ISO-8601). Default: now." }, { "name": "screenId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this screen." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProofOfPlayReport" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playback-log.view" ] } ] } }, "/v1/proof/events": { "get": { "operationId": "listProofEvents", "tags": [ "proof" ], "summary": "List proof-of-play events", "description": "List individual playback events, one per play, for a date range. The number of events returned is capped. For totals rolled up by content item and screen, use GET /v1/proof instead.", "x-brix-permission": "playback-log.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playback-log.view" ] } ] } }, "/v1/recall": { "get": { "operationId": "getRecall", "tags": [ "recall" ], "summary": "List recalled content", "description": "Return everything currently held off screens, including its kind, name, when it was recalled, and who recalled it. Since a recall is reversible, this list is the record of what is being withheld and why, so nothing stays off screens indefinitely without anyone knowing. An item is listed only where the caller can view that kind of content at its location. Who recalled it is returned in full only where the caller also holds the user view permission; otherwise only its kind, for example user or staff.", "x-brix-permission": "screen.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/recall/creative/{id}": { "post": { "operationId": "postRecallCreative", "tags": [ "recall" ], "summary": "Recall a creative from all screens", "description": "Immediately remove a creative from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.", "x-brix-permission": "creative.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.edit" ] } ] } }, "/v1/recall/creative/{id}/restore": { "post": { "operationId": "restoreRecallCreative", "tags": [ "recall" ], "summary": "Restore a recalled creative", "description": "Put a recalled creative back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.", "x-brix-permission": "creative.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.edit" ] } ] } }, "/v1/recall/media/{id}": { "post": { "operationId": "postRecallMedia", "tags": [ "recall" ], "summary": "Recall a media file from all screens", "description": "Immediately remove a media file from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.", "x-brix-permission": "media.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/recall/media/{id}/restore": { "post": { "operationId": "restoreRecallMedia", "tags": [ "recall" ], "summary": "Restore a recalled media file", "description": "Put a recalled media file back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.", "x-brix-permission": "media.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/recall/playlist/{id}": { "post": { "operationId": "postRecallPlaylist", "tags": [ "recall" ], "summary": "Recall a playlist from all screens", "description": "Immediately remove a playlist from every screen it appears on, without deleting it or changing any other playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.", "x-brix-permission": "playlist.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.edit" ] } ] } }, "/v1/recall/playlist/{id}/restore": { "post": { "operationId": "restoreRecallPlaylist", "tags": [ "recall" ], "summary": "Restore a recalled playlist", "description": "Put a recalled playlist back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.", "x-brix-permission": "playlist.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "playlist.edit" ] } ] } }, "/v1/recall/schedule/{id}": { "post": { "operationId": "postRecallSchedule", "tags": [ "recall" ], "summary": "Recall a schedule from all screens", "description": "Immediately remove a schedule from every screen it appears on, without deleting it or changing any playlist. This applies regardless of any approval settings at the affected locations. The action is reversible, and the underlying rotation is left untouched.", "x-brix-permission": "schedule.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.edit" ] } ] } }, "/v1/recall/schedule/{id}/restore": { "post": { "operationId": "restoreRecallSchedule", "tags": [ "recall" ], "summary": "Restore a recalled schedule", "description": "Put a recalled schedule back on the screens it was removed from. Nothing was changed by the recall, so playback resumes exactly as it was before.", "x-brix-permission": "schedule.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.edit" ] } ] } }, "/v1/recycle-bin": { "get": { "operationId": "getRecycleBin", "tags": [ "recycle-bin" ], "summary": "List deleted items", "description": "List every deleted item across your workspace, including media, playlists, schedules, layouts, creatives, apps, and data sources. Each entry includes the deletion time and size, so items can be restored or permanently erased within the 30-day recovery window. Deleted screens are not included; screens have their own recovery endpoints.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/recycle-bin/{kind}/{id}/purge": { "post": { "operationId": "createRecycleBinPurge", "tags": [ "recycle-bin" ], "summary": "Permanently delete an item", "description": "Permanently erase one deleted item before the 30-day recovery window would otherwise remove it. For media, this also deletes the stored file. This action cannot be undone.", "x-brix-schema": "none", "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for kind." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/roles": { "get": { "operationId": "listRoles", "tags": [ "roles" ], "summary": "List roles", "description": "Returns the workspace's roles, both built-in and custom, with the permissions each one carries.\n\n**Notes.**\n- Not paginated.", "x-brix-permission": "permission-group.view", "x-brix-schema": "verified", "x-brix-notes": [ "Not paginated." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Role" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "permission-group.view" ] } ] }, "post": { "operationId": "createRole", "tags": [ "roles" ], "summary": "Create role", "description": "Creates a custom role. Provide `name` and `permissions`, a list of `resource.action` strings or `\"all\"`. You cannot create a role that holds permissions you do not hold yourself.\n\n**Notes.**\n- `permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.\n- `builtIn` in the body is ignored.", "x-brix-permission": "permission-group.create", "x-brix-schema": "verified", "x-brix-notes": [ "`permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.", "`builtIn` in the body is ignored." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "color": { "type": "string" }, "description": { "type": "string" }, "permissions": { "description": "You must hold every permission you grant, workspace-wide. Default `[]`.", "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] }, "features": { "description": "Default `[]`.", "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] }, "scope": { "description": "Default `{ \"kind\": \"workspace\" }`.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "workspace" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "org-units" }, "orgUnitIds": { "type": "array", "items": { "type": "string" }, "description": "The locations (and their subtrees) where the role applies." } }, "required": [ "kind", "orgUnitIds" ] } ] }, "character": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ] }, "example": { "name": "Store manager", "permissions": [ "screen.view", "screen.cast", "media.view", "media.create" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Role" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`permissions` holds a permission you do not hold workspace-wide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "permission-group.create" ] } ] } }, "/v1/roles/{id}": { "delete": { "operationId": "deleteRole", "tags": [ "roles" ], "summary": "Delete role", "description": "Soft-deletes a custom role. The role can later be restored. Refuses the request while anyone is still assigned to the role.", "x-brix-permission": "permission-group.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Role id.", "example": "role_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such role in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`protected` (a built-in role), `last_owner_role`, or `in_use` (people still hold the role).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "permission-group.delete" ] } ] }, "get": { "operationId": "getRole", "tags": [ "roles" ], "summary": "Get role", "description": "Returns one role with its full list of permissions.", "x-brix-permission": "permission-group.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Role id.", "example": "role_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Role" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such role in this workspace (or it is deleted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "permission-group.view" ] } ] }, "patch": { "operationId": "updateRole", "tags": [ "roles" ], "summary": "Update role", "description": "Updates a role. The same rule as creating a role applies: you cannot add or remove a permission you do not hold yourself. Only a signed-in account owner can take full ownership away from a role that people hold; an API key cannot. On a built-in role, only the name, color and description change; its permissions, features and scope stay fixed.\n\n**Notes.**\n- `permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.\n- `builtIn` in the body is ignored.\n- On a built-in role, `permissions`, `features` and `scope` are ignored without an error; only `name`, `color`, `description` and `character` change.", "x-brix-permission": "permission-group.edit", "x-brix-schema": "verified", "x-brix-notes": [ "`permissions`, `features` and `scope` are stored as sent: the handler does not check their shape, so a malformed value is stored and read back as it was written.", "`builtIn` in the body is ignored.", "On a built-in role, `permissions`, `features` and `scope` are ignored without an error; only `name`, `color`, `description` and `character` change." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Role id.", "example": "role_5e6f7a8b9c0d1e2f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required on create." }, "color": { "type": "string" }, "description": { "type": "string" }, "permissions": { "description": "You must hold every permission you grant, workspace-wide. Default `[]`.", "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] }, "features": { "description": "Default `[]`.", "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] }, "scope": { "description": "Default `{ \"kind\": \"workspace\" }`.", "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "workspace" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "org-units" }, "orgUnitIds": { "type": "array", "items": { "type": "string" }, "description": "The locations (and their subtrees) where the role applies." } }, "required": [ "kind", "orgUnitIds" ] } ] }, "character": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Role" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You would add or remove a permission you do not hold workspace-wide, or change `scope` of a role whose permissions you do not hold workspace-wide; `owner_required`: the change takes full ownership away from a role people hold, and the caller is not a signed-in owner (an API key never is).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such role in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`last_owner_role`: this is the only role with full ownership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "permission-group.edit" ] } ] } }, "/v1/roles/{id}/restore": { "post": { "operationId": "restoreRole", "tags": [ "roles" ], "summary": "Restore deleted role", "description": "Restores a previously deleted custom role. Requires the same permission needed to delete a role.\n\n**Notes.**\n- Answers the whole restored role, not the `{ id, restored }` acknowledgement other restores use.", "x-brix-permission": "permission-group.delete", "x-brix-schema": "verified", "x-brix-notes": [ "Answers the whole restored role, not the `{ id, restored }` acknowledgement other restores use." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Role id.", "example": "role_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Role" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such role in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: the role is not deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "permission-group.delete" ] } ] } }, "/v1/schedules": { "get": { "operationId": "listSchedules", "tags": [ "schedules" ], "summary": "List schedules", "description": "List the workspace's schedules, including their dayparting blocks.", "x-brix-permission": "schedule.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.view" ] } ] }, "post": { "operationId": "createSchedule", "tags": [ "schedules" ], "summary": "Create a schedule", "description": "Create a schedule with a `name` and an optional `nodeId` and other fields. Safe to retry with an idempotency key.\n\nCreates an empty schedule. Add its dayparts with POST /v1/schedules/{id}/blocks, then assign it to screens.\n\n**Notes.**\n- Create returns the stored row plus `blocks: []`, not the composed schedule the other schedule routes return: no `usedByScreenCount`, `fallbackContentRef`, `fallbackThumbnailUrl`, `recalledAt`, `approvedSnapshot` or `importSourceId`.", "x-brix-permission": "schedule.create", "x-brix-schema": "verified", "x-brix-notes": [ "Create returns the stored row plus `blocks: []`, not the composed schedule the other schedule routes return: no `usedByScreenCount`, `fallbackContentRef`, `fallbackThumbnailUrl`, `recalledAt`, `approvedSnapshot` or `importSourceId`." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required." }, "nodeId": { "description": "Home location. Default: the caller's own location.", "type": "string" }, "fallbackName": { "type": "string" }, "fallbackContentKind": { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ] }, "fallbackContentId": { "type": "string" }, "fallbackMode": { "type": "string", "enum": [ "content", "off" ] }, "playsSolely": { "type": "boolean" }, "timeBasis": { "type": "string", "enum": [ "device", "cms" ] }, "startsAt": { "description": "`YYYY-MM-DD` or ISO-8601.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "description": "`YYYY-MM-DD` or ISO-8601.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ] }, "example": { "name": "Weekday dayparts", "fallbackContentKind": "playlist", "fallbackContentId": "pl_2a3b4c5d6e7f8a9b", "startsAt": "2026-10-01" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Schedule id.", "examples": [ "sch_6f7a8b9c0d1e2f3a" ] }, "spaceId": { "type": "string" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location (null = workspace root)." }, "name": { "type": "string" }, "fallbackName": { "type": "string", "description": "Label of the content played between blocks." }, "fallbackMode": { "type": "string", "enum": [ "content", "off" ], "description": "Between blocks: play the fallback content, or turn the screens off." }, "fallbackContentKind": { "anyOf": [ { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ] }, { "type": "null" } ] }, "fallbackContentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "playsSolely": { "type": "boolean" }, "timeBasis": { "type": "string", "enum": [ "device", "cms" ], "description": "Whose clock the block times use: each screen's local time, or the workspace's." }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`YYYY-MM-DD` or ISO-8601; null = no start bound." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleBlock" }, "description": "Always empty on create." } }, "required": [ "id", "spaceId", "nodeId", "name", "fallbackName", "fallbackMode", "fallbackContentKind", "fallbackContentId", "playsSolely", "timeBasis", "startsAt", "expiresAt", "approvalState", "createdAt", "updatedAt", "deletedAt", "blocks" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "sch_6f7a8b9c0d1e2f3a", "spaceId": "space_1a2b3c4d5e6f7a8b", "nodeId": null, "name": "Weekday dayparts", "fallbackName": "Default Loop", "fallbackContentKind": "playlist", "fallbackContentId": "pl_2a3b4c5d6e7f8a9b", "fallbackMode": "content", "playsSolely": false, "timeBasis": "device", "startsAt": "2026-10-01", "expiresAt": null, "approvalState": "draft", "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "deletedAt": null, "blocks": [] } } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the fallback content is not shared to the schedule's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The fallback content or location does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` missing, or an unparseable `startsAt` / `expiresAt`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.create" ] } ] } }, "/v1/schedules/{id}": { "delete": { "operationId": "deleteSchedule", "tags": [ "schedules" ], "summary": "Delete a schedule", "description": "Delete a schedule to the recycle bin. Screens using it fall back to their assigned content.\n\nSoft-deletes into the recycle bin. Screens on it fall back to their other content.", "x-brix-permission": "schedule.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id.", "example": "sch_6f7a8b9c0d1e2f3a" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Delete even when shared; the shares are removed too." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "sharesRemoved": { "type": "integer" } }, "required": [ "id", "deleted", "sharesRemoved" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`content_shared`: the schedule is shared; the body carries `shareCount`. Retry with `?force=true`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.delete" ] } ] }, "get": { "operationId": "getSchedule", "tags": [ "schedules" ], "summary": "Get a schedule", "description": "Retrieve one schedule, including its ordered blocks, with each block's time window, recurrence, content reference, and priority.", "x-brix-permission": "schedule.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id.", "example": "sch_6f7a8b9c0d1e2f3a" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Schedule id.", "examples": [ "sch_6f7a8b9c0d1e2f3a" ] }, "spaceId": { "type": "string" }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Home location (null = workspace root)." }, "name": { "type": "string" }, "fallbackName": { "type": "string", "description": "Label of the content played between blocks." }, "fallbackMode": { "type": "string", "enum": [ "content", "off" ], "description": "Between blocks: play the fallback content, or turn the screens off." }, "fallbackContentKind": { "anyOf": [ { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ] }, { "type": "null" } ] }, "fallbackContentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "playsSolely": { "type": "boolean" }, "timeBasis": { "type": "string", "enum": [ "device", "cms" ], "description": "Whose clock the block times use: each screen's local time, or the workspace's." }, "startsAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`YYYY-MM-DD` or ISO-8601; null = no start bound." }, "expiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvalState": { "type": "string", "enum": [ "draft", "pending", "approved", "rejected" ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "recalledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set while the schedule is recalled (withheld from every screen)." }, "recalledBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedSnapshot": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "JSON of the blocks as last approved (approval workflow)." }, "importSourceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usedByScreenCount": { "type": "integer", "description": "Screens assigned this schedule." }, "fallbackContentRef": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, { "type": "null" } ] }, "fallbackThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleBlock" } }, "requiresApproval": { "type": "boolean", "description": "The schedule's location requires approval before edits air." } }, "required": [ "id", "spaceId", "nodeId", "name", "fallbackName", "fallbackMode", "fallbackContentKind", "fallbackContentId", "playsSolely", "timeBasis", "startsAt", "expiresAt", "approvalState", "createdAt", "updatedAt", "deletedAt", "recalledAt", "recalledBy", "approvedSnapshot", "importSourceId", "usedByScreenCount", "fallbackContentRef", "fallbackThumbnailUrl", "blocks", "requiresApproval" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such schedule in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.view" ] } ] }, "patch": { "operationId": "updateSchedule", "tags": [ "schedules" ], "summary": "Update a schedule", "description": "Edit a schedule's own fields, such as name, node, timezone, and default behaviour. Blocks are managed through the separate /blocks routes.\n\nPartial update of schedule-level fields. A playback change to an approved schedule returns it to `draft`.", "x-brix-permission": "schedule.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id.", "example": "sch_6f7a8b9c0d1e2f3a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Required." }, "nodeId": { "description": "Move to another location (needs schedule.edit there too).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fallbackName": { "type": "string" }, "fallbackContentKind": { "anyOf": [ { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ] }, { "type": "null" } ] }, "fallbackContentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fallbackMode": { "type": "string", "enum": [ "content", "off" ] }, "playsSolely": { "type": "boolean" }, "timeBasis": { "type": "string", "enum": [ "device", "cms" ] }, "startsAt": { "description": "`YYYY-MM-DD` or ISO-8601.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "description": "`YYYY-MM-DD` or ISO-8601.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Schedule" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Moving to a location you cannot edit, or fallback content not shared there.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such schedule, fallback content or location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unparseable `startsAt` / `expiresAt`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.edit" ] } ] } }, "/v1/schedules/{id}/blocks": { "post": { "operationId": "addScheduleBlock", "tags": [ "schedules" ], "summary": "Add a block to a schedule", "description": "Add one dayparting block to a schedule with `refKind`, `refId`, `days`, `startTime`, `endTime`, and an optional `priority` and other fields.\n\n**Notes.**\n- The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current).", "x-brix-permission": "schedule.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current)." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id.", "example": "sch_6f7a8b9c0d1e2f3a" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refKind": { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ], "description": "Required on create." }, "refId": { "type": "string", "description": "Required on create." }, "label": { "description": "Default \"Block\".", "type": "string" }, "daysOfWeek": { "description": "0 = Sunday. Default: every day.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "startTime": { "description": "24-hour `HH:MM`. Default `09:00`.", "type": "string" }, "endTime": { "description": "24-hour `HH:MM`; `24:00` is accepted as midnight. Default `17:00`.", "type": "string" }, "priority": { "description": "Clamped to 0–1000.", "type": "integer" }, "startDate": { "description": "`YYYY-MM-DD`. Any other value is stored as null.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "repeatEveryWeeks": { "description": "Clamped to 1–52.", "type": "integer" }, "screensOff": { "type": "boolean" } }, "required": [ "refKind", "refId" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Schedule" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not shared to the schedule's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such schedule, or the content does not exist in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing `refKind`/`refId`, or a malformed time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.edit" ] } ] } }, "/v1/schedules/{id}/blocks/{blockId}": { "delete": { "operationId": "deleteScheduleBlock", "tags": [ "schedules" ], "summary": "Remove a schedule block", "description": "Remove one dayparting block from a schedule.\n\nRemoves the block (a hard delete of the child row) and re-packs positions.\n\n**Notes.**\n- The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current).\n- An unknown `blockId` is not an error: the route answers 200 with the unchanged schedule.", "x-brix-permission": "schedule.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current).", "An unknown `blockId` is not an error: the route answers 200 with the unchanged schedule." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id.", "example": "sch_6f7a8b9c0d1e2f3a" }, { "name": "blockId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Block id.", "example": "sb_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Schedule" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.edit" ] } ] }, "patch": { "operationId": "updateScheduleBlock", "tags": [ "schedules" ], "summary": "Update a schedule block", "description": "Edit one dayparting block's time window, days, priority, or content reference.\n\nPartial: omitted fields keep their stored value.\n\n**Notes.**\n- The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current).", "x-brix-permission": "schedule.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The returned schedule is composed from the row read BEFORE the edit, so `approvalState` / `updatedAt` can lag the edit by one read (the blocks are current)." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id.", "example": "sch_6f7a8b9c0d1e2f3a" }, { "name": "blockId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Block id.", "example": "sb_3c4d5e6f7a8b9c0d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refKind": { "type": "string", "enum": [ "media", "playlist", "app", "layout", "creative", "signage" ], "description": "Required on create." }, "refId": { "type": "string", "description": "Required on create." }, "label": { "description": "Default \"Block\".", "type": "string" }, "daysOfWeek": { "description": "0 = Sunday. Default: every day.", "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "startTime": { "description": "24-hour `HH:MM`. Default `09:00`.", "type": "string" }, "endTime": { "description": "24-hour `HH:MM`; `24:00` is accepted as midnight. Default `17:00`.", "type": "string" }, "priority": { "description": "Clamped to 0–1000.", "type": "integer" }, "startDate": { "description": "`YYYY-MM-DD`. Any other value is stored as null.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "repeatEveryWeeks": { "description": "Clamped to 1–52.", "type": "integer" }, "screensOff": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Schedule" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not shared to the schedule's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such schedule or block.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A malformed time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.edit" ] } ] } }, "/v1/schedules/{id}/restore": { "post": { "operationId": "restoreSchedule", "tags": [ "schedules" ], "summary": "Restore a deleted schedule", "description": "Restore a deleted schedule so its block layout returns to the schedule library.\n\n**Notes.**\n- Also restores the cross-workspace shares that were removed when the schedule was deleted.", "x-brix-permission": "schedule.delete", "x-brix-schema": "verified", "x-brix-notes": [ "Also restores the cross-workspace shares that were removed when the schedule was deleted." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Schedule id.", "example": "sch_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such schedule in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: the schedule is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "schedule.delete" ] } ] } }, "/v1/screen-groups": { "get": { "operationId": "listScreenGroups", "tags": [ "screen-groups" ], "summary": "List screen groups", "description": "List the screen groups in your workspace. Each group includes the number of screens in it and the IDs of the screens you have access to see.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScreenGroup" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "post": { "operationId": "createScreenGroup", "tags": [ "screen-groups" ], "summary": "Create a screen group", "description": "Create a named group of screens. Optionally pass `screenIds` to add screens to the group at creation time.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "description": "Unique in the workspace (case-insensitive). Trimmed; longer names are cut at 120." }, "description": { "description": "Trimmed; cut at 500 characters.", "type": "string" }, "screenIds": { "description": "Seed members. Ids you cannot edit are skipped.", "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenGroup" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`name_taken`: a group with this name exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` missing, or `screenIds` empty / over 5000.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screen-groups/{id}": { "delete": { "operationId": "deleteScreenGroup", "tags": [ "screen-groups" ], "summary": "Delete a screen group", "description": "Delete a screen group. The screens in the group are not affected, and the group's membership is kept so it can be fully restored with POST /v1/screen-groups/:id/restore.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen group id.", "example": "sgrp_7a8b9c0d1e2f3a4b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] }, "get": { "operationId": "getScreenGroup", "tags": [ "screen-groups" ], "summary": "Get a screen group", "description": "Get one screen group and the screens in it. Requesting a group that belongs to a different workspace returns a not-found error.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen group id.", "example": "sgrp_7a8b9c0d1e2f3a4b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenGroup" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such group in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "patch": { "operationId": "updateScreenGroup", "tags": [ "screen-groups" ], "summary": "Rename a screen group", "description": "Update a screen group's name or description. A name already used by another group in your workspace is refused with a `name_taken` conflict error.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen group id.", "example": "sgrp_7a8b9c0d1e2f3a4b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenGroup" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No screen group with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`name_taken`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screen-groups/{id}/restore": { "post": { "operationId": "restoreScreenGroup", "tags": [ "screen-groups" ], "summary": "Restore a deleted screen group", "description": "Restore a deleted screen group along with its original screen membership. A group that is not currently deleted is refused with a conflict error.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen group id.", "example": "sgrp_7a8b9c0d1e2f3a4b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenGroup" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No screen group with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`, or a live group has the same name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screen-groups/{id}/screens": { "post": { "operationId": "addScreensToGroup", "tags": [ "screen-groups" ], "summary": "Add screens to a group", "description": "Add screens to a group. Adding a screen already in the group has no additional effect. A screen from another workspace, a deleted screen, or a screen outside your organization scope is skipped and counted in the response, but not identified individually.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen group id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "screenIds": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" }, "description": "Screen ids (1–5000). Ids you cannot edit, or that do not exist, are skipped." } }, "required": [ "screenIds" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "added": { "type": "integer", "description": "Screens newly added (existing members are not counted)." }, "skipped": { "type": "integer", "description": "Requested ids that do not exist or that the caller cannot edit." }, "screenIds": { "type": "array", "items": { "type": "string" }, "description": "The screens newly added." } }, "required": [ "id", "added", "skipped", "screenIds" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`screenIds` empty or over 5000.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screen-groups/{id}/screens/{screenId}": { "delete": { "operationId": "deleteScreenGroupScreen", "tags": [ "screen-groups" ], "summary": "Remove a screen from a group", "description": "Remove one screen from a group. Returns a not-found error if the screen is not currently in the group.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen group id.", "example": "sgrp_7a8b9c0d1e2f3a4b" }, { "name": "screenId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "removed": { "type": "integer", "description": "1 when the screen was a member, else 0." }, "screenIds": { "type": "array", "items": { "type": "string" }, "description": "The remaining members the caller can see." } }, "required": [ "id", "removed", "screenIds" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screen-groups/{id}/screens/remove": { "post": { "operationId": "removeScreensFromGroup", "tags": [ "screen-groups" ], "summary": "Remove screens from a group", "description": "Remove one or more screens from a group. This only removes the screens from the group; the screens themselves are not affected. Removing a screen that is not in the group has no effect.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen group id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "screenIds": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" }, "description": "Screen ids (1–5000). Ids you cannot edit, or that do not exist, are skipped." } }, "required": [ "screenIds" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "removed": { "type": "integer" }, "skipped": { "type": "integer", "description": "Requested ids that do not exist or that the caller cannot edit." }, "screenIds": { "type": "array", "items": { "type": "string" }, "description": "The screens removed." } }, "required": [ "id", "removed", "skipped", "screenIds" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`screenIds` empty or over 5000.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens": { "get": { "operationId": "listScreens", "tags": [ "screens" ], "summary": "List screens", "description": "List the screens in your workspace, including each screen's organization node, assigned content, online status, and player settings. Pass `limit` (and optionally `cursor`) to page through results; without `limit`, the full list is returned. Results are limited to the organization nodes you can see.\n\n**Notes.**\n- The `state` object is a lean subset here (connection, currentContent, cache, proof, sync, telemetry.identity/display); GET /v1/screens/{id} returns the full snapshot.\n- `nextCursor` is a screen id (keyset by id), not the base64 cursor the shared resource routes use.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The `state` object is a lean subset here (connection, currentContent, cache, proof, sync, telemetry.identity/display); GET /v1/screens/{id} returns the full snapshot.", "`nextCursor` is a screen id (keyset by id), not the base64 cursor the shared resource routes use." ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Page size (max 500). Omit to get every screen." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page (a screen id)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Screen" } }, "nextCursor": { "description": "Present only when `limit` was passed; null on the last page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data" ] }, "example": { "data": [ { "id": "scr_1a2b3c4d5e6f7a8b", "spaceId": "space_1a2b3c4d5e6f7a8b", "nodeId": "node_4c5d6e7f8a9b0c1d", "name": "Lobby", "status": "online", "lastSeenAt": "2026-09-28T11:58:00.000Z", "coreUpdateOfferedAt": null, "contentKind": "playlist", "contentId": "pl_9a8b7c6d5e4f3a2b", "contentFit": null, "deactivatedAt": null, "tags": [ "lobby" ], "rotation": 0, "rotationCommandedAt": null, "timezone": "Europe/London", "timezoneSource": "operator", "operatingHours": "default", "lastPanelCommand": null, "scheduleScreensOff": false, "displayPowerMode": "always-on", "playbackMode": "unsync", "locationLabel": null, "locationLat": null, "locationLng": null, "ipCity": "London", "ipRegion": "England", "ipCountry": "GB", "ipLat": 51.5, "ipLng": -0.12, "ipTimezone": "Europe/London", "ipGeoAt": "2026-09-01T09:00:00.000Z", "playerSettings": null, "kioskEnabled": false, "kioskPinMode": "workspace", "kioskGraceSeconds": 30, "activeEmergencyId": null, "activeCastId": null, "playerVersionHold": null, "sealed": false, "sealedAt": null, "powerPolicyId": null, "importSourceId": null, "billingGroupId": null, "customFields": null, "lanSecretAt": null, "createdAt": "2026-09-01T09:00:00.000Z", "updatedAt": "2026-09-28T11:58:00.000Z", "deletedAt": null, "location": null, "deviceClaimed": false, "nodeName": "Head office", "groupIds": [], "contentName": "Lobby loop", "contentSharedFrom": null, "thumbnailUrl": null, "contentAppKey": null, "contentMediaKind": null, "contentState": null, "contentOrientation": "landscape", "liveThumbnailAt": "2026-09-28T11:45:00.000Z", "liveThumbnailFreshAt": "2026-09-28T11:57:00.000Z", "currentContentKind": "image", "currentContentPosterUrl": null, "emergencyHeadline": null, "castHeadline": null, "castStartedAt": null, "castExpiresAt": null, "castContentKind": null, "castContentId": null, "kioskHasCustomPin": false, "kioskHasRecovery": false, "obscuredSince": null, "pixelHealth": "ok", "displayOffSince": null, "displayOffReason": null, "expectedDark": { "dark": false, "reason": null, "nextOpen": null, "minutesSinceOpen": null, "minutesSinceClose": null }, "accountHold": null, "outageSummary30d": null, "state": { "updatedAt": "2026-09-28T11:58:00.000Z", "connection": "online", "currentContent": { "kind": "playlist", "id": "pl_9a8b7c6d5e4f3a2b" } } } ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "post": { "operationId": "createScreen", "tags": [ "screens" ], "summary": "Create a screen", "description": "Create a screen. `name` is required; `nodeId`, `location`, and `tags` are optional. This operation is safe to retry with an idempotency key. Each screen created increases your billed screen count, so this request is refused if your account is suspended or cancelled.\n\n**Notes.**\n- Returns the stored row, not the composed Screen that GET /v1/screens/{id} returns: `tags` is the JSON-encoded string, and the composed fields (`contentName`, `state`, …) are absent.\n- The screen waits in `pairing` status until a device claims it (POST /v1/screens/{id}/claim-replacement) — or use POST /v1/screens/claim or /v1/screens/enroll, which create and pair in one step.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "x-brix-notes": [ "Returns the stored row, not the composed Screen that GET /v1/screens/{id} returns: `tags` is the JSON-encoded string, and the composed fields (`contentName`, `state`, …) are absent.", "The screen waits in `pairing` status until a device claims it (POST /v1/screens/{id}/claim-replacement) — or use POST /v1/screens/claim or /v1/screens/enroll, which create and pair in one step." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "nodeId": { "description": "Location to create it in; default: the API key's own location, else the workspace root.", "type": "string" }, "billingGroupId": { "description": "Billing group that pays for the screen.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenRow" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The location does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The account is suspended or cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/screens/{id}": { "delete": { "operationId": "deleteScreen", "tags": [ "screens" ], "summary": "Delete a screen", "description": "Delete a screen. It moves to the 30-day recovery window, and its paired device is unpaired so the player shows its pairing screen. An optional `reason` field is recorded in the activity log.\n\nSoft-deletes the screen to the recycle bin (restorable for 30 days) and releases its device, which returns to the pairing screen.", "x-brix-permission": "screen.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such screen in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.delete" ] } ] }, "get": { "operationId": "getScreen", "tags": [ "screens" ], "summary": "Get a screen", "description": "Get one screen, with the same detail included in the screen list. A screen outside your organization scope returns a not-found error rather than a permission error.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Screen" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such screen in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "patch": { "operationId": "updateScreen", "tags": [ "screens" ], "summary": "Update a screen's settings", "description": "Update a screen's own fields, including name, location, tags, orientation, organization node, and player settings. This endpoint does not assign content; use POST /v1/screens/:id/assign to change what a screen plays.\n\nPartial update. To change what a screen plays use POST /v1/screens/{id}/assign — this route refuses `contentKind`/`contentId` with a 400.\n\n**Notes.**\n- The PATCH response does not merge the live socket facts (`linkFlaps10m`, a socket-fresh `lastSeenAt`) that GET adds.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The PATCH response does not merge the live socket facts (`linkFlaps10m`, a socket-fresh `lastSeenAt`) that GET adds." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "nodeId": { "description": "Move to another location (you need screen.edit there too).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "billingGroupId": { "description": "Needs billing.edit.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "online", "offline", "pairing" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "rotation": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 90 }, { "type": "number", "const": 180 }, { "type": "number", "const": 270 } ] }, "timezone": { "description": "IANA time zone; null to inherit.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operatingHours": { "type": "string" }, "displayPowerMode": { "type": "string", "enum": [ "always-on", "follow-schedule", "os-default" ] }, "powerPolicyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "playbackMode": { "type": "string", "enum": [ "sync", "unsync", "device-time" ] }, "location": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } } }, { "type": "null" } ] }, "deactivated": { "description": "True deactivates the screen (nothing plays); false reactivates it.", "type": "boolean" }, "playerVersionHold": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, { "type": "null" } ] }, "playerSettings": { "description": "Merged into the current settings; null resets them.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "customFields": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "kioskPinMode": { "type": "string", "enum": [ "workspace", "custom" ] }, "kioskGraceSeconds": { "type": "number" }, "kioskPin": { "description": "4-8 digits; null clears the custom PIN.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "kioskEnabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Screen" } }, "required": [ "data" ] } } } }, "400": { "description": "The body tried to set content (use POST /v1/screens/{id}/assign).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such screen (or destination location/billing group) in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid status, rotation, time zone or PIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/assign": { "post": { "operationId": "assignContent", "tags": [ "screens" ], "summary": "Set what a screen plays", "description": "Assign content to a screen using `contentKind` and `contentId`. Pass `null` to clear the current assignment. The content is validated to confirm it exists, can be used at the screen's organization node, and has no unfilled layout zones, before the screen is updated to play it.\n\nAssigns content to one screen (null clears it). The screen is told to reload immediately.", "x-brix-permission": "screen.cast", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentKind": { "anyOf": [ { "type": "string", "enum": [ "playlist", "schedule", "layout", "creative", "app", "media", "signage" ] }, { "type": "null" } ], "description": "What to assign; null clears the assignment." }, "contentId": { "description": "Required unless `contentKind` is null.", "type": "string" } }, "required": [ "contentKind" ] }, "example": { "contentKind": "playlist", "contentId": "pl_9a8b7c6d5e4f3a2b" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "contentKind": { "anyOf": [ { "type": "string", "enum": [ "playlist", "schedule", "layout", "creative", "app", "media", "signage" ] }, { "type": "null" } ] }, "contentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "contentKind", "contentId" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "scr_1a2b3c4d5e6f7a8b", "contentKind": "playlist", "contentId": "pl_9a8b7c6d5e4f3a2b" } } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`not_shared`: the content is not shared to this screen's location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such screen or content in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid kind, a layout with unbound zones, or content that cannot play (empty playlist, unprocessed media).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.cast" ] } ] } }, "/v1/screens/{id}/claim-replacement": { "post": { "operationId": "claimReplacementScreen", "tags": [ "screens" ], "summary": "Replace a screen's device", "description": "Bind a new device, identified by the 6-digit pairing code it is displaying, to an existing screen. The screen keeps its identity, assigned content, and history. This endpoint is rate-limited because the pairing code is a small, guessable value.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "The 6-digit code the new device shows." } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "paired": { "type": "boolean", "const": true } }, "required": [ "id", "paired" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No screen with this id, or no device shows that code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`ambiguous_code` (two devices show it) or `already_claimed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The code has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`code` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many wrong codes; wait and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/commands": { "post": { "operationId": "sendScreenCommand", "tags": [ "screens" ], "summary": "Send a command to a screen", "description": "Queue a command for a screen's device, such as reboot, turning the display on or off, taking a screenshot, or clearing the cache. The device runs the command the next time it checks in.\n\nQueues a device command (reboot, refresh, screenshot, volume, …). Poll GET /v1/screens/{id}/commands/{commandId} for the device's answer.\n\n**Notes.**\n- A `screenshot` that coalesces onto an older pending one answers 200 (not 201) with `coalesced: true`.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "A `screenshot` that coalesces onto an older pending one answers 200 (not 201) with `coalesced: true`." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "reboot", "cec-on", "cec-off", "clear-cache", "refresh", "screenshot", "start-mirror", "stop-mirror", "selftest", "pull-logs", "unlock-kiosk", "trigger", "set-volume", "set-mute", "set-brightness", "set-input", "rs232", "rekey", "set-proxy", "update-player", "update-app", "clear-obstruction", "add-wifi", "wake-screen", "set-timezone", "restart-app", "pause-recovery", "speed-test", "recover-peer", "set-fallback-wifi", "collect-diagnostics" ] }, "payload": { "description": "Per-kind payload: `set-volume` {level 0-100}, `set-brightness` {level}, `set-mute` {muted}, `set-input` {input}, … Most kinds take none.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "kind" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Command id." }, "kind": { "type": "string", "enum": [ "reboot", "cec-on", "cec-off", "clear-cache", "refresh", "screenshot", "start-mirror", "stop-mirror", "selftest", "pull-logs", "unlock-kiosk", "trigger", "set-volume", "set-mute", "set-brightness", "set-input", "rs232", "rekey", "set-proxy", "update-player", "update-app", "clear-obstruction", "add-wifi", "wake-screen", "set-timezone", "restart-app", "pause-recovery", "speed-test", "recover-peer", "set-fallback-wifi", "collect-diagnostics" ] }, "status": { "type": "string", "const": "pending" }, "coalesced": { "description": "True when a stale pending screenshot command was reused instead.", "type": "boolean" } }, "required": [ "id", "kind", "status" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such screen in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unknown kind or invalid payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/commands/{commandId}": { "get": { "operationId": "getScreenCommand", "tags": [ "screens" ], "summary": "Get a command's status", "description": "Get the outcome of one previously queued device command, including its status (acknowledged, failed, or pending) and any note reported by the device.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" }, { "name": "commandId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Command id from POST /v1/screens/{id}/commands." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "description": "The command kind (see POST /v1/screens/{id}/commands)." }, "status": { "type": "string", "enum": [ "pending", "delivered", "acked", "failed", "unconfirmed", "held" ] }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deliveredAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "ackedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "kind", "status", "result", "issuedAt", "deliveredAt", "ackedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/diagnose": { "get": { "operationId": "getScreenDiagnose", "tags": [ "screens" ], "summary": "Diagnose a screen issue", "description": "Get a likely-cause troubleshooting verdict for a screen, based on signals such as online or offline status, what is actually rendering, resource pressure, and early hardware warnings. The response also includes a guided checklist for checking the TV, input, and cable, which the screen itself cannot detect.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScreenDiagnosis" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/diagnostic-bundles": { "get": { "operationId": "listScreenDiagnosticBundles", "tags": [ "screens" ], "summary": "List a screen's diagnostic bundles", "description": "List the detailed diagnostic bundles a screen has uploaded, such as system logs, thread dumps, and exit reasons, newest first. This returns only the index; download an individual bundle separately.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reason": { "type": "string" }, "sections": { "type": "array", "items": { "type": "string" } }, "bytes": { "type": "integer" }, "downloadable": { "type": "boolean", "description": "False when the bundle was recorded but not stored." }, "playerVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "clockSkewMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "reason", "sections", "bytes", "downloadable", "playerVersion", "platform", "clockSkewMs", "createdAt" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/diagnostic-bundles/{bundleId}": { "get": { "operationId": "getScreenDiagnosticBundle", "tags": [ "screens" ], "summary": "Download a diagnostic bundle", "description": "Download one detailed diagnostic bundle as JSON, exactly as it was uploaded by the device.\n\n**Notes.**\n- The body is the bundle exactly as the device uploaded it, served as an attachment.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The body is the bundle exactly as the device uploaded it, served as an attachment." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" }, { "name": "bundleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bundle id." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such bundle, or it was not stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/diagnostics": { "get": { "operationId": "listScreenDiagnostics", "tags": [ "screens" ], "summary": "Get consolidated screen diagnostics", "description": "Get a consolidated diagnostic report for a screen: the likely-cause verdict from GET /v1/screens/:id/diagnose plus the underlying signals, including open alerts, recent health trends, crashes and self-heals, a recent log tail, and the latest reported state. Pass `format=text` for a plain-text report, or omit it for structured JSON.\n\n**Notes.**\n- `?format=text` returns the same report as plain text (text/plain) instead of JSON.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "`?format=text` returns the same report as plain text (text/plain) instead of JSON." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "screen": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "online", "offline", "pairing" ] }, "lastSeenAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "name", "status", "lastSeenAt" ] }, "diagnosis": { "$ref": "#/components/schemas/ScreenDiagnosis" }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": "string" }, "openedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "code", "severity", "message", "openedAt" ] }, "description": "Open alerts on this screen." }, "vitals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "screenId": { "type": "string" }, "storageFreeMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "storageTotalMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "memoryFreeMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "memoryTotalMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "heapUsedMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "heapLimitMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "networkLossRatio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "networkRttMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "thermalStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reloadCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "rebootCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "uptimeSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "videoDropPct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "webViewKillCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "renderFreezeCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxRenderFreezeMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "childFreezeCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "occurredAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "spaceId", "screenId", "storageFreeMb", "storageTotalMb", "memoryFreeMb", "memoryTotalMb", "heapUsedMb", "heapLimitMb", "networkLossRatio", "networkRttMs", "thermalStatus", "reloadCount", "rebootCount", "uptimeSec", "fps", "videoDropPct", "webViewKillCount", "renderFreezeCount", "maxRenderFreezeMs", "childFreezeCount", "occurredAt" ] }, "description": "Recent device vitals, newest first." }, "crashes": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "reportedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "reason", "reportedAt" ] } }, "logs": { "type": "array", "items": { "type": "object", "properties": { "entries": { "description": "The uploaded log lines (decoded JSON)." }, "reason": { "type": "string" }, "errorCount": { "type": "integer" }, "warnCount": { "type": "integer" }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "entries", "reason", "errorCount", "warnCount", "createdAt" ] } }, "state": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "The last heartbeat snapshot; null before the first heartbeat." }, "generatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "screen", "diagnosis", "alerts", "vitals", "crashes", "logs", "state", "generatedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/display-history": { "get": { "operationId": "getScreenDisplayHistory", "tags": [ "screens" ], "summary": "Get a screen's display history", "description": "Get the history of what the physical display itself did, such as being switched off, switched to another HDMI input, losing its HDMI connection, or coming back, separate from whether the player software was online. Entries are newest first, each showing how long the previous state lasted, along with the current state. This data is only available for displays that support CEC, and history is limited to the last 14 days.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window in days; default and maximum: the telemetry retention." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Most changes to list (default 50, max 500)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "screenId": { "type": "string" }, "windowDays": { "type": "integer" }, "retentionDays": { "type": "integer" }, "current": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "enum": [ "standby", "wrong-input", "disconnected", "lit" ] }, "since": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "state", "since" ] }, { "type": "null" } ], "description": "What the panel is doing now; null when the device cannot read the panel." }, "changes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "from": { "type": "string", "enum": [ "standby", "wrong-input", "disconnected", "lit" ] }, "to": { "type": "string", "enum": [ "standby", "wrong-input", "disconnected", "lit" ] }, "forSec": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "at", "from", "to", "forSec" ] } }, "truncated": { "type": "boolean" } }, "required": [ "screenId", "windowDays", "retentionDays", "current", "changes", "truncated" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/frames": { "get": { "operationId": "listScreenFrames", "tags": [ "screens" ], "summary": "Get a screen's frame history", "description": "Get a log of visual fingerprints captured from a screen over a time range, using the `since` and `until` query parameters. This log is a visual audit trail and is kept even after the screen is deleted.\n\n**Notes.**\n- The newest 500 frames in the window.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The newest 500 frames in the window." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO timestamp; only frames at or after it." }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO timestamp; only frames at or before it." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "hash": { "type": "string", "description": "Perceptual hash of the frame on the glass." }, "contentKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "capturedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "hash", "contentKind", "contentId", "capturedAt" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/kiosk-recovery/reveal": { "post": { "operationId": "revealScreenKioskRecovery", "tags": [ "screens" ], "summary": "Reveal a screen's recovery code", "description": "Reveal the offline recovery code for a screen with Screen Lock enabled. This action is recorded in the activity log.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "code": { "type": "string", "description": "The Screen Lock recovery code. Each reveal is recorded in the audit log." } }, "required": [ "code" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No screen with this id, or it has no recovery code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/kiosk-recovery/rotate": { "post": { "operationId": "rotateScreenKioskRecovery", "tags": [ "screens" ], "summary": "Rotate a screen's recovery code", "description": "Generate a new offline recovery code for a screen with Screen Lock enabled. The previous code stops working immediately. This action is recorded in the activity log.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "code": { "type": "string", "description": "The new Screen Lock recovery code." } }, "required": [ "code" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/lan-secret/rotate": { "post": { "operationId": "rotateScreenLanSecret", "tags": [ "screens" ], "summary": "Rotate a screen's local network key", "description": "Replace the key used to authenticate local-network requests to this screen. The new key is not returned in the response; only the device receives it. Any third-party integration that signs its own requests to the screen must be updated with the new key.\n\n**Notes.**\n- The key itself is never returned; the device collects it.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The key itself is never returned; the device collects it." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "rotatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "rotatedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No screen with this id, or Local trigger is off for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/live-thumbnail": { "get": { "operationId": "getScreenLiveThumbnail", "tags": [ "screens" ], "summary": "Get a screen's live thumbnail", "description": "Get the most recently captured still image for a screen, returned as image bytes. This accepts standard API authentication, including an API key, or a short-lived `asset` query parameter token so the image can be loaded directly in an image tag. A screen outside your access scope returns a not-found error rather than a permission error.\n\n**Notes.**\n- The response header `x-captured-at` carries the capture time.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The response header `x-captured-at` carries the capture time." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`capturedAt` of a specific capture; default the newest." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No screen with this id, or it has no capture yet (`no_screenshot`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/logs": { "get": { "operationId": "listScreenLogs", "tags": [ "screens" ], "summary": "Get a screen's activity log", "description": "Get a combined, newest-first feed of a screen's recent activity from the last 24 hours, including telemetry events, crash reports, command acknowledgements, and screenshot uploads.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "level": { "type": "string", "enum": [ "error", "info", "warn" ] }, "text": { "type": "string" } }, "required": [ "at", "level", "text" ] }, "description": "Newest first, at most 200." }, "windowHours": { "type": "integer" } }, "required": [ "lines", "windowHours" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/mirror": { "post": { "operationId": "mirrorScreen", "tags": [ "screens" ], "summary": "Start a screen mirror session", "description": "Start a live mirroring session for a screen. The response includes a signaling URL that a viewer connects to over WebRTC; the screen's device connects when it receives the corresponding command. End the session with POST /v1/mirror/:sessionId/end.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sessionId": { "type": "string" }, "signalingUrl": { "type": "string" }, "signalingToken": { "type": "string", "description": "Viewer token for `signalingUrl`; valid for 5 minutes, for this session only." }, "turnHint": { "type": "string" } }, "required": [ "sessionId", "signalingUrl", "signalingToken", "turnHint" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/outages": { "get": { "operationId": "listScreenOutages", "tags": [ "screens" ], "summary": "Get a screen's outage history", "description": "Get the outage history for a screen over the last N days (default 30, capped at the retention window). Each outage includes when it happened, how long it lasted, a plain-language cause such as a Wi-Fi drop or a power cut, and supporting evidence, along with a summary sentence such as \"went down 6 times in the last 30 days, all Wi-Fi drops\". Planned downtime is listed but excluded from the outage count.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Window in days (default 30), capped at the workspace's retention." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Most outages to list (default 50)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "screenId": { "type": "string" }, "windowDays": { "type": "integer" }, "retentionDays": { "type": "integer" }, "summary": { "type": "object", "properties": { "windowDays": { "type": "integer" }, "count": { "type": "integer", "description": "Unplanned outages in the window." }, "byCause": { "type": "object", "properties": { "power-loss": { "type": "integer" }, "powered-off": { "type": "integer" }, "os-reboot": { "type": "integer" }, "app-crash": { "type": "integer" }, "app-killed-low-memory": { "type": "integer" }, "app-anr": { "type": "integer" }, "app-restart": { "type": "integer" }, "wifi-dropped": { "type": "integer" }, "wifi-weak": { "type": "integer" }, "wifi-no-internet": { "type": "integer" }, "ethernet-dropped": { "type": "integer" }, "brix-unreachable": { "type": "integer" }, "display-off": { "type": "integer" }, "sleep": { "type": "integer" }, "scheduled-off": { "type": "integer" }, "unknown": { "type": "integer" }, "power-cycle": { "type": "integer" }, "network-only": { "type": "integer" } }, "description": "Outage count per cause; a cause with none is absent." }, "byBucket": { "type": "object", "properties": { "app": { "type": "integer" }, "display": { "type": "integer" }, "unknown": { "type": "integer" }, "network": { "type": "integer" }, "power": { "type": "integer" }, "brix": { "type": "integer" }, "planned": { "type": "integer" } }, "required": [ "app", "display", "unknown", "network", "power", "brix", "planned" ] }, "topCause": { "anyOf": [ { "type": "string", "enum": [ "power-loss", "powered-off", "os-reboot", "app-crash", "app-killed-low-memory", "app-anr", "app-restart", "wifi-dropped", "wifi-weak", "wifi-no-internet", "ethernet-dropped", "brix-unreachable", "display-off", "sleep", "scheduled-off", "unknown", "power-cycle", "network-only" ] }, { "type": "null" } ] }, "topCauseShare": { "type": "number" }, "hedgedShare": { "type": "number" }, "lastCause": { "anyOf": [ { "type": "object", "properties": { "cause": { "type": "string", "enum": [ "power-loss", "powered-off", "os-reboot", "app-crash", "app-killed-low-memory", "app-anr", "app-restart", "wifi-dropped", "wifi-weak", "wifi-no-internet", "ethernet-dropped", "brix-unreachable", "display-off", "sleep", "scheduled-off", "unknown", "power-cycle", "network-only" ] }, "confident": { "type": "boolean", "description": "False when the cause is a best guess." } }, "required": [ "cause", "confident" ] }, { "type": "null" } ] }, "lastAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastKnownCause": { "anyOf": [ { "type": "object", "properties": { "cause": { "type": "string", "enum": [ "power-loss", "powered-off", "os-reboot", "app-crash", "app-killed-low-memory", "app-anr", "app-restart", "wifi-dropped", "wifi-weak", "wifi-no-internet", "ethernet-dropped", "brix-unreachable", "display-off", "sleep", "scheduled-off", "unknown", "power-cycle", "network-only" ] }, "confident": { "type": "boolean", "description": "False when the cause is a best guess." } }, "required": [ "cause", "confident" ] }, { "type": "null" } ] }, "avgRssiDbm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "insight": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The rollup sentence, e.g. `All 6 were Wi-Fi drops.`" } }, "required": [ "windowDays", "count", "byCause", "byBucket", "topCause", "topCauseShare", "hedgedShare", "lastCause", "lastAt", "lastKnownCause", "avgRssiDbm", "insight" ] }, "outages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "to": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Null while the screen is still down." }, "durationSec": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "open": { "type": "boolean" }, "detectionPath": { "type": "string" }, "cause": { "anyOf": [ { "type": "object", "properties": { "cause": { "type": "string", "enum": [ "power-loss", "powered-off", "os-reboot", "app-crash", "app-killed-low-memory", "app-anr", "app-restart", "wifi-dropped", "wifi-weak", "wifi-no-internet", "ethernet-dropped", "brix-unreachable", "display-off", "sleep", "scheduled-off", "unknown", "power-cycle", "network-only" ] }, "confident": { "type": "boolean", "description": "False when the cause is a best guess." } }, "required": [ "cause", "confident" ] }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sentence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": { "anyOf": [ { "type": "object", "properties": { "rssiDbm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ssid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkValidated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "flaps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "fetchFailure": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bootReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exitReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "probeOk": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "requestIds": { "type": "array", "items": { "type": "string" } } } }, { "type": "null" } ] }, "expectedDark": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True for planned darkness (operating hours): listed, never counted." }, "expectedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "selfReportedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "playerVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "from", "to", "durationSec", "open", "detectionPath", "cause", "label", "sentence", "evidence", "expectedDark", "expectedReason", "selfReportedReason", "playerVersion" ] } }, "truncated": { "type": "boolean" } }, "required": [ "screenId", "windowDays", "retentionDays", "summary", "outages", "truncated" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/playback-quality": { "get": { "operationId": "getScreenPlaybackQuality", "tags": [ "screens" ], "summary": "Get a screen's playback quality", "description": "Check whether this screen's device is limiting playback quality. The response reports, for each 4K-capable video, whether it plays at full quality or has been reduced because of device limitations or stuttering, along with any hardware upgrade recommendation.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "serves4k": { "type": "boolean", "description": "True when the device is sent 4K renditions." }, "videos4k": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "demoted": { "type": "boolean" }, "served": { "type": "boolean" } }, "required": [ "id", "name", "demoted", "served" ] } }, "recommendation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "model", "tier", "serves4k", "videos4k", "recommendation" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/preview": { "get": { "operationId": "previewScreen", "tags": [ "screens" ], "summary": "Preview what a screen would play", "description": "Preview what a screen would play at a given time, without affecting the actual device. Pass `at` as an ISO timestamp to preview a different time; it defaults to now.\n\n**Notes.**\n- `data` is the player manifest. Content blocks are open objects in the player's own format; `v` versions it.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "`data` is the player manifest. Content blocks are open objects in the player's own format; `v` versions it." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" }, { "name": "at", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO timestamp to build the preview for; default now." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ManifestPreview" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/replace-device": { "post": { "operationId": "replaceDeviceScreen", "tags": [ "screens" ], "summary": "Unpair a screen's device", "description": "Release the device currently paired with a screen, without deleting the screen itself. The screen's name, content, location, and history are kept. Follow up with POST /v1/screens/:id/claim-replacement to pair a new device.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "awaitingReplacement": { "type": "boolean", "const": true } }, "required": [ "id", "awaitingReplacement" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/resource-pressure": { "get": { "operationId": "getScreenResourcePressure", "tags": [ "screens" ], "summary": "Get a screen's resource pressure", "description": "Check a screen's storage, memory, and offline cache pressure. The response ranks the content contributing most to that pressure, with suggestions to remove or replace it, and includes hardware upgrade recommendations if relevant.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "none", "warning", "critical" ] }, "resources": { "type": "array", "items": { "type": "string", "enum": [ "storage", "memory", "cache" ] }, "description": "The resources under pressure." }, "storage": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "none", "warning", "critical" ] }, "freeMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "freeFrac": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Free as a fraction of total (0–1)." }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysLeft": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Days until full at the recent rate; null when not shrinking." } }, "required": [ "severity", "freeMb", "totalMb", "freeFrac", "headline", "daysLeft" ] }, "memory": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "none", "warning", "critical" ] }, "freeMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "totalMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "freeFrac": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Free as a fraction of total (0–1)." }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "daysLeft": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Days until full at the recent rate; null when not shrinking." } }, "required": [ "severity", "freeMb", "totalMb", "freeFrac", "headline", "daysLeft" ] }, "cache": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "none", "warning", "critical" ] }, "cacheableBytes": { "type": "integer" }, "budgetBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ramTotalMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "videoCount": { "type": "integer" }, "overBytes": { "type": "integer" }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "severity", "cacheableBytes", "budgetBytes", "ramTotalMb", "videoCount", "overBytes", "headline" ] }, "heavyContent": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "layout", "app", "media" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "detail": { "type": "string" }, "freesMb": { "type": "number" }, "estimated": { "type": "boolean" }, "freesLabel": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "kind", "id", "name", "detail", "freesMb", "estimated", "freesLabel", "reason" ] }, "description": "Assigned content that costs the most, with what removing it frees." }, "hardware": { "anyOf": [ { "type": "object", "properties": { "currentModel": { "type": "string" }, "currentLimits": { "type": "object", "properties": { "ramTotalMB": { "type": "number" }, "maxConcurrentVideos": { "type": "integer" }, "multiZoneOk": { "type": "boolean" }, "advice": { "type": "string" } } }, "recommendedModel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recommendedRamTotalMB": { "type": "number" }, "message": { "type": "string" } }, "required": [ "currentModel", "recommendedModel", "message" ] }, { "type": "null" } ], "description": "A hardware upgrade suggestion, when the device is the limit." }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "severity", "resources", "storage", "memory", "cache", "heavyContent", "hardware", "summary" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/restore": { "post": { "operationId": "restoreScreen", "tags": [ "screens" ], "summary": "Restore a deleted screen", "description": "Restore a screen deleted within the last 30 days, and restore its device pairing. A device that has kept its access token reconnects automatically, without needing to be re-paired on site.", "x-brix-permission": "screen.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No deleted screen with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The screen is not deleted, or restoring it would exceed the plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.delete" ] } ] } }, "/v1/screens/{id}/revoke-device": { "post": { "operationId": "revokeDeviceScreen", "tags": [ "screens" ], "summary": "Revoke a screen's device access", "description": "Immediately invalidate the access token of the device currently paired with a screen, for example after a device is lost or stolen. The token can no longer be used, including to pair as a new screen. The screen itself is not deleted.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "type": "boolean", "const": true }, "at": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "revoked", "at" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/rotate-token": { "post": { "operationId": "rotateTokenScreen", "tags": [ "screens" ], "summary": "Rotate a screen's device token", "description": "Generate a new access token for a screen's paired device, invalidating the previous one immediately. The new token is returned once in the response and cannot be retrieved afterward.\n\n**Notes.**\n- The response carries the NEW device credential. The device holding the old token is disconnected and must be given this token (or re-paired) to keep playing.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The response carries the NEW device credential. The device holding the old token is disconnected and must be given this token (or re-paired) to keep playing." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deviceToken": { "type": "string", "description": "The new device credential. Shown once; the old token stops working now." }, "rotatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "deviceToken", "rotatedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/state": { "get": { "operationId": "getScreenState", "tags": [ "screens" ], "summary": "Get a screen's reported device state", "description": "Get the screen's most recently reported state, including what is currently displayed, the player software version, and its cache and resource status.\n\nThe device's last heartbeat snapshot (telemetry, cache, current content, pending updates). Free-form: fields vary by player shell and version.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "screenId": { "type": "string" }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "screenId", "updatedAt" ], "additionalProperties": {} }, { "type": "null" } ], "description": "Null before the first heartbeat." } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such screen in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/telemetry": { "get": { "operationId": "getScreenTelemetry", "tags": [ "screens" ], "summary": "Get a screen's raw telemetry", "description": "Get the 100 most recent raw telemetry events sent by a screen, newest first, with parsed payload data.\n\n**Notes.**\n- The newest 100 events.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "The newest 100 events." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "spaceId": { "type": "string" }, "screenId": { "type": "string" }, "type": { "type": "string" }, "payload": { "description": "The event payload (decoded JSON); its shape depends on `type`." }, "occurredAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "receivedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "spaceId", "screenId", "type", "payload", "occurredAt", "receivedAt" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/trigger": { "post": { "operationId": "triggerScreen", "tags": [ "screens" ], "summary": "Trigger a screen interaction", "description": "Send a real-time trigger to a screen: `refresh`, `next`, `go-to-scene`, or `send-event`. The screen receives it immediately.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "refresh", "next", "prev", "go-to-page", "go-to-scene", "send-event" ] }, "page": { "description": "`go-to-page`: 1–100.", "type": "integer" }, "sceneId": { "description": "`go-to-scene`: the scene to show.", "type": "string" }, "event": { "description": "`send-event`: the event name the content listens for.", "type": "string" }, "payload": { "description": "`send-event`: an optional string payload.", "type": "string" }, "overlay": { "description": "A popup shown over what is playing for `seconds`, then removed. The content underneath does not restart.", "type": "object", "properties": { "contentKind": { "type": "string", "enum": [ "media", "app", "canvas" ] }, "contentId": { "type": "string" }, "seconds": { "description": "1–600 (clamped); default 15.", "type": "number" }, "position": { "description": "Default `center`.", "type": "string", "enum": [ "center", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right" ] }, "params": { "description": "Values passed to the content, e.g. `{ \"table\": \"4\" }`.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "contentKind", "contentId" ] } }, "required": [ "kind" ], "description": "A trigger. Fields other than `kind` apply to the kinds named." } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The command id." }, "kind": { "type": "string", "const": "trigger" }, "trigger": { "type": "object", "properties": { "kind": { "type": "string" }, "page": { "type": "integer" }, "sceneId": { "type": "string" }, "event": { "type": "string" }, "payload": { "type": "string" } }, "required": [ "kind" ], "description": "The trigger as stored (only the fields its kind uses)." }, "overlay": { "type": "object", "properties": { "contentKind": { "type": "string", "enum": [ "media", "app", "canvas" ] }, "contentId": { "type": "string" }, "seconds": { "type": "integer", "description": "1–600; default 15." }, "position": { "type": "string", "enum": [ "center", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right" ] }, "params": { "description": "Values passed to the content, e.g. `{ \"table\": \"4\" }`.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "contentKind", "contentId", "seconds", "position" ] } }, "required": [ "id", "kind", "trigger" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Not a valid trigger, or the overlay content is not in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/{id}/unpower-and-delete": { "post": { "operationId": "unpowerAndDeleteScreen", "tags": [ "screens" ], "summary": "Power off and delete a screen", "description": "Retire a screen in one action: turn off the physical display, unpair the device, and delete the screen. The screen can be recovered within 30 days.", "x-brix-permission": "screen.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "commandId": { "type": "string", "description": "The `cec-off` command sent before the device was unpaired." } }, "required": [ "id", "deleted", "commandId" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.delete" ] } ] } }, "/v1/screens/{id}/up-next": { "get": { "operationId": "getScreenUpNext", "tags": [ "screens" ], "summary": "Get a screen's up-next schedule", "description": "Get the current running order and the next scheduled change for a screen, based on exactly what the screen itself will play. This endpoint is relatively expensive to compute and should be called on demand rather than polled regularly.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "now": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "name", "kind", "seconds" ] }, { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "emergency", "cast" ] } }, "required": [ "name", "kind" ] } ] }, { "type": "null" } ], "description": "What is on the glass now; null when nothing is." }, "overriddenBy": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "emergency", "cast" ] }, "endsAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "kind", "endsAt" ] }, { "type": "null" } ] }, "rotation": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "seconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Fixed dwell; null when the item plays for its own length." } }, "required": [ "name", "kind", "seconds" ] }, "description": "The running order under any override, in play order." }, "loops": { "type": "boolean" }, "nextChange": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "what": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screensOff": { "type": "boolean" } }, "required": [ "at", "what", "screensOff" ] }, { "type": "null" } ] } }, "required": [ "now", "overriddenBy", "rotation", "loops", "nextChange" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/{id}/why": { "get": { "operationId": "explainScreen", "tags": [ "screens" ], "summary": "Explain what a screen shows and why", "description": "Get a plain-language explanation of why a screen is currently showing what it is showing. The explanation follows the order of precedence: emergency content, then manually assigned content, then scheduled content, then the default, including reasons such as a missing asset or a revoked share.\n\nThe resolution chain (deactivated → emergency → cast → assigned content), what the device reports on the glass, and warnings.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screen id.", "example": "scr_1a2b3c4d5e6f7a8b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "string" }, "currentContent": { "type": "object", "properties": { "kind": { "type": "string", "description": "The winning layer, or `none`." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "id", "name" ] }, "renderTruth": { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "deactivated", "offline", "no-content", "render-failed", "wrong-content", "signature-mismatch", "blank", "frozen", "switching", "ok" ] }, "ok": { "type": "boolean" }, "problem": { "type": "boolean" }, "fault": { "anyOf": [ { "type": "string", "enum": [ "user", "platform" ] }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "verdict", "ok", "problem", "fault", "reason" ] }, "layers": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string", "enum": [ "deactivated", "emergency", "cast", "scheduled", "default", "unassigned", "missing-asset", "share-revoked", "content-unplayable", "content-preparing", "schedule-empty", "schedule-gap" ] }, "active": { "type": "boolean" }, "reason": { "type": "string" }, "contentName": { "type": "string" }, "startedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "layer", "active", "reason" ] } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "summary", "currentContent", "renderTruth", "layers", "warnings" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such screen in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/bulk-assign": { "post": { "operationId": "bulkAssignContent", "tags": [ "screens" ], "summary": "Set what many screens play", "description": "Assign one piece of content to many screens in a single request. The content is validated the same way as in the single-screen assign endpoint. Screen IDs outside your access scope or belonging to another workspace are dropped; screens at locations not shared with the content are skipped and counted in the response. This action is recorded as a single entry in the activity log.\n\nAssigns one piece of content to many screens. Unknown or out-of-reach screen ids are silently dropped; screens whose location the content is not shared to are skipped and counted in `notShared`.", "x-brix-permission": "screen.cast", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "screenIds": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" } }, "contentKind": { "type": "string", "enum": [ "playlist", "schedule", "layout", "creative", "app", "media", "signage" ] }, "contentId": { "type": "string" } }, "required": [ "screenIds", "contentKind", "contentId" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "updated": { "type": "integer" }, "notShared": { "type": "integer" }, "screenIds": { "type": "array", "items": { "type": "string" }, "description": "The screens actually assigned." } }, "required": [ "updated", "notShared", "screenIds" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Empty/oversized `screenIds`, invalid kind, or unplayable content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.cast" ] } ] } }, "/v1/screens/bulk-settings": { "post": { "operationId": "bulkSettingsScreen", "tags": [ "screens" ], "summary": "Apply settings to many screens", "description": "Apply a Display Profile, a bundle of player settings, to many screens at once. You can also set placement fields such as `nodeId`, `location`, and `tags` for the screens in the same request.\n\n**Notes.**\n- A `rotation`, `displayPowerMode` or `playbackMode` value outside its set is ignored, not refused.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "A `rotation`, `displayPowerMode` or `playbackMode` value outside its set is ignored, not refused." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "screenIds": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Screens to change. Ids you cannot edit are skipped." }, "settings": { "type": "object", "properties": { "rotation": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 90 }, { "type": "number", "const": 180 }, { "type": "number", "const": 270 } ] }, "timezone": { "description": "IANA time zone; null clears it.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "operatingHours": { "type": "string" }, "displayPowerMode": { "type": "string", "enum": [ "always-on", "follow-schedule", "os-default" ] }, "playbackMode": { "type": "string", "enum": [ "sync", "unsync", "device-time" ] }, "powerPolicyId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "description": "Move the screens to this location (needs screen.edit there).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "label", "lat", "lng" ] }, { "type": "null" } ] }, "tags": { "description": "Replaces each screen's tags.", "type": "array", "items": { "type": "string" } }, "playerSettings": { "description": "Merged into each screen's player settings.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } } }, "required": [ "screenIds", "settings" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "updated": { "type": "integer" } }, "required": [ "updated" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The destination location does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid time zone or screen list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/claim": { "post": { "operationId": "claimScreen", "tags": [ "screens" ], "summary": "Pair a device by its code", "description": "Pair a device using its 6-digit pairing code, creating a new screen. Provide `code`, `name`, and an optional `nodeId`. This endpoint is rate-limited because the pairing code space is small, and is refused if your account is suspended or cancelled.\n\nClaims the device showing a 6-digit pairing code into this workspace as a new screen.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "The 6-digit code the device shows." }, "name": { "description": "Screen name. Default \"New screen\".", "type": "string" }, "nodeId": { "description": "Location to file the screen under.", "type": "string" }, "billingGroupId": { "type": "string" } }, "required": [ "code" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "screenId": { "type": "string" }, "name": { "type": "string" }, "previousScreen": { "anyOf": [ { "type": "object", "properties": { "screenId": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "claimedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "screenId", "name", "deletedAt", "claimedAt" ] }, { "type": "null" } ], "description": "The screen this same device was last paired to in this workspace, if any." } }, "required": [ "screenId", "name", "previousScreen" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`invalid_code`: no device is waiting with that code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`ambiguous_code` or `already_claimed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "`code_expired`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`code` missing, or a foreign location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many failed codes; honour `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/screens/commands": { "post": { "operationId": "sendScreenCommands", "tags": [ "screens" ], "summary": "Send a command to many screens", "description": "Queue the same command across many screens in a single request, using `screenIds`, `kind`, and an optional `payload`. Screen IDs you do not have permission to edit are silently dropped from the request rather than causing an error. Use this instead of sending one request per screen.\n\nQueues one command on many screens. Unknown or out-of-reach ids are silently dropped. Risky kinds (set-proxy, set-input, rs232, add-wifi) on a large cohort go to a small canary batch first and the rest are staged.\n\n**Notes.**\n- When no requested screen is reachable the answer is 200 (not 201) with `{ issued: 0, commandIds: [] }`.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "When no requested screen is reachable the answer is 200 (not 201) with `{ issued: 0, commandIds: [] }`." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "reboot", "cec-on", "cec-off", "clear-cache", "refresh", "screenshot", "start-mirror", "stop-mirror", "selftest", "pull-logs", "unlock-kiosk", "trigger", "set-volume", "set-mute", "set-brightness", "set-input", "rs232", "rekey", "set-proxy", "update-player", "update-app", "clear-obstruction", "add-wifi", "wake-screen", "set-timezone", "restart-app", "pause-recovery", "speed-test", "recover-peer", "set-fallback-wifi", "collect-diagnostics" ] }, "payload": { "description": "Per-kind payload: `set-volume` {level 0-100}, `set-brightness` {level}, `set-mute` {muted}, `set-input` {input}, … Most kinds take none.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "screenIds": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "screenIds" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "issued": { "type": "integer" }, "commandIds": { "type": "array", "items": { "type": "string" } }, "staged": { "description": "Canary rollouts: commands held behind the canary.", "type": "integer" }, "rolloutId": { "type": "string" }, "canary": { "type": "boolean", "const": true } }, "required": [ "issued", "commandIds" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unknown kind, invalid payload, or empty/oversized `screenIds`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/screens/count-by-status": { "get": { "operationId": "countScreensByStatus", "tags": [ "screens" ], "summary": "Count screens by status", "description": "Get a count of screens by status: online, offline, and unpaired. Counts are limited to the organization nodes you can see.\n\n**Notes.**\n- Returns the counts at the top level — NOT wrapped in `{ data }` like other routes.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Returns the counts at the top level — NOT wrapped in `{ data }` like other routes." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "online": { "type": "integer" }, "offline": { "type": "integer" }, "degraded": { "type": "integer", "description": "Always 0 today (reserved)." }, "unpaired": { "type": "integer", "description": "Screens in `pairing` status." }, "obstructed": { "type": "integer", "description": "Online screens with a system dialog covering them (also counted in `online`)." } }, "required": [ "online", "offline", "degraded", "unpaired", "obstructed" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screens/enroll": { "post": { "operationId": "enrollScreen", "tags": [ "screens" ], "summary": "Enroll a screen programmatically", "description": "Create a screen and pair it in a single call using a workspace API key, without a 6-digit pairing code. This is intended for automated device provisioning. The returned device token is shown once and cannot be retrieved again. The screen is created in the workspace the API key belongs to; an API key scoped to one organization node creates the screen under that node, while an account-wide key can target any node in the account.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Default `New screen`.", "type": "string" }, "nodeId": { "type": "string" }, "billingGroupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "screenId": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "deviceToken": { "type": "string", "description": "The device credential. Shown ONCE: install it on the device; it cannot be read again." }, "space": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, "node": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name" ] }, { "type": "null" } ] } }, "required": [ "screenId", "name", "status", "deviceToken", "space", "node" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The location does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The account is suspended or cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 60 enrollments a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/screens/pending": { "get": { "operationId": "getScreenPending", "tags": [ "screens" ], "summary": "List pending discovered devices", "description": "List devices automatically discovered on the same network as your workspace's existing screens, newest first. Each entry includes its 6-digit pairing code.\n\n**Notes.**\n- Only devices on the caller's own network (same public IPv4, or the same IPv6 /64) are listed, so call it from the network the devices are on.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "x-brix-notes": [ "Only devices on the caller's own network (same public IPv4, or the same IPv6 /64) are listed, so call it from the network the devices are on." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "pairingId": { "type": "string" }, "code": { "type": "string", "description": "The 6-digit code the device shows." }, "ordinal": { "type": "integer", "description": "1 = newest; matches the number the device shows when identified." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deviceLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zmScreenName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The screen name the device carried over from a previous signage system, when it has one." }, "zmMachineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previousScreen": { "anyOf": [ { "type": "object", "properties": { "screenId": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "claimedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "screenId", "name", "deletedAt", "claimedAt" ] }, { "type": "null" } ], "description": "A screen in this workspace this device was paired to before; null for a new device." } }, "required": [ "pairingId", "code", "ordinal", "createdAt", "expiresAt", "deviceLabel", "zmScreenName", "zmMachineId", "previousScreen" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/screens/pending/{id}/dismiss": { "post": { "operationId": "dismissScreenPending", "tags": [ "screens" ], "summary": "Dismiss a pending device", "description": "Dismiss a discovered device that you do not want to claim. Its current pairing code expires and the device generates a new one. The dismissed entry is kept in the activity history.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pending pairing id (`pairingId` from the pending list).", "example": "pair_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No pending device with this id on the caller's network.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/screens/pending/{id}/identify": { "post": { "operationId": "identifyScreenPending", "tags": [ "screens" ], "summary": "Identify a pending device", "description": "Briefly flash a discovered device's display so you can tell which physical screen it is. This only works for devices discovered on your own network; an ID from another network returns a not-found error.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Pending pairing id (`pairingId` from the pending list).", "example": "pair_5e6f7a8b9c0d1e2f" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No pending device with this id on the caller's network.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/screens/pending/claim": { "post": { "operationId": "claimScreenPending", "tags": [ "screens" ], "summary": "Claim multiple discovered devices", "description": "Claim multiple discovered devices as screens in one request, using `items`, an array of objects with `pairingId`, `name`, and an optional `nodeId`. To claim a device from a different network using its 6-digit code, use POST /v1/screens/claim instead. This request is refused if your account is suspended or cancelled.\n\n**Notes.**\n- Items that are not pending on the caller's network are skipped, not refused; `claimed` lists the ones that became screens.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "x-brix-notes": [ "Items that are not pending on the caller's network are skipped, not refused; `claimed` lists the ones that became screens." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "pairingId": { "type": "string" }, "name": { "type": "string" }, "nodeId": { "description": "Location for the new screen.", "type": "string" } }, "required": [ "pairingId" ] } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "claimed": { "type": "array", "items": { "type": "object", "properties": { "pairingId": { "type": "string" }, "screenId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "pairingId", "screenId", "name" ] } } }, "required": [ "claimed" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The account is suspended or cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`items` is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/screens/pending/identify-all": { "post": { "operationId": "identifyAllScreenPending", "tags": [ "screens" ], "summary": "Identify all pending devices", "description": "Briefly flash the displays of every discovered device on your network at once. This is useful when several new devices appear at the same time.", "x-brix-permission": "screen.create", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "count": { "type": "integer", "description": "Devices asked to show their number." } }, "required": [ "count" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.create" ] } ] } }, "/v1/screens/recycle-bin": { "get": { "operationId": "getScreenRecycleBin", "tags": [ "screens" ], "summary": "List deleted screens", "description": "List screens deleted within the last 30 days that can still be restored with POST /v1/screens/:id/restore. For deleted items across all types, use GET /v1/recycle-bin.\n\n**Notes.**\n- Screens deleted in the last 30 days; older ones are purged.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Screens deleted in the last 30 days; older ones are purged." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "const": "screen" }, "id": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "kind", "id", "name", "deletedAt", "nodeId" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screenshots": { "get": { "operationId": "listScreenshots", "tags": [ "screenshots" ], "summary": "List screenshots", "description": "List screen captures uploaded by your screens. Filter by a specific screen using the `screenId` query parameter. The image bytes for each screenshot are retrieved separately from GET /v1/screenshots/:id/file.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "screenId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this screen's captures." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "screenId": { "type": "string" }, "screenName": { "type": "string" }, "url": { "type": "string", "description": "Download path (GET /v1/screenshots/{id}/file)." }, "capturedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "confirmedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sourceWidth": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sourceHeight": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "sizeBytes": { "type": "integer" }, "capturedBy": { "anyOf": [ { "type": "string", "enum": [ "agent", "projection", "accessibility", "webview" ] }, { "type": "null" } ] }, "belowNative": { "description": "Present and true when the capture is smaller than the panel's native resolution.", "type": "boolean" } }, "required": [ "id", "screenId", "screenName", "url", "capturedAt", "confirmedAt", "width", "height", "sourceWidth", "sourceHeight", "sizeBytes", "capturedBy" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/screenshots/{id}/file": { "get": { "operationId": "getScreenshotFile", "tags": [ "screenshots" ], "summary": "Download a screenshot", "description": "Download the image bytes of one screen capture.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Screenshot id." } ], "responses": { "200": { "description": "Success. The body is the file itself.", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No screenshot with this id, or its file is gone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/search": { "get": { "operationId": "searchContent", "tags": [ "search" ], "summary": "Search media, playlists, screens and creatives", "description": "Search across media, playlists, screens, and creatives using the `q` query parameter. Supports bare terms, prefix matching with `*`, the operators AND, OR, and NOT, and column filters such as `name:dashboard`. Results are scoped to the current space.\n\nFull-text search by name. Each list holds only kinds the caller may view (the others come back empty), best match first. A query under 2 characters returns empty lists.\n\n**Notes.**\n- The route is gated by `media.view` (the route-registry description says `screen.view`): a key without `media.view` is refused even if it could see screens.\n- A failing index query is swallowed and returns an empty list for that kind, so an empty result is not proof of no match.", "x-brix-permission": "media.view", "x-brix-schema": "verified", "x-brix-notes": [ "The route is gated by `media.view` (the route-registry description says `screen.view`): a key without `media.view` is refused even if it could see screens.", "A failing index query is swallowed and returns an empty list for that kind, so an empty result is not proof of no match." ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search text (2+ characters). The last word matches as a prefix." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "description": "Hits per kind (default 10, max 20)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "snippet": { "type": "string", "description": "Matched text with `<b>…</b>` around the hit." } }, "required": [ "id", "snippet" ] } }, "playlists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "snippet": { "type": "string", "description": "Matched text with `<b>…</b>` around the hit." } }, "required": [ "id", "snippet" ] } }, "screens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "snippet": { "type": "string", "description": "Matched text with `<b>…</b>` around the hit." } }, "required": [ "id", "snippet" ] } }, "creatives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "snippet": { "type": "string", "description": "Matched text with `<b>…</b>` around the hit." } }, "required": [ "id", "snippet" ] } } }, "required": [ "media", "playlists", "screens", "creatives" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.view" ] } ] } }, "/v1/serial-templates": { "get": { "operationId": "listSerialTemplates", "tags": [ "serial-templates" ], "summary": "List serial command templates", "description": "List saved RS232 serial command templates for your workspace, such as profiles for turning a display on or switching its input. Each template includes the exact bytes each command sends.\n\n**Notes.**\n- Not paginated. Only templates at locations where the key has `screen.view` are listed.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "x-brix-notes": [ "Not paginated. Only templates at locations where the key has `screen.view` are listed." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SerialTemplate" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "post": { "operationId": "createSerialTemplate", "tags": [ "serial-templates" ], "summary": "Create a serial command template", "description": "Create an RS232 command template. Provide a `name`, an optional `model`, an `items` array of commands each with `name`, `value`, `encoding` (`ascii` or `hex`), and `eol`, and an optional `nodeId`.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "description": "Home location; null = workspace root.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "description": "The commands, at most 200. On update the list replaces the stored one.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Keep an existing command's id; omit to get a new one.", "type": "string" }, "name": { "type": "string" }, "value": { "type": "string", "description": "At most 512 characters, and it must give at least one byte." }, "encoding": { "description": "Default `ascii`. An unknown value is read as `ascii`.", "type": "string", "enum": [ "ascii", "hex" ] }, "eol": { "description": "Default `none`. An unknown value is read as `none`.", "type": "string", "enum": [ "none", "cr", "lf", "crlf" ] } }, "required": [ "name", "value" ] } } }, "required": [ "name" ] }, "example": { "name": "Sony Bravia", "model": "FW-55BZ35", "items": [ { "name": "Power on", "value": "*SCPOWR0000000000000001", "encoding": "ascii", "eol": "lf" } ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SerialTemplate" } }, "required": [ "data" ] }, "example": { "data": { "id": "sertpl_2b3c4d5e6f7a8b9c", "spaceId": "space_1a2b3c4d5e6f7a8b", "name": "Sony Bravia", "model": "FW-55BZ35", "nodeId": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "items": [ { "id": "sti_3c4d5e6f7a8b9c0d", "name": "Power on", "value": "*SCPOWR0000000000000001", "encoding": "ascii", "eol": "lf", "hexPreview": "2A 53 43 50 4F 57 52 30 30 30 30 30 30 30 30 30 30 30 30 30 30 30 31 0A" } ] } } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`name` is missing, `invalid_node` (the location is not in this workspace), or a command is not valid (no name, no value, too long, no bytes, a duplicate id, over 200 commands); `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/serial-templates/{id}": { "delete": { "operationId": "deleteSerialTemplate", "tags": [ "serial-templates" ], "summary": "Delete a serial command template", "description": "Delete an RS232 command template. Commands already queued using this template are unaffected, because they carry their own fully expanded bytes rather than a reference to the template.\n\n**Notes.**\n- Answers `{ data: { ok: true } }`, not the `{ id, deleted: true }` most other deletes return. There is no restore route.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Answers `{ data: { ok: true } }`, not the `{ id, deleted: true }` most other deletes return. There is no restore route." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serial template id.", "example": "sertpl_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such serial template in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] }, "get": { "operationId": "getSerialTemplate", "tags": [ "serial-templates" ], "summary": "Get a serial command template", "description": "Get one RS232 command template, including a preview of the exact bytes each command will send to the device.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serial template id.", "example": "sertpl_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SerialTemplate" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such serial template in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "patch": { "operationId": "updateSerialTemplate", "tags": [ "serial-templates" ], "summary": "Update a serial command template", "description": "Update an RS232 command template's name, model, organization node, or list of commands. Existing command IDs are preserved, so anything referencing a specific command continues to work.", "x-brix-permission": "screen.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Serial template id.", "example": "sertpl_2b3c4d5e6f7a8b9c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Required on create. Cut to 120 characters.", "type": "string" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeId": { "description": "Home location; null = workspace root.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "description": "The commands, at most 200. On update the list replaces the stored one.", "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Keep an existing command's id; omit to get a new one.", "type": "string" }, "name": { "type": "string" }, "value": { "type": "string", "description": "At most 512 characters, and it must give at least one byte." }, "encoding": { "description": "Default `ascii`. An unknown value is read as `ascii`.", "type": "string", "enum": [ "ascii", "hex" ] }, "eol": { "description": "Default `none`. An unknown value is read as `none`.", "type": "string", "enum": [ "none", "cr", "lf", "crlf" ] } }, "required": [ "name", "value" ] } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SerialTemplate" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "No `screen.edit` at the destination location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such serial template in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An empty `name`, `invalid_node` (the destination is not in this workspace), or a command is not valid; `message` names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.edit" ] } ] } }, "/v1/shared-with-me": { "get": { "operationId": "getSharedWithMe", "tags": [ "shared-with-me" ], "summary": "List airtime shared with me", "description": "List airtime slices that other teams have reserved and made available for the caller's team to fill.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shared-with-me/{allocationId}/fill": { "post": { "operationId": "createSharedWithMeFill", "tags": [ "shared-with-me" ], "summary": "Fill a shared airtime slice", "description": "Create a new playlist and attach it as the fill for an airtime slice reserved for the caller's team.", "x-brix-schema": "none", "parameters": [ { "name": "allocationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for allocationId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "replaceSharedWithMeFill", "tags": [ "shared-with-me" ], "summary": "Set a shared airtime slice's fill", "description": "Attach an existing playlist as the fill for an airtime slice reserved for the caller's team. Send `playlistId` as `null` to remove it.", "x-brix-schema": "none", "parameters": [ { "name": "allocationId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for allocationId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shares/{kind}/{id}": { "get": { "operationId": "getShare", "tags": [ "shares" ], "summary": "Get a content item's shares", "description": "List the share entries for one content item, showing which nodes, users, and roles it is shared with, and at what level. Requires view, edit, or share permission on the item at its home node.", "x-brix-schema": "none", "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for kind." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "replaceShare", "tags": [ "shares" ], "summary": "Replace a content item's shares", "description": "Replace the entire share set for one content item. Each entry targets exactly one of a node, a user, or a role. Requires the item's own share permission at its home node.", "x-brix-schema": "none", "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for kind." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/shares/directory": { "get": { "operationId": "getShareDirectory", "tags": [ "shares" ], "summary": "List shareable people and roles", "description": "List the people and roles a share can target, including id, display name, and, for roles, colour and member count. Available to anyone holding a share permission on any content, rather than requiring full user directory access. People are listed only from the caller's own workspace: a franchise child workspace sees its own people, never the parent's or another child workspace's. Email is returned only for people the caller can see with the user view permission; otherwise it is null. A role's member count counts only the listed people.", "x-brix-permission": "user.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.view" ] } ] } }, "/v1/signage-master-templates": { "get": { "operationId": "listSignageMasterTemplates", "tags": [ "signage-master-templates" ], "summary": "List master signage templates", "description": "Return the published catalog of signage templates curated by Brix. This catalog is shared across all workspaces rather than scoped to one, and is the only source of the masterId values required when creating a signage template. Drafts and deleted entries are not included.\n\n**Notes.**\n- Not paginated: the whole published catalog comes back, sorted by `sortOrder` then name.", "x-brix-permission": "creative.view", "x-brix-schema": "verified", "x-brix-notes": [ "Not paginated: the whole published catalog comes back, sorted by `sortOrder` then name." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignageMasterTemplate" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.view" ] } ] } }, "/v1/signage-templates": { "get": { "operationId": "listSignageTemplates", "tags": [ "signage-templates" ], "summary": "List signage templates", "description": "Return the signage template instances in this workspace.", "x-brix-permission": "creative.view", "x-brix-schema": "verified", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Page size. Omit to get every row; pass it to page by `cursor`." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "With `limit`: also return `total`, the number of matching rows." }, { "name": "usableAt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Location id: only rows usable at that location (homed there, at the workspace root, or shared to it)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SignageTemplate" } }, "nextCursor": { "description": "Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "total": { "description": "Total matching rows, when the route computes it.", "type": "integer" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.view" ] } ] }, "post": { "operationId": "createSignageTemplate", "tags": [ "signage-templates" ], "summary": "Create a signage template", "description": "Create a signage template instance from a configuration object containing archetype, style, palette, orientation, and content.\n\n**Notes.**\n- The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column.", "x-brix-permission": "creative.create", "x-brix-schema": "verified", "x-brix-notes": [ "The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example `lastSnapshotAt`) are absent rather than null. `GET` returns every column." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "config": { "description": "A configuration object, or the same as a JSON string. Default `{}`.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write." }, { "type": "string" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "masterId": { "description": "An id from `GET /v1/signage-master-templates`.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Signage template id.", "examples": [ "sig_8b9c0d1e2f3a4b5c" ] }, "spaceId": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write." }, "nodeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "masterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "deletedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Always null on these reads: deleted rows are not listed." } }, "required": [ "id", "spaceId", "name", "config", "createdAt", "updatedAt", "deletedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing name, invalid JSON, or a location outside this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.create" ] } ] } }, "/v1/signage-templates/{id}": { "delete": { "operationId": "deleteSignageTemplate", "tags": [ "signage-templates" ], "summary": "Delete a signage template", "description": "Move a signage template instance to the recycle bin.", "x-brix-permission": "creative.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signage template id.", "example": "sig_8b9c0d1e2f3a4b5c" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Delete even when it is shared into other places; the shares go with it." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true }, "sharesRemoved": { "type": "integer", "description": "Shares removed with it." } }, "required": [ "id", "deleted", "sharesRemoved" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such signage template in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.delete" ] } ] }, "get": { "operationId": "getSignageTemplate", "tags": [ "signage-templates" ], "summary": "Get a signage template", "description": "Return one signage template instance.", "x-brix-permission": "creative.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signage template id.", "example": "sig_8b9c0d1e2f3a4b5c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SignageTemplate" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such signage template in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.view" ] } ] }, "patch": { "operationId": "updateSignageTemplate", "tags": [ "signage-templates" ], "summary": "Update a signage template", "description": "Edit a signage template instance's configuration or name. Screens currently playing it receive an updated manifest reflecting the change.\n\n**Notes.**\n- When the PATCH does not send `config`, the response carries the stored config as it is: an old row is not brought to the current `schemaVersion` here (GET does that).", "x-brix-permission": "creative.edit", "x-brix-schema": "verified", "x-brix-notes": [ "When the PATCH does not send `config`, the response carries the stored config as it is: an old row is not brought to the current `schemaVersion` here (GET does that)." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signage template id.", "example": "sig_8b9c0d1e2f3a4b5c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "config": { "description": "A configuration object, or the same as a JSON string. Default `{}`.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The template configuration: `archetype`, `style`, `palette`, `orientation`, `content`, and the `schemaVersion` the API stamps on every write." }, { "type": "string" } ] }, "nodeId": { "description": "Home location. Default: the caller's own location.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "masterId": { "description": "An id from `GET /v1/signage-master-templates`.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "baseUpdatedAt": { "description": "Optimistic concurrency: the `updatedAt` you read. A stale value is refused with 409 `conflict` and the `current` row.", "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SignageTemplate" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Moving it to a location where you lack creative.edit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such signage template in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`conflict`: the row changed since `baseUpdatedAt`; the body carries `current`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.edit" ] } ] } }, "/v1/signage-templates/{id}/restore": { "post": { "operationId": "restoreSignageTemplate", "tags": [ "signage-templates" ], "summary": "Restore a signage template", "description": "Bring back a deleted signage template instance from the recycle bin.", "x-brix-permission": "creative.delete", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Signage template id.", "example": "sig_8b9c0d1e2f3a4b5c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "restored": { "type": "boolean", "const": true } }, "required": [ "id", "restored" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such signage template in this workspace, or it was purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deleted`: it is not in the recycle bin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "creative.delete" ] } ] } }, "/v1/social-accounts": { "get": { "operationId": "listSocialAccounts", "tags": [ "social-accounts" ], "summary": "List connected social accounts", "description": "List the social accounts connected to your workspace. Use the provider query parameter, for example provider=youtube, to filter by provider. Each result includes the display name and connection status for the account, but never the stored credentials.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "post": { "operationId": "createSocialAccount", "tags": [ "social-accounts" ], "summary": "Connect a social account", "description": "Create a social account connection by submitting its credentials directly. Credentials are encrypted before they are stored. For most providers, use the provider's OAuth start endpoint instead, since it handles sign-in and consent on your behalf.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/social-accounts/{id}": { "delete": { "operationId": "deleteSocialAccount", "tags": [ "social-accounts" ], "summary": "Disconnect a social account", "description": "Delete a connected social account by its ID. This permanently removes the stored credentials and stops any apps that use the account from fetching new data.", "x-brix-permission": "integration.delete", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.delete" ] } ] }, "patch": { "operationId": "updateSocialAccount", "tags": [ "social-accounts" ], "summary": "Rename or move a social account", "description": "Update a connected social account by its ID. You can change its display name or move it to a different location in your organization.", "x-brix-permission": "integration.edit", "x-brix-schema": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for id." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/social-accounts/preview-token": { "get": { "operationId": "getSocialAccountPreviewToken", "tags": [ "social-accounts" ], "summary": "Get a preview token for social apps", "description": "Get a short-lived token used to preview a live social app before it is published to a screen. Pass this token as the dt query parameter when calling social feed endpoints from a preview. The token is issued only for your own workspace and cannot be requested for another one.", "x-brix-permission": "integration.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] } }, "/v1/social/bluesky/feed": { "get": { "operationId": "getSocialBlueskyFeed", "tags": [ "social" ], "summary": "Get a Bluesky account's public feed", "description": "Get the recent public posts from a Bluesky account. Pass the account handle in the handle query parameter. No API key or connected account is required, because the feed is public. If Bluesky cannot be reached, the last successful result is served instead.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/clover/connect": { "post": { "operationId": "connectSocialClover", "tags": [ "social" ], "summary": "Finish connecting a Clover account", "description": "Complete a Clover connection using the state returned from the OAuth consent flow. The connected merchant is saved, and its access tokens are encrypted before storage.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/clover/start": { "get": { "operationId": "startSocialClover", "tags": [ "social" ], "summary": "Start connecting a Clover account", "description": "Start the OAuth flow for connecting a Clover merchant for a Menu Board. The response gives a consent URL to open in a browser. This endpoint returns an error if Clover integration has not yet been configured for your environment.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/google-business/{accountId}/reviews": { "get": { "operationId": "listSocialGoogleBusinessReviews", "tags": [ "social" ], "summary": "List reviews for a Google Business location", "description": "Get recent customer reviews for a connected Google Business location, identified by accountId. Requests are limited to a reasonable rate. The connected credential is never included in the response.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/google-business/connect": { "post": { "operationId": "connectSocialGoogleBusiness", "tags": [ "social" ], "summary": "Finish connecting a Google Business location", "description": "Complete a Google Business connection. Submit either the state, accountId, and locationId returned from the OAuth consent flow, or a placeId chosen using the search endpoint.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/social/google-business/search": { "get": { "operationId": "getSocialGoogleBusinessSearch", "tags": [ "social" ], "summary": "Search for a Google Business location", "description": "Search for a business by name and town so it can be connected as a Google Business location. This is an alternative way to pick a location when direct account access is not yet available. Each result includes a place ID, name, and address; use the place ID to complete the connection.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/social/google-business/start": { "get": { "operationId": "startSocialGoogleBusiness", "tags": [ "social" ], "summary": "Start connecting a Google Business account", "description": "Start the process of connecting a Google Business location. The response either gives a consent URL to open in a browser, or indicates that you should use the search endpoint to find and pick the location instead.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/social/google-calendar/{accountId}/events": { "get": { "operationId": "listSocialGoogleCalendarEvents", "tags": [ "social" ], "summary": "Get a room board for a Google calendar", "description": "Get a meeting-room summary for a connected Google calendar: the current and next events, free time until the next booking, current busy status, and the day's agenda. Access requires a dt token, issued by the preview-token endpoint or provided automatically to a screen. If the stored access is no longer valid, it is refreshed automatically, and the last known result is served if the calendar cannot be reached.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/google-calendar/connect": { "post": { "operationId": "connectSocialGoogleCalendar", "tags": [ "social" ], "summary": "Finish connecting a Google calendar", "description": "Complete a Google Calendar connection using the state returned from the OAuth consent flow. The chosen calendar or room is saved as a connected account, and its access tokens are encrypted before storage.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/google-calendar/start": { "get": { "operationId": "startSocialGoogleCalendar", "tags": [ "social" ], "summary": "Start connecting a Google calendar", "description": "Start the OAuth flow for connecting a Google calendar. The response gives a consent URL to open in a browser, requesting read-only calendar access. This endpoint returns an error if Google Calendar integration has not yet been configured for your environment.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/google-sheets/{accountId}/picker": { "get": { "operationId": "getSocialGoogleSheetPicker", "tags": [ "social" ], "summary": "Get spreadsheet picker credentials", "description": "Get the access token and configuration needed to open the Google spreadsheet picker for a connected account. This endpoint does not accept a preview or player token, so a screen cannot call it. It never returns a long-lived refresh token. It returns an error if picker access is not configured, or if the connection needs to be reconnected because access was revoked.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/google-sheets/{accountId}/values": { "get": { "operationId": "listSocialGoogleSheetValues", "tags": [ "social" ], "summary": "Read values from a Google spreadsheet", "description": "Read cell values from a range in a connected Google spreadsheet. Pass the spreadsheetId and range query parameters to select the data. Access requires a dt token, issued by the preview-token endpoint or provided automatically to a screen. If the stored access is no longer valid, it is refreshed automatically, and the last known result is served if the spreadsheet cannot be reached.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/google-sheets/connect": { "post": { "operationId": "connectSocialGoogleSheet", "tags": [ "social" ], "summary": "Finish connecting a Google spreadsheet", "description": "Complete a Google Sheets connection using the state returned from the OAuth consent flow. The connected account is saved, and its access tokens are encrypted before storage.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/google-sheets/start": { "get": { "operationId": "startSocialGoogleSheet", "tags": [ "social" ], "summary": "Start connecting a Google spreadsheet", "description": "Start the OAuth flow for connecting a private Google spreadsheet. The response gives a consent URL to open in a browser, requesting read-only access to spreadsheets. This endpoint returns an error if Google Sheets integration has not yet been configured for your environment.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/mastodon/feed": { "get": { "operationId": "getSocialMastodonFeed", "tags": [ "social" ], "summary": "Get a Mastodon account's public posts", "description": "Get the recent public posts from a Mastodon account. Pass the instance and user query parameters to identify the account. No API key or connected account is required, because the posts are public. HTML formatting in the post text is removed before the response is returned.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/meta/connect": { "post": { "operationId": "connectSocialMeta", "tags": [ "social" ], "summary": "Finish connecting a Meta account", "description": "Complete a Meta connection by choosing which Facebook Page or Instagram account the connection applies to.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/social/meta/ig/{accountId}/posts": { "get": { "operationId": "listSocialMetaIgPosts", "tags": [ "social" ], "summary": "List posts from a connected Instagram account", "description": "Get recent posts from a connected Instagram account, identified by accountId. Requests are limited to a reasonable rate and do not require a signed-in session.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/meta/ig/{accountId}/stories": { "get": { "operationId": "listSocialMetaIgStories", "tags": [ "social" ], "summary": "List active Instagram stories", "description": "Get the stories currently live on a connected Instagram Business account. Stories last 24 hours, so results reflect only what is active now. Access requires a dt token, issued by the preview-token endpoint or provided automatically to a screen; an invalid or missing token returns a not-found error. Because stories are short-lived, no previous result is served if the account cannot be reached.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/meta/page/{accountId}/posts": { "get": { "operationId": "listSocialMetaPagePosts", "tags": [ "social" ], "summary": "List posts from a connected Facebook Page", "description": "Get recent posts from a connected Facebook Page, identified by accountId. This endpoint does not require a signed-in session and is rate-limited per workspace. The connected access token is never included in the response.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/meta/start": { "get": { "operationId": "startSocialMeta", "tags": [ "social" ], "summary": "Start connecting a Meta account", "description": "Start the process of connecting a Facebook or Instagram account. The response is a JSON object with a url field containing the consent link to open in a browser; it does not redirect automatically.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/social/microsoft-calendar/{accountId}/events": { "get": { "operationId": "listSocialMicrosoftCalendarEvents", "tags": [ "social" ], "summary": "Get a room board for a Microsoft calendar", "description": "Get a meeting-room summary for a connected Microsoft 365 calendar: the current and next events, free time until the next booking, current busy status, and the day's agenda. Access requires a dt token, issued by the preview-token endpoint or provided automatically to a screen. If the stored access is no longer valid, it is refreshed automatically, and the last known result is served if the calendar cannot be reached. The response has the same shape as the Google calendar room board.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/microsoft-calendar/connect": { "post": { "operationId": "connectSocialMicrosoftCalendar", "tags": [ "social" ], "summary": "Finish connecting a Microsoft calendar", "description": "Complete a Microsoft 365 calendar connection using the state returned from the OAuth consent flow. The chosen calendar or room is saved as a connected account, and its access tokens are encrypted before storage.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/microsoft-calendar/start": { "get": { "operationId": "startSocialMicrosoftCalendar", "tags": [ "social" ], "summary": "Start connecting a Microsoft calendar", "description": "Start the OAuth flow for connecting a Microsoft 365 calendar. The response gives a consent URL to open in a browser, requesting read-only calendar access. This endpoint returns an error if Microsoft 365 integration has not yet been configured for your environment.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/microsoft-files/browse": { "get": { "operationId": "getSocialMicrosoftFileBrowse", "tags": [ "social" ], "summary": "Browse Microsoft 365 drives and files", "description": "Browse a connected Microsoft 365 account's files while setting up a connection. Call without a driveId to list the available drives, including OneDrive and SharePoint libraries. Call with driveId and itemId to list one level of folders and files inside a drive. The connection must belong to your own workspace, or the request returns a not-found error.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/microsoft-files/connect": { "post": { "operationId": "connectSocialMicrosoftFile", "tags": [ "social" ], "summary": "Finish connecting Microsoft 365 files", "description": "Complete a Microsoft 365 files connection. Only one connection is allowed per account per workspace. Completing this creates a dedicated folder for the synced files and starts the first synchronization.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/microsoft-files/start": { "get": { "operationId": "startSocialMicrosoftFile", "tags": [ "social" ], "summary": "Start connecting Microsoft 365 files", "description": "Start the OAuth flow for connecting Microsoft 365 files. The response gives a consent URL to open in a browser, requesting read access to the account's OneDrive and SharePoint files. This endpoint returns an error if Microsoft 365 integration has not yet been configured for your environment.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/pending/{state}": { "get": { "operationId": "getSocialPending", "tags": [ "social" ], "summary": "Get pending choices for a Google connect", "description": "Get the remaining choices needed to finish connecting a Google account, identified by the state value from the OAuth callback. The response includes a heading, a description, and a list of options, such as calendars or business locations, each with the exact request body to submit to the matching connect endpoint. An invalid, expired, or already-used state always returns the same not-found response, so a state value cannot be guessed or tested. The response never includes access tokens.", "x-brix-schema": "none", "parameters": [ { "name": "state", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for state." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/square/connect": { "post": { "operationId": "connectSocialSquare", "tags": [ "social" ], "summary": "Finish connecting a Square account", "description": "Complete a Square connection using the state returned from the OAuth consent flow, optionally for one location. The connected account is saved, and its access tokens are encrypted before storage.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/square/start": { "get": { "operationId": "startSocialSquare", "tags": [ "social" ], "summary": "Start connecting a Square account", "description": "Start the OAuth flow for connecting a Square account for a Menu Board. The response gives a consent URL to open in a browser, requesting read-only access to the catalog, inventory and locations. This endpoint returns an error if Square integration has not yet been configured for your environment.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/tiktok/{accountId}/videos": { "get": { "operationId": "listSocialTiktokVideos", "tags": [ "social" ], "summary": "List videos from a connected TikTok account", "description": "Get recent videos from a connected TikTok account, identified by accountId. Requests are limited to a reasonable rate and do not require a signed-in session, so a screen can call this endpoint directly.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/tiktok/start": { "get": { "operationId": "startSocialTiktok", "tags": [ "social" ], "summary": "Start connecting a TikTok account", "description": "Start the process of connecting a TikTok account. The response is a JSON object with a url field containing the consent link to open in a browser; it does not redirect automatically.", "x-brix-permission": "integration.create", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.create" ] } ] } }, "/v1/social/viva/{accountId}/feed": { "get": { "operationId": "getSocialVivaFeed", "tags": [ "social" ], "summary": "Get a Viva Engage community feed", "description": "Get recent messages from a connected Viva Engage community. Pass the community query parameter to select which community to read. Access requires a dt token, issued by the preview-token endpoint or provided automatically to a screen. If the stored access is no longer valid, it is refreshed automatically, and the last known result is served if the community cannot be reached.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/viva/start": { "get": { "operationId": "startSocialViva", "tags": [ "social" ], "summary": "Start connecting a Viva Engage account", "description": "Start the OAuth flow for connecting a Viva Engage account. The response gives a consent URL to open in a browser. This endpoint returns an error if Viva Engage integration has not yet been configured for your environment.", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/x/{accountId}/tweets": { "get": { "operationId": "listSocialXTweets", "tags": [ "social" ], "summary": "List recent posts from a connected X account", "description": "Get recent posts from a connected X account, identified by accountId, using your own connected access token. Access requires a dt token, issued by the preview-token endpoint or provided automatically to a screen. If X is rate-limited or unavailable, the last known result is served instead.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/youtube/{accountId}/latest": { "get": { "operationId": "getSocialYoutubeLatest", "tags": [ "social" ], "summary": "List latest videos from a connected channel", "description": "Get the latest videos from a connected YouTube channel, identified by accountId. Requests are limited to a reasonable rate and do not require a signed-in session, so a screen can call this endpoint directly.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/youtube/{accountId}/live": { "get": { "operationId": "getSocialYoutubeLive", "tags": [ "social" ], "summary": "Check if a YouTube channel is live", "description": "Check whether a connected YouTube channel is currently live streaming, identified by accountId. The response includes the current viewer count when the channel is live.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/youtube/{accountId}/stats": { "get": { "operationId": "listSocialYoutubeStats", "tags": [ "social" ], "summary": "Get subscriber and view counts", "description": "Get the subscriber count and total view count for a connected YouTube channel, identified by accountId. This is intended for counter and milestone displays.", "x-brix-schema": "none", "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for accountId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/social/youtube/by-channel/{channelId}/latest": { "get": { "operationId": "getSocialYoutubeByChannelLatest", "tags": [ "social" ], "summary": "Get the latest video from any public channel", "description": "Get the newest upload from any public YouTube channel, identified by channelId, whose title matches the match query parameter. The response includes a ready-to-use embed URL. No connected account or API key is required, because this reads only publicly available data.", "x-brix-schema": "none", "parameters": [ { "name": "channelId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for channelId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sso-connections": { "get": { "operationId": "listSsoConnections", "tags": [ "sso-connections" ], "summary": "List SSO connections", "description": "Returns the workspace's enterprise single sign-on connections, with client secrets masked. The key or person must have `settings.view` for the whole workspace. A caller limited to a location or to a franchise workspace gets 403. `lastClaims` holds the claims from the last sign-in: a person's email, name and groups. It is `null` unless the caller also has `user.view` for the whole workspace.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SsoConnection" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] }, "post": { "operationId": "createSsoConnection", "tags": [ "sso-connections" ], "summary": "Create SSO connection", "description": "Creates an enterprise single sign-on connection. The client secret is encrypted before it is stored.\n\n**Notes.**\n- A new connection is unverified: prove its domains (`domain-challenge`, then `verify-domains`) before it is offered at sign-in.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "x-brix-notes": [ "A new connection is unverified: prove its domains (`domain-challenge`, then `verify-domains`) before it is offered at sign-in." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "vendor": { "description": "Free text, e.g. `okta`, `entra`.", "type": "string" }, "issuer": { "type": "string", "description": "Must start with `https://`. A trailing slash is removed." }, "clientId": { "type": "string" }, "clientSecret": { "type": "string", "description": "Encrypted before it is stored; never returned." }, "emailDomains": { "type": "string", "description": "Comma-separated email domains, e.g. `acme.com,acme.org`." }, "jitProvisioning": { "description": "Default true.", "type": "boolean" }, "enabled": { "description": "Default true.", "type": "boolean" }, "defaultRoleId": { "description": "You must be able to grant this role for the whole workspace.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "claimMapping": { "description": "You must be able to grant each rule's role where the rule grants it. Null clears it.", "anyOf": [ { "$ref": "#/components/schemas/SsoClaimMapping" }, { "type": "null" } ] }, "extraScopes": { "description": "Space- or comma-separated scope tokens (at most 20). Null or empty clears them.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "displayName", "issuer", "clientId", "clientSecret", "emailDomains" ] }, "example": { "displayName": "Acme Okta", "issuer": "https://acme.okta.com", "clientId": "0oa1b2c3d4", "clientSecret": "example-client-secret", "emailDomains": "acme.com" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SsoConnection" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Also: `defaultRoleId` or a rule's role holds permissions you cannot grant there.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection, role or location in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A required field is missing, `issuer` is not `https://`, an invalid `claimMapping`, or `extraScopes` is not a valid scope list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/sso-connections/{id}": { "delete": { "operationId": "deleteSsoConnection", "tags": [ "sso-connections" ], "summary": "Delete SSO connection", "description": "Soft-deletes an enterprise single sign-on connection.\n\n**Notes.**\n- Answers `{ ok: true }`, not the `{ id, deleted }` shape of other deletes. The connection is also disabled.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Answers `{ ok: true }`, not the `{ id, deleted }` shape of other deletes. The connection is also disabled." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SSO connection id.", "example": "sso_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] }, "patch": { "operationId": "updateSsoConnection", "tags": [ "sso-connections" ], "summary": "Update SSO connection", "description": "Updates an enterprise single sign-on connection. `clientSecret` is optional: when provided, it replaces the stored secret; when omitted, the existing secret is left unchanged.\n\n**Notes.**\n- Changing `emailDomains` clears `domainsVerifiedAt`. Changing `issuer`, `clientId`, `clientSecret` or `emailDomains` clears `provenAt`.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Changing `emailDomains` clears `domainsVerifiedAt`. Changing `issuer`, `clientId`, `clientSecret` or `emailDomains` clears `provenAt`." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SSO connection id.", "example": "sso_2b3c4d5e6f7a8b9c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string" }, "vendor": { "description": "Free text, e.g. `okta`, `entra`.", "type": "string" }, "issuer": { "type": "string", "description": "Must start with `https://`. A trailing slash is removed." }, "clientId": { "type": "string" }, "clientSecret": { "description": "Replaces the stored secret. Omitted or empty keeps it.", "type": "string" }, "emailDomains": { "type": "string", "description": "Comma-separated email domains, e.g. `acme.com,acme.org`." }, "jitProvisioning": { "description": "Default true.", "type": "boolean" }, "enabled": { "description": "Default true.", "type": "boolean" }, "defaultRoleId": { "description": "You must be able to grant this role for the whole workspace.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "claimMapping": { "description": "You must be able to grant each rule's role where the rule grants it. Null clears it.", "anyOf": [ { "$ref": "#/components/schemas/SsoClaimMapping" }, { "type": "null" } ] }, "extraScopes": { "description": "Space- or comma-separated scope tokens (at most 20). Null or empty clears them.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SsoConnection" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Also: `defaultRoleId` or a rule's role holds permissions you cannot grant there.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection, role or location in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A required field is missing, `issuer` is not `https://`, an invalid `claimMapping`, or `extraScopes` is not a valid scope list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/sso-connections/{id}/domain-challenge": { "get": { "operationId": "getSsoConnectionDomainChallenge", "tags": [ "sso-connections" ], "summary": "Get domain verification challenge", "description": "Returns the DNS TXT records you must publish to prove control of the email domains used by this SSO connection. The key or person must have `settings.view` for the whole workspace.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SSO connection id.", "example": "sso_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "name": { "type": "string", "description": "The record name: `_brix-verify.<domain>`." }, "type": { "type": "string", "const": "TXT" }, "value": { "type": "string", "description": "The record value to publish: `brix-domain-verify=<token>`." } }, "required": [ "domain", "name", "type", "value" ] } }, "verifiedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "records", "verifiedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] } }, "/v1/sso-connections/{id}/scim": { "get": { "operationId": "getSsoConnectionScim", "tags": [ "sso-connections" ], "summary": "Get SCIM configuration", "description": "Returns the SCIM base URL for this SSO connection and a preview of its currently live provisioning tokens. Token secrets themselves are never returned.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SSO connection id.", "example": "sso_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "baseUrl": { "type": "string", "description": "The SCIM 2.0 base URL to give the identity provider." }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "preview": { "type": "string", "description": "`••••` and the last four characters." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "lastUsedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "id", "preview", "createdAt", "lastUsedAt" ] }, "description": "Live tokens only." } }, "required": [ "baseUrl", "tokens" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] } }, "/v1/sso-connections/{id}/scim/tokens": { "post": { "operationId": "createSsoConnectionScimToken", "tags": [ "sso-connections" ], "summary": "Create SCIM token", "description": "Creates a new SCIM provisioning token for this SSO connection. The token value is shown exactly once, in this response. A connection can have at most 5 live tokens at a time. This action cannot be taken while impersonating another user.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SSO connection id.", "example": "sso_2b3c4d5e6f7a8b9c" } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string", "description": "The SCIM bearer token. Shown only here; store it now." }, "baseUrl": { "type": "string" } }, "required": [ "id", "token", "baseUrl" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`too_many_tokens`: the connection already has 5 live tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/sso-connections/{id}/scim/tokens/{tokenId}": { "delete": { "operationId": "deleteSsoConnectionScimToken", "tags": [ "sso-connections" ], "summary": "Revoke SCIM token", "description": "Revokes one SCIM provisioning token belonging to this SSO connection.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SSO connection id.", "example": "sso_2b3c4d5e6f7a8b9c" }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SCIM token id.", "example": "scimt_4d5e6f7a8b9c0d1e" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection, or no live token with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/sso-connections/{id}/test-mapping": { "post": { "operationId": "createSsoConnectionTestMapping", "tags": [ "sso-connections" ], "summary": "Test SSO claim mapping", "description": "Previews the role and location a person would be granted, given a set of example identity-provider claims, by running the same mapping logic used at sign-in. This is read-only and does not sign anyone in or change anything.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SSO connection id.", "example": "sso_2b3c4d5e6f7a8b9c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "claims": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Example identity-provider claims." }, "claimMapping": { "description": "An unsaved mapping to test; omitted = the saved one.", "anyOf": [ { "$ref": "#/components/schemas/SsoClaimMapping" }, { "type": "null" } ] } }, "required": [ "claims" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "mapped": { "type": "boolean", "description": "False when there is no mapping: `grants` is then the default role at the root, without names." }, "grants": { "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "description": "Location id (the workspace id for the root)." }, "roleId": { "type": "string" }, "roleName": { "description": "Absent when `mapped` is false.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nodeName": { "description": "Absent when `mapped` is false.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nodeId", "roleId" ] } }, "matchedRules": { "type": "array", "items": { "type": "integer" }, "description": "Indexes of the rules that matched." }, "unmatchedLocations": { "type": "array", "items": { "type": "string" }, "description": "Location values that matched no location." }, "ambiguousLocations": { "type": "array", "items": { "type": "string" }, "description": "Location values that matched more than one location." }, "usedDefault": { "type": "boolean" }, "denied": { "type": "boolean", "description": "True when the sign-in would be refused (`noMatch: deny`)." } }, "required": [ "mapped", "grants", "matchedRules", "unmatchedLocations", "ambiguousLocations", "usedDefault", "denied" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`claims` is not an object, or `claimMapping` is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] } }, "/v1/sso-connections/{id}/verify-domains": { "post": { "operationId": "createSsoConnectionVerifyDomain", "tags": [ "sso-connections" ], "summary": "Verify SSO domains", "description": "Verifies an SSO connection's email domains using a DNS TXT record lookup. Verified domains control whether the connection is offered at sign-in and whether cross-workspace sign-in is allowed for that domain.\n\n**Notes.**\n- Answers 200 with `verified: false` when a domain fails; the connection stays unverified.", "x-brix-permission": "settings.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Answers 200 with `verified: false` when a domain fails; the connection stays unverified." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "SSO connection id.", "example": "sso_2b3c4d5e6f7a8b9c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "True only when every domain proved out." }, "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "ok": { "type": "boolean" }, "reason": { "description": "Why a domain failed: `claimed_by_another_workspace`, `dns_<status>`, or a lookup error. Absent when the lookup answered.", "type": "string" } }, "required": [ "domain", "ok" ] } }, "verifiedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] } }, "required": [ "verified", "results", "verifiedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such connection in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`no_domains`: the connection has no email domains.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.edit" ] } ] } }, "/v1/sso-connections/test": { "post": { "operationId": "testSsoConnection", "tags": [ "sso-connections" ], "summary": "Test SSO discovery", "description": "Fetches the identity provider's OpenID Connect discovery document and returns its parsed authorization, token, and key endpoints, so the connection can be confirmed as reachable before the setup form is submitted.\n\n**Notes.**\n- Needs `settings.view` held anywhere, unlike the other SSO routes, which need it for the whole workspace.", "x-brix-permission": "settings.view", "x-brix-schema": "verified", "x-brix-notes": [ "Needs `settings.view` held anywhere, unlike the other SSO routes, which need it for the whole workspace." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string", "description": "Must start with `https://`." } }, "required": [ "issuer" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "issuer": { "description": "The issuer the discovery document names; absent when it names none.", "type": "string" }, "authorizationEndpoint": { "type": "string" }, "tokenEndpoint": { "type": "string" }, "jwksUri": { "type": "string" } }, "required": [ "ok", "authorizationEndpoint", "tokenEndpoint", "jwksUri" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`issuer` is not `https://`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "`discovery_failed` (the provider answered an error), `discovery_incomplete` (an endpoint is missing), or `discovery_threw` (not reachable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "settings.view" ] } ] } }, "/v1/status": { "get": { "operationId": "getStatus", "tags": [ "status" ], "summary": "Get platform status", "description": "Get the current platform status, including overall state, 30-day latency attainment, open and recent published incidents, and a 90-day history strip. This endpoint requires no authentication. If the underlying status data is more than three hours old, the state is reported as `unknown` rather than `operational`. Pass `format=text` for a plain-text response.\n\n**Notes.**\n- Answers 200 during an outage too: the state is in the body.\n- With `format=text` the body is `text/plain`.", "x-brix-schema": "verified", "x-brix-notes": [ "Answers 200 during an outage too: the state is in the body.", "With `format=text` the body is `text/plain`." ], "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "text" ] }, "description": "`text` answers a plain-text summary instead of JSON." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "operational", "degraded", "outage", "unknown" ] }, "computedAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "When the status was measured; null when never." }, "stale": { "type": "boolean", "description": "True when the measurement is more than three hours old (the state is then `unknown`)." }, "latency": { "anyOf": [ { "type": "object", "properties": { "windowDays": { "type": "integer" }, "targetMs": { "type": "number" }, "targetShare": { "type": "number", "description": "The target share of requests under `targetMs`, 0–1." }, "share": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The measured share, 0–1; null when not measured." }, "met": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "windowDays", "targetMs", "targetShare", "share", "met" ] }, { "type": "null" } ] }, "incidents": { "type": "array", "items": { "$ref": "#/components/schemas/StatusIncident" }, "description": "Open incidents." }, "recent": { "type": "array", "items": { "$ref": "#/components/schemas/StatusIncident" }, "description": "Recently resolved incidents." }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "`YYYY-MM-DD`." }, "state": { "type": "string", "enum": [ "operational", "degraded", "outage" ] } }, "required": [ "date", "state" ] }, "description": "One entry per day, for the last 90 days." } }, "required": [ "state", "computedAt", "stale", "latency", "incidents", "recent", "days" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/status/deprecations": { "get": { "operationId": "listStatusDeprecations", "tags": [ "status" ], "summary": "List API deprecations", "description": "List every API route scheduled for retirement, when it stops working, and its replacement. This endpoint requires no authentication and is safe to poll from a script. An empty list means no routes are currently scheduled for retirement.", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "noticeDays": { "type": "integer", "description": "The minimum notice a retired route gets." }, "policy": { "type": "string" }, "deprecations": { "type": "array", "items": { "type": "object", "properties": { "route": { "type": "string", "description": "`METHOD /path`." }, "announced": { "type": "string", "description": "Date (`YYYY-MM-DD`) it was listed." }, "sunset": { "type": "string", "description": "Date (`YYYY-MM-DD`) it stops working." }, "replacement": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "why": { "type": "string" }, "noticeDays": { "type": "integer", "description": "Days between `announced` and `sunset`." } }, "required": [ "route", "announced", "sunset", "replacement", "why", "noticeDays" ] } } }, "required": [ "noticeDays", "policy", "deprecations" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/uptime": { "get": { "operationId": "getUptime", "tags": [ "uptime" ], "summary": "Get an uptime report", "description": "Get an uptime report for a date range, with online percentage per screen and per location, downtime windows, and mean time to recovery.", "x-brix-permission": "screen.view", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] } }, "/v1/users": { "get": { "operationId": "listUsers", "tags": [ "users" ], "summary": "List users", "description": "Returns the workspace roster: each person's role, which locations they can access, their sign-in method, two-factor authentication status, and last login.\n\n**Notes.**\n- Not paginated. Deleted (erased) people are not listed. A caller whose access is limited to some locations sees only the people with access there, and only those locations in `access`.", "x-brix-permission": "user.view", "x-brix-schema": "verified", "x-brix-notes": [ "Not paginated. Deleted (erased) people are not listed. A caller whose access is limited to some locations sees only the people with access there, and only those locations in `access`." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.view" ] } ] } }, "/v1/users/{id}": { "patch": { "operationId": "updateUser", "tags": [ "users" ], "summary": "Update user", "description": "Updates a person's profile. Supported fields are `name` and `trainingStep` (which resets a feature walkthrough for that person). Email address and account status cannot be changed through this operation. Requires access to every location the target person belongs to.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id.", "example": "user_3c4d5e6f7a8b9c0d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Trimmed; must not be empty.", "type": "string", "minLength": 1, "maxLength": 120 }, "trainingStep": { "description": "Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`); null resets it.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "invited", "deactivated" ] }, "trainingStep": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Walkthrough position; null when not started or reset." } }, "required": [ "id", "email", "name", "status", "trainingStep" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The person belongs to a location where you do not hold `user.edit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such person in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Nothing to update, an empty or over-long `name`, or an unknown `trainingStep`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/users/{id}/deactivate": { "post": { "operationId": "createUserDeactivate", "tags": [ "users" ], "summary": "Deactivate user", "description": "Deactivates a person's account. This revokes all of their active sessions, signing them out everywhere immediately and blocking further sign-in including through SSO, and removes them from every location's approver list. This action is reversible. You cannot deactivate your own account or the last remaining account owner. Only an account owner can do this to an owner, and you cannot do it to a person who holds a permission you do not hold. An API key is never an owner.\n\n**Notes.**\n- Only an owner can deactivate an owner, and nobody can deactivate a person who holds a permission they do not hold. An API key is never an owner, whatever its permissions.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Only an owner can deactivate an owner, and nobody can deactivate a person who holds a permission they do not hold. An API key is never an owner, whatever its permissions." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id.", "example": "user_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "const": "deactivated" }, "deactivatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." } }, "required": [ "id", "status", "deactivatedAt" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The person belongs to a location where you do not hold `user.edit`; `owner_required`: the person is an owner and you are not an owner there (an API key is never an owner); or `outranked`: the person holds a permission you do not hold where they hold it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such person in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cant_deactivate_self`, `already_deactivated`, or `last_owner` (the last owner of the workspace or of a location).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/users/{id}/erase": { "post": { "operationId": "createUserErase", "tags": [ "users" ], "summary": "Erase user under GDPR", "description": "Permanently erases a deactivated person's personal data to satisfy a right-to-be-forgotten request: it anonymizes their profile and hard-deletes their passkeys, linked identities, sessions, and location role assignments. The account must already be deactivated. You cannot erase your own account or the last remaining account owner. Only an account owner can do this to an owner, and you cannot do it to a person who holds a permission you do not hold. An API key is never an owner.\n\n**Notes.**\n- Irreversible. The same rule as deactivation applies: only an owner can erase an owner, and the caller must hold every permission the person holds.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Irreversible. The same rule as deactivation applies: only an owner can erase an owner, and the caller must hold every permission the person holds." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id.", "example": "user_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "erased": { "type": "boolean", "const": true } }, "required": [ "id", "erased" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The person belongs to a location where you do not hold `user.edit`; `owner_required`: the person is an owner and you are not an owner there (an API key is never an owner); or `outranked`: the person holds a permission you do not hold where they hold it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such person in this workspace (an erased person is not found again).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`cant_erase_self`, `last_owner`, or `must_deactivate_first`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/users/{id}/reactivate": { "post": { "operationId": "createUserReactivate", "tags": [ "users" ], "summary": "Reactivate user", "description": "Restores a deactivated person's account to active status. Their previous role assignments are restored along with the access they grant. Any approver-list entries removed at deactivation are not automatically restored. Only an account owner can do this to an owner, and you cannot do it to a person who holds a permission you do not hold. An API key is never an owner.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id.", "example": "user_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "const": "active" } }, "required": [ "id", "status" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The person belongs to a location where you do not hold `user.edit`; `owner_required`: the person is an owner and you are not an owner there (an API key is never an owner); or `outranked`: the person holds a permission you do not hold where they hold it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such person in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_deactivated`: the person is not deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/users/{id}/sessions": { "get": { "operationId": "listUserSessions", "tags": [ "users" ], "summary": "List user sessions", "description": "Returns a person's currently active sign-in sessions: id, creation time, last used time, expiry, device or browser, IP address, and which session belongs to the caller. Revoked and expired sessions are not included.\n\n**Notes.**\n- Needs `user.edit`, not `user.view`: the rows carry IP addresses. Sorted by last use, newest first.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Needs `user.edit`, not `user.view`: the rows carry IP addresses. Sorted by last use, newest first." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id.", "example": "user_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserSession" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The person belongs to a location where you do not hold `user.edit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such person in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/users/{id}/sessions/{sessionId}": { "delete": { "operationId": "deleteUserSession", "tags": [ "users" ], "summary": "Revoke user session", "description": "Signs one of a person's devices out by revoking that session. The session record itself is kept, not deleted. Calling this on an already-revoked session is safe and reports `revoked: false`.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id.", "example": "user_3c4d5e6f7a8b9c0d" }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Session id from the session list.", "example": "ses_9c0d1e2f3a4b5c6d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "type": "boolean", "description": "False when the session was already revoked." } }, "required": [ "id", "revoked" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The person belongs to a location where you do not hold `user.edit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such person, or no such session for this person.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/users/{id}/sessions/revoke-all": { "post": { "operationId": "createUserSessionRevokeAll", "tags": [ "users" ], "summary": "Revoke all user sessions", "description": "Signs a person out of every active session without deactivating their account, so they can still sign back in afterward. Returns the number of sessions that were revoked.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "User id.", "example": "user_3c4d5e6f7a8b9c0d" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "User id." }, "revoked": { "type": "integer", "description": "Sessions revoked." } }, "required": [ "id", "revoked" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The person belongs to a location where you do not hold `user.edit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such person in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/users/invite": { "post": { "operationId": "inviteUser", "tags": [ "users" ], "summary": "Invite user", "description": "Creates a new person in the workspace, or reuses an existing one, and assigns them a role at the chosen locations. A new person gets an email with a link to set their password. When a signed-in user sends the invite, the email goes out only when that user's own email address is verified. An invite made with an API key sends the email in the workspace's name. You cannot grant a role carrying permissions you do not hold yourself.\n\n**Notes.**\n- Answers 200 (not 201) for a new person too; `created` tells the two apart.\n- For a signed-in user, the set-password email is sent only when that user's own email address is verified. An invite made with an API key sends the email too, from the workspace (the key's name is not shown). The 30-a-minute limit counts per key for a key.", "x-brix-permission": "user.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Answers 200 (not 201) for a new person too; `created` tells the two apart.", "For a signed-in user, the set-password email is sent only when that user's own email address is verified. An invite made with an API key sends the email too, from the workspace (the key's name is not shown). The 30-a-minute limit counts per key for a key." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Stored in lower case." }, "name": { "description": "Used only when the person is new.", "type": "string" }, "roleId": { "type": "string" }, "nodeIds": { "minItems": 1, "type": "array", "items": { "type": "string" }, "description": "Locations to grant the role at. You need `user.edit` and every permission of the role at each one." } }, "required": [ "email", "roleId", "nodeIds" ] }, "example": { "email": "sam@example.com", "name": "Sam Rivera", "roleId": "role_5e6f7a8b9c0d1e2f", "nodeIds": [ "on_4d5e6f7a8b9c0d1e" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "invited", "deactivated" ] }, "created": { "type": "boolean", "description": "True when a new person was created; false when an existing person got the extra access." }, "emailSent": { "type": "boolean", "description": "A set-password email went out." }, "emailBlockedReason": { "anyOf": [ { "type": "string", "enum": [ "inviter-unverified", "provider-refused" ] }, { "type": "null" } ], "description": "Why no email went out for a new person: the calling user's own email address is not verified (never for an API key), or the mail provider refused it. Null when sent, or when the person already existed." } }, "required": [ "id", "email", "status", "created", "emailSent", "emailBlockedReason" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The role holds permissions you do not hold, or you lack `user.edit` or the role's permissions at one of the locations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such role or location in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid `email`, or `roleId` / `nodeIds` missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 30 invites a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "user.edit" ] } ] } }, "/v1/web-recorder/{sid}": { "get": { "operationId": "getWebRecorder", "tags": [ "web-recorder" ], "summary": "Get a web recording session", "description": "Return the steps recorded so far in an in-progress sign-in recording session.", "x-brix-permission": "media.edit", "x-brix-schema": "none", "parameters": [ { "name": "sid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for sid." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/web-recorder/{sid}/abort": { "post": { "operationId": "abortWebRecorder", "tags": [ "web-recorder" ], "summary": "Cancel a web recording session", "description": "Discard an in-progress sign-in recording session without changing the associated media asset.", "x-brix-permission": "media.edit", "x-brix-schema": "none", "parameters": [ { "name": "sid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for sid." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/web-recorder/{sid}/action": { "post": { "operationId": "createWebRecorderAction", "tags": [ "web-recorder" ], "summary": "Add an action to a web recording session", "description": "Append one recorded interaction, such as a click, typed text, or a wait, to an open sign-in recording session.", "x-brix-permission": "media.edit", "x-brix-schema": "none", "parameters": [ { "name": "sid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for sid." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/web-recorder/{sid}/finalize": { "post": { "operationId": "createWebRecorderFinalize", "tags": [ "web-recorder" ], "summary": "Finalize a web recording session", "description": "Save a completed recording to a web asset, using mediaId and optional secrets. The recorded steps are stored on the asset's web configuration, secrets are encrypted and referenced by name, and the session ends.", "x-brix-permission": "media.edit", "x-brix-schema": "none", "parameters": [ { "name": "sid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for sid." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/web-recorder/links/{mediaId}/verify": { "post": { "operationId": "verifyWebRecorderLink", "tags": [ "web-recorder" ], "summary": "Verify a web recording's sign-in", "description": "Run the finalized sign-in recording for a web asset and report whether the resulting session looks successfully logged in. This lets a caller confirm the recording works right after capturing it, rather than waiting until the content plays on a screen.", "x-brix-schema": "none", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Identifier for mediaId." } ], "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/web-recorder/start": { "post": { "operationId": "startWebRecorder", "tags": [ "web-recorder" ], "summary": "Start a web recording session", "description": "Begin a sign-in recording session for a web asset, given a url. Returns a session id, the url, and the steps recorded so far, which starts empty. Steps are then submitted using the Brix Recorder browser extension.", "x-brix-permission": "media.edit", "x-brix-schema": "none", "responses": { "2XX": { "description": "Success. Body is `{ data: … }` unless the endpoint serves bytes. The shape of `data` is not yet modelled for this operation." }, "4XX": { "description": "Client error. 404 rather than 403 for another tenant's resource, so account existence is not leaked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "media.edit" ] } ] } }, "/v1/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "webhooks" ], "summary": "List webhook endpoints", "description": "List the workspace's outbound webhook endpoints. The signing secret is never included in this response; it is shown only once, at creation.\n\n**Notes.**\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "integration.view", "x-brix-schema": "verified", "x-brix-notes": [ "Needs the permission at the workspace root: a location-scoped key is refused." ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] }, "post": { "operationId": "createWebhook", "tags": [ "webhooks" ], "summary": "Create a webhook endpoint", "description": "Create an endpoint. The response includes the signing secret once; after that, only a preview of it is available, since it is stored encrypted and cannot be retrieved in full. The endpoint URL is checked at creation and again before every delivery, since a hostname that resolved to a public address at save time could later be re-pointed at an internal address. Only `content.recalled` and `content.restored` events are actually sent today, even though the event catalog lists more.\n\nThe response carries the signing `secret` ONCE. Store it: later reads return only `secretPreview`.\n\n**Notes.**\n- Validation failures are 400 `bad_request`, where most other routes answer 422 `validation_error`.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Validation failures are 400 `bad_request`, where most other routes answer 422 `validation_error`." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "An https URL on the public internet (private and loopback hosts are refused)." }, "events": { "description": "Events to deliver. Default: none. An unknown name is refused.", "type": "array", "items": { "type": "string", "enum": [ "screen.offline", "screen.online", "content.recalled", "content.restored", "approval.requested", "approval.decided", "emergency.started", "emergency.cleared" ] } }, "description": { "description": "Label; cut to 200 characters.", "type": "string" } }, "required": [ "url" ] }, "example": { "url": "https://hooks.example.com/brix", "events": [ "screen.offline", "screen.online" ], "description": "Ops alerts" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint id.", "examples": [ "whe_7a8b9c0d1e2f3a4b" ] }, "url": { "type": "string", "description": "Where deliveries are POSTed." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secretPreview": { "type": "string", "description": "First 8 characters of the signing secret." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event names (see `GET /v1/webhooks/events`)." }, "enabled": { "type": "boolean" }, "autoDisabledAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ], "description": "Set when repeated failures switched the endpoint off." }, "autoDisabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "consecutiveFailures": { "type": "integer" }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status of the last delivery attempt." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp (UTC)." }, "secret": { "type": "string", "description": "The HMAC signing secret (64 hex characters). Shown only in this response." } }, "required": [ "id", "url", "description", "secretPreview", "events", "enabled", "autoDisabledAt", "autoDisabledReason", "consecutiveFailures", "lastDeliveryAt", "lastStatus", "createdAt", "updatedAt", "secret" ] } }, "required": [ "data" ] }, "example": { "data": { "id": "whe_7a8b9c0d1e2f3a4b", "url": "https://hooks.example.com/brix", "description": "Ops alerts", "secretPreview": "3f9a1c2e", "events": [ "screen.offline", "screen.online" ], "enabled": true, "autoDisabledAt": null, "autoDisabledReason": null, "consecutiveFailures": 0, "lastDeliveryAt": null, "lastStatus": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z", "secret": "3f9a1c2e4b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f" } } } } }, "400": { "description": "`bad_request` (missing url, unknown event) or `unsafe_url`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "tags": [ "webhooks" ], "summary": "Delete a webhook endpoint", "description": "Delete a webhook endpoint. Any deliveries still pending for it are abandoned rather than retried.\n\n**Notes.**\n- Answers `{ data: { id } }` — without the `deleted: true` most other deletes return.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Answers `{ data: { id } }` — without the `deleted: true` most other deletes return." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint id.", "example": "whe_7a8b9c0d1e2f3a4b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such endpoint in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] }, "patch": { "operationId": "updateWebhook", "tags": [ "webhooks" ], "summary": "Update a webhook endpoint", "description": "Change a webhook endpoint's URL, event subscriptions, description, or enabled state. Re-enabling an endpoint clears any automatic disable and resets its failure count, since re-enabling means the receiver has been confirmed fixed.\n\n**Notes.**\n- Needs the permission at the workspace root: a location-scoped key is refused.\n- Validation failures are 400 `bad_request`, where most other routes answer 422 `validation_error`.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Needs the permission at the workspace root: a location-scoped key is refused.", "Validation failures are 400 `bad_request`, where most other routes answer 422 `validation_error`." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint id.", "example": "whe_7a8b9c0d1e2f3a4b" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "An https URL on the public internet.", "type": "string" }, "events": { "description": "Replaces the subscription. An unknown name is refused.", "type": "array", "items": { "type": "string", "enum": [ "screen.offline", "screen.online", "content.recalled", "content.restored", "approval.requested", "approval.decided", "emergency.started", "emergency.cleared" ] } }, "description": { "description": "Cut to 200 characters.", "type": "string" }, "enabled": { "description": "`true` also clears an automatic switch-off and the failure count.", "type": "boolean" } } }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "data" ] }, "example": { "data": { "id": "whe_7a8b9c0d1e2f3a4b", "url": "https://hooks.example.com/brix", "description": "Ops alerts", "secretPreview": "3f9a1c2e", "events": [ "screen.offline", "screen.online" ], "enabled": true, "autoDisabledAt": null, "autoDisabledReason": null, "consecutiveFailures": 0, "lastDeliveryAt": null, "lastStatus": null, "createdAt": "2026-09-28T09:00:00.000Z", "updatedAt": "2026-09-28T09:00:00.000Z" } } } } }, "400": { "description": "`bad_request` (unknown event) or `unsafe_url`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such endpoint in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "tags": [ "webhooks" ], "summary": "Send a test webhook delivery", "description": "Send a real, signed sample delivery to this endpoint now. It is a genuine delivery rather than a simulation, so it exercises the same signature verification your receiver uses in production. The sample event is `screen.offline`; this call returns 409 if the endpoint is not subscribed to that event.\n\nSends a real, signed `screen.offline` delivery with `data: { test: true, note }` now and records it in the delivery log. A failed send is NOT an HTTP error: the answer is 200 with `ok: false`.\n\n**Notes.**\n- The test event is always `screen.offline`: an endpoint subscribed only to other events gets 409 `not_subscribed`, with a message that says it is subscribed to no event.\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "x-brix-notes": [ "The test event is always `screen.offline`: an endpoint subscribed only to other events gets 409 `not_subscribed`, with a message that says it is subscribed to no event.", "Needs the permission at the workspace root: a location-scoped key is refused." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint id.", "example": "whe_7a8b9c0d1e2f3a4b" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deliveryId": { "type": "string", "description": "Id of the delivery this call made (a new `whd_…` row in the delivery log)." }, "ok": { "type": "boolean", "description": "The receiver answered 2xx." }, "status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status the receiver answered with; null when no answer came." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the delivery failed (`http 500`, a timeout, an unsafe address); null on success." } }, "required": [ "deliveryId", "ok", "status", "error" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such endpoint in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`not_subscribed`: the endpoint is not subscribed to `screen.offline`, or it is switched off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/webhooks/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "webhooks" ], "summary": "List webhook deliveries", "description": "List the webhook delivery log: what was sent, the response received, the number of attempts, and what is still pending. Each entry includes the exact payload that was sent. Results are paginated and can be filtered by endpoint and status. Failed deliveries are retried with increasing delay over roughly 8 to 12 hours before they are given up on.\n\n**Notes.**\n- Always paged: without `?limit` a page has 50 deliveries (not every row, unlike the lists that page only on request), and `nextCursor` is always present.\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "integration.view", "x-brix-schema": "verified", "x-brix-notes": [ "Always paged: without `?limit` a page has 50 deliveries (not every row, unlike the lists that page only on request), and `nextCursor` is always present.", "Needs the permission at the workspace root: a location-scoped key is refused." ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Page size, 1–200. Default 50." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The `nextCursor` of the previous page." }, { "name": "endpointId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this endpoint's deliveries." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "failed", "abandoned" ] }, "description": "Only deliveries in this state. Another value is ignored." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "description": "Newest first." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Send it back as `?cursor=` for the next page; null on the last page." } }, "required": [ "data", "nextCursor" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] } }, "/v1/webhooks/deliveries/{id}/replay": { "post": { "operationId": "replayWebhookDelivery", "tags": [ "webhooks" ], "summary": "Replay a webhook delivery", "description": "Resend a delivery as a new delivery with its own id and a `replayOf` field pointing at the original. The original delivery record is left unchanged, so a receiver that deduplicates on delivery id will not silently ignore the resend.\n\nSends the payload again now, as a new delivery. A failed send is NOT an HTTP error: the answer is 200 with `ok: false`.\n\n**Notes.**\n- Needs the permission at the workspace root: a location-scoped key is refused.", "x-brix-permission": "integration.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Needs the permission at the workspace root: a location-scoped key is refused." ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id of the delivery to send again.", "example": "whd_8b9c0d1e2f3a4b5c" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "deliveryId": { "type": "string", "description": "Id of the delivery this call made (a new `whd_…` row in the delivery log)." }, "ok": { "type": "boolean", "description": "The receiver answered 2xx." }, "status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "HTTP status the receiver answered with; null when no answer came." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the delivery failed (`http 500`, a timeout, an unsafe address); null on success." } }, "required": [ "deliveryId", "ok", "status", "error" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such delivery in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.edit" ] } ] } }, "/v1/webhooks/events": { "get": { "operationId": "listWebhookEvents", "tags": [ "webhooks" ], "summary": "List subscribable webhook events", "description": "List the catalog of event types that can be subscribed to, each with a label and a description of what it carries. Only `content.recalled` and `content.restored` events are actually sent today; other listed events are not yet emitted.", "x-brix-permission": "integration.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "screen.offline", "screen.online", "content.recalled", "content.restored", "approval.requested", "approval.decided", "emergency.started", "emergency.cleared" ] }, "label": { "type": "string" }, "what": { "type": "string", "description": "What the event means and carries." } }, "required": [ "event", "label", "what" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "integration.view" ] } ] } }, "/v1/workspace": { "get": { "operationId": "getWorkspace", "tags": [ "workspace" ], "summary": "Get the workspace", "description": "Returns the calling workspace's id and name.", "x-brix-permission": "screen.view", "x-brix-schema": "verified", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkspaceRef" } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks the permission this operation needs (see `x-brix-permission`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "screen.view" ] } ] }, "patch": { "operationId": "updateWorkspace", "tags": [ "workspace" ], "summary": "Rename workspace", "description": "Renames the workspace. The name must be non-empty and no more than 120 characters. Requires permission to edit billing for the whole workspace.\n\n**Notes.**\n- Only `name` can be changed here.", "x-brix-permission": "billing.edit", "x-brix-schema": "verified", "x-brix-notes": [ "Only `name` can be changed here." ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Trimmed; 1–120 characters." } }, "required": [ "name" ] }, "example": { "name": "Riverside Coffee" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, expired or revoked bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "You do not hold `billing.edit` for the whole workspace (a grant at one location is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`invalid`: `name` missing, empty or over 120 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Server error. The body carries a `requestId` to quote to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [ "billing.edit" ] } ] } } } }