Skip to content

Endpoints

GET /api/health

Health check with version and update information. Always reachable without auth.

curl http://localhost:8786/api/health

{
  "status": "ok",
  "version": "4.0.0",
  "update_check": {
    "update_available": false,
    "current_version": "4.0.0",
    "latest_version": null
  }
}

GET /api/services

List all available streaming services (filtered by the effective allowlist for the caller).

curl -H "X-Secret-Key: $KEY" http://localhost:8786/api/services

Returns {"services": [...]}. Each entry has tag, aliases, geofence, title_regex, url (from cli.short_help), help (full docstring), and cli_params describing the service-level Click parameters.

POST /api/search

Search for titles from a streaming service.

Required parameters: | Parameter | Type | Description | | --- | --- | --- | | service | string | Service tag | | query | string | Search query |

Optional parameters: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | profile | string | null | Profile for credentials/cookies | | proxy | string | null | Proxy URI or country code | | no_proxy | boolean | false | Disable all proxy use |

curl -X POST http://localhost:8786/api/search \
  -H "X-Secret-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "EXAMPLE1", "query": "example show"}'

{
  "results": [
    {
      "id": "abc123def456",
      "title": "Example Show",
      "description": null,
      "label": "TV Show",
      "url": "https://example.com/show/abc123def456"
    }
  ],
  "count": 1
}

POST /api/list-titles

Get available titles (seasons/episodes/movies) for a service and title ID. Disabled in --remote-only mode.

Required parameters: | Parameter | Type | Description | | --- | --- | --- | | service | string | Service tag | | title_id | string | Title ID or URL |

curl -X POST http://localhost:8786/api/list-titles \
  -H "X-Secret-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"service": "EXAMPLE1", "title_id": "abc123def456"}'

POST /api/list-tracks

Get video, audio, and subtitle tracks for a title. Disabled in --remote-only mode.

Required parameters: | Parameter | Type | Description | | --- | --- | --- | | service | string | Service tag | | title_id | string | Title ID or URL |

Optional parameters: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | wanted | array | all | Episode filter (e.g., ["S01E01"]) | | profile | string | null | Profile for credentials/cookies | | proxy | string | null | Proxy URI or country code | | no_proxy | boolean | false | Disable all proxy use |

Returns video, audio, and subtitle tracks with codec, bitrate, resolution, language, and DRM information.

POST /api/download

Start a download job. Returns immediately with a job ID (HTTP 202). Disabled in --remote-only mode.

Required parameters: | Parameter | Type | Description | | --- | --- | --- | | service | string | Service tag | | title_id | string | Title ID or URL |

Quality and codec parameters: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | quality | array[int] | best | Resolution(s) (e.g., [1080, 2160]) | | vcodec | string or array | any | Video codec(s): H264, H265/HEVC, VP9, AV1, VC1, VP8 | | acodec | string or array | any | Audio codec(s): AAC, AC3, EC3, AC4, OPUS, FLAC, ALAC, DTS, OGG | | vbitrate | int | highest | Video bitrate in kbps | | abitrate | int | highest | Audio bitrate in kbps | | range | array[string] | ["SDR"] | Color range(s): SDR, HDR10, HDR10+, HLG, DV, HYBRID | | channels | float | any | Audio channels (e.g., 5.1, 7.1) | | no_atmos | boolean | false | Exclude Dolby Atmos tracks | | split_audio | boolean | null | Create separate output per audio codec | | sub_format | string | null | Output subtitle format: SRT, VTT, ASS, SSA, TTML |

Episode selection: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | wanted | array[string] | all | Episodes (e.g., ["S01E01", "S01E02-S01E05"]) | | latest_episode | boolean | false | Download only the most recent episode |

Language parameters: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | lang | array[string] | ["orig"] | Language for video and audio (orig = original) | | v_lang | array[string] | [] | Language override for video tracks only | | a_lang | array[string] | [] | Language override for audio tracks only | | s_lang | array[string] | ["all"] | Language for subtitles | | require_subs | array[string] | [] | Required subtitle languages (skip if missing) | | forced_subs | boolean | false | Include forced subtitle tracks | | exact_lang | boolean | false | Exact language matching (no variants) |

Track selection: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | video_only | boolean | false | Only download video tracks | | audio_only | boolean | false | Only download audio tracks | | subs_only | boolean | false | Only download subtitle tracks | | chapters_only | boolean | false | Only download chapters | | no_video | boolean | false | Skip video tracks | | no_audio | boolean | false | Skip audio tracks | | no_subs | boolean | false | Skip subtitle tracks | | no_chapters | boolean | false | Skip chapters | | audio_description | boolean | false | Include audio description tracks |

Output and tagging: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | tag | string | null | Override group tag | | repack | boolean | false | Add REPACK tag to filename | | tmdb_id | int | null | Use specific TMDB ID for tagging | | imdb_id | string | null | Use specific IMDB ID (e.g., tt1375666) | | animeapi_id | string | null | Anime database ID via AnimeAPI (e.g., mal:12345) | | enrich | boolean | false | Override show title and year from external source | | no_folder | boolean | false | Disable folder creation for TV shows | | no_source | boolean | false | Remove source tag from filename | | no_mux | boolean | false | Do not mux tracks into container | | output_dir | string | null | Override output directory |

Download behavior: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | profile | string | null | Profile for credentials/cookies | | proxy | string | null | Proxy URI or country code | | no_proxy | boolean | false | Disable all proxy use | | no_proxy_download | boolean | false | Bypass proxy for segment downloads only. Manifest, license, and auth still use proxy | | workers | int | null | Max threads per track download | | downloads | int | 1 | Concurrent track downloads | | slow | boolean or string | null | Add randomized delay between titles. true = 60-120s, or "MIN-MAX" string (e.g., "20-40"). Min must be >= 20 | | best_available | boolean | false | Continue if requested quality unavailable | | worst | boolean | false | Select the lowest bitrate track within the specified quality. Requires quality | | skip_dl | boolean | false | Skip download, only get decryption keys | | export | boolean | false | Export manifest, track URLs, keys, and subtitles to JSON in the exports directory | | cdm_only | boolean | null | Only use CDM (true) or only vaults (false) | | no_cache | boolean | false | Bypass title cache | | reset_cache | boolean | false | Clear title cache before fetching |

Example:

curl -X POST http://localhost:8786/api/download \
  -H "X-Secret-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "EXAMPLE1",
    "title_id": "abc123def456",
    "wanted": ["S01E01"],
    "quality": [1080, 2160],
    "vcodec": ["H265"],
    "acodec": ["AAC", "EC3"],
    "range": ["HDR10", "SDR"],
    "split_audio": true,
    "lang": ["en"]
  }'

{
  "job_id": "504db959-80b0-446c-a764-7924b761d613",
  "status": "queued",
  "created_time": "2026-02-27T18:00:00.000000"
}

GET /api/download/jobs

List all download jobs with optional filtering and sorting. Disabled in --remote-only mode.

Query parameters: | Parameter | Type | Default | Description | | --- | --- | --- | --- | | status | string | all | Filter by status: queued, downloading, completed, failed, cancelled | | service | string | all | Filter by service tag | | sort_by | string | created_time | Sort field: created_time, started_time, completed_time, progress, status, service | | sort_order | string | desc | Sort order: asc, desc |

curl -H "X-Secret-Key: $KEY" "http://localhost:8786/api/download/jobs?status=completed"

GET /api/download/jobs/{job_id}

Get detailed information about a specific download job including progress, parameters, and error details.

{
  "job_id": "504db959-80b0-446c-a764-7924b761d613",
  "status": "completed",
  "created_time": "2026-02-27T18:00:00.000000",
  "service": "EXAMPLE1",
  "title_id": "abc123def456",
  "progress": 100.0,
  "parameters": { },
  "started_time": "2026-02-27T18:00:01.000000",
  "completed_time": "2026-02-27T18:00:15.000000",
  "output_files": [],
  "error_message": null,
  "error_details": null
}

DELETE /api/download/jobs/{job_id}

Cancel a queued or running download job. Returns 400 if the job has already terminated.