WatchLive API

The WatchLive API is a REST interface over your organization's events, camera feeds, recordings and sales. It speaks JSON, authenticates with an API key, and sends webhooks when things happen.

The base URL is https://api.watchlive.org/v1. Every endpoint is scoped to the organization that owns the key — there is no way to read another organization's data.

The API requires:

• An Enterprise WatchLive organization with an active subscription.
• An API key, created from your dashboard.

Enterprise is priced per contract. Talk to us about upgrading. Once you are on Enterprise, create keys at Dashboard → Developers.

Calling the API without Enterprise returns 402 PLATFORM_ACCESS_REQUIRED.

List your events:

curl https://api.watchlive.org/v1/events \
  -H "Authorization: Bearer wl_live_your_key_here"

{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "45a45b4e-c865-454b-9df3-ce48b1c69b96",
      "name": "County Finals",
      "slug": "county-finals",
      "status": "live",
      "visibility": "public",
      "ticket_price": "12.00",
      "created_at": "2026-07-28T00:46:52.402Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Pass your key as a bearer token. An x-api-key header is also accepted.

# Either of these works
curl https://api.watchlive.org/v1/events -H "Authorization: Bearer wl_live_..."
curl https://api.watchlive.org/v1/events -H "x-api-key: wl_live_..."

Keys are shown once, when you create them. We store only a hash, so a lost key cannot be recovered — rotate it instead.

Rotating issues a new key and keeps the old one working for 24 hours, so you can roll it through a deploy without downtime.

Each key carries an explicit list of scopes. A call outside them returns 403.

Grant the narrowest set that works. A key that only reads recordings cannot touch your sales data even if it leaks.

Write bodies are validated strictly: an unrecognised or wrong-case field returns 400 rather than being quietly ignored, so a typo can never look like a successful save.

Keys are either wl_live_ or wl_test_.

• Test keys read your real data, so responses look exactly like production.
• Writes with a test key are accepted and discarded — you get a test_mode_response and nothing changes.

List endpoints are cursor paginated. Pass limit (default 20, max 100) and cursor. Keep going while has_more is true.

curl "https://api.watchlive.org/v1/recordings?limit=50" \
  -H "Authorization: Bearer wl_live_..."

# then
curl "https://api.watchlive.org/v1/recordings?limit=50&cursor=eyJjcmVhdGVkQXQi..." \
  -H "Authorization: Bearer wl_live_..."

Cursors are keyset-based, so pages stay stable even while new records are being created.

Failures return a stable machine-readable code. Branch on the code, not the message.

{
  "error": {
    "type": "permission_error",
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key is missing the required \"read:purchases\" scope.",
    "status": 403,
    "request_id": "req-14",
    "required_scope": "read:purchases"
  }
}

Limits are per key: 600 requests/minute for live keys, 60/minute for test keys.

Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset. On a 429, honor retry-after and back off.

A field is a camera feed within an event.

Ingest credentials — stream keys, RTMP/SRT URLs and passphrases — are never returned by the API. They are visible only to signed-in organizers in the dashboard.

Read-only. Purchases must go through checkout so that fees and entitlements are applied correctly, so there is no endpoint for creating one.

Register an HTTPS endpoint and choose the events you want:

curl -X POST https://api.watchlive.org/v1/webhook_endpoints \
  -H "Authorization: Bearer wl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/watchlive/webhook",
    "enabled_events": ["stream.started", "stream.ended", "purchase.completed"]
  }'

Event types:

Delivery is at least once. Retries run at 1m, 5m, 30m, 2h and 6h; deduplicate on the event id. An endpoint that keeps failing is disabled automatically and can be re-enabled from your dashboard.

Respond 2xx quickly and do your work asynchronously — we time out after 10 seconds.

Every delivery carries an X-WatchLive-Signature header:

X-WatchLive-Signature: t=1785199740,v1=98140a550dbf5b76dc0686...

v1 is HMAC-SHA256(secret, "{t}.{raw body}"). Verify against the raw request body — parsing and re-serializing the JSON changes the bytes and the signature will not match.

import crypto from 'crypto';

// express.raw keeps the body as bytes — express.json() would break verification
app.post('/watchlive/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.headers['x-watchlive-signature'];
  const [tPart, v1Part] = String(header).split(',');
  const timestamp = tPart.split('=')[1];
  const signature = v1Part.split('=')[1];

  // Reject replays of an old, previously-valid delivery
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(400).send('Timestamp too old');
  }

  const expected = crypto
    .createHmac('sha256', process.env.WATCHLIVE_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.body}`)
    .digest('hex');

  // Constant-time compare — a plain === leaks timing information
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  if (!ok) return res.status(400).send('Bad signature');

  const event = JSON.parse(req.body);
  console.log(event.type, event.data);

  res.sendStatus(200); // ack fast, process asynchronously
});

{
  "id": "0fac1f7f-1a02-4a99-a7c8-89f8ab17718e",
  "type": "stream.started",
  "livemode": true,
  "created": 1785199740,
  "data": {
    "field": { "id": "9b804156-...", "name": "Cam 1", "status": "live" },
    "event": { "id": "45a45b4e-...", "name": "County Finals", "slug": "county-finals" }
  }
}