Health, testing, and safe operations

Observe SDK providers and diagnose a Stream API deployment without making debug data public.

Health

GET /health (or /api/health) probes active providers and returns a JSON summary. It includes a status, timestamp, TMDB-key presence, cache size, and a map of provider keys to { ok, ms } results.

Health is a signal, not a promise of playback. Provider behavior can differ by title, client network, and the moment of the request. Use it for observability and source selection—not as a guarantee that a viewer will receive a stream.

Test one provider

GET /test/:id?source=:providerKey resolves a single provider for a movie. Add season and episode (or s and e) for TV. 

curl "http://localhost:7860/test/155?source=provider-key"
curl "http://localhost:7860/test/1396?season=1&episode=1&source=provider-key"

Use source keys reported by the running deployment. A test result reports whether resolution and verification succeeded; clients should inspect the result body rather than relying only on a transport success.

Debug route

GET /debug/:id?source=:providerKey offers detailed candidate and request traces, but it is only available when ENABLE_DEBUG_ROUTE=true.

Do not enable the debug route on a public deployment. It can expose upstream request data, raw candidates, and headers. Enable it temporarily in a controlled environment, then disable it again.

Production checklist

  • Set TMDB_API_KEY when metadata-dependent sources are required.
  • Keep ENABLE_DEBUG_ROUTE=false outside controlled troubleshooting.
  • Use TLS and enforce your own access policy before making the service remotely reachable.
  • Monitor health trends and playback failures separately.
  • Run updates and provider changes through your normal deployment process.
  • Build player fallbacks instead of assuming a specific provider is always available.