> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layarva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage and Pair Screens

> Create and pair a Screen, assign Channel and Location, and check or control playback.

## Before you start

Use the [Postman setup](https://docs.layarva.com/developers/platform-quickstart.md): `platform_base` is `https://api.layarva.com/api/platform/v1/workspaces/YOUR_WORKSPACE_ID`, with your Platform key as the Bearer token.

For POST, PATCH and DELETE, use **Body → raw → JSON**, `Content-Type: application/json` and a new [Idempotency-Key](https://docs.layarva.com/developers/platform-request-keys.md) per new change. GET needs no body or operation key.

For the main workflow, select `screens.read`, `screens.create`, `screens.pair`, `screens.update` and `screens.playback`. Other actions have their own permissions listed below. Your plan limits apply; all assigned IDs must belong to the same workspace. Queue-managed Screens are protected.

## Step 1: Choose the delivery mode

| Mode | Use it for | What you need |
| - | - | - |
| `CLOUD` | A Player that connects directly to Layarva | A pairing code from the actual Player |
| `EDGE` | A LAN display served by Layarva Edge | An owned, paired `ACTIVE` Edge; [follow the Edge guide](https://docs.layarva.com/developers/platform-edges.md) |
| `OFFLINE` | A Screen using an offline content package | A prepared Channel; package export currently uses the [dashboard workflow](https://docs.layarva.com/developers/platform-offline.md) |

The steps below use **CLOUD**. Cloud pairing codes are not used to pair an Edge-served LAN display or an offline-package Screen.

## Step 2: List or create the Screen record

List existing Screens with **GET** `{{platform_base}}/screens?limit=25`, or search with `/screens?q=Lobby&limit=25`.

To create an unpaired Cloud Screen, send **POST** `{{platform_base}}/screens`:

```json theme={null}
{
  "name": "Main lobby",
  "deliveryMode": "CLOUD",
  "channelId": "{{channel_id}}",
  "locationId": "{{location_id}}"
}
```

Create or choose these IDs using the [Channel and Location guide](https://docs.layarva.com/developers/platform-channels-locations.md). They are optional for a Cloud Screen; omit fields you have not assigned.

The response is **201 Created**. Save `data.id` as `screen_id`. Creating the record does **not** pair the physical Player.

## Step 3: Pair the actual Cloud Player

1. Open Layarva Player on the device you own.
2. Read its current six-digit pairing code.
3. Send **POST** `{{platform_base}}/screens/{{screen_id}}/pair`:

```json theme={null}
{
  "code": "{{pairing_code}}"
}
```

Set `pairing_code` to the real code as a string, including leading zeroes. Do not generate a random number or use a code from another device. Keep it private. If it expires, obtain a fresh code from the Player; do not repeatedly retry the old code.

### Alternative: create and pair in one request

If you have **not** already created a Screen record, send **POST** `{{platform_base}}/screens/pair` with `screens.pair`:

```json theme={null}
{
  "name": "Main lobby",
  "code": "{{pairing_code}}",
  "channelId": "{{channel_id}}",
  "locationId": "{{location_id}}"
}
```

Save the returned `data.id`. Choose either this one-request flow **or** the create-then-pair flow above; do not use both for the same device.

## Step 4: Assign or change Channel and Location

Send **PATCH** `{{platform_base}}/screens/{{screen_id}}`:

```json theme={null}
{
  "channelId": "{{channel_id}}",
  "locationId": "{{location_id}}"
}
```

This changes the assignments, not the Playlist itself. [Publish Ready content to the Channel](https://docs.layarva.com/developers/platform-playlists-publication.md) so assigned Screens can receive it.

You can also change `name` and `clientId`. Where permitted, `null` clears an assignment. Do not change delivery mode through PATCH; use the dedicated delivery endpoint below.

### Optional: configure output size and fit

Include a **complete** `displayConfig` in your create or PATCH request:

```json theme={null}
{
  "displayConfig": {
    "targetWidthPx": 1920,
    "targetHeightPx": 1080,
    "contentFitMode": "FIT",
    "contentAnchor": "CENTER",
    "contentZoomPct": 100,
    "contentOffsetXPct": 0,
    "contentOffsetYPct": 0
  }
}
```

This PATCH example uses 1920×1080, centered content, 100% zoom and zero offsets. Width supports 320–7680, height 240–4320, zoom 25–400%, and offsets −100 to 100. Fit modes are `FIT`, `FILL`, `STRETCH`, `CUSTOM`; anchors include `CENTER` and the eight edge/corner positions.

## Step 5: Check connection and playback

Read **GET** `{{platform_base}}/screens/{{screen_id}}`. Check `paired`, `status`, `lastPingAt` and assignments. `status` represents current connectivity; do not use `storedStatus` as proof of a recent heartbeat.

Read **GET** `{{platform_base}}/screens/{{screen_id}}/playback`:

* `playbackEnabled` shows whether playback is enabled.
* `desiredPublicationId` is the expected release.
* `activePublicationId` is the release reported active by the Player.
* `state` and `updatedAt` help interpret the report. A new Screen may have no report yet.

A successful pairing or command response is not proof of physical playback. Check recent reports and the actual display.

## Step 6: Enable playback or control audio

Send **POST** `{{platform_base}}/screens/{{screen_id}}/playback`:

```json theme={null}
{
  "enabled": true
}
```

Use `false` to disable playback. For audio, send **POST** `/screens/{{screen_id}}/audio` with `{"videoMuted": false}`; `true` mutes video audio. Both changes require `screens.playback`.

## Other Screen actions

Use the same authenticated JSON setup and a new operation UUID for each new change.

| Action | Method and path | Body | Permission |
| - | - | - | - |
| Unpair | POST `/screens/{{screen_id}}/unpair` | `{}` | `screens.unpair` |
| Move Cloud delivery to Edge | POST `/screens/{{screen_id}}/delivery` | `{"mode":"EDGE","edgeDeviceId":"YOUR_ACTIVE_EDGE_ID"}` | `screens.delivery` |
| Return delivery to Cloud | POST `/screens/{{screen_id}}/delivery` | `{"mode":"CLOUD","force":false}` | `screens.delivery` |
| Set an unlock code | POST `/screens/{{screen_id}}/unlock-code` | `{"unlockPasscode":"1234"}` — replace with your own 4–6 digit code; `null` clears it | `screens.unlock-code` |
| Request a connection probe | POST `/screens/{{screen_id}}/probe` | `{}` — paired Cloud only; GET the same path to check acknowledgement | `screens.probe` |
| Retry delivery of expected content | POST `/screens/{{screen_id}}/resync` | `{}` — Cloud/Edge with a Channel | `screens.resync` |
| List offline leases | GET `/screens/{{screen_id}}/offline-leases?limit=25` | No body | `screens.read` |
| Revoke an offline lease | POST `/screens/{{screen_id}}/offline-revoke` | `{"leaseId":"YOUR_LEASE_ID"}` | `screens.offline-revoke` |
| Archive the Screen | DELETE `/screens/{{screen_id}}` | `{}` | `screens.delete` |

Do not change `force` to true simply to bypass a delivery conflict. Review the handover requirements first. This endpoint does not convert a Screen into offline-package mode. Unlock codes are not returned by reads; do not log them.

Deleting/archiving is not a remote wipe of a disconnected device. Offline lease revocation is enforced when the Player reconnects.

## Filter and paginate Screen lists

Examples: `/screens?channelId={{channel_id}}&limit=25`, `/screens?locationId={{location_id}}&status=ONLINE`, or `/screens?deliveryMode=EDGE&edgeDeviceId={{edge_id}}`.

For more pages, send the returned `page.nextCursor` as `after`. Stop when it is null. See [all supported filters](https://docs.layarva.com/developers/platform-quickstart.md#list-resources).

## Related guides

* [Playlist → Ready → Publish](https://docs.layarva.com/developers/platform-playlists-publication.md)
* [Channels and Locations](https://docs.layarva.com/developers/platform-channels-locations.md)
* [Register and assign Edge](https://docs.layarva.com/developers/platform-edges.md)
* [Offline API availability](https://docs.layarva.com/developers/platform-offline.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.