--- title: "Update a screen's settings" method: PATCH path: "/v1/screens/{id}" tags: ["screens"] --- # Update a screen's settings `PATCH /v1/screens/{id}` ## Request - Base URL: `https://api.brixsignage.com` - URL: `https://api.brixsignage.com/v1/screens/{id}` - Auth: HTTP bearer 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. ## Path parameters - `id` string, required ## Request body - object - `name` string - `nodeId` string, nullable: Move to another location (you need screen.edit there too). - `billingGroupId` string, nullable: Needs billing.edit. - `status` 'online' | 'offline' | 'pairing' - `tags` string[] - `rotation` union - 0 - 90 - 180 - 270 - `timezone` string, nullable: IANA time zone; null to inherit. - `operatingHours` string - `displayPowerMode` 'always-on' | 'follow-schedule' | 'os-default' - `powerPolicyId` string, nullable - `playbackMode` 'sync' | 'unsync' | 'device-time' - `location` object, nullable - `label` string - `lat` number - `lng` number - `deactivated` boolean: True deactivates the screen (nothing plays); false reactivates it. - `playerVersionHold` union - boolean - string - `playerSettings` object, nullable: Merged into the current settings; null resets them. - `customFields` object, nullable - `kioskPinMode` 'workspace' | 'custom' - `kioskGraceSeconds` number - `kioskPin` string, nullable: 4-8 digits; null clears the custom PIN. - `kioskEnabled` boolean ## Response `200` Success. - object - `data` Screen, required: A screen, composed with its content, live state and health facts. - `id` string, required: Screen id. - `spaceId` string, required: Workspace id. - `nodeId` string, nullable, required: Location (org node) the screen belongs to; null = workspace root. - `name` string, required - `status` 'online' | 'offline' | 'pairing', required: `pairing` = no device has checked in yet. - `lastSeenAt` string, nullable, required: ISO-8601 timestamp (UTC). - `coreUpdateOfferedAt` string, nullable, required: ISO-8601 timestamp (UTC). - `contentKind` 'playlist' | 'schedule' | 'layout' | 'creative' | 'app' | 'media' | 'signage', nullable, required: What is assigned. Null = nothing assigned. - `contentId` string, nullable, required - `contentFit` unknown, required - `deactivatedAt` string, nullable, required: ISO-8601 timestamp (UTC). - `awaitingPaymentAt` string, nullable, required: ISO-8601 timestamp (UTC). - `tags` string[], required - `rotation` integer, required: 0, 90, 180 or 270 degrees. - `rotationCommandedAt` string, nullable, required: ISO-8601 timestamp (UTC). - `timezone` string, nullable, required: IANA time zone; null = inherited. - `timezoneSource` 'operator' | 'device', nullable, required - `operatingHours` string, required: `default`, or a JSON-encoded weekly window. - `lastPanelCommand` string, nullable, required - `scheduleScreensOff` boolean, required - `displayPowerMode` 'always-on' | 'follow-schedule' | 'os-default', required - `playbackMode` 'sync' | 'unsync' | 'device-time', required - `locationLabel` string, nullable, required - `locationLat` number, nullable, required - `locationLng` number, nullable, required - `ipCity` string, nullable, required - `ipRegion` string, nullable, required - `ipCountry` string, nullable, required - `ipLat` number, nullable, required - `ipLng` number, nullable, required - `ipTimezone` string, nullable, required - `ipGeoAt` string, nullable, required: ISO-8601 timestamp (UTC). - `playerSettings` string, nullable, required: Player settings as a JSON-ENCODED string (not an object). - `kioskEnabled` boolean, required - `kioskPinMode` 'workspace' | 'custom', required - `kioskGraceSeconds` integer, required - `activeEmergencyId` string, nullable, required: The live emergency overriding this screen, if any. - `activeCastId` string, nullable, required: The live cast overriding this screen, if any. - `playerVersionHold` string, nullable, required - `sealed` boolean, required - `sealedAt` string, nullable, required: ISO-8601 timestamp (UTC). - `powerPolicyId` string, nullable, required - `importSourceId` string, nullable, required - `billingGroupId` string, nullable, required - `customFields` string, nullable, required: Custom fields as a JSON-ENCODED string. - `lanSecretAt` string, nullable, required: ISO-8601 timestamp (UTC). - `createdAt` string, required: ISO-8601 timestamp (UTC). - `updatedAt` string, required: ISO-8601 timestamp (UTC). - `deletedAt` string, nullable, required: ISO-8601 timestamp (UTC). - `location` object, nullable, required - `label` string, required - `lat` number, required - `lng` number, required - `deviceClaimed` boolean, required: Status is `pairing` but a device has claimed it and not yet checked in. - `nodeName` string, nullable, required - `groupIds` string[], required: Screen groups this screen is in. - `contentName` string, nullable, required - `contentSharedFrom` string, nullable, required: Name of the workspace that shared the assigned content in; null when it is this workspace's own. - `thumbnailUrl` string, nullable, required: Preview of the assigned content. - `contentAppKey` string, nullable, required - `contentMediaKind` string, nullable, required - `contentState` object, nullable, required: Assigned media that is not playable yet (processing, failed, needs_action); null otherwise. - `state` string, required - `reason` string, nullable, required - `contentOrientation` 'portrait' | 'landscape' | 'adaptive', nullable, required - `liveThumbnailAt` string, nullable, required: ISO-8601 timestamp (UTC). - `liveThumbnailFreshAt` string, nullable, required: ISO-8601 timestamp (UTC). - `currentContentKind` 'image' | 'video' | 'stream', nullable, required - `currentContentPosterUrl` string, nullable, required - `emergencyHeadline` string, nullable, required - `castHeadline` string, nullable, required - `castStartedAt` string, nullable, required: ISO-8601 timestamp (UTC). - `castExpiresAt` string, nullable, required: ISO-8601 timestamp (UTC). - `castContentKind` string, nullable, required - `castContentId` string, nullable, required - `kioskHasCustomPin` boolean, required - `kioskHasRecovery` boolean, required - `obscuredSince` string, nullable, required: ISO-8601 timestamp (UTC). - `pixelHealth` 'ok' | 'frozen' | 'blank', nullable, required - `displayOffSince` string, nullable, required: ISO-8601 timestamp (UTC). - `displayOffReason` 'standby' | 'wrong-input' | 'disconnected' | 'input-unconfirmed', nullable, required - `expectedDark` object, required - `dark` boolean, required: True when the rules say the panel should be off now. - `reason` 'schedule-block' | 'power-policy' | 'operating-hours', nullable, required - `nextOpen` object, nullable, required - `at` string, required - `day` string, required - `inMinutes` number, required - `minutesSinceOpen` number, nullable, required - `minutesSinceClose` number, nullable, required - `accountHold` object, nullable, required - `status` 'suspended' | 'cancelled' | 'deactivated' | 'trial_expired' | 'awaiting_payment', required - `reason` string, required - `outageSummary30d` object, nullable, required - `windowDays` integer, required - `count` integer, required - `topCause` string, nullable, required - `topCauseShare` number, required - `hedgedShare` number, required - `lastCause` object, nullable, required - `cause` string, required: Outage cause key, e.g. `wifi-dropped`, `power-loss`, `unknown`. - `confident` boolean, required - `lastKnownCause` object, nullable, required - `cause` string, required: Outage cause key, e.g. `wifi-dropped`, `power-loss`, `unknown`. - `confident` boolean, required - `insight` string, nullable, required - `linkFlaps10m` integer: Socket link flips in the last ten minutes; present only when > 0 (list and get). - `state` object, nullable, required: 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. ## Other responses - `400`: The body tried to set content (use POST /v1/screens/{id}/assign). - `401`: Missing, expired or revoked bearer token. - `403`: The token lacks the permission this operation needs (see `x-brix-permission`). - `404`: No such screen (or destination location/billing group) in this workspace. - `422`: Invalid status, rotation, time zone or PIN. - `5XX`: Server error. The body carries a `requestId` to quote to support. ## Changes - **2026-10-20** `02fd3665dc7d`: 1 warning, 1 info - added the new `awaiting_payment` enum value to the `data/accountHold/anyOf[subschema #1]/status` response property for the response status `200` - added the required property `data/awaitingPaymentAt` to the response with the `200` status [Operation history](https://skmtc.dev/brixsignage/apis/brix-api/changes/v1/screens/:id/patch.md) --- [API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)