Repository navigation
Developer API
chodeus edited this page Oct 22, 2026
·
10 revisions
🏠 Home › 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.
- Basics
- Auth
- Setup
- Modules
- Media
- Posters
- Border Replacerr
- Jobs
- Schedule
- Instances
- System
- Cache
- Config
- Logs
- Notifications
- Webhooks
- Nestarr & Labelarr
- Extensions (:full image)
-
Base path:
/api(e.g.http://<host>:8000/api). -
Auth: get a JWT from
POST /api/auth/login, then sendAuthorization: Bearer <token>on every authenticated call. For SSE and image URLs (browsers can't set headers onEventSourceor<img>), mint a short-lived stream token withPOST /api/auth/stream-tokenand 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 acceptlimitandoffset.
-
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.
First-run wizard.
-
GET /api/setup/status— whether the wizard is complete (completed; unauthenticated). -
POST /api/setup/complete— mark the wizard done.
-
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_replacerrruns to completion andplex_maintenanceis partial.
-
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 byperiod(7d/30d/90d/1y; omit for all time).GET /api/media/stats/detailedandGET /api/media/genresadd breakdowns. -
GET /api/media/duplicates+POST /api/media/duplicates/{group_id}/resolve— find/resolve duplicate groups;POST /api/media/duplicates/membersfetches 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-exclusionsub-routes. -
GET|POST|PUT|DELETE /api/media/collections…— collection CRUD, plusfrom-tag.
-
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}/hasapply,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}, plusPOST /{collection_id}/addandDELETE /{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/scanenqueues 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 andscan_required: true; enqueue one withPOST /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):Use{ "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": ["…"] }"mode": "nothing"to run stale/orphan passes without touching Plex metadata bloat. Each cleaner runs independently at its own mode.asset_dirsoverrides the configured list and must sit inside the allowed roots.
-
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 (count1–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}.pngserves one as a thumbnail.
-
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 thandays(default 30). -
GET /api/jobs/webhook-origins— aggregate webhook-sourced job origins.
-
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).
-
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 underGET /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 authoritativetype;PATCHsets the instance's opted-in libraries.GET /api/plex/librarieslists libraries for every Plex instance.
-
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/dismissdrive 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.
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.
-
GET /api/config— fullconfig.ymlas 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); neverpassword_hashorjwt_secret. -
GET /api/config/gdrive-credentials— whethersync_gdrivefalls back to rclone's shared client ID.
-
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.
-
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.
See Webhooks for the walkthrough.
-
POST /api/webhooks/poster/add— inbound poster webhook (X-Webhook-Secretor?secret=; no JWT). -
GET /api/webhooks/unmatched/status/POST /api/webhooks/unmatched/process— unmatched queue (processis secret-gated likeposter/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.
-
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.
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}/applyor/dismiss.
Related: Developer Guide, Webhooks