API, documentation and API keys

Everything the panel does can also be done from your own software through the server's REST API: channels (start, stop, restart, configuration), live statistics, events, audience, clips, scheduled recordings, monitoring wall, users. The panel itself uses the same API.

The documentation and API keys are in all plans. Scoped, IP-bound keys with a custom limit are in the Enterprise edition. Available from Castreon 1.6.0.

The API page

Administration → API (administrators only) has two tabs:

• API keys — the keys for integrations (automation systems, NOC tools, scripts);
• Documentation — the full API reference: every operation with its method, path, minimum role, scope, parameters, a request and response example and a ready-to-copy curl command.

Download openapi.json gives the OpenAPI 3.1 document — import it straight into Postman, Insomnia or Swagger UI, or into code generators (Python, TypeScript, Go, C#). It is generated from the same table the server uses to check every request, so it always matches the installed version. Its address: https://server:port/api/v1/openapi.json (with an API key or a panel session).

Authentication

Every request sends the key in a header:

curl -H 'Authorization: Bearer cst_…' https://server:33443/api/v1/channels

Example — restarting a channel (a key with the operator role or the “Channel control” scope):

curl -X POST -H 'Authorization: Bearer cst_…' https://server:33443/api/v1/channels/<id>/restart

Errors always look like {"error":{"code":"…","message":"…"}} — code is stable (for programs), message is for people.

API keys

New API key → name, access, expiry. The key is shown only once — copy it then; the server keeps only a fingerprint of it.

• By role (all plans): the key has the rights of a whole role — Viewer, Operator or Administrator.
• By scopes (Enterprise): the key can do only what its ticked scopes allow — Monitoring (live state), Read configuration, Channel control (start, stop, restart, playout commands), Change configuration, Administration. A key for a NOC screen gets only Monitoring; an automation system gets Channel control. Anything outside its scopes is refused with 403 and the code scope, naming the missing scope.
• Allowed IPs (Enterprise): the key works only from the given addresses or networks (e.g. 10.20.0.0/24); from elsewhere — 403 key_ip.
• Request limit: every key has a limit (600 per minute by default; in Enterprise you choose it). Above it the server answers 429 with Retry-After; every response carries X-RateLimit-Limit and X-RateLimit-Remaining.

The table shows each key's last use, IP address and request count.

A new key without stopping integrations

Rotate on an existing key creates another one with the same rights. Choose how long the old one keeps working — 24 hours, 7 days or not at all — so you can change the key in your integrations without interruption. Revoke stops a key immediately.

For support

Every response has an X-Request-ID header (you can send your own too, to tie requests to your logs). If a request fails, include it in your ticket.

Live events and webhooks

• GET /api/v1/events is a Server-Sent Events stream with channel state, statistics and configuration changes.
• Notifications (see Notifications) can send alerts to a signed webhook; its format is described in the OpenAPI document.

Tips

• One key per integration, with as few rights as possible and, where you can, bound to the integration's IP.
• Change keys regularly with Rotate (with overlap); do not reuse them between systems.
• Older keys from Users → API tokens (previous versions) keep working unchanged; they are now managed on the API page.