documentation/stream-api/reference/operations.md

Operations, Health & Diagnostics

Monitoring, cluster diagnostics, live health probing, and testing endpoints in Stream API.

Health Check: GET /health

Runs responsiveness checks across registered scraper modules.

GET /health HTTP/1.1
Host: api.vyla.cc

Status Codes

• 200 OK: All active scrapers passed their health probes.
• 207 Multi-Status: One or more providers failed (degraded state), but the gateway is functional.

Response Payload

{
  "status": "ok",
  "timestamp": "2026-11-14T20:30:00.000Z",
  "tmdb": true,
  "cache": 142,
  "probe_id": 155,
  "sources": {
    "vidlink": { "ok": true, "ms": 420 },
    "vixsrc": { "ok": true, "ms": 610 },
    "cinecat": { "ok": true, "ms": 890 },
    "movy": { "ok": false, "ms": null }
  }
}

Key Fields:

• status: Overall state ("ok" or "degraded").
• timestamp: ISO 8601 probe timestamp.
• tmdb: True if TMDB_API_KEY is configured and responding.
• cache: Current number of active cached titles in LRU memory.
• probe_id: The TMDB ID used for the probe query.
• sources: Dictionary of per-source availability (ok) and roundtrip latency in milliseconds (ms).

---

Direct Source Testing: GET /test/:source

Tests a single scraper directly without triggering all other providers:

GET /test/vidlink?id=155 HTTP/1.1

For television episodes, include season and episode:

GET /test/vixsrc?id=1396&s=1&e=1 HTTP/1.1

Response

Returns the raw candidate stream resolved by that scraper:

{
  "source": "vidlink",
  "url": "https://upstream.example.com/playlist.m3u8",
  "quality": "1080p",
  "type": "hls",
  "server": "vidlink-cf"
}

---

Deep Debug Route: GET /debug/:source

Exposes diagnostic internals when ENABLE_DEBUG_ROUTE=true is set:

GET /debug/vidlink?id=155 HTTP/1.1

Output details:

• Raw HTML or JSON received from upstream hosts.
• Time spent solving tokens and parsing DOM.
• Status code and headers from Phase 1 verification (HEAD check).
• First 500 bytes of the master M3U8 manifest.
• Preview of rewritten segment URLs.

:::callout-warning Keep ENABLE_DEBUG_ROUTE=false in production to prevent leaking upstream tokens or credentials. :::

---

Cluster & Cache Architecture

• In-Memory Cache: Up to 1,500 verified titles stored in an LRU cache with a 5-minute TTL.
• Cache Pruner: Runs every 30 seconds to evict expired keys.
• Worker Lifecycle: The supervisor process maintains workers matching CPU core count, automatically replacing crashed processes.
• IPC Messaging: Workers coordinate via cache:get and cache:set messages, allowing instant cache hits across worker boundaries without an external database.