OpenAPI

Every endpoint in this documentation is also published as a machine-readable OpenAPI 3.1 document, so you can drive tooling from the contract instead of transcribing tables by hand.

Copy	URL	Notes
Documentation	https://docs.zelnum.com/openapi.yaml	Stable, on this domain. Canonical for readers of this site.
Platform	https://app.zelnum.com/docs/openapi.yaml	Upstream. The documentation copy is a byte-identical mirror of it.

Both files are the same document. The mirror exists so the spec lives on the host you are already reading, at a path tooling can find.

What the document contains

Part	Count	Contents
Servers	1	https://api.zelnum.com/api/v1
Paths	10	The nine documented endpoints plus the legacy realtime alias
Tags	3	Common, Realtime, Bulk — the same split the navigation uses
Schemas	9	Request and response bodies, including the error envelope
Security schemes	2	X-API-Key and Authorization: Bearer

Operation-level details are in the document itself: required headers, minItems/maxItems on arrays, enums for series, mode, status and billing_status, and the deprecated: true flag on POST /v1/realtime/detect.

Import into API tooling

Postman — Import → File → openapi.yaml. Postman creates a collection with an environment variable for the base URL; set your key as a collection-level X-API-Key header so every request inherits it.

Insomnia — Create → Import From → File, then add X-API-Key as a collection header.

Bruno / HTTPie / curl generators — all consume OpenAPI 3.1 directly:

curl -fsSL https://docs.zelnum.com/openapi.yaml -o zelnum.yaml

Generate a typed client

There is no first-party SDK — the API is plain JSON over HTTPS, and a generated client is usually a better fit than a hand-written one anyway, because it follows your language’s conventions.

# Pick your generator: python, typescript-fetch, php, go, java, csharp, ruby, …
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.zelnum.com/openapi.yaml \
  -g python \
  -o ./zelnum-client

Generated clients read the base URL and the security scheme from the document, so the only thing you supply at runtime is your API key.

Realtime requires a header the generator cannot invent

Idempotency-Key is a required header on the realtime endpoints, and a generated client will surface it as a method parameter you must set. It must be unique per submission — see Idempotency & retries.

Keeping the mirror honest

The mirror follows upstream; it is never edited here. Because drift between a published contract and its documentation is the failure this page exists to prevent, the copy is checked against upstream rather than trusted:

npm run openapi:check   # fetch upstream and fail if the bytes differ
npm run openapi:sync    # re-vendor, printing which operations changed

openapi:check needs network access and is deliberately not part of the site build — a deploy must not fail because the platform host had a bad minute. What the build does enforce is the offline half of the invariant: every endpoint this documentation describes must exist in the vendored document, so a page cannot document an operation the contract does not have.

Next

• Versioning & deprecation — what the deprecated flag on the legacy endpoint means for you
• Response format — the envelope every endpoint shares