API introduction

Everything in Cardinal is available over a REST API: JSON over HTTPS. The API reference describes every endpoint, with examples in cURL, Python, JavaScript, TypeScript, PHP, Ruby, Go, Java and C#.

Base URL: https://api.cardinalstreaming.com

Authentication

Every request carries an API key as a bearer token:

Authorization: Bearer strm_...

A key identifies one organization, which is what a stream is billed to. Create and revoke keys in the console. Keep keys on your servers — never in a browser or an app. The examples read the key from the CARDINAL_API_KEY environment variable.

A missing, unknown or revoked key is 401 unauthenticated, and so is a key whose organization is suspended; the answer is the same in every case, on purpose. Billing routes are the exception: they accept a key suspended for non-payment, so the bill can always be paid. Another organization’s stream, customer or recording is 404 not_found, never 403.

Your customers

If you stream for your own customers — you are a partner — put your identifier for each one in customer_ref when you book a stream. Booking registers the customer; the customers endpoints name, list and archive them, usage breaks down by customer so you can bill them, and recordings lists each customer’s recordings with download links.

Errors

Every error has one shape:

{ "error": "invalid_tier", "detail": "tier must be standard_1080p or pro_4k" }

Branch on error, which is stable; show or log detail, which is written for a person and may change. Each endpoint’s reference lists the codes it can return. See Errors and limits for the codes every endpoint shares.

Paging

Lists come a page at a time, newest first. Ask for up to 200 with limit (default 50) and pass the page’s cursor back to get the next one: next_cursor as cursor for recordings and customers, next_before as before for streams. The last page has no cursor.

Retrying safely

Send an Idempotency-Key header when booking a stream. A retry with the same key and body returns the stream the first request booked instead of booking a second; the same key with a different body is 422 idempotency_key_reused. A key is up to 255 printable ASCII characters with no spaces; a UUID is ideal. Starting, ending and deleting are safe to repeat without one.

For AI assistants and tools

The API is described by an OpenAPI 3 document (YAML) — the same description the API’s own tests check every response against, so it is exact. Use it to generate a client or to give an AI coding assistant the whole API at once.

Every page of these docs is also available as Markdown at its own address plus .md — for example /docs/api/reference/recordings.md — and the whole documentation is in llms.txt and llms-full.txt.