Skip to content

Developer API

Jump to bottom
chodeus edited this page Jun 17, 2026 · 8 revisions

🏠 Home › REST API

REST API

A grouped index of CHUB's REST API. The always-current, interactive reference is the OpenAPI UI at /docs on any running instance.

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. SSE streams accept ?token=<jwt> instead (browsers can't set headers on EventSource). Webhooks use a shared secret, not a JWT.
  • Full reference: the interactive OpenAPI UI at /docs is authoritative — FastAPI generates it from source, so it never drifts. The groups below are representative, not exhaustive.
  • Request/response bodies are JSON. Errors return {"detail": "message"} with conventional status codes. Timestamps are ISO-8601 UTC. Paginated endpoints accept limit and offset.

Auth

  • GET /api/auth/status — is an admin configured? (unauthenticated)
  • POST /api/auth/setup — first-run only; create the admin.
  • POST /api/auth/login — exchange username/password for a JWT (rate-limited).
  • GET /api/auth/me — current user.
  • POST /api/auth/logout — invalidate the session.

Setup

First-run wizard.

  • GET /api/setup/status — whether setup is complete and what's still needed.
  • POST /api/setup/complete — mark the wizard done.

Modules

  • GET /api/modules — list modules with enabled flag, last run, status.
  • GET /api/modules/status — run-state snapshot for every module.
  • GET /api/modules/history / GET /api/modules/stats — recent runs / aggregate counters.
  • GET /api/modules/events — SSE stream of run-state changes (?token=<jwt>).
  • 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/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 (type, status, tag, sort, order).
  • GET /api/media/stats — counters by period (7d/30d/90d/all).
  • GET /api/media/duplicates + POST /api/media/duplicates/{group_id}/resolve — find/resolve duplicate groups.
  • GET /api/media/low-rated / GET /api/media/incomplete-metadata — quality filters.
  • POST /api/media/refresh / scan / export / fix-metadata — cache + bulk actions.
  • GET|PUT|DELETE /api/media/{media_id} — single record (with ?delete_files=); /poster, /metadata, /history, /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/duplicates + resolve, 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 (and /artwork/{image_type}/…).
    • GET /api/posters/recently-matched / applied / unmatched/artwork — review feeds.
    • GET /api/posters/analyze / preview — inspect a match before applying.
  • Upload: POST /api/posters/upload, /upload/media/{media_id}, /upload/collection/{collection_id}.
  • Collections: GET|POST /api/posters/collections, plus /{collection_id}/add and /remove/{poster_id}.
  • GET /api/posters/sources/gdrive/search / sources/assets/search — source-specific search.
  • GET|DELETE /api/posters/{poster_id} — single poster, with /thumbnail, /download, /sync-metadata.

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.

Jobs

  • GET /api/jobs — filter + paginate (status, module).
  • 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 — purge old completed jobs.
  • GET /api/jobs/webhook-origins — aggregate webhook-sourced job origins.

Schedule

  • GET|POST /api/schedule — read / replace the per-module schedule dict.
  • 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 — latest health probe per instance.
  • 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.

System

  • GET /api/version / GET /api/health — version string / liveness (unauthenticated).
  • 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/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.

Logs

  • GET /api/logs — log files grouped by module.
  • GET /api/logs/{module_name} — tail of the latest log.
  • GET /api/logs/{module}/{filename} — serve a specific rotated log file.

Notifications

  • GET|POST /api/notifications — read / write notification config.
  • GET /api/notifications/{module_id} — per-module config.
  • POST /api/notifications/test — send a test.
  • DELETE /api/notifications/{module_id}/{service_type} — remove one target.

Webhooks

See Webhooks for the walkthrough.

  • POST /api/webhooks/poster/add — inbound poster webhook (X-Webhook-Secret or ?secret=).
  • GET /api/webhooks/unmatched/status / POST /api/webhooks/unmatched/process — unmatched queue.

Related: Developer Guide, Webhooks

Getting Started

Guides

Help

Developer

Clone this wiki locally