5-minute quickstart
Five steps, end to end

From signup
to a watched stream.

A linear walkthrough that finishes on the streams dashboard. Copy the curls, paste them into your terminal, then step five lands you on /app/streams with a real probe ticking.

You need a working HLS or DASH manifest URL for step two.
Every step assumes the session cookie from step one.
The first probe lands within ~60 seconds of registration.
Quickstart steps
Step 01Auth

Create an account & sign in

Sign up through the UI at /sign-up. Better-auth sets a session cookie on the response — every subsequent call in this quickstart includes it as better-auth.session_token. The shape and the cookie contract are spelled out in the auth guide.

For scripted setups the same path works as a REST endpoint. The shape below is what the better-auth handler accepts.

POST /api/auth/sign-up/email
curl -X POST https://streamwake.polsia.io/api/auth/sign-up/email \
  -H "content-type: application/json" \
  -d '{
    "name": "Your Name",
    "email": "you@example.com",
    "password": "choose-a-strong-password"
  }'
Step 02Write

Register a stream

POST the manifest URL you want to monitor. The handler validates the URL (it must be http(s) and pass an SSRF guard before the row is written), then upserts on sourceUrl.

Idempotent: re-posting the same URL returns the existing record instead of 409, so a retried request is safe to leave in a deploy script. The 201 response below is what the handler actually returns.

POST /api/v1/streams
curl -X POST https://streamwake.polsia.io/api/v1/streams \
  -H "content-type: application/json" \
  -b "better-auth.session_token=<your-session-cookie>" \
  -d '{
      "sourceUrl": "https://example.com/manifest.m3u8"
    }'
201 Response — StreamItem
{
  "id": "ckq3xstreamabc123",
  "sourceUrl": "https://example.com/manifest.m3u8",
  "name": "Primary CDN — eu-west",
  "targetRegion": "eu-west",
  "createdAt": "2026-08-03T18:24:11.000Z",
  "agentState": "healthy",
  "status": "watching",
  "lastAction": "registered",
  "lastCheckedAt": null,
  "uptimePct": 100
}
Step 03Read

Read the monitor record

The id from step two is your handle. GET it back to see the current StreamStatus.

Note that uptimePct is computed server-side from the last 24 hours of StreamProbe rows — so right after registration it's 100 (no failures observed yet) and it starts to drift as the cron samples the manifest.

GET /api/v1/streams/<id>
curl https://streamwake.polsia.io/api/v1/streams/ckq3xstreamabc123 \
  -b "better-auth.session_token=<your-session-cookie>"
200 Response — StreamStatus
{
  "id": "ckq3xstreamabc123",
  "sourceUrl": "https://example.com/manifest.m3u8",
  "agentState": "healthy",
  "uptimePct": 100,
  "lastAction": "registered",
  "lastCheckedAt": "2026-08-03T18:25:00.000Z"
}
Step 04Observe

Confirm the stream shows as watched

A cron job — probe-streams in polsia.toml — runs every minute and writes a new StreamProbe row per stream. The streams dashboard at /app/streams polls /api/v1/streams and renders one row per stream with the toneClasses() status pill. The row's uptimePct is computed from the same 24-hour window.

For programmatic confirmation, /api/v1/agents surfaces the same probes as a feed — useful when you want to wire a webhook or a custom alert.

What you'll see
watching
Primary CDN — eu-west
Uptime 24h
100%
Last action
registered
Checked
just now
Open /app/streams
GET /api/v1/agents — programmatic counterpart
curl https://streamwake.polsia.io/api/v1/agents \
  -b "better-auth.session_token=<your-session-cookie>"
200 Response — AgentEventList
{
  "items": [
    {
      "id": "ckq3xprobe123",
      "streamId": "ckq3xstreamabc123",
      "sourceUrl": "https://example.com/manifest.m3u8",
      "streamName": "Primary CDN — eu-west",
      "severity": "info",
      "anomalyClass": "no anomaly",
      "fix": "registered",
      "action": "no action needed — stream healthy",
      "createdAt": "2026-08-03T18:25:00.000Z",
      "latencyMs": 142
    },
    {
      "id": "ckq3xprobe124",
      "streamId": "ckq3xstreamdef456",
      "sourceUrl": "https://backup.example.com/manifest.m3u8",
      "streamName": "Backup CDN — eu-west",
      "severity": "warn",
      "anomalyClass": "slow response",
      "fix": "raised the latency budget and re-probed to confirm the trend",
      "action": "raised the latency budget and re-probed to confirm the trend",
      "createdAt": "2026-08-03T18:25:00.000Z",
      "latencyMs": 1840
    }
  ]
}
Step 05Operate

Continue in the dashboard

The page you just opened is the streams dashboard. It polls /api/v1/streams every 5 seconds and gates the route with the same cookie session you used above — signed in once, every surface reads it.

From here you can register additional streams, drill into a per-stream report, and watch new probes land in the agents feed. The same loop runs across /app/agents and /app/integrations.

Open /app/streams

Same cookie, same session. If the route redirects you to /sign-in, your session cookie is missing — repeat step one.

Next steps

You have the loop.
Now operate it.

The page you just landed on in step five

Streams dashboard

See every registered stream, its current state, and the last action the agent took. Auth-gated.

Open /app/streams
Live observations

Agents feed

The latest probes, severity, latency, and the action the agent took. Auth-gated.

Open /app/agents

Want the API in one place?

The reference is on its own page — three endpoints, exact shapes, copy-paste curls.

Open the API reference