Your media. Your server.
Your rules.
Host the content you want for the people you care about. Buy the server software once and own it. No paywalled features, no third-party content, no ads.
Up and running in minutes
A single docker-compose up is all it takes. No complicated dependencies, no manual configuration.
Free during beta
Own Your Media
Browse and manage your entire collection from a clean, modern UI. Odeion handles the complexity of hosting a diverse media library so you don't have to.
No tracking, no analytics, no third-party accounts. Your library stays on your server, and everything in it belongs to you.
An app for every screen
Native apps for iOS, iPadOS, Android, Android TV, and tvOS. Your watch progress, playlists, and preferences sync across every device.
Watch Together
Start a watch session and invite others to join. Playback stays in sync across all devices in real time, so everyone sees the same thing at the same time.
Share a link, hit play, and enjoy together. No plugins or third-party extensions required, and no “3… 2… 1…”
Play Anything
If ffmpeg can handle it, Odeion can stream it. Transcoding adapts to each client on the fly, with HDR and Dolby Vision passthrough when your device supports it.
Multiple audio tracks, embedded and external subtitles (SRT, ASS, VTT, and more), and quick language selection. Pick what you want and hit play.
Take Control
Configure libraries, manage users, monitor active streams, and fine-tune transcoding settings from a clean, responsive admin panel. Key features like user management and telemetry are available on mobile too.
Automate Everything
Every library, user, stream, backup, and setting is reachable through a dense REST API with 275+ endpoints. Wire Odeion into your scripts, your home automation, or your own clients. If it's in the UI, it's in the API.
Browse the API reference GET /openapi.json
GET /api/libraries
List libraries
Returns all libraries with their paths.
Libraries 200 auth required
POST /api/auth/reset-password
Redeem password reset
Set a new password using a reset token. Public endpoint.
Auth 200
POST /api/watchtogether/sessions/{id}/invites/{invite_id}/decline
Decline invitation
Declines a Watch Together session invitation.
Watch Together 204 auth required
GET /api/playback/{type}/{id}/trickplay/manifest.json
Get trickplay manifest
Returns the trickplay sprite sheet manifest for timeline thumbnails.
Playback auth required
GET /api/admin/telemetry/metrics
List available telemetry metrics
Returns every registered metric definition — name, label, unit, and the group it belongs to — so the admin UI can build chart pickers. Requires the administrator role.
Telemetry 200 auth required
GET /api/admin/content/{type}/{id}/requests
List requests for a content item
Returns all user-submitted media requests associated with a given movie or series, including their fulfilment status. Requires the administrator role.
Content 200 auth required
GET /api/users/me
Get current user
Returns the authenticated user's profile.
Users 200 auth required
GET /api/admin/transcoding/profiles
List transcoding profiles
Returns the catalog of transcoding profiles (codec/bitrate/resolution presets) that sessions can target. Profiles are currently built-in and not user-editable. Requires the administrator role.
Transcoding 200 auth required
POST /api/admin/settings/integrations/reset-webhooks
Re-register *arr webhooks
Deletes any existing Odeion webhook on the configured *arr services and re-registers a fresh one with a new signature. Use this if *arr webhook delivery has drifted or the base URL changed. Requires the administrator role.
Settings 200 auth required
PUT /api/playlists/favorites/items/{type}/{id}
Add to Favorites
Idempotently adds a media item to the user's Favorites list.
Playlists 204 auth required
DELETE /api/admin/users/{userId}/api-keys/{id}
Revoke a user's API key (admin)
Revokes an API key for any user. Admin only.
API Keys 204 auth required
POST /api/jobs
Create a transcode job (temp download)
Creates a temp-download transcode job for the requesting user. The server transcodes the media to the requested profile and makes it available for download under /api/jobs/{id}/file.
Jobs 201 auth required
GET /api/auth/oauth/providers
List enabled OAuth providers
Returns the list of OAuth providers the admin has enabled, so the login UI can render a provider button row.
Auth 200
PUT /api/playlists/{id}
Update playlist
Renames a playlist (builtin playlists cannot be renamed).
Playlists 200 auth required
GET /api/admin/transcoding/pools
List transcoder pools
Returns every configured transcoder pool with its device, concurrency limit, live lease count, and last-probed capability set. Requires the administrator role.
Transcoding 200 auth required
DELETE /api/progress/all
Clear watch history
Deletes the authenticated user's entire watch history (resume points and completion signal).
Progress 204 auth required
PUT /api/admin/transcoding/settings
Update transcoder settings
Updates global transcoder settings. Changes to concurrency limits apply to new sessions immediately; in-flight sessions are not interrupted. Requires the administrator role.
Transcoding 200 auth required
POST /api/admin/tasks/cancel-pending
Cancel every pending task
Moves every task in `pending` status to `cancelled` in a single transaction. Running tasks are not affected. Useful after a configuration change that invalidates queued work. Requires the administrator role.
Tasks 202 auth required
POST /api/watchtogether/sessions/{id}/invite
Invite user to session
Invites a user to a Watch Together session.
Watch Together 201 auth required
GET /api/files
Download a signed file
Serves a file referenced by a signed JWT token in the ?token= query param. The token's `kind` claim (backup, log, job, job_admin, media, media_transcoded) selects which resource is served and which access check runs. Tokens are minted by the per-kind POST /url endpoints (e.g. POST /api/jobs/{id}/url). The response body is the file bytes with a Content-Disposition attachment header.
Files 200
GET /api/admin/webhooks/{id}/deliveries
List webhook delivery history
Returns a paginated delivery history for a single webhook, newest first, with status, attempt count, and timing. Requires the administrator role.
Webhooks 200 auth required
GET /api/admin/jobs/{id}
Get a transcode job
Returns a single job with its derived params / user options. Requires the moderator role.
Jobs 200 auth required
GET /api/libraries/{id}
Get library
Returns a single library with its paths.
Libraries 200 auth required
GET /api/requests/{id}/status
Get request status
Returns rich real-time status for a single request including episode-level detail and download queue.
Requests 200 auth required
GET /api/admin/playback-sessions
List persistent playback audit sessions
Returns paginated playback_sessions audit records with filters for user, media, device, mode, date range, and active-only. Independent of watch_history — not cleared by user history resets. Requires moderator role.
Admin 200 auth required
POST /api/auth/oauth/link/start
Start OAuth account link
Starts an OAuth flow bound to the authenticated user so the callback links an identity instead of logging in.
Auth 200 auth required
POST /api/watchtogether/sessions/{id}/invites/{invite_id}/accept
Accept invitation
Accepts a Watch Together session invitation.
Watch Together 204 auth required
PUT /api/admin/settings/oauth
Update OAuth provider settings
Admin 200 auth required
GET /api/admin/webhooks/{id}
Get webhook subscription
Returns full details for a single webhook subscription, including subscribed event types and recent delivery stats. The signing secret is not returned. Requires the administrator role.
Webhooks 200 auth required
GET /api/admin/storage/summary
Get storage summary
Returns per-library-root byte counts and file counts, plus transcode and subtitle cache sizes. Requires the administrator role.
Storage 200 auth required
GET /api/watchtogether/invites
List my pending invites
Returns pending Watch Together invitations for the current user.
Watch Together 200 auth required
POST /api/v1/me/push-tokens
Register a device push token
Called by mobile apps after receiving an APNS or FCM token. Stores the token locally and forwards it to push.odeion.app for this license.
Push 200 auth required
GET /api/admin/license/info
Get license information
Returns the current license key's validity, identity fields (license ID, key index, version), and the stored key itself. Admin only. Intentionally does not require a valid license — admins must be able to inspect and replace the key when it is invalid.
System 200 auth required
POST /api/admin/media-files/{id}/associate
Associate a media file with content
Links a single media file to a movie, episode, or extras bucket, specifying the role (main, trailer, bonus, etc.). The file is moved to the target content's canonical location if configured. Requires the administrator role.
Media Files 204 auth required
GET /api/admin/requests/{id}/arr-details
Get *arr details
Returns live *arr API data for a media request. Mod+ read access.
Requests 200 auth required
GET /api/admin/content/search-providers
Search external metadata providers
Performs a live search against the configured metadata providers (TMDB, TVDB, etc.) by title and type. Returns provider IDs that can be passed to `admin-create-and-link` or `admin-match-folder`. Requires the administrator role.
Content 200 auth required
POST /api/admin/doctor/generate
Generate a diagnostic bundle and return a signed download URL
Collects system info, postgres stats, system_settings, task summary, and a tail of the logs into a redacted zip, identical to the `odeion doctor` CLI. The bundle is written under <data-dir>/diagnostics and the returned signed URL (/api/files?token=...) downloads it once, after which the file is deleted. Requires the administrator role.
Diagnostics 200 auth required
POST /api/auth/oauth/register
Complete OAuth signup
Redeems an invite code to create a new account linked to the provider identity captured during the flow.
Auth 201
POST /api/auth/oauth/apple/native/link
Link Apple identity (native)
Verify an Apple identity_token and attach it to the authenticated user.
Auth 204 auth required
POST /api/admin/webhooks
Create webhook subscription
Creates a new outbound webhook subscription. The server generates a signing secret that is returned exactly once in the response — store it. Requires the administrator role.
Webhooks 201 auth required
GET /api/playlists/{id}
Get playlist
Returns a single playlist with enriched items.
Playlists 200 auth required
PUT /api/admin/settings/processing
Update processing pipeline settings
Updates processing pipeline configuration. Concurrency changes are applied to the dispatcher immediately; the next scan cycle picks up any timing changes. Requires the administrator role.
Settings 200 auth required
GET /api/admin/settings/integrations
Get *arr integration settings
Returns Sonarr and Radarr connection settings, quality profile mappings, and request-handling behavior. API keys are redacted in the response. Requires the moderator role.
Settings 200 auth required
POST /api/admin/settings/metadata/providers/{name}/test
Test a provider's connectivity
Issues a known-good probe against the provider's API using its current in-memory credentials. Returns ok=false with the upstream error message if the probe fails.
Settings 200 auth required
GET /api/playback/{type}/{id}/info
Get media info
Returns detailed technical metadata about the media file (codecs, resolution, bitrate, etc.).
Playback auth required
POST /api/auth/device-login
Redeem device code
Exchange a device pairing code for a JWT session token.
Auth 200
PUT /api/admin/settings/integrations
Update *arr integration settings
Updates Sonarr/Radarr connection and request-handling settings. Enabling an integration schedules webhook registration on the upstream service; see `admin-reset-webhooks` to force re-registration. Requires the administrator role.
Settings 200 auth required
GET /api/admin/dashboard/playtime-heatmap
Per-day playtime totals
Returns total playback seconds per day for the last N days (default 30), zero-filling days with no activity. Requires the administrator role.
Dashboard 200 auth required
GET /api/series/{id}
Get series
Returns a series with seasons, episodes, genres, and credits.
Series 200 auth required
POST /api/admin/backups
Create a server backup
Enqueues a backup task that snapshots the database and configuration to a timestamped archive under the data directory. Returns 202; use `admin-list-backups` to find the resulting file. Requires the administrator role.
Backups 202 auth required
POST /api/playback/{type}/{id}/download-url
Mint a signed media download URL
Returns a short-lived signed URL for downloading the raw media file. The returned URL points to /api/files?token=... and can be opened by browsers, curl, or wget without any auth header.
Playback 200 auth required
POST /api/admin/media-files/associate-directory
Associate every file in a directory
Associates all unmatched media files under a directory with a single target content in one batch. Use when the scanner split a title across a folder that should map to one item. Requires the administrator role.
Media Files 200 auth required
GET /api/requests/discover
Discover content
Returns trending/popular content from *arr import lists.
Requests 200 auth required
POST /api/admin/media-files/associate-bulk
Associate many media files in one call
Accepts an explicit list of (media_file_id, content_id, role) tuples and applies them in one transaction. Used by the bulk matcher UI after a drag-and-drop selection. Requires the administrator role.
Media Files 200 auth required
PUT /api/users/me/password
Change password
Change the authenticated user's password.
Auth 204 auth required
POST /api/subtitles/{type}/{id}/search
Search subtitles
Searches external providers for subtitles.
Subtitles 200 auth required
GET /api/admin/tasks
List background tasks
Returns a paginated, filterable view of background processing tasks. Supports filtering by status, type, and related media. Use `admin-get-tasks-summary` for dashboard counts. Requires the administrator role.
Tasks 200 auth required
GET /api/playback/{type}/{id}/trickplay/{sheet}
Get trickplay sprite sheet
Returns a trickplay sprite sheet image.
Playback 200 auth required
GET /api/requests/sonarr-seasons
Get Sonarr seasons
Returns the real season monitoring state from Sonarr. Curator+ only.
Requests 200 auth required
GET /api/series
List series
Returns a paginated list of series with optional filters.
Series 200 auth required
DELETE /api/admin/backups/tasks/{task_id}
Delete a backup task record
Permanently removes a backup task row. Use this to dismiss failed or cancelled backup attempts that have no file. If the task recorded a filename and that file still exists, it is also removed. Rejects pending or running tasks — cancel them first. Requires the administrator role.
Backups 204 auth required
GET /api/settings
Get user settings
Returns the authenticated user's settings, with defaults applied.
Settings 200 auth required
GET /api/admin/logs/{name}/search
Search within a log file
Streams lines from a log file that match a substring or regex query, optionally case-insensitive. Intended for quick debugging without downloading the full file. Requires the administrator role.
Logs 200 auth required
DELETE /api/v1/me/push-tokens/{id}
Unregister a device push token
Push 200 auth required
POST /api/admin/playback-sessions/{id}/terminate
Forcibly terminate a playback session
Ends an active playback session by routing through the audit logger's finalize path, which also kills any in-flight ffmpeg and closes the ingest. Returns 409 if the session has already ended. Requires the administrator role.
Admin 200 auth required
PUT /api/admin/requests/{id}/arr-details
Update *arr details
Forwards modified JSON to the *arr API. Admin only.
Requests 200 auth required
DELETE /api/admin/backups/{filename}
Delete a backup archive
Permanently removes a backup file from disk and any matching task records. This cannot be undone. Requires the administrator role.
Backups 204 auth required
GET /api/admin/logs/settings
Get logging settings
Returns the current log level, per-component level overrides, and retention policy. Requires the administrator role.
Logs 200 auth required
POST /api/webhooks/arr/{token}
Handle *arr webhook
Receives webhook events from Sonarr/Radarr.
Webhooks 204
GET /api/admin/storage/datadir
Get storage data directory tree
Walks the server's data directory (thumbnails, trickplay, backups, postgres, assets, etc.) and returns a treemap-compatible hierarchy of on-disk sizes. Results are cached in-memory for ~30s. Requires the administrator role.
Storage 200 auth required
GET /api/admin/settings
Get aggregated admin settings
Returns every settings group in a single response: general, paths, metadata, subtitles, integrations, NFO, PlexMatch, processing, kill switches, and telemetry. Intended as the single hydration endpoint for the admin settings UI. Requires the moderator role.
Settings 200 auth required
GET /api/admin/media-files/summary
Summarize media file catalog
Returns totals for files, bytes, associated/unassociated counts, and probe-missing counts. Used by the dashboard tile. Requires the administrator role.
Media Files 200 auth required
DELETE /api/progress/{type}/{id}
Delete progress
Removes watch progress for a media item.
Progress 204 auth required
GET /api/watchtogether/sessions/{id}
Get Watch Together session
Returns details of a Watch Together session.
Watch Together 200 auth required
PUT /api/admin/settings
Bulk update admin settings
Applies partial updates across any combination of settings groups in one atomic transaction. Unknown or malformed sections abort the whole update. Requires the administrator role.
Settings 200 auth required
PUT /api/admin/settings/metadata/providers/{name}
Update a metadata provider config
Replaces the provider's enabled flag and merges supplied settings. Existing settings keys not in the request body are preserved.
Settings 200 auth required
GET /api/admin/playback-sessions/{id}
Get a playback audit session
Returns a single playback audit session by its numeric ID. Requires moderator role.
Admin 200 auth required
POST /api/jobs/{id}/complete
Confirm download completion
Client confirms it has successfully fetched + validated the file. Server extends the retention window so re-downloads don't trigger a fresh transcode.
Jobs 200 auth required
GET /api/recommendations
Get recommendations
Personalized movie and series recommendations for the authenticated user.
Search 200 auth required
POST /api/admin/tasks/reprocess
Enqueue bulk reprocess
Enqueues a bulk reprocess for every media item of a given task type (e.g. `refresh_metadata`, `analyze_segments`). Returns 202; inspect the queue via `admin-list-tasks`. Requires the administrator role.
Tasks 202 auth required
GET /api/admin/settings/oauth
Get OAuth provider settings
Admin 200 auth required
DELETE /api/watchtogether/sessions/{id}
Close Watch Together session
Closes a Watch Together session.
Watch Together 204 auth required
GET /api/admin/users/{id}/playback-sessions
List playback sessions for a user
Returns paginated playback audit sessions for the given user. Requires moderator role.
Admin 200 auth required
PUT /api/progress/{type}/{id}
Update progress
Creates or updates watch progress for a media item.
Progress 200 auth required
POST /api/admin/jobs/{id}/retry
Retry a failed or cancelled transcode job
Resets a terminal job back to pending so the dispatcher picks it up again. Requires the administrator role.
Jobs 200 auth required
GET /api/subtitles/file/{id}
Get subtitle file
Serves a subtitle file (VTT/SRT). Accepts playback token or JWT.
Subtitles 200 auth required
POST /api/account/api-keys
Create API key
Generates a new API key. The plaintext value is returned exactly once.
API Keys 201 auth required
GET /api/v1/me/push-tokens
List my registered push tokens
Push 200 auth required
GET /api/playback/{type}/{id}/profiles
Get transcode profiles
Returns available transcode profiles for the media item.
Playback auth required
POST /api/playback/sessions
Create an explicit playback session
Opens (or resumes) a playback_sessions audit row, stamps the supplied options + capability blob onto it, and returns the multi-rendition master playlist URL the player should hand to hls.js / AVFoundation. Capabilities posted here drive server-side rendition filtering — the master playlist only advertises variants the client says it can decode. Replaces the implicit session creation that previously happened inside the master.m3u8 GET.
Playback 201 auth required
DELETE /api/admin/tasks/clear-old
Purge old terminal tasks
Deletes `completed`, `failed`, and `cancelled` tasks from the history so the admin UI stays responsive. Active and pending tasks are untouched. Requires the administrator role.
Tasks 204 auth required
GET /api/progress/all
List progress
Returns watch progress for the authenticated user. Pass `view=resume` for the curated continue-watching feed (with next-episode resolution for series; pagination ignored); default `view=all` returns the paginated full watch history.
Progress 200 auth required
DELETE /api/admin/maintenance/cache/transcode
Clear the transcode cache
Deletes every cached transcode output from the transcode cache directory. Active transcoder sessions are unaffected (they write to per-session temp locations). Requires the administrator role.
Maintenance 204 auth required
POST /api/playlists/{id}/items
Add playlist item
Adds a media item to a playlist.
Playlists 201 auth required
GET /api/admin/content
List library content
Returns paginated library content (movies and series) with metadata, filter support for type/status/library, and free-text title search. Requires the administrator role.
Content 200 auth required
GET /api/users/invites
List invite codes
Returns invite codes created by the current user. Mod+ only.
Invites 200 auth required
POST /api/auth/oauth/apple/native
Apple native sign-in
Verifies an identity_token from Apple's native iOS sign-in sheet.
Auth 200
GET /api/admin/telemetry/pool-metrics
List per-pool telemetry metric names
Returns the live transcoder pools together with the metric names that the collector is emitting for each one. Used by the pool health chart picker. Requires the administrator role.
Telemetry 200 auth required
GET /api/requests
List media requests
Returns all media requests.
Requests 200 auth required
GET /api/admin/backups/{filename}/inspect
Inspect a backup archive
Opens a backup archive and returns its manifest: schema version, included tables, approximate row counts, and the Odeion version that produced it. Does not restore anything. Requires the administrator role.
Backups 200 auth required
POST /api/admin/backups/restore
Restore from a backup archive
Enqueues a restore task that replaces the current database with the contents of the supplied backup filename. The server schedules itself to restart after a successful restore. Handle with care — this is destructive. Requires the administrator role.
Backups 202 auth required
GET /api/playlists/membership
Playlist item status
Returns which of the user's playlists contain a given media item.
Playlists 200 auth required
POST /api/users/{id}/reset-link
Generate password reset link
Creates a password reset token for a user. Admin only.
Users 201 auth required
POST /api/auth/refresh
Refresh token
Generate a new JWT token with extended expiry.
Auth 200 auth required
GET /api/admin/filesystem/browse
Browse filesystem
Lists subdirectories at a given path. Admin only.
Filesystem 200 auth required
GET /api/auth/oauth/identities
List linked OAuth identities
Auth 200 auth required
DELETE /api/auth/oauth/identities/{provider}
Unlink an OAuth identity
Auth 204 auth required
GET /api/admin/settings/processing
Get processing pipeline settings
Returns the scan cadence, dispatcher concurrency, and retry policy for background processing. Requires the moderator role.
Settings 200 auth required
GET /api/admin/media-files
List media files
Returns paginated raw media files with filters for directory, association state, probe status, and free-text path search. Use this for the admin file browser. Requires the administrator role.
Media Files 200 auth required
POST /api/auth/login
Log in
Authenticate with username and password. Returns a JWT token and user profile.
Auth 200
GET /api/playlists/shared/{shareId}
Get shared playlist
Returns a playlist by its share ID (public, no auth required).
Playlists 200
PUT /api/admin/settings/general
Update general server settings
Updates the general settings group. Changing the release channel schedules an update check; changing the base URL does not restart the server but affects generated links immediately. Requires the administrator role.
Settings 200 auth required
GET /api/system/licenses
Get open source licenses
Returns the list of open source licenses used by the server.
System 200
POST /api/watchtogether/sessions
Create Watch Together session
Creates a new Watch Together session.
Watch Together 201 auth required
POST /api/auth/oauth/start
Start an OAuth flow
Creates a pending OAuth state and returns the provider's authorize URL.
Auth 200
PUT /api/admin/settings/killswitches
Update kill switch settings
Toggles feature kill switches. Changes take effect immediately for all new requests. Requires the administrator role.
Settings 200 auth required
GET /api/admin/transcode-sessions/{id}
Get transcoder session detail
Returns the full record of one ffmpeg invocation: source ffprobe, ffmpeg argv, stderr tail, output specs, attached playback sessions, and live throughput history when active. Requires the moderator role.
Transcoding 200 auth required
GET /api/notifications
List notifications
Returns the caller's notifications, newest first. Excludes expired rows. Supports cursor pagination and an unread-only filter.
Notifications 200 auth required
GET /api/admin/webhooks
List webhook subscriptions
Returns every configured outbound webhook together with its enabled state, subscribed event types, and recent delivery statistics (success/failure counts over the last 24 hours). Requires the administrator role.
Webhooks 200 auth required
GET /api/series/{id}/seasons/{seasonNumber}
Get season
Returns a single season with its episodes.
Series 200 auth required
DELETE /api/admin/tasks/{id}
Cancel a single task
Cancels one task by ID. Pending tasks transition to `cancelled` immediately; running tasks are asked to stop at their next checkpoint. Requires the administrator role.
Tasks 204 auth required
POST /api/notifications/bulk
Bulk mutate notifications
Mark-read or delete every one of the caller's notifications matching `scope`. Replaces the former mark-all-read and clear-read endpoints.
Notifications 200 auth required
GET /api/episodes/{id}/next
Get next episode
Returns the next episode in the series after the given episode.
Episodes 200 auth required
GET /api/jobs
List my transcode jobs
Returns the caller's recent transcode jobs.
Jobs 200 auth required
POST /api/admin/push/test
Send a test push notification to the calling admin
Sends a test push via push.odeion.app to every device registered by the calling admin user. Useful for smoke-testing APNS/FCM plumbing.
Push 200 auth required
POST /api/admin/jobs/{id}/url
Mint a signed job file URL
Returns a short-lived signed URL that lets a browser navigate to a completed job's output file without needing an auth header. Tokens expire in a few minutes. Requires the administrator role.
Jobs 200 auth required
DELETE /api/playlists/favorites/items/{type}/{id}
Remove from Favorites
Idempotently removes a media item from the user's Favorites list.
Playlists 204 auth required
GET /api/admin/webhooks/event-types
List available webhook event types
Returns every event type that a webhook can subscribe to, with the JSON schema of its payload. Used by the subscription UI to build checkbox lists. Requires the administrator role.
Webhooks 200 auth required
POST /api/admin/webhooks/{id}/test
Send a test event to a webhook
Dispatches a synthetic test event to the webhook's configured URL, signed with its real secret, and returns the raw request/response pair so operators can diagnose receiver issues. Requires the administrator role.
Webhooks 200 auth required
GET /api/search/suggest
Search suggestions
Autocomplete suggestions for the search box.
Search 200 auth required
GET /api/admin/jobs
List transcode jobs
Returns every transcode job on the server (both user temp downloads and admin library variants), filterable by destination, task type, status, preset, user, or source media file. Requires the moderator role.
Jobs 200 auth required
GET /api/admin/tasks/{mediaType}/{mediaID}
List tasks for a media item
Returns every task historically recorded against a single movie, episode, or season — used by the per-item activity sidebar in the admin UI. Requires the administrator role.
Tasks 200 auth required
GET /api/admin/storage/treemap
Get storage treemap
Returns library storage usage bucketed by title and season, suitable for rendering a treemap visualization. Requires the administrator role.
Storage 200 auth required
DELETE /api/admin/maintenance/cache/subtitles
Clear the subtitle cache
Deletes every subtitle file from the subtitle cache directory. Previously-downloaded subtitles will be re-fetched on the next playback that requests them. Requires the administrator role.
Maintenance 204 auth required
PUT /api/admin/settings/telemetry
Update telemetry collection settings
Enables or disables individual telemetry groups. Disabling a group stops new samples from being written but does not purge existing history. All data stays local — see the project's no-phone-home policy. Requires the administrator role.
Settings 200 auth required
GET /api/admin/users/{userId}/api-keys
List a user's API keys (admin)
Returns API keys belonging to the given user. Admin only.
API Keys 200 auth required
GET /api/playback/{type}/{id}/segments
Get skip segments
Returns intro/credits skip segments for the media item.
Playback auth required
GET /api/admin/content/series-search
Search series already in the library
Returns series matching a title substring from the local catalog — intended as the target picker for episode-move operations. Requires the administrator role.
Content 200 auth required
POST /api/admin/backups/upload
Upload backup archive
Uploads a backup archive. Multipart form data. Admin only.
Backups auth required
PUT /api/requests/sonarr-seasons
Update Sonarr seasons
Updates monitored seasons in Sonarr for a series. Curator+ only.
Requests 200 auth required
DELETE /api/users/invites/{id}
Delete invite code
Deletes an invite code. Only the creator can delete their own invites. Mod+ only.
Invites 204 auth required
POST /api/series/{id}/subscribe
Subscribe to a series
Subscribing opts the caller into notifications when new episodes of this series arrive.
Notifications 204 auth required
GET /api/events
Subscribe to server events (fallback)
Server-Sent Events stream for real-time updates. Auth via query parameter token. Kept as a fallback transport; the preferred channel is the /api/ws WebSocket.
App 200 auth required
POST /api/admin/settings/oauth/{provider}/test
Test OAuth provider configuration
Lightweight sanity check — verifies required fields are set and the provider's public endpoint is reachable. Does not perform a full sign-in round-trip.
Admin 200 auth required
GET /api/admin/webhooks/deliveries/{deliveryId}
Get webhook delivery details
Returns the full request/response pair for a specific delivery attempt, including the signed headers and the receiver's body. Required for debugging failed deliveries. Requires the administrator role.
Webhooks 200 auth required
POST /api/admin/media-files/reingest
Re-run ingestion for a library
Clears the media file catalog for the specified library and enqueues a fresh scan. Existing associations to content are preserved by path. Returns 202. Requires the administrator role.
Media Files 202 auth required
DELETE /api/account/api-keys/{id}
Revoke API key
Revokes one of the calling user's API keys.
API Keys 204 auth required
PATCH /api/users/{id}
Update a user
Partial update for a user. Any combination of role, locked, password, username, and permissions may be supplied; absent fields are left untouched. Self-mutation guards apply to role, lock, and password. Admin only.
Users 200 auth required
GET /api/thumbnails/{path}
Get thumbnail image
Serves a locally generated thumbnail image.
Media 200 auth required
GET /api/requests/config
Get requests config
Returns which *arr services are enabled.
Requests 200 auth required
PUT /api/admin/segments/{type}/{id}
Replace skip segments for a media item
Atomically replaces the full set of skip segments for a media item with the supplied list. Pass an empty list to clear them. Requires the administrator role.
Segments 200 auth required
POST /api/admin/update-check
Force an update check
Contacts the configured package repository immediately, updates the cached result, and returns it. Respects the release channel selected in general settings. Requires the administrator role.
Updates 200 auth required
GET /api/admin/telemetry/query
Query telemetry time series
Returns raw or downsampled samples for a metric over a time window. Parameters select the metric name, time range, and resolution. Backed by the local time-series database; no external calls. Requires the administrator role.
Telemetry 200 auth required
POST /api/requests
Create media request
Submits a new media request. Curator+ only.
Requests 201 auth required
POST /api/admin/backups/{filename}/url
Mint a signed backup download URL
Returns a short-lived signed URL that lets a browser navigate to a backup archive without setting an auth header. The returned URL points to /api/files?token=... — the token encodes the backup filename. Requires the administrator role.
Backups 200 auth required
GET /api/jobs/{id}
Get a transcode job
Returns status / progress of a single job. Only accessible to the owner.
Jobs 200 auth required
POST /api/subtitles/{type}/{id}/download
Download subtitle
Downloads a subtitle from search results.
Subtitles 200 auth required
GET /api/admin/logs
List server log files
Returns every log file under the configured log directory with its size, modification time, and rotation number. Requires the administrator role.
Logs 200 auth required
GET /api/admin/settings/metadata/providers
List metadata provider configs
Returns the unified provider config table (api keys, base urls, enabled flags) for all registered metadata, skip-segment, and subtitle providers. Sensitive values are masked.
Settings 200 auth required
GET /api/admin/tasks/{id}
Get a single task
Returns a single processing task by ID, including the latest status, progress, and timing fields. Used by the admin task detail page. Requires the administrator role.
Tasks 200 auth required
POST /api/admin/content/{type}/{id}/link
Link media files to existing content
Attaches one or more media files to an existing movie or series identified by the path parameters. The type must be `movie` or `series`. Requires the administrator role.
Content 200 auth required
DELETE /api/admin/webhooks/{id}
Delete webhook subscription
Removes a webhook subscription and all of its delivery history records. Pending deliveries in the retry queue are cancelled. Requires the administrator role.
Webhooks 204 auth required
DELETE /api/notifications/{id}
Delete a notification
Notifications 204 auth required
POST /api/admin/fingerprints/season/{season_id}/rematch
Re-run season fingerprint matching
Enqueues a season-scoped `analyze_segments` task that replays the pairwise matcher against existing fingerprints without re-extracting them. Useful after tuning matcher thresholds. Requires the administrator role.
Fingerprints 202 auth required
DELETE /api/playlists/{id}/items/{itemId}
Remove playlist item
Removes an item from a playlist.
Playlists 204 auth required
POST /api/playlists
Create playlist
Creates a new user playlist.
Playlists 201 auth required
POST /api/admin/content/create-and-link
Create content from provider and link files
Creates a new movie or series from a provider result and links the supplied media files to it in a single call. Use this when matching unmatched files against a title that does not yet exist in the library. Requires the administrator role.
Content 201 auth required
GET /api/admin/playback-sessions/{id}/export
Export a playback session as JSON
Returns a self-contained debug bundle: enriched session row, debug side-table row (may be null if older than 30 days), resolved content metadata (movie or episode + season + series), and the source media file with its stream metadata. Designed to be saved to disk and shared for offline triage. Requires moderator role.
Admin 200 auth required
POST /api/users/invite
Create invite code
Generates a new invite code. Mod+ only.
Invites 201 auth required
POST /api/admin/media-files/associate-unassociated
Re-attempt auto-association for all unassociated video files
Enqueues an associate task for every video media file that is not yet linked to content. Reuses the normal ingestion auto-matcher (NFO + metadata provider lookup). Returns 202; watch progress via the tasks API. Requires the administrator role.
Media Files 202 auth required
GET /api/notifications/unread-count
Unread notification count
Returns the count of unread, non-expired notifications for the caller. Cheap — designed for polling.
Notifications 200 auth required
GET /api/admin/transcoding/gpus
Scan for available GPUs
Detects usable GPU devices on the host and returns their vendor, name, and PCI path. Used by the pool creation UI to populate a device dropdown. Requires the administrator role.
Transcoding 200 auth required
PUT /api/admin/settings/paths
Update media path settings
Updates library roots and cache directories. Paths must exist and be readable/writable by the server process; the handler validates accessibility before persisting. Adding a new library root does not trigger an automatic scan — use the tasks API to schedule one. Requires the administrator role.
Settings 200 auth required
GET /api/admin/stats
Get server statistics
Returns aggregated counts and sizes across the library (movies, episodes, media files, total bytes), active transcoding sessions, and recent watch time totals. Requires the administrator role.
Stats 200 auth required
GET /api/system/version
Get version
Returns the server version, commit hash, and build time.
System 200
DELETE /api/admin/media-files/{id}/associate
Dissociate a media file from content
Removes the link between a media file and its content without deleting the file from disk. Moves it back to the unmatched bucket. Requires the administrator role.
Media Files 204 auth required
GET /api/admin/settings/killswitches
Get kill switch settings
Returns the current state of each feature kill switch. Kill switches let operators disable a feature globally without a restart. Requires the moderator role.
Settings 200 auth required
GET /api/progress/{type}/{id}
Get progress
Returns watch progress for a specific media item.
Progress 200 auth required
POST /api/admin/logs/{name}/url
Mint a signed log file download URL
Returns a short-lived signed URL that lets a browser navigate to a log file without setting an auth header. The returned URL points to /api/files?token=... — the token encodes the log file name. Requires the moderator role.
Logs 200 auth required
GET /api/admin/content/search
Search library content by title
Searches the local library catalog (not external providers) for content matching a title substring. Requires the administrator role.
Content 200 auth required
POST /api/jobs/{id}/url
Generate a signed download URL
Mints a short-lived signed URL the browser can navigate to directly (browser navigation can't set auth headers). The returned URL points to /api/files?token=... — the token encodes the job reference. Only valid for completed temp-download jobs owned by the caller.
Jobs 200 auth required
GET /api/movies
List movies
Returns a paginated list of movies with optional filters.
Movies 200 auth required
POST /api/auth/register
Register
Create a new account using an invite code.
Auth 201
DELETE /api/playlists/{id}
Delete playlist
Removes a playlist (builtin playlists cannot be deleted).
Playlists 204 auth required
POST /api/auth/oauth/exchange
Exchange an OAuth code
Trades a one-time exchange code for a session JWT, or returns pending-signup details if the provider identity is new.
Auth 200
GET /api/admin/stats/top-viewers
Get top viewers for a time window
Returns the top users by watch time restricted to the requested rolling window (allowed values: 30, 90, 180, 365 days; defaults to 30). Each entry includes the user's most recently distinct watched media for the panel poster strip. Requires the administrator role.
Stats 200 auth required
POST /api/admin/transcoding/pools/{id}/probe
Probe pool capabilities
Runs a capability probe against the pool's device to enumerate supported encoders, decoders, and filters, and caches the result. Safe to re-run. Requires the administrator role.
Transcoding 200 auth required
POST /api/admin/transcoding/pools
Create a transcoder pool
Adds a new pool bound to a specific GPU or CPU transcoder with a concurrency limit. The pool is probed for capabilities after creation. Requires the administrator role.
Transcoding 201 auth required
GET /api/admin/telemetry/live-buffer
Get live telemetry ring buffer
Returns the ~5-minute in-memory ring buffer of the most recent samples for a set of metrics so the live chart UI can seed before subscribing to the SSE stream. Requires the administrator role.
Telemetry 200 auth required
POST /api/admin/jobs/estimate
Preview derived transcode params (library variants)
Runs transcoder.Derive() against each source without enqueueing anything and returns the resulting encode parameters. Requires the moderator role.
Jobs 200 auth required
POST /api/notifications/{id}/read
Mark a notification as read
Idempotent.
Notifications 204 auth required
GET /api/admin/transcoding/settings
Get transcoder settings
Returns the transcoder global settings: max concurrent sessions, default hardware preferences, quality ceilings, and segment length. Requires the administrator role.
Transcoding 200 auth required
DELETE /api/series/{id}/subscribe
Unsubscribe from a series
Notifications 204 auth required
PUT /api/playlists/{id}/reorder
Reorder playlist
Sets the order of items in a playlist.
Playlists 204 auth required
PUT /api/playlists/watch-later/items/{type}/{id}
Add to Watch Later
Idempotently adds a media item to the user's Watch Later list.
Playlists 204 auth required
POST /api/admin/media-files/{id}/probe
Enqueue ffprobe for a media file
Schedules an ffprobe task for a single media file and returns 202. The result populates stream, codec, and duration fields and is stored on the file record. Requires the administrator role.
Media Files 202 auth required
PATCH /api/admin/media-files/{id}/role
Update media file role
Changes the content-file role of an associated media file (e.g. promote a trailer to the main cut). The file remains linked to the same content. Requires the administrator role.
Media Files 204 auth required
GET /api/admin/fingerprints/season/{season_id}
Get season fingerprint analysis
Debug endpoint: returns per-episode intro/outro audio fingerprints, the currently-matched skip segments, and the pairwise match scores the analyzer produced. Requires the administrator role.
Fingerprints 200 auth required
POST /api/admin/episodes/{id}/refresh-metadata
Enqueue episode metadata refresh
Schedules a metadata refresh task that re-fetches the episode from the configured provider and updates local fields. Returns 202 immediately; poll the tasks API for progress. Requires the administrator role.
Episodes 202 auth required
GET /api/admin/system/status
Get system status
Returns ffmpeg/ffprobe status and transcoder capabilities. Mod+ only.
System 200 auth required
POST /api/admin/webhooks/deliveries/{deliveryId}/retry
Retry a failed webhook delivery
Re-dispatches a specific historical delivery attempt to its webhook's current URL. Only valid for deliveries in a terminal failed state. Returns 202. Requires the administrator role.
Webhooks 202 auth required
GET /api/libraries/{id}/scan
Get scan status
Returns the current scan status for a library.
Libraries 200 auth required
POST /api/admin/tasks/retry-failed
Retry every failed task
Re-queues every task currently in `failed` state with its original payload. Useful after fixing an upstream outage that caused mass failures. Requires the administrator role.
Tasks 202 auth required
GET /api/admin/transcode-sessions/{id}/export
Export transcoder session bundle
Returns a self-contained JSON bundle (transcode session, attached playback rows, processing task, download request) for offline triage and bug reports. Requires the moderator role.
Transcoding 200 auth required
POST /api/admin/jobs/cleanup
Purge old terminal temp-download jobs
Removes temp-download jobs in completed/failed/cancelled state older than 24 hours and deletes their output files. Returns 202. Requires the administrator role.
Jobs 202 auth required
DELETE /api/playback/{type}/{id}/session
Stop playback session
Signals that a playback session has ended, releasing transcoder resources.
Playback auth required
GET /api/admin/settings/integrations/webhook-status
Get *arr webhook registration status
Returns whether Odeion has registered its webhook with each configured *arr instance, and when it was last verified. Requires the moderator role.
Settings 200 auth required
POST /api/admin/tasks/{id}/retry
Retry a single task
Re-queues one failed task by ID. The task must currently be in `failed` or `cancelled` state; succeeds with 202 on acceptance. Requires the administrator role.
Tasks 202 auth required
GET /api/admin/migrations
Get database migration status
Returns every known migration together with whether it has been applied. Useful for verifying that a freshly-started server has reached the expected schema version. Requires the administrator role.
Migrations 200 auth required
GET /api/requests/search
Search *arr content
Queries configured *arr services for content.
Requests 200 auth required
GET /api/admin/update-check
Get cached update information
Returns the most recent update check result from the package repository without contacting it again. Use `admin-force-update-check` to refresh. Requires the administrator role.
Updates 200 auth required
DELETE /api/admin/maintenance/library-content
Drop all library content records
Deletes every movie, series, episode, and media-file record from the database while leaving files on disk untouched. Intended for rebuilding from scratch — scan the libraries afterward to re-ingest. Destructive; requires the administrator role.
Maintenance 204 auth required
GET /api/admin/dashboard/recently-added
List recently added content
Returns the most recently ingested movies and episodes in a flat, chronologically-sorted list for the admin dashboard. Requires the administrator role.
Dashboard 200 auth required
GET /api/account/api-keys
List API keys
Returns the calling user's API keys (without plaintext).
API Keys 200 auth required
GET /api/admin/media/{type}/{id}/playback-sessions
List playback sessions for a media item
Returns paginated playback audit sessions for the given media item across all users. Requires moderator role.
Admin 200 auth required
POST /api/admin/jobs
Create transcode jobs
Creates one or more transcode jobs. Library variants accept a batch of media_file_ids + an intent (archive_av1/preview/custom). Temp downloads accept media_type/media_id + profile name. Duplicates are skipped. Requires the administrator role.
Jobs 201 auth required
GET /api/subtitles/{type}/{id}
List subtitles
Returns subtitles for a media item.
Subtitles 200 auth required
GET /api/admin/content/{type}/{id}/images
List image candidates for a content entity
Returns every entity_asset candidate (poster, backdrop, logo, etc.) linked to a movie, series, season, episode or person, grouped by role. Each entry carries the provider, language, and dimensions so the admin CMS can render a picker. Requires the administrator role.
Content 200 auth required
GET /api/admin/settings/telemetry
Get telemetry collection settings
Returns which telemetry groups (transcoder, pools, playback, etc.) are being collected into the local time-series database. Requires the moderator role.
Settings 200 auth required
POST /api/playback/{type}/{id}/heartbeat
Playback session heartbeat
Keeps the caller's active playback session for this media alive. Clients should call this on a fixed ~30s interval regardless of play/pause state. Returns 204 while the session is active and 410 once it has been finalized by the reaper — on 410, clients should treat the session as dead and start a new one (e.g. by re-requesting the HLS master playlist).
Playback 204 auth required
GET /api/admin/jobs/summary
Summarize transcode jobs
Totals by status and the aggregate on-disk footprint of completed jobs. Requires the moderator role.
Jobs 200 auth required
GET /api/requests/options
Get request options
Returns available quality profiles for the given media type.
Requests 200 auth required
GET /api/watchtogether/sessions
List Watch Together sessions
Returns Watch Together sessions the user is part of.
Watch Together 200 auth required
GET /api/users
List all users
Returns all users. Admin only.
Users 200 auth required
POST /api/admin/filesystem/validate
Validate path
Checks whether a path exists, is a directory, and is readable. Admin only.
Filesystem 200 auth required
POST /api/playback/{type}/{id}/download-url/{profile}
Mint a signed transcoded download URL
Returns a short-lived signed URL for downloading a transcoded media file. The serve handler runs the transcode synchronously before streaming, so token TTL is longer than other kinds.
Playback 200 auth required
PUT /api/subtitles/{id}/default
Set default subtitle
Sets a subtitle as the default for its media item.
Subtitles 204 auth required
POST /api/auth/device-code
Generate device code
Create a device pairing code for the authenticated user.
Auth 200 auth required
DELETE /api/admin/segments/{type}/{id}
Delete all skip segments for a media item
Removes every skip segment attached to a media item. Equivalent to `admin-set-segments` with an empty list but does not require a body. Requires the administrator role.
Segments 204 auth required
GET /api/admin/content/unmatched
List unmatched media files
Returns media files that the scanner has ingested but that have not yet been associated with any content. These files are candidates for manual or assisted matching. Requires the administrator role.
Content 200 auth required
GET /api/movies/{id}
Get movie
Returns a single movie with genres, credits, and files.
Movies 200 auth required
GET /api/admin/users/{id}/activity
Get user activity
Returns watch history, progress, and requests for a user. Admin only.
Users 200 auth required
GET /api/admin/logs/{name}
Read a log file
Returns a page of lines from a log file, with optional byte-offset and line-count controls. The `name` must match an entry from `admin-list-log-files` — path traversal is rejected. Requires the administrator role.
Logs 200 auth required
DELETE /api/admin/content/{type}/{id}
Delete an orphaned content item
Hard-deletes an orphaned movie or series (one with zero non-missing media files) and all its associated metadata, credits, genres, and assets. Returns 409 if the item still has media files attached. Requires the administrator role.
Content 204 auth required
DELETE /api/admin/maintenance/cache/metadata
Clear the metadata image cache
Deletes every cached poster, backdrop, and thumbnail. Images will be re-downloaded on the next request or metadata refresh. Requires the administrator role.
Maintenance 204 auth required
DELETE /api/admin/transcoding/pools/{id}
Delete a transcoder pool
Removes a transcoder pool. The pool must have no active leases; fails with 409 if sessions are still running on it — kill those sessions first. Requires the administrator role.
Transcoding 204 auth required
POST /api/admin/episodes/{id}/move
Move episode to another series
Reparents an episode onto a different series while preserving its media files and watch history. The target series and its destination season must already exist. Requires the administrator role.
Episodes 200 auth required
GET /api/subtitles/config
Get subtitle config
Returns subtitle configuration flags for clients.
Subtitles 200 auth required
GET /api/episodes/{id}
Get episode
Returns an episode with parent season and series context.
Episodes 200 auth required
GET /api/admin/tasks/summary
Summarize task queue state
Returns counts grouped by status (pending/running/completed/failed/cancelled) and task type for the dashboard header. Requires the administrator role.
Tasks 200 auth required
DELETE /api/playlists/watch-later/items/{type}/{id}
Remove from Watch Later
Idempotently removes a media item from the user's Watch Later list.
Playlists 204 auth required
POST /api/admin/media-files/probe-all
Enqueue ffprobe for every unprobed file
Scans the catalog for media files with no probe data and enqueues an ffprobe task for each one. Returns 202; watch progress via the tasks API. Requires the administrator role.
Media Files 202 auth required
DELETE /api/subtitles/{id}
Delete subtitle
Removes a subtitle.
Subtitles 204 auth required
POST /api/admin/content/folders/match
Match a media folder to provider content
Associates every media file under a folder with a specific provider result, creating new content records if needed. Used by the assisted matching UI for unmatched folders. Requires the administrator role.
Content 200 auth required
PUT /api/movies/{id}/metadata
Update movie metadata
Partially update a movie's metadata fields.
Movies 200 auth required
PUT /api/admin/transcoding/pools/{id}
Update a transcoder pool
Updates the name, concurrency limit, or enabled state of an existing pool. The bound device is immutable; delete and recreate to change it. Requires the administrator role.
Transcoding 200 auth required
GET /api/search
Search media
Unified search across movies and series with filters and facets.
Search 200 auth required
GET /api/playlists
List playlists
Returns all playlists for the current user with item counts.
Playlists 200 auth required
GET /api/admin/settings/paths
Get media path settings
Returns the configured library roots, transcode cache, and subtitle cache locations. Requires the moderator role.
Settings 200 auth required
PATCH /api/admin/episodes/{id}
Patch an episode
Partial update for an episode. Accepts season/episode reassignment (season_number, episode_number — stays within the same series; use `admin-move-episode` to change series) and metadata fields (title, overview, air_date, runtime, absolute_number, lock). Only fields present in the request body are applied. Requires the administrator role.
Episodes 200 auth required
GET /api/admin/backups
List available backups
Returns the backup archives present on disk, newest first, with size and creation time. Requires the administrator role.
Backups 200 auth required
DELETE /api/requests/{id}
Cancel media request
Deletes a media request. Admin only.
Requests 204 auth required
POST /api/admin/fingerprints/episode/{episode_id}/reextract
Re-extract episode fingerprints
Clears any cached fingerprints for the episode and enqueues an `analyze_segments` task that recomputes them from the source audio. Returns 202; poll tasks for progress. Requires the administrator role.
Fingerprints 202 auth required
PUT /api/series/{id}/metadata
Update series metadata
Partially update a series' metadata fields.
Series 200 auth required
DELETE /api/jobs/{id}
Cancel or delete a transcode job
Cancels an in-progress job or clears a completed job's output file.
Jobs 204 auth required
PUT /api/admin/webhooks/{id}
Update webhook subscription
Updates a webhook's URL, subscribed event types, description, or enabled state. Does not rotate the signing secret. Requires the administrator role.
Webhooks 200 auth required
DELETE /api/admin/jobs/{id}
Cancel or delete a transcode job
For pending/running jobs, marks the task cancelled. For terminal jobs, deletes the row and (when remove_file=true) removes the output file plus any registered MediaFile/ContentFile for library variants. Requires the administrator role.
Jobs 200 auth required
GET /api/admin/push/deliveries
Recent push deliveries for this license
Fetches the recent delivery log from push.odeion.app.
Push 200 auth required
PATCH /api/admin/content/{type}/{id}/images
Patch image state for a content entity
Applies a partial update to the entity's image curation. Today the supported mutation is promoting a candidate to default for a given role — send {role, asset_id} and the chosen asset is bumped to AssetPriorityAdminPick while others in the slot are demoted to the Remote tier. Requires the administrator role.
Content 200 auth required
POST /api/admin/metadata/refresh
Enqueue bulk metadata refresh
Enqueues a metadata refresh task for every movie and series matching the supplied filters (library, type, age). Returns 202; monitor progress via the tasks API. Requires the administrator role.
Metadata 202 auth required
GET /api/admin/segments/{type}/{id}
List skip segments for a media item
Returns the intro, recap, and credits skip segments currently attached to a media item. Type is `movie` or `episode`. Requires the administrator role.
Segments 200 auth required
GET /api/watchtogether/users
List Watch Together users
Returns users available for Watch Together invitations.
Watch Together 200 auth required
POST /api/progress/{type}/{id}/stop
Stop playback
Signals that playback has stopped for a media item.
Progress 200 auth required
GET /api/admin/settings/general
Get general server settings
Returns the general settings group: server name, base URL, link service toggle, release channel, and other top-level server identity fields. Requires the moderator role.
Settings 200 auth required
GET /api/admin/transcode-sessions
List transcoder sessions
Lists every ffmpeg/ffprobe invocation that ran through the transcoder pool — live HLS playback, downloads, library variants, plus optional system tasks (probe, media_process, analyze_segments). Tells the story of media from input to output. Requires the moderator role.
Transcoding 200 auth required
POST /api/admin/transcode-sessions/{id}/cancel
Cancel a live transcoder session
Forcibly terminates an active live HLS/DASH transcode. Job-driven transcodes (download, content) should be cancelled via /api/admin/jobs/{id} instead. Requires the administrator role.
Transcoding 200 auth required
PUT /api/settings
Update user settings
Merges the request body into the user's settings.
Settings 200 auth required
GET /api/ws
Unified WebSocket (events + Watch Together)
Bidirectional WebSocket that carries both broker events (scan/job/playback/etc.) and Watch Together session traffic. Authenticates in-band: the first client frame must be {"type":"c2s_auth","payload":{"token":"<JWT>"}}. Server responds s2c_auth_ok on success or closes with policy-violation (1008) on auth failure/timeout. Filtering is applied per-user: admins receive admin.* events; regular users receive only events they own or are authorized for.
AppWatch Together auth required
GET /api/playback/{type}/{id}/transcode/{profile}
Stream transcoded media
Returns a progressive-download transcoded stream of the media file.
Playback 200 auth required
GET /api/libraries/scans
Get active scans
Returns all currently running scan statuses.
Libraries 200 auth required
DELETE /api/users/{id}
Delete a user
Removes a user account. Admin only.
Users 204 auth required
GET /api/admin/media-files/{id}
Get media file details
Returns full details for a single media file, including ffprobe output, associated content, and subtitle sidecar list. Requires the administrator role.
Media Files 200 auth required
PUT /api/admin/logs/settings
Update logging settings
Updates the log level, per-component overrides, and retention policy. Level changes apply live without restart. Requires the administrator role.
Logs 200 auth required
POST /api/admin/settings/integrations/test
Probe a Sonarr or Radarr instance
Runs a live probe against a Sonarr or Radarr instance using the supplied URL and API key without persisting them. Dispatches on `action`: `ping` verifies connectivity; `quality-profiles` returns the instance's quality profile catalog for dropdown population. Requires the administrator role.
Settings 200 auth required
GET /api/admin/watch-activity
List watch activity
Returns a paginated, filterable log of watch sessions across all users. Supports filtering by user, media type, status, and a free-text search, plus column sorting. Requires the administrator role.
Stats 200 auth required
And more
Hardware Transcoding
Full VAAPI, QSV, and NVENC hardware transcoding support out of the box.
Radarr & Sonarr Integration
Your users can request movies and shows directly in-app, with automatic downloads.
Discord & HTTP Webhooks
Get real-time notifications about server and user activity via Discord or HTTP.
Backups
Restoring from data loss or critical failures is easy and safe with built-in backup support.
Offline Downloads
Users can download media in device-compatible formats for offline access.
Trickplay Support
Thumbnail previews on the seek bar so users can visually scrub through their media.
Pay once. Own it forever.
Buy the server software once. One purchase, shared across your family.
Lifetime Family License
TBD
- ✓ One license covers your whole household
- ✓ Updates included
- ✓ One-time purchase for the server software
- ✓ Self-hosted means your data stays yours
Questions
Can I share my license with other people?
Your license is meant to be shared with your family and household. We're not building DRM walls or making it hard to share. But if you can afford it and you're getting value out of Odeion, please pay for it. That's what funds development.
Will I have to pay again for future versions?
We may introduce major version bumps down the road that require a new license purchase. But we plan to support the current version for a long time, with ongoing bug fixes and new features, not just maintenance mode.
How do I report bugs or request features?
Use the in-app bug reporting tool. It's built right into Odeion and is the best way to get issues and feature requests in front of us.
Does it need to be publicly accessible?
Odeion is designed to run behind a public HTTPS endpoint, especially for remote access and mobile apps. Local-only setups may work depending on your network configuration.