HTTP API

HTTP API

Every management operation in the admin UI has a JSON API equivalent under /api/*. The API is the supported way to script TinyIce from CI, cron, or your own dashboards.

• Interactive docs (authoritative): /api/docs (Swagger UI)
• OpenAPI spec: /api/openapi.yaml

Treat /api/docs on your running instance as the source of truth for the complete, versioned endpoint list — it always matches the binary you're running. This page is an orientation, not an exhaustive catalogue.

Authentication

Caller	Mechanism
Web UI	Session cookie (set by /login).
Scripts / CI / integrations	Authorization: Bearer ti_…

Create a bearer token in Admin → API Tokens (shown once, stored hashed). Tokens carry a role and optional expiry — see Authentication and Users. Use a token, not your admin password, for automation.

Examples

TOKEN="ti_your_token_here"

# List streams (has_video=true when the mount carries H.264)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/streams

# Create a mount
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mount": "/radio", "password": "secret"}' \
  http://localhost:8000/api/streams

# Toggle visibility in place
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"mount":"/radio","visible":true}' http://localhost:8000/api/streams

# Server stats
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/stats

Stream management, AutoDJ (CRUD + transport), transcoders, relays, webhooks, users, and security all have JSON endpoints. Webhook and AutoDJ CRUD require the superadmin role (see Security).

Source ingest (Icecast protocol)

Not part of the JSON API — an Icecast 2 source client speaks its own protocol on the main port:

SOURCE /live HTTP/1.1
Host: server:8000
Authorization: Basic base64(source:<password>)
Ice-Name: My Station
Ice-Genre: Various
Content-Type: audio/mpeg

[raw audio data]

See Streaming Sources for RTMP, SRT, and WebRTC ingest.

Server-Sent Events

Two SSE streams push live state without polling:

Endpoint	Auth	Payload
/events	public	Array of visible streams: mount, name, listeners, bitrate, uptime, genre, description, song.
/admin/events	session	Full server snapshot every ~500 ms: byte counters, totals, per-stream stats and health, relays, streamers (AutoDJ state), runtime memory/goroutine/GC gauges, uptime.

Example public consumer:

const es = new EventSource("https://radio.example.com/events");
es.onmessage = (e) => console.log(JSON.parse(e.data));

/admin/events is what drives the dashboard; reconnects are de-duplicated so you don't get double event delivery.

Compatibility endpoints

Endpoint	Purpose
/status-json.xsl	Icecast-compatible stats JSON for existing tooling.
/{mount}.m3u · .m3u8 · .pls	Playlist files.

For Prometheus /metrics, see Observability (it lives on a separate internal port).

---

Next: Observability · Webhooks · Authentication and Users