Screens API (part 1 of 4)

GET /v1/screens

Auth: Bearer token. Permission: screen.view.

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

curl "https://api.brixsignage.com/v1/screens" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

{
  "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,
      "awaitingPaymentAt": 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"
        }
      }
    }
  ]
}

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 5XX: Server error. The body carries a requestId to quote to support.

POST /v1/screens

Auth: Bearer token. Permission: screen.create.

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

Request body: application/json

curl -X POST "https://api.brixsignage.com/v1/screens" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 201: Success.

Response 401: Missing, expired or revoked bearer token.

Response 402: plan_full: every screen on the plan is in use. The body has data.plan with the price of one more screen today. Add screens to the plan, or send payment: "later".

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: The location does not exist.

Response 409: The account is suspended or cancelled.

Response 422: name is missing.

Response 5XX: Server error. The body carries a requestId to quote to support.

GET /v1/screens/{id}

Auth: Bearer token. Permission: screen.view.

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.

curl "https://api.brixsignage.com/v1/screens/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200: Success.

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: No such screen in this workspace.

Response 5XX: Server error. The body carries a requestId to quote to support.

PATCH /v1/screens/{id}

Auth: Bearer token. Permission: screen.edit.

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. Partial update. To change what a screen plays use POST /v1/screens/{id}/assign — this route refuses contentKind/contentId with a 400. Notes. - The PATCH response does not merge the live socket facts (linkFlaps10m, a socket-fresh lastSeenAt) that GET adds.

Request body: application/json

curl -X PATCH "https://api.brixsignage.com/v1/screens/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200: Success.

Response 400: The body tried to set content (use POST /v1/screens/{id}/assign).

Response 401: Missing, expired or revoked bearer token.

Response 403: The token lacks the permission this operation needs (see x-brix-permission).

Response 404: No such screen (or destination location/billing group) in this workspace.

Response 422: Invalid status, rotation, time zone or PIN.

Response 5XX: Server error. The body carries a requestId to quote to support.