Reference

API documentation

All API calls go to this origin. Every route requires a valid API key. Create keys from your account after you register (7-day trial after you verify your email). Commercial access is arranged offline. The playground is unauthenticated preview data only—it is not a substitute for the customer API.

Base URL

https://broadcast-calendar.cloud

Authentication

Send the key on every request:

Authorization: Bearer <your_api_key>
or X-API-Key: <your_api_key>

Create and revoke keys from the account page. The full key is shown only once.

Access and trial

The account email must be verified. You can call the v1 API while you have an active trial or while your account has a future access_until set by the operator (paid access granted offline). If both trial and access_until apply, the longer effective access wins for eligibility.

Rate limiting

By default, trial API keys (and all customer v1 API traffic) are limited to 3 requests per second per account, using a 1-second fixed window. If you exceed the limit, the API responds with 429 and a Retry-After header (seconds). Contact support if you need a higher sustained throughput for production.

Endpoints

All methods are GET and return JSON.

Channel IDs are UUIDs (e.g. aff8c27a-0765-4acc-8e41-58f8f75a49d7). Use the id returned from country channel lists or channel search in programme URLs.

List countries

/api/v1/countries

curl -s "https://broadcast-calendar.cloud/api/v1/countries" \
  -H "Authorization: Bearer YOUR_KEY"

List channels in a country

/api/v1/countries/{country}/channels

curl -s "https://broadcast-calendar.cloud/api/v1/countries/NO/channels" \
  -H "Authorization: Bearer YOUR_KEY"

Search channels

/api/v1/channels/search?q=…&country=…

Query: q (required for search text), country (optional filter).

curl -s "https://broadcast-calendar.cloud/api/v1/channels/search?q=news" \
  -H "Authorization: Bearer YOUR_KEY"

Channel programmes (schedule)

/api/v1/channels/{channelId}/programmes

path channelId: UUID. Optional query: days, all — same meaning as the public playground.

curl -s "https://broadcast-calendar.cloud/api/v1/channels/aff8c27a-0765-4acc-8e41-58f8f75a49d7/programmes" \
  -H "Authorization: Bearer YOUR_KEY"

Errors

Error bodies are JSON with error (message) and code (stable identifier) where applicable.

401 — missing or invalid API key
403 — no active trial or paid access
429 — rate limit exceeded
503 — upstream or configuration problem

Pricing · Playground