# Server and models

These requests need no video. Use them to check that a server is up, which formats it renders and which models it can reach with the keys it has.

## Health

**Check the server** (`GET /api/v1/health`): Version, runtime, formats, and every provider and rung with whether it is enabled.

```bash
curl https://vid2context.com/api/v1/health
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```json
{
  "ok": true,
  "name": "vid2context",
  "version": "0.1.0",
  "runtime": "node",
  "formats": [
    {
      "id": "text",
      "description": "Plain transcript text. With timestamps, one \"[m:ss] line\" per caption.",
      "mimeType": "text/plain; charset=utf-8"
    },
    {
      "id": "json",
      "description": "The full VideoContext as JSON: metadata, chapters, timed segments, and how it was produced.",
      "mimeType": "application/json"
    },
    {
      "id": "markdown",
      "description": "Markdown transcript: title and metadata, chapters as headings, paragraphs prefixed with timestamp links. Options: linkTimestamps, includeComments, includeVisual.",
      "mimeType": "text/markdown; charset=utf-8"
    },
    {
      "id": "srt",
      "description": "SubRip (.srt) captions: at most 2 lines of 42 characters per cue, no overlaps, for players and editors.",
      "mimeType": "application/x-subrip; charset=utf-8"
    },
    {
      "id": "vtt",
      "description": "WebVTT (.vtt) captions for the HTML <track> element, with speaker voice tags when known.",
      "mimeType": "text/vtt; charset=utf-8"
    },
    {
      "id": "pack",
      "description": "Context pack: one Markdown file for one or many videos, written for an AI model to read, with citation instructions. Options: maxTokens, includeComments, includeVisual, linkTimestamps.",
      "mimeType": "text/markdown; charset=utf-8"
    }
  ],
  "providers": [
    {
      "id": "bilibili",
```

(881 more lines; run the request to see them.)
`enabled` on a rung means its credentials are present and its tier is allowed. Keyless rungs need nothing, so a fresh server can already transcribe and answer questions.

## Readiness

`/healthz` is for container probes. Without `deep` it only says the process is up, which is what a liveness probe wants. With `deep=1` it checks everything a request needs and answers `503` when a required check fails, so a readiness probe holds traffic until the server can serve it.

**Readiness for a container probe** (`GET /api/v1/healthz`): Without deep it only says the process is up. With deep=1 it checks storage, rungs, disk, yt-dlp, ffmpeg and the network, and answers 503 when a required check fails.

```bash
curl -G https://vid2context.com/api/v1/healthz \
  --data-urlencode deep=1
```

Response recorded on 2026-11-15 (HTTP 200 OK):

```json
{
  "ok": true,
  "status": "ok",
  "checkedAt": "2026-11-15T15:29:16.862Z",
  "checks": [
    {
      "id": "storage",
      "status": "ok",
      "detail": "sqlite: write, read and delete ok",
      "required": true
    },
    {
      "id": "rungs",
      "status": "ok",
      "detail": "4 speech-to-text and 7 LLM rungs enabled, first stt/cloudflare/@cf/openai/whisper-large-v3-turbo and llm/cloudflare/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "required": true
    },
    {
      "id": "disk",
      "status": "ok",
      "detail": "774948 MB free in the data directory",
      "required": true
    },
    {
      "id": "yt-dlp",
      "status": "ok",
      "detail": "2026.10.26",
      "required": false
    },
    {
      "id": "ffmpeg",
      "status": "ok",
      "detail": "7.0.2-static",
      "required": false
    },
    {
      "id": "network",
      "status": "ok",
      "detail": "oai.endpoints.kepler.ai.cloud.ovh.net answered HTTP 200",
      "required": false
```

(4 more lines; run the request to see them.)
## Formats

**List the output formats** (`GET /api/v1/formats`)

```bash
curl https://vid2context.com/api/v1/formats
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```json
{
  "formats": [
    {
      "id": "text",
      "description": "Plain transcript text. With timestamps, one \"[m:ss] line\" per caption.",
      "mimeType": "text/plain; charset=utf-8",
      "extension": "txt"
    },
    {
      "id": "json",
      "description": "The full VideoContext as JSON: metadata, chapters, timed segments, and how it was produced.",
      "mimeType": "application/json",
      "extension": "json"
    },
    {
      "id": "markdown",
      "description": "Markdown transcript: title and metadata, chapters as headings, paragraphs prefixed with timestamp links. Options: linkTimestamps, includeComments, includeVisual.",
      "mimeType": "text/markdown; charset=utf-8",
      "extension": "md"
    },
    {
      "id": "srt",
      "description": "SubRip (.srt) captions: at most 2 lines of 42 characters per cue, no overlaps, for players and editors.",
      "mimeType": "application/x-subrip; charset=utf-8",
      "extension": "srt"
    },
    {
      "id": "vtt",
      "description": "WebVTT (.vtt) captions for the HTML <track> element, with speaker voice tags when known.",
      "mimeType": "text/vtt; charset=utf-8",
      "extension": "vtt"
    },
    {
      "id": "pack",
      "description": "Context pack: one Markdown file for one or many videos, written for an AI model to read, with citation instructions. Options: maxTokens, includeComments, includeVisual, linkTimestamps.",
      "mimeType": "text/markdown; charset=utf-8",
      "extension": "md"
    }
  ]
}
```
## Models

**List the models** (`GET /api/v1/models`): Every rung, enabled or not. requires names env vars, never their values.

```bash
curl -G https://vid2context.com/api/v1/models \
  --data-urlencode kind=stt
```

Response recorded on 2026-11-14 (HTTP 200 OK):

```json
{
  "models": [
    {
      "id": "stt/cloudflare-binding/@cf/openai/whisper-large-v3-turbo",
      "kind": "stt",
      "label": "whisper-large-v3-turbo",
      "service": "cloudflare-binding",
      "provider": "cloudflare-ai-stt",
      "model": "@cf/openai/whisper-large-v3-turbo",
      "tier": "free",
      "quality": 4,
      "capabilities": [
        "segments",
        "words",
        "language-detect",
        "prompt"
      ],
      "enabled": false,
      "requires": [
        "CLOUDFLARE_AI_BINDING"
      ]
    },
    {
      "id": "stt/cloudflare-binding/@cf/openai/whisper",
      "kind": "stt",
      "label": "whisper",
      "service": "cloudflare-binding",
      "provider": "cloudflare-ai-stt",
      "model": "@cf/openai/whisper",
      "tier": "free",
      "quality": 2,
      "capabilities": [
        "segments",
        "words"
      ],
      "enabled": false,
      "requires": [
        "CLOUDFLARE_AI_BINDING"
      ]
    },
```

(219 more lines; run the request to see them.)
Pick a kind to narrow the list. The same rows, grouped by tier, are in [Providers and rungs](https://vid2context.com/docs/providers.md).
