Documentation
Streamwake developer reference

Read the loop,
then run it.

Four doors in: sign up for a session, skim the live API surface, follow the five-minute quickstart and watch a probe land in the agents feed, or read the API key issuance guide for the player SDK. Every curl on this site matches the handlers in production — what you copy is what gets executed.

Open quickstartJump to API reference
Where to start

Pick the door that fits your day.

Each card lands you on the right artifact for what you came to do. Nothing behind a signup wall unless the page says so.

Auth
Create a session and use it on every API call.

Better-auth powers the cookie session. Sign up through the UI at /sign-up, or script it with the REST endpoint. Every /api/v1/* call below expects the resulting better-auth.session_token cookie.

Public signup
Read the auth guide
API Reference
The three endpoints you'll actually call.

Read the live contract for /api/v1/streams, /api/v1/streams/<id>, and /api/v1/agents. Copy-paste curls, JSON shapes pulled from the route handlers, and badges for auth.

Auth required
Open the reference

Drill into POST → /docs/api/streams-post

Quickstart
Five steps, end to end, in five minutes.

A linear copy-paste narrative: register a stream, read its monitor record, watch the first probe land in the streams dashboard, and step five lands on /app/streams. The whole loop runs against the live handlers — no sandbox, no fake data.

5-minute
Start the walk
API keys
Mint a key, authorize the player SDK.

Two tracks, fully spelled out. The cookie track is the better-auth session that gates /api/v1/* and the key mint. The bearer track is the swk_… key the SDK sends as Authorization: Bearer on /api/v1/telemetry.

Public
Read the issuance guide
Live API surface

Three endpoints,
one continuous loop.

All three are auth-gated — include the better-auth.session_token cookie set by step one of the quickstart. Responses are JSON; shapes below are pulled from the route handlers, not paraphrased.

POST
/api/v1/streams
Auth required

Register a stream

Upsert a stream by its sourceUrl. POST is idempotent — re-posting the same URL returns the existing record, so a retried request never 409s. Returns 201 with the row, including the initial agentState and a 100% uptimePct placeholder that updates after the first probe.

curl -X POST https://streamwake.app/api/v1/streams \
  -H "content-type: application/json" \
  -b "better-auth.session_token=<your-session-cookie>" \
  -d '{ "sourceUrl": "https://example.com/manifest.m3u8" }'
{
  "id": "ckq3x...stream",
  "sourceUrl": "https://example.com/manifest.m3u8",
  "createdAt": "2026-08-03T18:24:11.000Z",
  "agentState": "healthy",
  "lastAction": "registered",
  "lastCheckedAt": null,
  "uptimePct": 100
}
GET
/api/v1/streams/<id>
Auth required

Read the monitor record

Returns the live StreamStatus for one stream. The uptimePct is computed from the last 24 hours of probe history — same window as the list endpoint, so the two numbers always agree. 404 if the id is unknown.

curl https://streamwake.app/api/v1/streams/<id> \
  -b "better-auth.session_token=<your-session-cookie>"
{
  "id": "ckq3x...stream",
  "sourceUrl": "https://example.com/manifest.m3u8",
  "agentState": "healthy",
  "uptimePct": 100,
  "lastAction": "registered",
  "lastCheckedAt": null
}
GET
/api/v1/agents
Auth required

Recent agent activity

Returns the most recent 100 probes joined with their stream. The severity is derived from the underlying probe status (healthy → info, degraded → warn, failing → critical). An open failing probe with no subsequent healthy probe shows "fix": "investigating".

curl https://streamwake.app/api/v1/agents \
  -b "better-auth.session_token=<your-session-cookie>"
{
  "items": [
    {
      "id": "ckq3x...probe",
      "streamId": "ckq3x...stream",
      "sourceUrl": "https://example.com/manifest.m3u8",
      "severity": "info",
      "anomalyClass": "no anomaly",
      "fix": "registered",
      "createdAt": "2026-08-03T18:25:00.000Z",
      "latencyMs": 142
    }
  ]
}

Want to watch it land?

The quickstart walks every endpoint above in order — register a stream, then read it back, then watch a probe appear.

Open the quickstart