Files
documentation/stream-api/reference/operations.md
2026-11-15 17:34:41 -08:00

3.5 KiB

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. Both /health and /api/health are supported.

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

{
  "note": "This is a health check endpoint. This is extremely unreliable, be sure to test sources directly.",
  "status": "ok",
  "timestamp": "2026-11-15T12:00:00.000Z",
  "sources": {
    "vidlink": { "ok": true, "latency": 350 },
    "vixsrc": { "ok": true, "latency": 480 },
    "cinecat": { "ok": false, "latency": 15000 }
  }
}

Test Directory: GET /test

Calling GET /test or GET /api/test returns auto-generated test URLs for every registered source:

GET /test HTTP/1.1
Host: api.vyla.cc
{
  "vidlink": {
    "movie": "/api/test/155?source=vidlink",
    "tv": "/api/test/1396?season=1&episode=1&source=vidlink"
  },
  "vixsrc": {
    "movie": "/api/test/155?source=vixsrc",
    "tv": "/api/test/1396?season=1&episode=1&source=vixsrc"
  }
}

Direct Source Testing: GET /test/:tmdb_id

Tests a single scraper directly without triggering all other providers. Supports /test/:id and /api/test/:id.

Movie Test

GET /api/test/155?source=vidlink HTTP/1.1
Host: api.vyla.cc

Parameters:

  • tmdb_id (path, required) — Numeric TMDB ID (e.g. 155).
  • source (query, required) — Source key to test (e.g. vidlink).

TV Episode Test

GET /api/test/1396?season=1&episode=1&source=vidlink HTTP/1.1
Host: api.vyla.cc

Parameters:

  • tmdb_id (path, required) — Numeric TMDB Series ID (e.g. 1396).
  • source (query, required) — Source key to test (e.g. vidlink).
  • season or s (query, required) — Season number (e.g. 1).
  • episode or e (query, required) — Episode number (e.g. 1).

Response Example

{
  "source": "vidlink",
  "ok": true,
  "stream": {
    "url": "https://api.vyla.cc/api?url=https%3A%2F%2Fupstream.example.com%2Fmaster.m3u8",
    "quality": "1080p",
    "type": "hls",
    "server": "vidlink-cf"
  }
}

Deep Debug Route: GET /debug/:tmdb_id

Exposes diagnostic internals when ENABLE_DEBUG_ROUTE=true is enabled in .env:

GET /api/debug/155?source=vidlink HTTP/1.1
Host: api.vyla.cc

Diagnostics Returned:

  • Raw HTML and JSON payloads from upstream providers.
  • Resolution latency and DOM parsing metrics.
  • Upstream HTTP status codes and headers from probe checks.
  • First 500 bytes of upstream playlist manifests.
  • Rewritten proxy segment URLs.

:::callout-warning Keep ENABLE_DEBUG_ROUTE=false in production to prevent leaking upstream tokens and API keys. :::


Cluster & Cache Architecture

  • In-Memory Cache: Up to 1,500 entries stored in primary process memory with a 5-minute TTL (CACHE_TTL).
  • Pruning Timer: Runs automatically every 30 seconds to purge expired entries and maintain cache boundaries.
  • Worker Management: Cluster primary supervises worker processes, automatically respawning workers on process exit.
  • IPC Synchronization: Workers communicate through cache:get, cache:set, and cache:push IPC messages for fast cross-process cache hits.