HTTP API

RelayTV companion apps use the same local HTTP surface available to scripts and custom clients. This page is an orientation; the server repository owns the complete API contract.

Base URL and authentication

http://YOUR_RELAYTV_HOST:8787

When RELAYTV_API_TOKEN is enabled:

Authorization: Bearer YOUR_TOKEN

Do not put tokens in query strings.

Health

curl -fsS http://YOUR_RELAYTV_HOST:8787/health

Smart play

Queues when media is already playing; otherwise starts playback:

curl -X POST http://YOUR_RELAYTV_HOST:8787/smart \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/video"}'

Immediate playback

Endpoint names have compatibility history and can differ in whether current queue state is preserved. Consult the complete API reference before wiring an automation that may clear a queue.

Other capability groups

• current status and realtime capability discovery
• playback controls and absolute seeking
• queue inspection and mutation
• text/image overlays
• current-frame snapshots
• temporary playback and resume flows
• scheduled/synchronized start
• local media ingest, play, and enqueue
• peer RelayTV device operations

Client guidance

• Set connection and read timeouts.
• Treat non-2xx responses as meaningful failures.
• Do not retry state-changing requests without considering duplicate effects.
• Refresh authoritative status after reconnecting to a realtime stream.
• Redact credentials and private media URLs from logs.

Canonical server source: HTTP API. Reviewed 2026-08-29.