Advanced usage

Patterns for production integrations. None of this is required to get started — see Getting started for the basics.

Safe retries with Idempotency-Key

Every write endpoint accepts an optional Idempotency-Key header (any opaque string up to 256 characters — a UUID is perfect). If a request with the same key is repeated within 24 hours, the cached original response is replayed instead of executing the write again:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1f8e4a2c-7b3d-4e9f-a1c5-2d6b8e0f4a7c" \
  -d '{"title": "Brave Show — June 14"}' \
  https://api-v1.rundownstudio.app/rundowns

This makes re-running an import script after a network error or a 500 safe — the rundown is created once, no matter how many times the request is sent.

Calling from the browser

The API is CORS-permissive on every endpoint: Access-Control-Allow-Origin: *, no credentials. A fetch() from any web page reaches the API without a CORS error — no allow-list, no per-origin setup.

// Browser, any origin:
const res = await fetch('https://api-v1.rundownstudio.app/rundowns', {
  headers: { Authorization: `Bearer ${token}` },
  // do NOT set credentials: 'include' — the API never uses cookies
})

Two things to know:

• No cookies, no credentials. Auth rides the token, never a cookie, so Access-Control-Allow-Credentials is intentionally absent. Don’t set credentials: 'include' / withCredentials — it will make the browser reject the response.
• A token in front-end code is visible to anyone who views source. That’s fine for trusted first-party pages and prototypes; for anything public, proxy the API calls through your own backend and keep the token there. This is general token hygiene, not a CORS limitation — the browser is just where people are most tempted to inline a token.

Tighter origin controls (per-team origin allow-lists, per-token origin pinning) are on the roadmap but not in v1. Today the model is: permissive CORS + token in the header.

Where to go next

• Error reference — every error code, what triggers it, and how to recover.
• API reference — every endpoint, parameter, and schema.