# Luna Screens API > REST API for Luna Screens digital signage. Create and delete screens, pair devices to screens, create, update and delete adverts (images, videos and webpages) in an account's library, manage permission groups, and receive account events with webhooks. This API is in preview and may change. Base URL: https://api.lunascreens.com/v1 Requests and responses are JSON. ## Authentication Send `Authorization: Bearer `. API keys start with `lsk_` and are created in the Luna Screens dashboard (https://app.lunascreens.com) under Account → API keys. A key is shown only once, when it's created. Requests act on the account the key belongs to, with the permissions of the key's permission group. ## Errors Non-2xx responses return `{ "message": string, "code"?: string }`. 400 = invalid request or missing Authorization header. 403 = invalid, disabled or revoked API key, or insufficient permission. 404 = not found, including resources in another account. 500 = server error. ## Endpoints - `POST /screens` — Create a screen. Body: `name` (required), `timeZone` (required, IANA), `description`. Returns `{ screen }`. - `DELETE /screens/{id}` — Delete a screen. Returns `{ success: true }`. - `POST /screens/{id}/pair` — Pair a physical device to a screen. Body: `pairingCode` (required), the code shown on the device's display; spaces and case are ignored. Codes change regularly, so use the one currently shown. Requires permission to modify the screen (otherwise 403 with `code` `CANNOT_MODIFY_SCREEN`). An invalid or expired code returns 400 `Invalid pairing code.`. Sends a `device.paired` webhook event. Returns `{ success: true }`. - `POST /adverts` — Create an advert. Body: `advert` with `content` (HTTPS URL) and `customType` (`image` | `video` | `webpage`), both required. There's no upload endpoint: images and videos are given by URL and processed in the background, copied into Luna Screens' storage (up to 300MB), their `type`, `width`, `height` and `duration` read from the file (values sent are ignored) and videos optimised. Track it with the advert's `processingState` (`uploading` | `extracting` | `optimising` | `ready` | `errored`, with `processingProgress` while uploading or optimising and `processingError` when errored); errored adverts are skipped by screens. Optional: `name`, `soundEnabled`. `thumbnailUrl` is made by us, any value sent is ignored: from the file for images and videos, a screenshot taken in the background for webpages, a placeholder until it's ready. Returns `{ advert }` including `id` — store it. The response's `listingKey` isn't needed and is likely to be removed in the future. - `PUT /adverts/{id}` — Update an advert. Body: `advert` with only the fields to change (`name`, `content`, `soundEnabled`); the rest keep their current values. Changing an image or video's `content` processes the new file the same way as creating it, and changing a webpage's `content` takes a new thumbnail. Returns `{ advert }`. - `DELETE /adverts/{id}` — Delete an advert. No body needed. Returns `{ success: true }`. - `GET /account/permission-groups` — List the account's permission groups, including the Owner group (`isOwnerPermissionGroup: true`, always full access). Requires view access to permissions or users. Returns `{ permissionGroups }`. - `POST /account/permission-groups` — Create a permission group. Body: `name` (required) and any permissions (see below). Omitted permissions default to `canModify` for `screens`, `contentItems`, `contentItemsLocal`, `billing`, `permissions`, `users` and `noAccess` for `accountSetup`, `apiKeys`, `webhooks`, lowered to the caller's own access; send them all to be sure. Permissions you send that exceed your own access give 403. Returns `{ permissionGroup }` including `id`. - `PUT /account/permission-groups/{id}` — Update a permission group. Body: only the fields to change. The `id` comes from the URL; an `id` in the body is optional and must match it (otherwise 400). Can't give more access than your own or change a group with more access than you (403). 404 if the group isn't in the account. Returns `{ success: true, permissionGroup }`. - `DELETE /account/permission-groups/{id}` — Delete a permission group. No body needed. Fails with 400 if users are still in the group, 404 if the group isn't in the account. Returns `{ success: true }`. Permission group fields: `name`, and a level for each feature: `noAccess` | `canView` | `canModify`. Features: `screens`, `contentItems` (adverts), `billing`, `permissions` (permission groups), `users`, `accountSetup` (custom domain and email), `apiKeys`, `webhooks`. `screens` can also be `granular`, using `screensPermissions` (`{ [screenId]: level }`, only screens in the account get access, cleared unless `screens` is `granular`). `contentItems` can also be `granular`, giving access only to adverts added by the group's members, with `contentItemsLocal` as the level for them. Unknown fields give 400 (`id` is allowed, and must match the URL on update). Responses also include `id`, `createdAt`, `updatedAt` (Unix ms) and `isOwnerPermissionGroup` on the Owner group. Every user and API key belongs to one permission group. ## Webhooks Endpoints are added in the dashboard under Account → Webhooks (up to 5 per account). Each subscribes to chosen event types and has a signing secret starting with `whsec_`. URLs must be public `https://` addresses on port 443 using a domain name. Events are sent as `POST` with a JSON body `{ id, type, createdAt, source, actor, data }` (`createdAt` in Unix ms) and headers `Luna-Event-Id`, `Luna-Event-Type`, `Luna-Signature`. - `screen.created`, `screen.updated`, `screen.deleted` — `data.screen` has `id`, `name`, `description`, `timeZone` (deleted: `id`, `name`). `screen.updated` also has `data.updatedFields`: any of `name`, `description`, `display`, `content`. - `advert.created`, `advert.updated`, `advert.deleted` — `data.advert` has the same fields as the API's advert (deleted: `id`, `name`). - `advert.optimisation_progress` — A video advert's optimisation progress. `source` is `system`. `data`: `advertId`, `state`, `progress`, `error`. While `state` is `optimising` it's sent at most once a second per advert, only when `progress` (0 to 99, the same as the advert's `processingProgress`) goes up. Once finished, one event with `state` `complete` (`progress` 100) or `errored` (`progress` null, `error` the reason, same as `processingError`). Can arrive out of order, so rely on `state`, not arrival order. - `device.paired` — A device was paired to a screen. `data`: `screenId`, `screenName` (string or null), `pairedAt` (Unix ms). - `device.connected`, `device.disconnected` — A screen's device came online or went offline. `source` is `system`. `data`: `screenId`, `screenName` (string or null), and `connectedAt` or `disconnectedAt` (Unix ms). A device that's switched off or loses its network can take up to 10 minutes to be noticed. A short network drop can send `device.disconnected` then `device.connected`. Throttled to about 10 events per device in 10 minutes if a device keeps reconnecting, so the last event received might not match its current state until it settles. - `user.invite_accepted` — Someone accepted an invite to the account, sent from the dashboard or with the API. `source` is `system`. `data`: `inviteId` (the `invite.id` returned by `POST /users`), `userId`, `permissionGroupId` (or null). - `webhook.test` — Sent by the dashboard's Send test event button. `data`: `message`. `source` is `dashboard`, `api` or `system`. `actor` is `{ type: 'user', id }`, `{ type: 'api_key', id, name }`, or null for `system`. Events are also sent for changes made with your own API key; to ignore them, skip events where `actor.id` is your API key's ID (shown in Account → API keys). Verify `Luna-Signature: t=,v1=`: compute HMAC-SHA256 of `.` with the signing secret, compare to `v1` in constant time, and reject if `t` is more than 5 minutes old. Respond with any 2xx within 10 seconds; anything else (including redirects) is a failure. Failures are retried after 15m, 1h, 6h and 24h (5 attempts in total), with the same event `id`. The same event can arrive more than once, so handling it twice should have the same result as handling it once. Events may arrive out of order. Disabled endpoints receive no new events and their retries stop. Events can be viewed and resent from the dashboard for 30 days. ## Docs - [API reference](https://lunascreens.com/api/): Human-readable reference with examples. - [Webhooks guide](https://lunascreens.com/api/webhooks/): How to set up an endpoint, check signatures and handle retries. - [OpenAPI definition (JSON)](https://lunascreens.com/api/openapi.json): Full machine-readable spec. - [OpenAPI definition (YAML)](https://lunascreens.com/api/openapi.yaml): Same spec in YAML.