# Szenera Developer

> The developer documentation of the Szenera digital signage platform (HKNovaTech UG (haftungsbeschränkt), Ahrensburg, Germany): HTTP API under `/v1`, the `szenera` command line, the Apps SDK and webhooks. It is written for developers who call Szenera from their own systems — from the first request to a running integration. Instructions for using the portal are not here but at https://szenera.com/docs.

Key points:
- The API is OpenAPI 3.1 and lives under `/v1`; you sign in with an API key from the portal.
- The same rules apply on every route: one uniform error format, ETag/If-Match for safe updates, `Idempotency-Key` for repeatable writes, rate limits and paging with `limit`/`cursor`.
- The complete reference is at https://developer.szenera.com/api/reference, the specification as a file at https://developer.szenera.com/api/openapi.json.
- Webhooks carry the organization's events outwards; delivery is signed with HMAC and retried on errors.
- Every page of this site is also available as a Markdown twin: a leaf page under its own address with the ending `.md` (`/api/error-format` → `/api/error-format.md`), an area overview and the start page under `<address>/index.md` (`/api` → `/api/index.md`, the start page → `/index.md`).
- The same documentation in German lives under `/de` (`https://developer.szenera.com/de/llms.txt` is its page list).

## Machine-readable

- [OpenAPI specification](https://developer.szenera.com/api/openapi.json): the public tenant API as an OpenAPI 3.1 document — the source from which the reference and every generated client arise.
- [API reference](https://developer.szenera.com/api/reference): the same specification as a readable interface.
- [Section index of the search](https://developer.szenera.com/search.json): one entry per heading with area, page and anchor.

## Pages

All pages in curated order. Each is also available as a Markdown twin — the same text without frame, navigation and script.

- [Develop with Szenera](https://developer.szenera.com/): Szenera’s API, CLI, Apps SDK, and webhooks: how to create keys, make calls, and receive events, plus the rules that apply on every route. — Markdown: https://developer.szenera.com/index.md
- [Getting started](https://developer.szenera.com/getting-started): From API key to first call: create a key, query with curl, read responses, and make retries safe from the start. — Markdown: https://developer.szenera.com/getting-started/index.md
- [How does a call flow through the platform?](https://developer.szenera.com/getting-started/about-request-flow): From the bearer header through the permission check to the response with a trace ID: the stations every call passes through. — Markdown: https://developer.szenera.com/getting-started/about-request-flow.md
- [Create an API key](https://developer.szenera.com/getting-started/create-api-key): In the portal under Settings › Organization › API keys, create a key with class, permissions, and expiry. The plaintext appears exactly once. — Markdown: https://developer.szenera.com/getting-started/create-api-key.md
- [Your first call with curl](https://developer.szenera.com/getting-started/first-call): Call GET /v1/me and GET /v1/playlists with a key and curl, and look at the response and its headers, in five minutes. — Markdown: https://developer.szenera.com/getting-started/first-call.md
- [What a response contains](https://developer.szenera.com/getting-started/response-contents): Status, headers, list shape, IDs with a prefix, and the error body: everything a response of the API holds, in tables. — Markdown: https://developer.szenera.com/getting-started/response-contents.md
- [Idempotency from the start](https://developer.szenera.com/getting-started/idempotency): Protect write calls with Idempotency-Key, so that a retry after a network drop does not create a second operation. — Markdown: https://developer.szenera.com/getting-started/idempotency.md
- [When the first call fails](https://developer.szenera.com/getting-started/troubleshooting): 401, 403, 404, 422, 429, and network errors on the first call: what the code means and which page shows the way back. — Markdown: https://developer.szenera.com/getting-started/troubleshooting.md
- [API](https://developer.szenera.com/api): The rules that apply on every route (address, authentication, errors, limits, paging, stability), the ways in for third-party applications, directory… — Markdown: https://developer.szenera.com/api/index.md
- [Base URL, /v1, and stability](https://developer.szenera.com/api/base-url-and-stability): Where the base URL comes from, why almost every route carries /v1, which paths lie outside it, and what x-stability promises per operation. — Markdown: https://developer.szenera.com/api/base-url-and-stability.md
- [Authentication: keys and sessions](https://developer.szenera.com/api/authentication): Bearer header, key prefixes, permission scope, expiry and rotation of a key, and when a session makes more sense than a key. — Markdown: https://developer.szenera.com/api/authentication.md
- [The error format](https://developer.szenera.com/api/error-format): The error body with code, message, and traceId, the RFC 9457 form, and the rule by which a code becomes the HTTP status. — Markdown: https://developer.szenera.com/api/error-format.md
- [Concurrent changes: ETag and If-Match](https://developer.szenera.com/api/etag-and-if-match): Read a versioned resource, send the version back as If-Match, and resolve a 409 conflict cleanly. — Markdown: https://developer.szenera.com/api/etag-and-if-match.md
- [Throttling and rate-limit headers](https://developer.szenera.com/api/rate-limits): Which routes have a limit of their own, which rate limit is attached to a key, what the four headers mean, and how a client reacts to 429. — Markdown: https://developer.szenera.com/api/rate-limits.md
- [Paging: limit, cursor, items, nextCursor](https://developer.szenera.com/api/pagination): Cursor paging on all lists, the limits 50/200 and 25/100, the four routes with page, and how the CLI follows all pages with --all. — Markdown: https://developer.szenera.com/api/pagination.md
- [Delegated access with OAuth 2.1](https://developer.szenera.com/api/oauth-delegated-access): Your application runs at other customers’ sites: register, have users consent with PKCE, exchange the oat_ token, renew, revoke. — Markdown: https://developer.szenera.com/api/oauth-delegated-access.md
- [Provisioning with SCIM 2.0](https://developer.szenera.com/api/scim-provisioning): A directory service should create accounts, suspend them, and set roles: token sct_, endpoints under /scim/v2, mapping, and errors. — Markdown: https://developer.szenera.com/api/scim-provisioning.md
- [The MCP service for AI assistants](https://developer.szenera.com/api/mcp-service): An assistant should work with your inventory: address, authentication, tool list, confirmation requirement, limits, and errors. — Markdown: https://developer.szenera.com/api/mcp-service.md
- [Locations](https://developer.szenera.com/api/locations): Mirror a branch structure: fields of a location, its routes, assigning a display, and analytics by location. — Markdown: https://developer.szenera.com/api/locations.md
- [Web displays](https://developer.szenera.com/api/web-displays): Create a display with no device behind it: routes, connection URL, the two states, deletion, and the limits compared with a device. — Markdown: https://developer.szenera.com/api/web-displays.md
- [Error codes: possible on any route](https://developer.szenera.com/api/error-codes-general): The platform-wide codes for authentication, permissions, validation, conflicts, throttling, payload, HTTP, events, caching, jobs, and resources. — Markdown: https://developer.szenera.com/api/error-codes-general.md
- [Error codes: accounts and sessions](https://developer.szenera.com/api/error-codes-accounts): The codes of the areas Identity and Sessions: user accounts, keys, invitations, sign-in, second factor, sessions. — Markdown: https://developer.szenera.com/api/error-codes-accounts.md
- [Error codes: organization, access, joining](https://developer.szenera.com/api/error-codes-organization): The codes of the areas Tenancy, Access, Onboarding, and Cloud-Connections: master data, domain, roles, grants, registration, storage connections. — Markdown: https://developer.szenera.com/api/error-codes-organization.md
- [Error codes: billing](https://developer.szenera.com/api/error-codes-billing): The codes of the area Billing: package, licenses, add-ons, payment method, invoices, and why 402 appears here. — Markdown: https://developer.szenera.com/api/error-codes-billing.md
- [Error codes: media, scenes, programs, apps](https://developer.szenera.com/api/error-codes-content): The codes of the areas Media-Library, Composition, Scheduling, App-Catalog, Marketplace, App-Runtime, and Advertising. — Markdown: https://developer.szenera.com/api/error-codes-content.md
- [Error codes: devices, playback, notifications, operations](https://developer.szenera.com/api/error-codes-devices-operations): The codes of the areas Fleet, Playback, Realtime, Notifications, Analytics, Audit, and Ops-Console, the latter only on operator routes. — Markdown: https://developer.szenera.com/api/error-codes-devices-operations.md
- [Error codes: server errors (5xx)](https://developer.szenera.com/api/error-codes-server): The 119 codes to which a client cannot react in a domain-specific way: invariants, startup, database, downstream services. Retry or report. — Markdown: https://developer.szenera.com/api/error-codes-server.md
- [Read the reference](https://developer.szenera.com/api/read-reference): Find an operation at /api/reference, read off permission, security scheme, example, and stability, and download the specification. — Markdown: https://developer.szenera.com/api/read-reference.md
- [The areas of the reference](https://developer.szenera.com/api/reference-areas): The 19 tags of the specification in their 7 groups with one sentence of purpose each, and why the operator surface is not part of it. — Markdown: https://developer.szenera.com/api/reference-areas.md
- [Generate your own client from the specification](https://developer.szenera.com/api/generate-client): There is currently no published client. Here is how you generate your own from openapi.json and map the conventions of the API into it. — Markdown: https://developer.szenera.com/api/generate-client.md
- [CLI](https://developer.szenera.com/cli): The szenera command line: profiles, credentials, 136 commands, JSON output and exit codes, and what applies today when you obtain it. — Markdown: https://developer.szenera.com/cli/index.md
- [Get the CLI](https://developer.szenera.com/cli/get-cli): How to get the CLI today: no npm package, no download. The CLI is built from the platform’s source tree, and without access you are left with the API. — Markdown: https://developer.szenera.com/cli/get-cli.md
- [Profiles and credentials](https://developer.szenera.com/cli/profiles-and-credentials): Create a profile with an environment, a credential type, and write protection, either as a file or with environment variables only, and check it with… — Markdown: https://developer.szenera.com/cli/profiles-and-credentials.md
- [Commands for your organization](https://developer.szenera.com/cli/commands-organization): All szenera commands that run with a key or account of your organization: media, scenes, playlists, programs, devices, team, apps, package. — Markdown: https://developer.szenera.com/cli/commands-organization.md
- [Commands for platform operations](https://developer.szenera.com/cli/commands-platform-operations): The commands of the internal szenera-ops tool that run only with an operator profile: device software, approvals, incidents, queues, organizations… — Markdown: https://developer.szenera.com/cli/commands-platform-operations.md
- [JSON output and exit codes](https://developer.szenera.com/cli/output-and-exit-codes): JSON without an envelope on standard output, errors only on standard error, --raw for contract violations, and the 13 exit codes from 0 to 12. — Markdown: https://developer.szenera.com/cli/output-and-exit-codes.md
- [Scripts and CI](https://developer.szenera.com/cli/scripts-and-ci): Work without a profile file by using environment variables, evaluate exit codes, fetch lists completely, limit wait times, and make retries safe. — Markdown: https://developer.szenera.com/cli/scripts-and-ci.md
- [When the CLI aborts](https://developer.szenera.com/cli/troubleshooting): Unknown command, profile blocked, 401 despite a key, response contradicts the contract, exit 11 or 12: symptom, meaning, solution. — Markdown: https://developer.szenera.com/cli/troubleshooting.md
- [Webhooks](https://developer.szenera.com/webhooks): Your organization’s events, delivered to your systems: create an endpoint, verify the signature, understand retries, look up event types, and retrieve… — Markdown: https://developer.szenera.com/webhooks/index.md
- [How is a webhook delivered?](https://developer.szenera.com/webhooks/about-delivery): From the event through matching against your endpoints, signing, and sending, to a retry or disabling. — Markdown: https://developer.szenera.com/webhooks/about-delivery.md
- [What is sent and how it is retried](https://developer.szenera.com/webhooks/delivery-and-retries): The request to your endpoint (method, headers, body), the states of a delivery, the retry schedule, and disabling. — Markdown: https://developer.szenera.com/webhooks/delivery-and-retries.md
- [Create a webhook endpoint](https://developer.szenera.com/webhooks/create-endpoint): Enter an https address and the subscribed events under Settings › Organization › Webhooks, and store the signing secret safely. — Markdown: https://developer.szenera.com/webhooks/create-endpoint.md
- [Verify the signature of a delivery](https://developer.szenera.com/webhooks/verify-signature): Recompute HMAC-SHA256 over the raw body, compare it with X-Signature in constant time, deduplicate by X-Delivery-Id, and rotate the secret. — Markdown: https://developer.szenera.com/webhooks/verify-signature.md
- [Event types: organization, accounts, billing](https://developer.szenera.com/webhooks/event-types-organization): The subscribable event types from organization, storage connections, access, accounts and delegated access, sessions, billing, and joining, with their… — Markdown: https://developer.szenera.com/webhooks/event-types-organization.md
- [Event types: content, programs, devices, apps](https://developer.szenera.com/webhooks/event-types-content-devices): The subscribable event types from media, scenes, programs, marketplace, fleet, app runtime, playback, analytics, and advertising, plus the platform types… — Markdown: https://developer.szenera.com/webhooks/event-types-content-devices.md
- [Fetch the event catalog through the API](https://developer.szenera.com/webhooks/fetch-event-catalog): You create endpoints from your own system or show the selection in your own interface: fetch the catalog as JSON and check a list of events before the… — Markdown: https://developer.szenera.com/webhooks/fetch-event-catalog.md
- [When no delivery arrives](https://developer.szenera.com/webhooks/troubleshooting): Endpoint rejected, inactive after failures, no retry after a 4xx, signature does not match, duplicate deliveries, an event never occurs. — Markdown: https://developer.szenera.com/webhooks/troubleshooting.md
- [Apps SDK](https://developer.szenera.com/apps-sdk): How an app is built (manifest, widget, backend, data access, signature) and how it gets into the catalog and onto the display. The whole path of a new… — Markdown: https://developer.szenera.com/apps-sdk/index.md
- [From template to release](https://developer.szenera.com/apps-sdk/template-to-release): The whole path of a new app: create it from the template with pnpm app:new , write the widget, config, texts, and images, check it with pnpm app:check… — Markdown: https://developer.szenera.com/apps-sdk/template-to-release.md
- [An app in the new standard](https://developer.szenera.com/apps-sdk/new-app-standard): Convert an app to templates with size, formats, fit report, surfaces, and the declarative form, using the weather app as an example, plus fit check… — Markdown: https://developer.szenera.com/apps-sdk/new-app-standard.md
- [What is an app, and how does it get onto a display?](https://developer.szenera.com/apps-sdk/about-apps): From the manifest through release, channels, and installation to the signed bundle on the device: the lifecycle of an app in one picture. — Markdown: https://developer.szenera.com/apps-sdk/about-apps.md
- [The manifest](https://developer.szenera.com/apps-sdk/manifest): Every field of the app manifest with whether it is required, its format, and its effect, from id and version to legal, unlocks, and connects. — Markdown: https://developer.szenera.com/apps-sdk/manifest.md
- [Widget, configuration, and preview](https://developer.szenera.com/apps-sdk/widget-and-preview): defineWidget with configSchema and noResolver, formats (useWidgetFormat), preview variants with size for catalog and thumbnails, and preview states, with… — Markdown: https://developer.szenera.com/apps-sdk/widget-and-preview.md
- [Configure widgets](https://developer.szenera.com/apps-sdk/configure-widgets): Read the widget catalog: configSchema as JSON Schema, required fields, examples, and a ready-made widget instance for each built-in building block. — Markdown: https://developer.szenera.com/apps-sdk/configure-widgets.md
- [Backend: resolvers, fetchers, and jobs](https://developer.szenera.com/apps-sdk/backend): The three decorators @WidgetResolver, @Fetcher, and @JobHandler, their rules, and the capabilities that an app’s backend obtains through tokens. — Markdown: https://developer.szenera.com/apps-sdk/backend.md
- [Data access, permissions, and terms](https://developer.szenera.com/apps-sdk/data-access): dataAccess (reads, external, retention), permissions for team and operator, unlocks and connects, the legal block: what an app discloses before… — Markdown: https://developer.szenera.com/apps-sdk/data-access.md
- [Signing and the path into the catalog](https://developer.szenera.com/apps-sdk/signing-and-catalog): What belongs to a release, sha256 and Ed25519 signature, the policy on the device, channels canary → beta → stable, and who creates releases today. — Markdown: https://developer.szenera.com/apps-sdk/signing-and-catalog.md
- [The example apps](https://developer.szenera.com/apps-sdk/example-apps): All 26 bundled apps with profile and special feature, and the three references clock (widget only), weather (fetcher), pharmacies-on-duty (resources and… — Markdown: https://developer.szenera.com/apps-sdk/example-apps.md
- [Changes](https://developer.szenera.com/changes): Where changes to the API originate, what a breaking change is, and how you compare the specification against your own copy, without promises that do not… — Markdown: https://developer.szenera.com/changes/index.md
- [Stability classes and sunset](https://developer.szenera.com/changes/stability-and-sunset): What stable, beta, and internal promise, how long the period between announcement and shutdown is, and how your client recognizes a sunset on its own. — Markdown: https://developer.szenera.com/changes/stability-and-sunset.md
- [Release trains, notes, and deprecations](https://developer.szenera.com/changes/release-notes): How a release train comes about, how its notes are structured, what is attached to the release, and what applies to deprecations today. — Markdown: https://developer.szenera.com/changes/release-notes.md
- [Packages and their versions](https://developer.szenera.com/changes/packages): Which version of the API client, Apps SDK, CLI, and contracts applies and what changed for developers in each version. — Markdown: https://developer.szenera.com/changes/packages.md
- [Compare the specification against your version](https://developer.szenera.com/changes/compare-specification): Save openapi.json with a date, reload it with every train, and compare paths, required fields, and error codes, with the site and your own environment… — Markdown: https://developer.szenera.com/changes/compare-specification.md