API reference

API overview and endpoint reference, organized by functional area.

API reference

CrossWatch exposes a self-hosted JSON API for application automation and operations.

Use the categories below to find endpoints by purpose. The complete inventory remains on this page.

Category

Base URLs, sessions, responses, and OpenAPI.

Reference

API foundations

Category

Provider sign-in, status, discovery, and profiles.

Reference

Connections and profiles

Category

Pairs, sync runs, progress streams, and schedules.

Reference

Synchronization and scheduling

Category

Watcher routes, runtime control, and inbound webhooks.

Reference

Scrobbling and webhooks

Category

Insights, metadata, events, playlists, analysis, and exports.

Reference

Data, insights, and tools

Category

Logs, captures, backups, and maintenance operations.

Reference

Storage and operations

Scope and compatibility

CrossWatch does not currently expose a versioned base path such as /api/v1. All routes in this document are implementation routes, not a formal long term compatibility contract.

Some request and response models are plain Python dictionaries rather than explicit Pydantic models. Those routes appear in OpenAPI, but their field level schema can be incomplete. This document therefore records the fields enforced or consumed by the implementation and describes opaque service payloads by purpose.

Legacy aliases, UI only routes, callbacks, debug routes and destructive routes are marked in the Stability column.

Base URL

The API is served by the CrossWatch instance.

http://localhost:8787
https://crosswatch.example.com

Use HTTPS whenever the instance is reachable beyond localhost or a trusted private network.

Most API responses are JSON. File download routes return JSON, CSV, PEM or ZIP. Streaming routes return Server Sent Events with Content-Type: text/event-stream.

Authentication

Application session

Normal API access uses the local CrossWatch application session. A successful login sets an HTTP only cookie named cw_auth. CrossWatch does not currently provide a general bearer token for external API clients.

When application authentication is enabled:

1. GET /api/health and GET /healthz remain public.
2. Login, initial setup and OAuth callback routes remain reachable as required by their flows.
3. Normal /api/* routes require a valid cw_auth session.
4. Unauthenticated API requests normally return HTTP 401.
5. An instance that still requires setup can return HTTP 403 with a setup required response.
6. Webhook routes use webhook tokens and are excluded from normal application session enforcement.

Show cURL example

Webhook authentication

Generated webhook URLs contain a scoped token. Profile webhooks use the profile token generated by the Scrobbler configuration API. Plex rating webhooks use token and can additionally use route for a route specific target.

Do not expose webhook tokens in screenshots, public issue reports or logs. Regenerate a token through the Scrobbler API when it has been disclosed.

OAuth callbacks

The SIMKL, AniList and Plex SSO callbacks are browser flow endpoints. They are not general integration endpoints.

Common behavior

Response handling

CrossWatch commonly returns an ok boolean. Clients must inspect both the HTTP status and the JSON body. Several provider, webhook and operational routes deliberately return HTTP 200 with ok: false, ignored: true or an error field.

Typical success response:

Typical application error:

FastAPI validation errors normally use:

Common status codes

Status	Meaning
200	Successful request, or an intentionally acknowledged webhook or provider operation. Inspect the body.
400	Invalid request, missing field or unsupported operation.
401	Missing or invalid application session, or invalid provider credentials.
403	Setup required, origin rejected or provider authorization denied.
404	Resource, state item, capture or backup not found.
409	Resource is in use, conflicting provider profile or unsafe operation.
410	Expired authorization flow.
429	Login rate limit or upstream rate limit.
500	Internal CrossWatch failure or unavailable runtime component.
502	Upstream provider or server connection failure.
504	Upstream timeout.

Caching

CrossWatch adds no store response headers to /api/* routes. Clients should not assume browser or proxy caching for API responses.

Provider profile identifiers

Every provider has an implicit default profile. Additional profile identifiers normally use PROVIDER-P##, for example PLEX-P01 or TRAKT-P02. Depending on the route, the profile field can be named instance, instance_id, provider_instance, source_instance or target_instance.

Endpoint catalogue

Auth values:

1. Public, no application session.
2. Session, valid cw_auth cookie when application authentication is enabled.
3. Setup or session, available during initial setup, otherwise authenticated.
4. Webhook token, generated scoped token in the webhook URL.

Health

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
GET	/api/health	Liveness and readiness check	None	{ok,status}	Public	Stable
GET	/healthz	Container health alias, excluded from OpenAPI	None	{ok,status}	Public	Alias

Application authentication

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
GET	/api/app-auth/status	Return app authentication, session and Plex SSO status	None	Authentication status and session summaries	Public	Stable
POST	/api/app-auth/login	Create a local admin session	JSON: username, password, remember_me	Sets cw_auth cookie, returns ok and expires_at	Public	Stable
POST	/api/app-auth/logout	End current session	None	Clears current session and cookie	Session or public when disabled	Stable
POST	/api/app-auth/logout-all	End all sessions	None	Clears all sessions and current cookie	Session	Stable
POST	/api/app-auth/logout-others	End every session except current	None	{ok}	Session	Stable
POST	/api/app-auth/apply-now	Apply auth change by clearing sessions and restarting	Optional JSON	{ok}, process exits shortly afterwards	Session	Operational
POST	/api/app-auth/credentials	Enable, disable or change local credentials	JSON: enabled, username, password, remember_session_enabled, remember_session_days	{ok,enabled,expires_at?}, may replace session	Setup or session	Stable
GET	/login	Render local login page	None	HTML	Public	UI
GET	/logout	Logout and redirect	None	Redirect	Session	UI

Plex SSO

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
GET	/api/app-auth/plex/status	Return Plex SSO link status	None	Status, linked identity only when authenticated	Public	Stable
POST	/api/app-auth/plex/start	Start Plex SSO login flow	JSON: remember_me	state and auth_url, sets temporary flow cookie	Public	Stable
POST	/api/app-auth/plex/check	Poll Plex SSO login flow	JSON: state	pending or authenticated result, sets cw_auth cookie	Public	Stable
POST	/api/app-auth/plex/link/start	Start linking a Plex identity to local login	None	state and auth_url	Session	Stable
POST	/api/app-auth/plex/link/check	Poll and complete Plex identity linking	JSON: state	Linked identity status	Session	Stable
POST	/api/app-auth/plex/unlink	Remove Plex identity link	None	Updated link status	Session	Stable
GET	/api/app-auth/plex/callback	OAuth popup landing page	None	HTML	Public	Callback

Configuration

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
GET	/api/config/meta	Return configuration and setup metadata	None	Setup state, version state and authenticated file metadata	Session	Stable
GET	/api/config	Return redacted effective configuration	None	Configuration with secrets masked	Session	Stable
POST	/api/config	Deep merge and persist configuration	JSON object, masked values preserve existing secrets	Saved redacted configuration and runtime reload status	Session	Stable
POST	/api/config/migrate	Back up and migrate legacy configuration	Optional JSON overrides	Migration, backup and version result	Session	Stable

TLS

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
GET	/api/ui/tls/status	Return UI certificate status	None	Certificate paths, validity and configured host	Session	Stable
POST	/api/ui/tls/regenerate	Generate a new self signed UI certificate	JSON: hostname, valid_days, alt_dns, alt_ips	Generation status and certificate metadata	Session	Stable
GET	/api/ui/tls/cert	Download the current UI certificate	None	PEM certificate	Session	Stable

Version

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
GET	/api/update	Return update information	None	Current and available version information	Session	Stable
GET	/api/version	Return application version	None	Version payload	Session	Stable
GET	/api/version/check	Check the configured update source	None	Update check result	Session	Stable
GET	/api/modules/versions	Return provider and module versions	None	Module version map	Session	Stable

Provider authentication

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
GET	/api/auth/providers	List authentication provider manifests	None	Array of provider manifests	Session	Stable
GET	/api/auth/providers/html	Render authentication provider cards	None	HTML	Session	UI

Plex provider

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/plex/pin/new	Start Plex PIN authentication	Query: instance	PIN code, pin id and expiry	Session	Stable
GET	/api/plex/inspect	Inspect and persist Plex account and server details	Query: instance	Connection, server and account details	Session	Stable
POST	/api/plex/token/delete	Disconnect and reset a Plex profile	Query: instance	{ok,instance}, 409 when profile is in use	Session	Stable
GET	/api/plex/libraries	List Plex libraries	Query: instance, server, verify_ssl	libraries and instance	Session	Stable
GET	/api/plex/pms/probe	Probe configured Plex Media Server	Query: timeout, instance, server, verify_ssl	Reachability, HTTP status and server URL	Session	Stable
GET	/api/plex/pickusers	List selectable Plex users	Query: instance, server, verify_ssl	users, count and instance	Session	Stable
GET	/api/plex/users	List Plex users, registered by both auth and scrobble modules	Query: instance and optional access filters	users, count and instance	Session	Stable
GET	/api/plex/server_uuid	Resolve Plex server UUID	Query: instance	server_uuid and instance	Session	Stable
GET	/api/plex/pms	List Plex Media Servers for the account	Query: instance	servers, count and instance	Session	Stable

Jellyfin provider

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/jellyfin/login	Authenticate to Jellyfin with username and password	Query: instance, JSON: server, username, password, verify_ssl	Connection and user details	Session	Stable
POST	/api/jellyfin/token/delete	Disconnect Jellyfin profile	Query: instance	{ok} or usage conflict	Session	Stable
GET	/api/jellyfin/status	Return stored Jellyfin connection status	Query: instance	connected, user, server_version, instance	Session	Stable
GET	/api/jellyfin/quickconnect/available	Check Jellyfin Quick Connect support	Query: instance	supported, enabled and reason	Session	Stable
POST	/api/jellyfin/quickconnect/start	Start Quick Connect	Query: instance, JSON: server, verify_ssl	Quick Connect code and state	Session	Stable
GET	/api/jellyfin/quickconnect/poll	Poll Quick Connect	Query: instance	pending or authorized state	Session	Stable
POST	/api/jellyfin/quickconnect/cancel	Cancel Quick Connect	Query: instance	Cancellation result	Session	Stable
GET	/api/jellyfin/inspect	Inspect and persist Jellyfin server details	Query: instance	Inspection result	Session	Stable
GET	/api/jellyfin/libraries	List Jellyfin libraries	Query: instance, server, verify_ssl	libraries and instance	Session	Stable
GET	/api/jellyfin/users	List Jellyfin users	Query: instance, server, verify_ssl	users, count and instance	Session	Stable

Emby provider

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/emby/login	Authenticate to Emby	Query: instance, JSON: server, username, password, verify_ssl, timeout	Connection and user details	Session	Stable
GET	/api/emby/status	Return stored Emby connection status	Query: instance	connected, user and instance	Session	Stable
POST	/api/emby/token/delete	Disconnect Emby profile	Query: instance	{ok,instance} or usage conflict	Session	Stable
GET	/api/emby/inspect	Inspect and persist Emby server details	Query: instance	Inspection result	Session	Stable
GET	/api/emby/libraries	List Emby libraries	Query: instance, server, verify_ssl	libraries and instance	Session	Stable
GET	/api/emby/users	List Emby users	Query: instance, server, verify_ssl	users, count and instance	Session	Stable

TMDb metadata authentication

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/tmdb/verify	Validate TMDb v3 API key	JSON: api_key, masked value reuses stored key	ok, valid and error	Session	Stable
POST	/api/tmdb/save	Validate and save TMDb v3 API key	JSON: api_key	{ok,error?}	Session	Stable
POST	/api/tmdb/disconnect	Remove TMDb metadata API key	None	{ok}	Session	Stable

TMDb account authentication

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/tmdb_sync/connect/start	Start TMDb account authorization	Query: instance, JSON: api_key	request_token, auth_url and expiry	Session	Stable
POST	/api/tmdb_sync/connect/finish	Exchange approved request token for session	Query: instance, JSON: api_key?, request_token?	session_id, account_id and instance	Session	Stable
POST	/api/tmdb_sync/save	Save TMDb account credentials directly	Query: instance, JSON: api_key, session_id	{ok,instance}	Session	Stable
GET	/api/tmdb_sync/verify	Verify or auto finish TMDb account authorization	Query: instance	connected, pending, account and error	Session	Stable
POST	/api/tmdb_sync/disconnect	Remove TMDb account credentials	Query: instance	{ok,instance}	Session	Stable

MDBList provider

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/mdblist/save	Save MDBList API key or select device code authentication	Query: instance, JSON: auth_method, api_key	ok, instance and auth_method	Session	Stable
POST	/api/mdblist/device/start	Start MDBList device authentication	Query: instance, optional JSON	Device authorization result	Session	Stable
POST	/api/mdblist/device/poll	Poll MDBList device authentication	Query: instance, JSON: device_code?	Pending or authorized status	Session	Stable
POST	/api/mdblist/refresh	Refresh MDBList OAuth token	Query: instance	Refresh status	Session	Stable
GET	/api/mdblist/status	Return MDBList authentication status	Query: instance	Connection and token status	Session	Stable
POST	/api/mdblist/disconnect	Disconnect MDBList profile	Query: instance	{ok,instance} or usage conflict	Session	Stable

PublicMetaDB provider

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/publicmetadb/save	Validate and save PublicMetaDB API key	Query: instance, JSON: api_key	{ok,instance,error?}	Session	Stable
GET	/api/publicmetadb/status	Validate stored PublicMetaDB connection	Query: instance	connected, instance and reason	Session	Stable
POST	/api/publicmetadb/disconnect	Remove PublicMetaDB API key	Query: instance	{ok,instance}	Session	Stable

Nuvio provider

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/nuvio/device/start	Start Nuvio TV device login	Query: instance, JSON: redirect_base_url?	Device login state	Session	Stable
POST	/api/nuvio/device/poll	Poll Nuvio device login	Query: instance, optional JSON	Poll status	Session	Stable
POST	/api/nuvio/device/finish	Complete Nuvio login session exchange	Query: instance, optional JSON	Expiry and available profiles	Session	Stable
GET	/api/nuvio/status	Return Nuvio authentication status	Query: instance	Token and connection status	Session	Stable
GET	/api/nuvio/profiles	Refresh and list Nuvio profiles	Query: instance	profiles	Session	Stable
POST	/api/nuvio/profile/select	Select Nuvio profile	Query: instance, JSON: profile_id	Selected profile	Session	Stable
POST	/api/nuvio/refresh	Refresh Nuvio token	Query: instance	Refresh status without token values	Session	Stable
POST	/api/nuvio/disconnect	Disconnect Nuvio profile	Query: instance	{ok,instance} or usage conflict	Session	Stable

Tautulli provider

Method	Endpoint	Purpose	Main request input	Main response	Auth	Stability
POST	/api/tautulli/save	Validate and save Tautulli connection	Query: instance, JSON: server_url or server, api_key or key, user_id or history.user_id	Connection summary