> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vyla.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Health Check

> Probe all configured providers in real time and get per-source latency and status.

The health endpoint probes every active provider using a known-good TMDB ID and reports whether each one is up, along with the response time in milliseconds. No query parameters needed.

<Note>
  Health checks are **not cached**. Each call triggers a fresh live probe of all active providers — expect a response time of 2–10 seconds depending on provider count and speed.
</Note>

This endpoint accepts any valid API key (including `public`) or a session token from `POST /api/auth`.

***

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://1c34-y.hf.space/api/health \
    -H "Authorization: Bearer public_api_key"
  ```

  ```javascript JavaScript theme={null}
  const res  = await fetch('https://1c34-y.hf.space/api/health', {
    headers: {
      Authorization: 'Bearer public_api_key'
    }
  });
  const data = await res.json();

  if (data.status !== 'ok') {
    const down = Object.entries(data.sources)
      .filter(([, v]) => !v.ok)
      .map(([k]) => k);
    console.warn('Degraded providers:', down);
  }
  ```

  ```python Python theme={null}
  import requests

  data = requests.get(
    'https://1c34-y.hf.space/api/health',
    headers={
      'Authorization': 'Bearer public_api_key'
    }
  ).json()
  print(data['status'])

  for source, info in data['sources'].items():
      status = '✓' if info['ok'] else '✗'
      ms = info['ms'] or 'N/A'
      print(f'  {status} {source}: {ms}ms')
  ```

  ```typescript TypeScript theme={null}
  interface SourceHealth {
    ok: boolean;
    ms: number | null;
  }

  interface HealthResponse {
    status: 'ok' | 'degraded';
    timestamp: string;
    tmdb: boolean;
    cache: number;
    probe_id: string;
    sources: Record<string, SourceHealth>;
  }

  const data: HealthResponse = await fetch(
    'https://1c34-y.hf.space/api/health',
    {
      headers: {
        Authorization: 'Bearer public_api_key'
      }
    }
  ).then(r => r.json());
  ```
</CodeGroup>

***

## Response Fields

<ResponseField name="status" type="string" required>
  Overall health of the API.

  * `"ok"` — all providers returned a valid stream
  * `"degraded"` — one or more providers failed; others still work
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  ISO 8601 timestamp of when the health check was run.
</ResponseField>

<ResponseField name="tmdb" type="boolean" required>
  Whether a `TMDB_API_KEY` is configured. `false` means the `meta` field will be `null` in movie and TV responses.
</ResponseField>

<ResponseField name="cache" type="number" required>
  Number of entries currently in the in-memory stream cache.
</ResponseField>

<ResponseField name="probe_id" type="string" required>
  The TMDB ID used to probe all providers during this health check.
</ResponseField>

<ResponseField name="sources" type="object" required>
  Per-provider health results, keyed by provider key.

  <Expandable title="Per-source object">
    <ResponseField name="ok" type="boolean">
      `true` if the provider returned a valid, playable HLS stream during this probe.
    </ResponseField>

    <ResponseField name="ms" type="number | null">
      Response time in milliseconds. `null` if the probe threw an error before a response was received.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Responses

<Tabs>
  <Tab title="200 — All OK">
    All providers are live and returned valid streams.

    ```json theme={null}
    {
      "status": "ok",
      "timestamp": "2025-06-01T12:00:00.000Z",
      "tmdb": true,
      "cache": 12,
      "probe_id": "155",
      "sources": {
        "provider-a": { "ok": true, "ms": 1204 },
        "provider-b": { "ok": true, "ms": 980  },
        "provider-c": { "ok": true, "ms": 2100 }
      }
    }
    ```
  </Tab>

  <Tab title="207 — Degraded">
    One or more providers failed. HTTP status is `207 Multi-Status`. Working sources are still usable.

    ```json theme={null}
    {
      "status": "degraded",
      "timestamp": "2025-06-01T12:00:00.000Z",
      "tmdb": true,
      "cache": 4,
      "probe_id": "155",
      "sources": {
        "provider-a": { "ok": true,  "ms": 1204 },
        "provider-b": { "ok": false, "ms": 435  },
        "provider-c": { "ok": false, "ms": 1138 }
      }
    }
    ```
  </Tab>
</Tabs>

***

## Status Reference

| HTTP  | `status` field | Meaning                           |
| ----- | -------------- | --------------------------------- |
| `200` | `"ok"`         | All providers healthy             |
| `207` | `"degraded"`   | At least one provider down        |
| `401` | —              | Missing or invalid authentication |

<Warning>
  A `207 Degraded` response does **not** mean the API is unusable. Movie and TV endpoints will still return sources from whichever providers are working. Check `data.sources.length > 0` rather than depending on `status === "ok"` when deciding whether to proceed.
</Warning>