Stream All Day API

Overview

The API is a small set of authenticated REST endpoints under https://streamallday.live/api. Everything you can do in the dashboard — list your library, disable/delete VODs, set the play order — is available through these endpoints. There's no separate "API plan" or paid tier; it's included.

The base URL is always https://streamallday.live. All endpoints accept and return JSON. All endpoints are scoped to your own account — there is no way for one customer's key to see or touch another customer's data.

Authentication

Every request needs an API key. Create one in your dashboard under "API access" — give it a name, copy the key (you'll only see it once), and pass it on every request with the Authorization header:

curl https://streamallday.live/api/me \
  -H "Authorization: Bearer sad_live_abc123..."

Keys are prefixed with sad_live_ so GitHub's secret scanner can detect leaked keys in public repos. If a key leaks, revoke it from the dashboard — the prefix is shown so you can identify which one to kill.

Keys can be revoked at any time. Revoked keys return 401 not_authenticated immediately.

Rate limits

60 requests per minute per key, refilled continuously (about one request per second). Most automations use a fraction of this — the limit is here to prevent runaway loops from hammering the SAD server.

Every response includes a X-RateLimit-Remaining header. If you exceed the limit, you'll get 429 rate_limit_exceeded with a Retry-After header (in seconds) and a JSON body like {"error": "rate_limit_exceeded", "retry_after": 12}. Wait that long, then retry.

Errors

Standard HTTP status codes, with a JSON body containing an error field (a short machine-readable code) and sometimes a detail field with a human-readable explanation.

The VOD library

Your library is the set of mp4 files we've downloaded from your Twitch archive. There are three states a VOD can be in:

Each VOD has a stable vod_id — the numeric Twitch VOD ID parsed out of the filename. This is what every endpoint uses to identify a VOD.

The play queue

Your stream client reads from a single playlist file. The play order can be:

• Shuffle mode (default) — we randomize the order at startup and reshuffle each time the cycle wraps. Best for "set it and forget it" channels.
• Manual mode — your order is preserved forever. When the cycle wraps, we loop back to the top in the same order. When new VODs are ingested by the daily cron, they're appended to the end of your queue (never inserted randomly).

Any queue edit auto-switches to manual mode. If you PUT /api/queue or use play-next, your channel will stay in manual mode until you explicitly call POST /api/queue/reset.

The cursor (cursor field) is the 1-indexed line number of the currently-playing entry. It advances each time a VOD finishes. You can use it to know what's playing right now and what's coming up.

Shuffle vs. manual

These two modes have different ergonomics, so it's worth being deliberate about which you want.

VOD lifecycle

Every day at 4 AM server time, a cron runs the ingest pipeline. For each customer it:

1. Calls yt-dlp to fetch your latest Twitch VOD (one per run).
2. Prunes the oldest mp4 if you're over the 240GB archive limit.
3. If no new VOD was available, tries to "reseed" an older VOD you previously had (unless you deleted it via the API).

If you're in manual mode, newly-ingested VODs are appended to your queue. If you're in shuffle mode, the whole playlist is reshuffled on the streamer's next library check.

Twitch deletes non-affiliate VODs after 14 days and affiliate VODs after 60 days. Once they're gone from Twitch, we can't re-download them — but our copy on disk is unaffected and will keep playing for as long as you want.

Endpoints

curl https://streamallday.live/api/me \
  -H "Authorization: Bearer $SAD_KEY"

{
  "client_code": "CX260001",
  "vods": [
    {
      "filename": "20260513_v2770615914.mp4",
      "vod_id": "2770615914",
      "date": "2026-05-13",
      "title": "Marvel Monday",
      "disabled": false
    },
    ...
  ]
}

curl -X POST https://streamallday.live/api/vods/2770615914/disable \
  -H "Authorization: Bearer $SAD_KEY"

curl -X DELETE https://streamallday.live/api/vods/2770615914 \
  -H "Authorization: Bearer $SAD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": "DELETE"}'

{
  "client_code": "CX260001",
  "mode": "manual",
  "cursor": 3,
  "queue": [
    { "filename": "...", "vod_id": "...", "date": "...", "title": "..." },
    ...
  ]
}

curl -X PUT https://streamallday.live/api/queue \
  -H "Authorization: Bearer $SAD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order": ["20260513_v2770615914.mp4", "20260512_v2770550045.mp4"]}'

curl -X POST https://streamallday.live/api/stream/start \
  -H "Authorization: Bearer $SAD_KEY"

curl -X POST https://streamallday.live/api/stream/stop \
  -H "Authorization: Bearer $SAD_KEY"

{
  "used_bytes": 142836429120,
  "cap_bytes": 257698037760,
  "vod_count_active": 18,
  "vod_count_disabled": 2
}

curl -X POST https://streamallday.live/api/uploads \
  -H "Authorization: Bearer $SAD_KEY" \
  -F "file=@my_vod.mp4;type=video/mp4" \
  -F "title=Marvel Monday Special" \
  -F "date=2026-05-24"

{
  "ok": true,
  "filename": "20260524_uABC12345.mp4",
  "size_bytes": 5234896127,
  "title": "Marvel Monday Special"
}

{
  "masked": "live_1454850409_…iHKm",
  "history": [
    {
      "masked": "live_1454850409_…abcd",
      "retired_at": "2026-04-12T10:14:00Z",
      "replaced_by_source": "web"
    }
  ]
}

curl -X POST https://streamallday.live/api/stream-key \
  -H "Authorization: Bearer $SAD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "live_1454850409_NEW_KEY_HERE"}'

{
  "ok": true,
  "masked": "live_1454850409_…HERE",
  "restarted": true,
  "history": [ ... ]
}

Recipes

Auto-disable VODs older than 60 days

Cron this to run nightly. Keeps your rotation fresh without deleting anything irreversibly.

#!/usr/bin/env python3
import os, requests
from datetime import date, timedelta

KEY = os.environ["SAD_KEY"]
BASE = "https://streamallday.live"
H = {"Authorization": f"Bearer {KEY}"}
CUTOFF = (date.today() - timedelta(days=60)).isoformat()

vods = requests.get(f"{BASE}/api/vods", headers=H).json()["vods"]
for v in vods:
    if not v["disabled"] and v["date"] and v["date"] < CUTOFF:
        print(f"disabling {v['vod_id']} from {v['date']}")
        requests.post(f"{BASE}/api/vods/{v['vod_id']}/disable", headers=H)

Run a Marvel-themed block at 8 PM

Filter your VODs by title, set them as the queue, and let the streamer play them in order. After it loops once, the next day's cron can reset to shuffle.

#!/usr/bin/env python3
import os, requests
KEY = os.environ["SAD_KEY"]
BASE, H = "https://streamallday.live", {"Authorization": f"Bearer {os.environ['SAD_KEY']}"}

vods = requests.get(f"{BASE}/api/vods", headers=H).json()["vods"]
marvel = [v["filename"] for v in vods
          if not v["disabled"] and v.get("title", "").lower().find("marvel") >= 0]

print(f"Setting {len(marvel)} Marvel VODs as the queue")
requests.put(f"{BASE}/api/queue", headers=H, json={"order": marvel})

Mirror "now playing" to Discord

Poll the queue every couple minutes; when the cursor changes, announce the new entry in a Discord channel via webhook.

#!/usr/bin/env python3
import os, time, requests
KEY = os.environ["SAD_KEY"]
DISCORD = os.environ["DISCORD_WEBHOOK"]
H = {"Authorization": f"Bearer {KEY}"}

last_cursor = None
while True:
    q = requests.get("https://streamallday.live/api/queue", headers=H).json()
    if q["cursor"] != last_cursor and q["queue"]:
        nowplaying = q["queue"][q["cursor"] - 1]
        title = nowplaying.get("title") or nowplaying["filename"]
        requests.post(DISCORD, json={"content": f"Now playing: **{title}**"})
        last_cursor = q["cursor"]
    time.sleep(120)

Changelog

• v1 (today) — Initial public API. Library, queue, mode toggle, mutations, audit logging on the server side.