Skip to content

Developer API

chodeus edited this page Oct 22, 2026 · 10 revisions

🏠 Home › REST API

REST API

A grouped index of CHUB's REST API. The complete, always-current reference is the OpenAPI UI at /docs on any running instance; the groups below are representative, not exhaustive.

On this page

Basics

  • Base path: /api (e.g. http://<host>:8000/api).
  • Auth: get a JWT from POST /api/auth/login, then send Authorization: Bearer <token> on every authenticated call. For SSE and image URLs (browsers can't set headers on EventSource or <img>), mint a short-lived stream token with POST /api/auth/stream-token and pass it as ?token=; a session JWT in the URL is refused. With the login turned off, no token is needed. Webhooks use a shared secret, not a JWT.
  • Request/response bodies are JSON. Responses use one envelope: {"success": true, "message": "…", "data": {…}} on success, {"success": false, "message": "…", "error_code": "…"} on error, with conventional status codes. Most list endpoints accept limit and offset.

Auth

  • GET /api/auth/status — is a login configured? (unauthenticated)
  • POST /api/auth/setup — create the login; only works while none is stored (first run, or after it was turned off).
  • POST /api/auth/login — exchange username/password for a JWT (rate-limited).
  • GET /api/auth/me — current user.
  • POST /api/auth/logout — acknowledge logout (stateless; the client drops its token).
  • POST /api/auth/stream-token — 5-minute token for ?token= on GET image/SSE routes.
  • POST /api/auth/disable — turn the login off; body {"password": "…"} (current password, rate-limited). Clears the credentials and the JWT secret, so every token stops working.

Setup

First-run wizard.

  • GET /api/setup/status — whether the wizard is complete (completed; unauthenticated).
  • POST /api/setup/complete — mark the wizard done.

Modules

  • GET /api/modules — list modules with enabled flag, last run, status.
  • GET /api/modules/run-states — run-state snapshot for every module.
  • GET /api/modules/status?module=<name> — current status of one module.
  • GET /api/modules/history / GET /api/modules/stats — recent runs / aggregate counters (per module: /api/modules/{name}/history, /stats).
  • GET /api/modules/events — SSE stream of run-state changes (?token=<stream token>).
  • GET /api/modules/{name} — full state for one module.
  • GET /api/modules/{name}/schema — config JSON schema (drives settings forms).
  • PUT /api/modules/{name}/config — replace a module's config block.
  • PATCH /api/modules/{name} — partial update (e.g. toggle enabled).
  • POST /api/modules/{name}/test — check a module's connectivity and config.
  • POST /api/modules/run / POST /api/modules/{name}/execute — queue a manual run.
  • GET /api/modules/{name}/status/{job_id} — live job status.
  • DELETE /api/modules/{name}/execution/{job_id} — request cooperative cancellation.

Gotcha: Cancellation is cooperative. Most modules stop on the next loop iteration; border_replacerr runs to completion and plex_maintenance is partial.

Media

  • GET /api/media/search — unified search across configured ARRs (query, type, genres, year_min/year_max, rating_min/rating_max, instance, matched, sort, order).
  • GET /api/media/stats — counters by period (7d/30d/90d/1y; omit for all time). GET /api/media/stats/detailed and GET /api/media/genres add breakdowns.
  • GET /api/media/duplicates + POST /api/media/duplicates/{group_id}/resolve — find/resolve duplicate groups; POST /api/media/duplicates/members fetches live info per member.
  • GET /api/media/low-rated / GET /api/media/incomplete-metadata — quality filters.
  • GET /api/media/orphaned + POST /api/media/orphaned/purge — cache rows whose ARR item is gone.
  • POST /api/media/refresh / export / bulk-delete — cache + bulk actions.
  • GET|DELETE /api/media/{media_id} — single record (DELETE takes an optional JSON body {"deleteFiles": true} to remove it from the ARR too); GET /poster, PUT /metadata, GET /history, GET /import-exclusion sub-routes.
  • GET|POST|PUT|DELETE /api/media/collections… — collection CRUD, plus from-tag.

Posters

  • GET /api/posters/list / search / browse / stats — index, search, browse, counts.
  • GET /api/posters/low-resolution / added-since — cleanup queries.
  • POST /api/posters/optimize / auto-match / backfill-dimensions — batch operations.
  • Asset matching (powers /poster/unmatched):
    • GET /api/posters/match/{media_id}/candidates + /artwork/{image_type}/candidates — candidate art.
    • POST /api/posters/match/{media_id}/apply / approve / ignore / unlock (/artwork/{image_type}/ has apply, ignore, unlock).
    • GET /api/posters/recently-matched / applied / unmatched/artwork / unmatched/details — review feeds.
    • GET /api/posters/matched/stats / unmatched/stats — coverage counts.
  • GET /api/posters/analyze / preview — scan a poster directory / serve one poster file.
  • Upload: POST /api/posters/upload, /upload/media/{media_id}, /upload/collection/{collection_id}.
  • Collections: GET|POST /api/posters/collections, DELETE /{collection_id}, plus POST /{collection_id}/add and DELETE /{collection_id}/remove/{poster_id}.
  • Google Drive: GET /api/posters/sources/gdrive/search, GET /api/posters/gdrive/stats, POST /api/posters/gdrive/sync, POST /api/posters/gdrive/delete-local.
  • GET|DELETE /api/posters/{poster_id} — single poster; GET /thumbnail, POST /download.
  • Plex metadata / Kometa asset cleanup:
    • GET /api/posters/plex-metadata/by-media — per-bundle bloat scan (powers the master-detail grid); POST /plex-metadata/scan enqueues the background scan that warms it.
    • GET /api/posters/plex-metadata/bloat — flat paginated list of bloat variants, largest first.
    • GET /api/posters/plex-metadata/variant-thumbnail, POST /plex-metadata/set-active, DELETE /plex-metadata/variant, DELETE /plex-metadata/orphan — inspect, activate, or delete single items.
    • GET /api/posters/plex-metadata/kometa-assets-scan — read-only; returns the cached result of the last Kometa asset scan: { stale: [{rating_key, name, canonical, canonical_present, size, folder}], orphans: [{path, parsed, size}], stats: {stale_count, orphan_count} }. With no cached scan it returns empty lists and scan_required: true; enqueue one with POST /api/posters/plex-metadata/kometa-scan. Detection uses the same logic as the cleanup job so results match exactly.
    • POST /api/posters/plex-metadata/cleanup — enqueue a Poster Cleanarr job. Body fields (all optional):
      {
        "mode": "report|move|remove|nothing",
        "target_paths": ["…"],
        "orphan_assets_enabled": true,
        "orphan_assets_mode": "report|move|remove",
        "stale_duplicates_enabled": true,
        "stale_duplicates_mode": "report|move|remove",
        "asset_dirs": ["…"]
      }
      Use "mode": "nothing" to run stale/orphan passes without touching Plex metadata bloat. Each cleaner runs independently at its own mode. asset_dirs overrides the configured list and must sit inside the allowed roots.

Border Replacerr

Read-only preview for /poster/border-replacerr — composites are generated into a temp dir, nothing under destination_dir is touched.

  • GET /api/border-replacerr/preview/options — holiday choices for the dropdown.
  • POST /api/border-replacerr/preview — generate fresh composites (count 1–24, holiday).
  • GET /api/border-replacerr/preview/file/{token}.jpg — fetch a composite by token.
  • GET /api/border-replacerr/presets — bundled border presets.
  • GET /api/border-replacerr/borders/{holiday} — borders available for a holiday; /borders/{holiday}/{source}/{variant}.png serves one as a thumbnail.

Jobs

  • GET /api/jobs — filter + paginate (status, job_type, module, limit, offset).
  • GET /api/jobs/stats — counts by status/module.
  • GET /api/jobs/{job_id} + /log-tail — record and log tail.
  • POST /api/jobs/{job_id}/retry — re-queue a failed job.
  • DELETE /api/jobs/old?days=30 — purge completed/errored jobs older than days (default 30).
  • GET /api/jobs/webhook-origins — aggregate webhook-sourced job origins.

Schedule

  • GET /api/schedule — every module's schedule.
  • POST /api/schedule — set one module's schedule ({"module": "…", "schedule": "…"}).
  • POST /api/schedule/blocks — replace a module's multi-block schedules.
  • GET|DELETE /api/schedule/{module_id} — one module's rule (delete = manual-only).

Instances

  • GET /api/instances — all Radarr/Sonarr/Lidarr/Plex instances (secrets redacted).
  • GET /api/instances/types + /{type}/schema — discover instance schemas.
  • GET /api/instances/health — probe every instance now (stored 6-hour snapshots are under GET /api/system/health/snapshots).
  • POST /api/instances / POST /api/instances/test — add / dry-run a config.
  • GET|PUT|PATCH|DELETE /api/instances/{id} — CRUD; plus /test, /refresh, /sync, /stats, /health, /logs.
  • GET /api/plex/{instance}/libraries — Plex sections with authoritative type; PATCH sets the instance's opted-in libraries. GET /api/plex/libraries lists libraries for every Plex instance.

System

  • GET /api/version / GET /api/health — version string / liveness (unauthenticated).
  • GET /api/version/check — whether a newer build is available (needs a login).
  • GET /api/system/disk — disk usage.
  • GET /api/system/db-stats + POST /api/system/db/vacuum — DB size / compaction.
  • POST /api/system/db/poster-cache/clear, /artwork-matches/clear, /poster-matches/reset, /artwork-matches/reset — clear / reset cache tables.
  • GET /api/allowed-roots / GET /api/gdrive-presets — path-picker roots / Google Drive presets (GET /api/gdrive-presets/new + POST /new/dismiss drive the new-preset notice).
  • GET /api/directory / POST /api/folder — browse / create folders for path pickers.
  • POST /api/backup / GET /api/backups / POST /api/restore — config+DB backup lifecycle (restore is destructive).
  • GET /api/system/health/snapshots / digest / cleanup-candidates — telemetry feeds.

Cache

Raw access to internal cache tables. limit (1–500) and offset are optional.

  • GET /api/cache/media / collection / plex — read cache rows.
  • POST /api/cache/refresh — queue a background cache refresh.
  • DELETE /api/cache/media/{id} / collection/{id} — drop a single row.

Config

  • GET /api/config — full config.yml as JSON, secrets shown as ********.
  • POST /api/config — write config; fields still equal to ******** keep their on-disk value.
  • GET /api/config/secret?path=<dotted.path> — reveal one secret (e.g. tmdb.apikey); never password_hash or jwt_secret.
  • GET /api/config/gdrive-credentials — whether sync_gdrive falls back to rclone's shared client ID.

Logs

  • GET /api/logs — modules that have logs.
  • GET /api/logs/{module_name} — that module's log files.
  • GET /api/logs/{module}/{filename} — serve one log file (current or rotated) as text.

Notifications

  • GET /api/notifications — list notification destinations.
  • POST /api/notifications/destinations — add a destination.
  • PUT|DELETE /api/notifications/destinations/{destination_id} — replace / remove one.
  • POST /api/notifications/test — send a test through the supplied destination.

Webhooks

See Webhooks for the walkthrough.

  • POST /api/webhooks/poster/add — inbound poster webhook (X-Webhook-Secret or ?secret=; no JWT).
  • GET /api/webhooks/unmatched/status / POST /api/webhooks/unmatched/process — unmatched queue (process is secret-gated like poster/add).
  • GET /api/webhooks/wiring — inbound path and secret for the UI's paste-ready URLs.
  • GET /api/webhooks/provision/status, POST /api/webhooks/provision, POST /api/webhooks/provision/remove — check, add/repair, or remove CHUB's webhook in Radarr/Sonarr.

Nestarr & Labelarr

  • POST /api/nestarr/scan / GET /api/nestarr/results — run a scan / read the cached results.
  • POST /api/nestarr/preview / POST /api/nestarr/fix — preview / apply a path fix in Radarr/Sonarr.
  • POST /api/labelarr/sync / POST /api/labelarr/bulk-sync — queue ARR tag → Plex label sync for one item / up to 1000 items.

Extensions (:full image)

Mounted only when the extension is active (the :full image); on :latest these return 404.

  • /api/cl2k-maker/… — CL2K poster maker: artwork lookup, previews, generation, PSD export.
  • /api/poster-self-heal/… — review queue: GET /reviews, GET /count, GET /coverage, POST /reviews/{review_id}/apply or /dismiss.

Related: Developer Guide, Webhooks

Clone this wiki locally