API Reference

API Reference

🌐 English · Deutsch

There are two API layers:

1. External REST API (/api/v1/...) — for scripts, dashboards (e.g. Homepage/Homarr) and third-party systems. Authenticated via API key, no login needed.
2. Internal API (/api/...) — used by the WebUI, session-based (login required, partly admin). It is not a stable contract, but the most important endpoints are documented below anyway.

External API v1

Authentication

Send the API key in the X-Api-Key header. The key is generated automatically on first start and can be viewed (and regenerated) under Settings → API.

curl -H "X-Api-Key: <key>" http://localhost:8080/api/v1/status

Missing/wrong key → 401 Unauthorized.

Endpoints

Method	Path	Description
GET	/api/v1/status	Overall status: version, pause state, queue counters by status, currently running download incl. live progress (episode_progress: percent, phase, speed, bandwidth; overall_progress_percent)
GET	/api/v1/queue	All queue entries; filter: `?status=queued
GET	/api/v1/queue/<id>	Single queue entry (404 if unknown)
GET	/api/v1/library	Full library (all paths, titles, seasons, episodes, sizes)
GET	/api/v1/library/series	Series only
GET	/api/v1/library/movies	Movies only
GET	/api/v1/stats	Overall download statistics

Example: status

{
  "version": "2.5.3",
  "paused": false,
  "queue": {"total": 12, "queued": 2, "running": 1, "completed": 8, "failed": 1, "cancelled": 0},
  "currently_running": {
    "id": 42, "title": "…", "current_episode": 3, "total_episodes": 12,
    "episode_progress": {"percent": 57, "phase": "download", "speed": "2.1x", "bandwidth": "8.4 MB/s", "active": true},
    "overall_progress_percent": 29
  }
}

Internal API (selection)

All internal endpoints require a logged-in session; POST/PUT/DELETE require Content-Type: application/json. Entries marked (admin) additionally require the admin role.

Search & browse

Method	Path	Description
POST	/api/search	`{keyword, site: "aniworld"
GET	/api/series / /api/seasons / /api/episodes	Series/season/episode data for a URL
GET	/api/providers	Available hosts/languages of an episode
GET	/api/new-animes, /api/popular-animes, /api/new-series, /api/popular-series, /api/new-movies, /api/random	Browse lists

Queue

Method	Path	Description
POST	/api/download	Create a download job
GET	/api/queue	Queue incl. progress
POST	/api/queue/pause / /api/queue/resume	Global pause
POST	/api/queue/<id>/cancel / restart / skip-episode / retry-episode / move	Actions
DELETE	/api/queue/<id> / /api/queue/completed	Delete an entry / all finished entries

AutoSync

Method	Path	Description
GET/POST	/api/autosync	List / create jobs (create: admin); body incl. language, provider, custom_path_id, episode_filter (JSON), movie_custom_path_id
POST	/api/autosync/site-search	Resolve a title to candidate series on AniWorld/serienstream.to (used by the Library "Add to Auto-Sync"); body {title}, returns results[] with site, site_label, title, url, score
PUT/DELETE	/api/autosync/<id>	Update (incl. episode_filter, movie_custom_path_id, group_name) / delete (admin)
POST	/api/autosync/<id>/sync, /api/autosync/sync-all	Sync immediately
GET/POST	/api/autosync/export, /api/autosync/import, /api/autosync/batch	Backup / restore / bulk add. batch actions: enable, disable, set_path, set_group (+group_name), remove_group, delete
POST	/api/autosync/group/rename	Rename a group; body {old, new} — sets group_name of all own jobs (admin: all) from old to new

Calendar & download history

Method	Path	Description
GET	/api/calendar	Aggregated calendar events for the user (AutoSync + optional Seerr/Library overlays). Returns events[], a watcher status block (active, is_scanning, last_sync) and meta (seerr_active, seerr_count). Requires the calendar to be enabled + a TMDB key.
GET	/api/history	Download history; query: ?search=, ?status=all|completed|failed|cancelled|skipped, ?source=all|manual|autosync|seerr, ?range=all|1d|7d|30d, ?limit= (max 200), ?offset=. Users see their own entries, admins all. Returns entries[] + total.
GET	/api/history/<id>	Single history entry (403 if not yours and not admin)
GET	/api/history/export	Export the filtered view; ?format=csv|json plus the same filters as /api/history
POST	/api/history/<id>/retry	Re-queue a failed/cancelled episode
DELETE	/api/history/<id>	Delete a single entry
POST	/api/history/delete	Delete multiple entries (body {ids: [...]})
POST	/api/history/clear	Clear the history; body may include status/source/range/search to delete only the filtered subset (otherwise all; own entries, admins all)

Settings (admin)

Method	Path	Description
GET/PUT	/api/settings	General settings
GET/PUT	/api/settings/sso, /api/settings/cineinfo, /api/settings/mediaplayer, /api/settings/mediascan, /api/settings/seerr, /api/settings/crunchyroll, /api/settings/dns	Sub-areas
GET/POST	/api/settings/api-key, /api/settings/api-key/regenerate	External API key
GET/POST	/api/encoding/settings, /api/encoding/detect-hw	Encoding
GET/POST	/api/upscale/settings, …	Upscaling (reading settings is allowed for everyone)

Crunchyroll

Method	Path	Description
GET/PUT	/api/settings/crunchyroll	Load/save settings (password is write-only; clear_password: true forgets it)
POST	/api/settings/crunchyroll/test	Validate login → {ok, mode, profile, premium}
GET	/api/settings/crunchyroll/profiles	List account profiles for the selector
GET	/api/crunchyroll/availability?title=…	Whether a title is on Crunchyroll (powers the provider pill; cached 24 h)

Backed by web/crunchyroll_service.py — a thread-safe client cache (6 h re-login TTL, encrypted session-token file, failure-tolerant) on top of the vendored vendor/crunchyroll_api.py client. Anonymous mode needs no account; watchlist/profile and premium checks require a login. The calendar uses get_simulcast_titles() / get_watchlist_titles() (Crunchyroll knows which anime; TMDB supplies the air dates). Video streams are DRM-protected and never downloaded.

Library & player

Method	Path	Description
GET	/api/library / /api/library/status / /api/library/watcher	Inventory & scan status
POST	/api/library/refresh (admin), /api/library/delete (admin), /api/library/rename (admin), /api/library/move (admin), /api/library/media_info	Management
POST	/api/stream/start / /api/stream/stop	Start/stop an HLS transcode session (library files)
GET	/api/stream/<token>/index.m3u8, /api/stream/<token>/segNNN.ts, /api/stream/<token>/status	HLS delivery
POST	/api/stream/start-source	Stream an episode directly from the provider via transcode; body {episode_url, provider, language, start_pos}
POST	/api/stream/start-proxy / /api/stream/close-proxy	Start/stop a passthrough proxy session for the provider's native HLS (no FFmpeg); returns {token, playlist_url, hls}
GET	/api/proxy/<token>/r/<b64url>	Proxy a provider playlist (rewritten) or segment/key (streamed); forwards Range. SSRF-guarded (http/https only, private/loopback hosts blocked)
POST/GET	/api/progress/save, /api/progress/get, /api/progress/bulk	Watch progress (per user)

Syncplay & Web Console

Method	Path	Description
GET	/api/syncplay/config	Whether a Syncplay server is configured
POST	/api/syncplay/join / /api/syncplay/leave	Join/leave a room (server opens a real Syncplay client); body {room, username?}
POST	/api/syncplay/control / /api/syncplay/report	Send play/pause/seek; report current position (heartbeat)
GET	/api/syncplay/poll	Poll authoritative state events + room user list (?session_id=&after=)
GET	/api/console (admin)	Read-only live console output buffer; ?after=<seq> for incremental polling (only when the Web Console is enabled)

Miscellaneous

Method	Path	Description
GET	/api/captcha/<queue_id>/screenshot / status; POST /api/captcha/<queue_id>/click	Interactive captcha solving
GET/POST	/api/notif/settings, /api/notif/user-settings, /api/notif/admin-settings, /api/notif/test	Notifications
GET	/api/seerr/requests; POST …/approve, …/decline, …/hide	Seerr requests
GET/POST	/api/update-check	Update check
GET/POST/DELETE	/api/favourites	Favourites
GET	/api/stats, /api/stats/queue, /api/stats/sync, /api/stats/general	Statistics