Skip to content
Szenera DeveloperDocs
API › Guide to the reference › Generate your own client from the specification
Chapters

Generate your own client from the specification

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.

3 minute readAPIUpdated: 10/25/2026

On this page

Before you start

For
Anyone who calls the API from a programming language and does not want to write every call by hand.
Prerequisite
a generator for OpenAPI 3.1 in your language and an ak_… key
Where
command line

There is currently no published client for the Szenera API. This guide shows you how to generate your own from openapi.json and map the conventions of the API into it: credential, errors, version check, idempotency, and paging.

The honest status

The platform has a TypeScript client, but it is part of the portals and is not published. The developer site does not promise one. What exists is the specification: complete, with an example per schema, in the OpenAPI 3.1.0 format. Any common generator can produce a client from it.

Steps

  1. Download the specification:

    curl -sS -o openapi.json "https://developer.szenera.com/api/openapi.json"

    Or download it from your environment if its version differs from the release: curl -sS -o openapi.json "$SZENERA_API/v1/openapi.json".

  2. Generate the client with a generator of your choice. First check that it understands OpenAPI 3.1: The specification uses types such as ["string", "null"], which a 3.0 generator does not know. The 19 tags of the specification work well as module boundaries.

  3. Set the credential centrally: Authorization: Bearer ak_… on every call, taken from an environment variable and never from the source code. A key does not expire after 15 minutes, so your client needs no refresh.

  4. Map errors to code. Every error has the form Area.Cause. Derive one typed error per namespace (Auth.*, Permission.*, Validation.*, Conflict.*, RateLimit.*, *.NotFound, Integration.*) and carry traceId in each of them. Never branch on message. The format is described under The error format.

  5. Map the version check: For scenes, playlists, programs, roles, and displays, read the version field and send it as If-Match with every change. On 409 Conflict.OptimisticLock, your client reads again and retries once. See Concurrent changes.

  6. Give every modifying call an Idempotency-Key: self-chosen, at least 8 characters, new for each action. A repeat with the same key returns the stored response with Idempotent-Replay: true, and the same key with a different body answers 422 Validation.IdempotencyKeyReused. Details are described under Idempotency from the start.

  7. Build a cursor loop for lists: send limit and cursor, collect items, and continue with nextCursor until it is missing. Handle the four routes with page separately, see Paging.

Check the result

  • The schema examples are your first test data: all 741 schemas of the served specification carry one, and they fit together (same identifiers, same organization).
  • A first read call, GET /v1/me, answers 200 with the tenantId of your organization.
  • A call with a wrong key lands in your typed Auth error with code: Auth.ApiKeyUnknown.
  • Every operation your client offers carries x-stability: stable or beta in the specification (with beta, the shape can still move). You compare a later version of the specification with Compare the specification against your version.

If something goes wrong

Symptom Meaning Solution
The generator aborts with a format error It does not know OpenAPI 3.1. Choose a generator with 3.1 support.
422 Validation.Failed with details.issues The body violates the schema, and issues names the field path. Compare the example of the request schema with your body.
403 Permission.Denied on a route that the client offers The generator produces every operation, including those a key may not call. Check the permission in the reference. Permissions that are not key-capable stay reserved for sessions, see Authentication.
A field the client requires is missing from the response Your environment runs a different build than the specification you generated from. Download the specification of the environment (GET /v1/openapi.json) and generate again.