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

# Platform API Quickstart

> Make your first authenticated request and paginate Library, Playlist, Screen, Schedule, Channel and Location lists.

## Prerequisites

Create a Platform / Workspace key with read permissions using the [key guide](https://docs.layarva.com/developers/platform-api-keys.md). Substitute your actual workspace ID; example IDs are placeholders.

## Your first request in Postman

1. Choose **GET** and enter `https://api.layarva.com/api/platform/v1/workspaces/YOUR_WORKSPACE_ID/playlists?ready=true&limit=25`.
2. In **Authorization**, choose **Bearer Token** and use your Platform API key. Keep it in a private Postman environment or vault.
3. Select **Send**. A successful response contains `data` and `page`.

GET does not need `Idempotency-Key`. For POST, PATCH or DELETE, follow the [operation ID examples](https://docs.layarva.com/developers/platform-request-keys.md).

### cURL alternative

```sh theme={null}
# Supply these variables securely; do not paste real secrets into shell history.
curl --fail-with-body --request GET \
  "https://api.layarva.com/api/platform/v1/workspaces/${LAYARVA_WORKSPACE_ID}/playlists?ready=true&limit=25" \
  --header "Authorization: Bearer ${LAYARVA_PLATFORM_KEY}"
```

## Backend request helper

This Node.js example obtains configuration from environment variables; no real credential is included. Start with a test workspace. GET requests omit body/Idempotency-Key; all writes use a caller-persisted operation key.

```js theme={null}
import { randomUUID } from "node:crypto";
const base = `https://${process.env.LAYARVA_API_HOST}/api/platform/v1/workspaces/${encodeURIComponent(process.env.LAYARVA_WORKSPACE_ID)}`;
const secret = process.env.LAYARVA_PLATFORM_KEY;
async function platform(method, path, body, operationKey) {
  if (!secret || !operationKey && method !== "GET") throw new Error("Missing backend configuration");
  const response = await fetch(base + path, {
    method, redirect: "error", signal: AbortSignal.timeout(20000),
    headers: {
      Authorization: `Bearer ${secret}`,
      ...(method !== "GET" ? { "Content-Type": "application/json", "Idempotency-Key": operationKey } : {}),
    },
    ...(method !== "GET" ? { body: JSON.stringify(body ?? {}) } : {}),
  });
  const receipt = await response.json();
  if (!response.ok) {
    // Log only safe code/request ID; never key, request PIN or capability URL.
    throw Object.assign(new Error(receipt.error.message), {
      status: response.status, code: receipt.error.code,
      requestId: receipt.error.requestId, retryAfter: response.headers.get("Retry-After"),
    });
  }
  return receipt;
}
```

Set `LAYARVA_API_HOST=api.layarva.com`. Supply `LAYARVA_WORKSPACE_ID` and `LAYARVA_PLATFORM_KEY` only on your backend. The public service information is at `/`, this guide at `/docs`, and the machine-readable schema at `/openapi.json`; these three read-only documents require no key and expose no customer data. Every management endpoint still requires its workspace key.

## List resources

Successful collection reads are `{data:[...],page:{limit,nextCursor}}`. Order is ascending opaque ID, **not** newest-first. `limit` defaults to 50, max 100. Send returned `nextCursor` as `after`; stop when null. This is keyset pagination, not a transactionally frozen snapshot of all pages. Detail reads are `{data:{...}}` and reject query parameters. IDs are restricted to 1–100 ASCII letters/digits/underscore/hyphen.

| Resource | GET path / required scope | Additional list filters |
| - | - | - |
| Library assets | `/assets` / `library.read` | `q`, `id`, `groupId` (or `no-group`), `libraryType`, `type` |
| Playlist | `/playlists` / `playlists.read` | `q`, `id`, `ready=true\|false` |
| Screen | `/screens` / `screens.read` | `q`, `id`, `channelId`, `locationId`, `edgeDeviceId`, `paired=true\|false`, `deliveryMode=CLOUD\|EDGE\|OFFLINE`, `status=ONLINE\|OFFLINE` |
| Schedule | `/schedules` / `schedules.read` | `q`, `id`, `channelId`, `playlistId`, `controlState`, `scheduleType=ALWAYS\|ONE_TIME\|WEEKLY` |
| Channel | `/channels` / `channels.read` | `q`, `id`, `playlistId` (Channel default Playlist) |
| Location | `/locations` / `locations.read` | `q`, `id` |
| Edge | `/edges` / `edges.read` | `q`, `id`, `status`, `archived=true\|false` |

Additional collections: `/groups` (`library.read`: `q,id,libraryType`), `/publications` (`publications.read`: `id,channelId,playlistId`), `/approval-requests` (`publications.request`: pagination only). Playlist `/playlists/{id}/versions`, Screen `/screens/{id}/offline-leases` and `/screens/{id}/offline-exports` accept pagination only. `q` is case-insensitive name-substring search, not arbitrary SQL/full-text expressions. Filter values are case-sensitive where enums are specified. Repeated or unknown parameters are rejected, not silently ignored. `ready=true` means a server-owned immutable Ready version exists; it does not mean unsaved/current draft edits are published.

Schedule `controlState` filter accepts `DRAFT|ENABLED|PAUSED`: `ENABLED` is a normalized query alias matching stored `ACTIVE` as well as `ENABLED`. Returned `controlState` remains the actual stored state and may therefore be `ACTIVE`; do not infer that response values are identical to query enums.

```js theme={null}
await platform("GET", "/assets?groupId=no-group&limit=25");
await platform("GET", "/playlists?ready=true&limit=25");
await platform("GET", "/screens?channelId=channel_example&status=ONLINE");
await platform("GET", "/schedules?channelId=channel_example");
await platform("GET", "/channels?playlistId=playlist_example");
await platform("GET", "/locations?q=Lobby");
await platform("GET", "/groups?libraryType=IMAGE");
await platform("GET", "/publications?channelId=channel_example");
// Continue any collection with ?limit=25&after=<page.nextCursor>.
```

## Related guides

* [Platform API overview and security](https://docs.layarva.com/developers/platform-api.md)
* [Create, rotate and revoke Platform keys](https://docs.layarva.com/developers/platform-api-keys.md)
* [First request and pagination](https://docs.layarva.com/developers/platform-quickstart.md)
* [Full OpenAPI 3.1 specification](https://api.layarva.com/openapi.json)


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