> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/advanced-and-api/api-reference.md). # API reference ## 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.
CategoryReference
Base URLs, sessions, responses, and OpenAPI./spaces/3rh5THg1PdhVsBt3GALo/pages/nQt9U8rY0Lw488M9JZA5
Provider sign-in, status, discovery, and profiles./spaces/3rh5THg1PdhVsBt3GALo/pages/9DjiyJyc2wIs7tbCbr8j
Pairs, sync runs, progress streams, and schedules./spaces/3rh5THg1PdhVsBt3GALo/pages/09rGQTh4JEilsyoec9MT
Watcher routes, runtime control, and inbound webhooks./spaces/3rh5THg1PdhVsBt3GALo/pages/9a8gBC41huecuySRxWFo
Insights, metadata, events, playlists, analysis, and exports./spaces/3rh5THg1PdhVsBt3GALo/pages/OcfapGshs2ocBoOJ26dl
Logs, captures, backups, and maintenance operations./spaces/3rh5THg1PdhVsBt3GALo/pages/x4hNl4pWDQc00H5oPtXL
### 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 ```bash BASE_URL="http://localhost:8787" curl -sS -c cookies.txt \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":"replace-me","remember_me":true}' \ "$BASE_URL/api/app-auth/login" curl -sS -b cookies.txt "$BASE_URL/api/provider-instances" ```
#### 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: ``` {"ok": true} ``` Typical application error: ``` {"ok": false, "error": "validation_failed"} ``` FastAPI validation errors normally use: ``` {"detail": [{"loc": ["body", "field"], "msg": "Field required", "type": "missing"}]} ``` #### 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 | Session | Stable | | GET | `/api/tautulli/status` | Return or verify Tautulli connection | Query: instance, verify | connected, instance and optional reason | Session | Stable | | POST | `/api/tautulli/disconnect` | Remove Tautulli credentials | Query: instance | {ok,instance} | Session | Stable | #### Trakt provider | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------- | ------------------------------------- | ---------------------------------------------------------- | ---------------------------------------- | ------- | --------- | | POST | `/api/trakt/pin/new` | Start Trakt device PIN authentication | Query: instance, optional JSON: client\_id, client\_secret | user\_code, verification\_url and expiry | Session | Stable | | POST | `/api/trakt/token/delete` | Disconnect Trakt profile | Query: instance | {ok} or usage conflict | Session | Stable | #### AniList provider | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | --------------------------- | ------------------------------------- | ------------------------------------------------- | ---------------------------- | ------- | --------- | | POST | `/api/anilist/save` | Save AniList OAuth client credentials | Query: instance, JSON: client\_id, client\_secret | {ok,instance} | Session | Stable | | GET | `/api/anilist/status` | Return AniList connection status | Query: instance | connected, user and instance | Session | Stable | | POST | `/api/anilist/authorize` | Create AniList authorization URL | Query: instance, JSON: origin | authorize\_url | Session | Stable | | GET | `/callback/anilist` | AniList OAuth callback | Query: code, state | Plain text completion page | Public | Callback | | POST | `/api/anilist/token/delete` | Disconnect AniList profile | Query: instance | {ok} | Session | Stable | #### SIMKL provider | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------- | ------------------------------------ | ----------------------------- | ------------------------------- | ------- | --------- | | POST | `/api/simkl/authorize` | Create SIMKL OAuth authorization URL | Query: instance, JSON: origin | authorize\_url and instance | Session | Stable | | GET | `/callback` | SIMKL OAuth callback | Query: code, state | Plain text completion page | Public | Callback | | POST | `/api/simkl/token/delete` | Disconnect SIMKL profile | Query: instance | {ok,instance} or usage conflict | Session | Stable | | POST | `/api/simkl/pin/start` | Start SIMKL PIN authentication | Query: instance | PIN flow details | Session | Stable | | POST | `/api/simkl/pin/poll` | Poll SIMKL PIN authentication | Query: instance | Pending or authorized status | Session | Stable | | POST | `/api/simkl/pin/cancel` | Cancel SIMKL PIN authentication | Query: instance | Cancellation result | Session | Stable | #### Provider profiles | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | -------------------------------------------------- | ------------------------------------ | ----------------------------------------------------- | --------------------------------- | ------- | --------- | | GET | `/api/provider-instances` | List profiles for all providers | None | Provider instance map | Session | Stable | | GET | `/api/provider-instances/{provider}` | List profiles for one provider | None | Provider instance list | Session | Stable | | POST | `/api/provider-instances/{provider}/next` | Create the next PROVIDER-P## profile | Optional JSON: copy\_from or source instance settings | Created instance | Session | Stable | | POST | `/api/provider-instances/{provider}/{instance_id}` | Create or replace a named profile | JSON provider configuration | Saved instance summary | Session | Stable | | DELETE | `/api/provider-instances/{provider}/{instance_id}` | Delete a non default profile | None | Deletion result or usage conflict | Session | Stable | #### Runtime status | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------------ | ----------------------------------------------- | ------------------ | ------------------- | ------- | --------- | | GET | `/api/status` | Aggregate provider health and connection probes | Query: fresh | Provider status map | Session | Stable | | POST | `/api/debug/clear_probe_cache` | Clear provider probe cache | None | {ok} | Session | Debug | #### Dashboard and insights | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | --------------------------------- | ---------------------------------------- | ---------------------------------------- | ------------------------ | ------- | --------- | | GET | `/api/dashboard/widgets` | Return dashboard widget data | Query: per widget limits and include CSV | Dashboard widget payload | Session | Stable | | GET | `/api/settings/overview` | Return settings overview | None | Configuration overview | Session | Stable | | GET | `/api/stats/raw` | Return raw statistics | None | Raw statistics | Session | Stable | | GET | `/api/stats` | Return calculated statistics | None | Statistics payload | Session | Stable | | POST | `/api/crosswatch/select-snapshot` | Select CrossWatch snapshot for a feature | Query: feature, snapshot | Selection result | Session | Stable | | GET | `/api/insights` | Return insights payload | Query: limit\_samples, history, runtime | Aggregated insights | Session | Stable | | GET | `/api/state/wall` | Return provider state wall | Query: both\_only, active\_only, limit | State wall rows | Session | Stable | #### Metadata | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------------ | --------------------------------------- | --------------------------------------------------------- | --------------------------------- | ------- | --------- | | GET | `/api/metadata/providers` | List metadata providers | None | Provider descriptors | Session | Stable | | GET | `/api/metadata/providers/html` | Render metadata provider cards | None | HTML | Session | UI | | GET | `/art/tmdb/{typ}/{tmdb_id}` | Resolve or proxy TMDb artwork | Query: size, kind, season, episode, locale, title, year | Image or redirect | Session | Stable | | GET | `/api/metadata/search` | Search metadata | Query: q, typ, year, limit | Search results | Session | Stable | | POST | `/api/metadata/resolve` | Resolve IDs and metadata for one entity | JSON: entity?, ids, locale?, need?, strategy? | Resolved metadata and identifiers | Session | Stable | | POST | `/api/metadata/bulk` | Resolve metadata for multiple items | Query: overview, locale, JSON: items, need?, concurrency? | Per item resolution results | Session | Stable | #### Activity | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ----------------------- | ----------------------- | --------------------------------------------------- | ---------------------- | ------- | --------- | | GET | `/api/activity/recent` | Return recent activity | Query: limit, since | Recent activity events | Session | Stable | | GET | `/api/activity/history` | Search activity history | Query: limit, offset, media\_type, status, q, since | Paged activity history | Session | Stable | | DELETE | `/api/activity/history` | Clear activity history | None | Deletion result | Session | Stable | #### Events | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | --------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ------- | --------- | | GET | `/api/events/status` | Return event store health and counts | None | Status payload | Session | Stable | | GET | `/api/events/statistics` | Return event statistics | Query: range, since, until, bucket | Time series and totals | Session | Stable | | GET | `/api/events/recent` | Return recent events | Query: limit, offset, visibility, order, view, domain | Paged events | Session | Stable | | GET | `/api/events/search` | Search events with filters | Query: q, event\_type, provider, origin\_provider, destination\_provider, source\_provider, feature, pair\_key, item\_key, run\_id, reason\_code, status, category, since, until, visibility, order, view, domain, limit, offset | Paged events | Session | Stable | | GET | `/api/events/groups` | Search event groups | Query: event filters, visibility, order, view, domain, limit, offset | Paged event groups | Session | Stable | | GET | `/api/events/tree` | Return grouped event tree | Query: event filters, children, visibility, order, view, domain, limit, offset | Event tree | Session | Stable | | GET | `/api/events/groups/{group_id}` | Return group detail | Query: run\_items\_limit, run\_items\_offset | Group, aggregate and run items | Session | Stable | | GET | `/api/events/groups/{group_id}/run-items` | Return group run items | Query: limit, offset | Paged run items | Session | Stable | | GET | `/api/events/groups/{group_id}/events` | Return events in a group | Query: order, limit, offset | Paged events | Session | Stable | | POST | `/api/events/groups/{group_id}/acknowledge` | Acknowledge a group | Optional JSON: by | Updated acknowledgement | Session | Stable | | POST | `/api/events/groups/{group_id}/unacknowledge` | Remove group acknowledgement | None | Updated acknowledgement | Session | Stable | | POST | `/api/events/correlate` | Rebuild event correlations | Optional JSON: reset | Correlation result | Session | Stable | | GET | `/api/events/item/{item_key}` | Return events for an item key | Query: limit, offset, visibility | Paged events | Session | Stable | | GET | `/api/events/run/{run_id}` | Return events for a run | Query: limit, offset, visibility | Paged events | Session | Stable | | POST | `/api/events/{event_id}/acknowledge` | Acknowledge one event | Optional JSON: by | Updated event | Session | Stable | | POST | `/api/events/{event_id}/unacknowledge` | Remove event acknowledgement | None | Updated event | Session | Stable | | GET | `/api/events/context` | Resolve event context | Query: event\_id, item\_key, provider, feature, pair\_key, run\_id, source\_provider, destination\_provider, origin\_provider | Context payload | Session | Stable | | POST | `/api/events/import` | Import event data | JSON import payload | Import counts and errors | Session | Stable | | POST | `/api/events/clear` | Clear event data | JSON: confirm, domain | Clear result | Session | Stable | #### Synchronization | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ---------------------------- | --------------------------------------- | ----------------------------------------------------- | ------------------------------- | ------- | --------- | | GET | `/api/sync/providers` | List sync providers and capabilities | None | Provider capabilities | Session | Stable | | GET | `/api/pairs` | List sync pairs | None | Pair array | Session | Stable | | POST | `/api/pairs` | Create a sync pair | JSON pair definition | Created or normalized pair | Session | Stable | | POST | `/api/pairs/reorder` | Reorder sync pairs | JSON ordered ids or pair list | Updated pair order | Session | Stable | | PUT | `/api/pairs/{pair_id}` | Update a sync pair | JSON partial or full pair | Updated pair | Session | Stable | | DELETE | `/api/pairs/{pair_id}` | Delete a sync pair | Query: purge\_state | Deletion and state purge result | Session | Stable | | GET | `/api/sync/providers/counts` | Return provider feature counts | Query: max\_age, force, source | Counts, age and errors | Session | Stable | | POST | `/api/run` | Start a synchronization run | Optional JSON: pair\_id or pairId and runtime options | Run accepted or skipped status | Session | Stable | | GET | `/api/run/summary` | Return latest run summary | None | Run summary | Session | Stable | | GET | `/api/run/unresolved` | Return unresolved items from latest run | None | Unresolved item list | Session | Stable | | GET | `/api/run/summary/file` | Download latest run summary | None | JSON file | Session | Stable | | GET | `/api/run/summary/stream` | Stream run progress and summary | None | Server Sent Events | Session | Stable | #### Scheduling | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ----------------------------- | -------------------------------------- | -------------------------------- | ------------------------------ | ------- | --------- | | POST | `/api/scheduling/replan_now` | Recalculate scheduler plan immediately | None | Updated schedule state | Session | Stable | | POST | `/api/scheduling/trigger_now` | Trigger scheduled work now | Optional JSON job or run payload | Trigger result | Session | Stable | | POST | `/api/scheduling/stop` | Stop scheduler | None | Scheduler state | Session | Stable | | GET | `/api/scheduling` | Return scheduling configuration | None | Scheduling configuration | Session | Stable | | POST | `/api/scheduling` | Save scheduling configuration | JSON scheduling configuration | Normalized saved configuration | Session | Stable | | GET | `/api/scheduling/status` | Return scheduler runtime status | None | Scheduler state | Session | Stable | | GET | `/api/scheduling/next` | Return next scheduled work | None | Next run details | Session | Stable | #### Scrobbler configuration | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | -------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------- | ------- | --------- | | GET | `/api/scrobbler/overview` | Return Watcher and webhook configuration overview | None | Sources, routes, profiles and generated URLs | Session | Stable | | POST | `/api/scrobbler/webhooks/profile` | Create or update a profile webhook | JSON: provider, provider\_instance, sinks, sink\_instances and settings | Saved config and runtime status | Session | Stable | | POST | `/api/scrobbler/webhooks/profile/disable` | Disable or remove a profile webhook | JSON: provider, provider\_instance, sink?, remove? | Saved config and runtime status | Session | Stable | | POST | `/api/scrobbler/webhooks/profile/regenerate` | Regenerate a profile webhook token | JSON: provider, provider\_instance | Saved config and new URL data | Session | Stable | | POST | `/api/scrobbler/webhooks/cleanup-legacy` | Remove legacy webhook identifiers | None | Saved config | Session | Stable | | POST | `/api/scrobbler/routes` | Create a Watcher route | JSON route definition | Saved config and runtime status | Session | Stable | | PUT | `/api/scrobbler/routes/{route_id}` | Update a Watcher route | JSON route fields | Saved config and runtime status | Session | Stable | | DELETE | `/api/scrobbler/routes/{route_id}` | Delete a Watcher route | None | Saved config and runtime status | Session | Stable | | POST | `/api/scrobbler/settings` | Save global scrobble settings | JSON sources, watcher and webhook settings | Saved config and runtime status | Session | Stable | #### Watcher runtime | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------------- | ---------------------------------------- | ---------------------- | ----------------------------------------- | ------- | --------- | | GET | `/api/watch/currently_watching` | Return current active playback streams | None | Primary stream, streams array and count | Session | Stable | | GET | `/api/watch/logs` | Return Watcher log tail | Query: tail, tag, tags | Selected tags and lines | Session | Stable | | GET | `/api/watch/status` | Return Watcher groups and route state | None | Groups, routes, alive, provider and sinks | Session | Stable | | POST | `/api/watch/start` | Start Watcher routes from configuration | None | Watcher state | Session | Stable | | POST | `/api/watch/stop` | Stop all Watcher routes | None | Watcher state | Session | Stable | | POST | `/api/watch/refresh` | Reload Watcher routes from configuration | None | Watcher state | Session | Stable | #### Webhooks | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------ | --------------------------------- | --------------------------------------------------------- | --------------------------------- | ------------- | --------- | | POST | `/webhook/plex` | Receive Plex playback webhook | Plex multipart, form or JSON payload, query profile token | Always HTTP 200 processing result | Webhook token | Stable | | POST | `/webhook/plextrakt` | Legacy Plex webhook alias | Same as /webhook/plex | Always HTTP 200 processing result | Webhook token | Legacy | | POST | `/webhook/jellyfin` | Receive Jellyfin playback webhook | Jellyfin JSON or form payload, query profile token | Always HTTP 200 processing result | Webhook token | Stable | | POST | `/webhook/jellyfintrakt` | Legacy Jellyfin webhook alias | Same as /webhook/jellyfin | Always HTTP 200 processing result | Webhook token | Legacy | | POST | `/webhook/emby` | Receive Emby playback webhook | Emby JSON or form payload, query profile token | Always HTTP 200 processing result | Webhook token | Stable | | POST | `/webhook/embytrakt` | Legacy Emby webhook alias | Same as /webhook/emby | Always HTTP 200 processing result | Webhook token | Legacy | | POST | `/webhook/plexwatcher` | Receive Plex rating webhook | Plex payload, query token, optionally route | Always HTTP 200 processing result | Webhook token | Stable | #### Files and logs | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------- | ------------------------------------------------ | ------------------------------ | ---------------------------------------- | ------- | --------- | | GET | `/api/files` | List a directory within configured storage scope | Query: path | Array of name, is\_dir and optional size | Session | Stable | | GET | `/api/logs/dump` | Return buffered log lines | Query: channel, n | channel and lines | Session | Stable | | GET | `/api/logs/stream` | Stream one log channel | Query: tag, tail, since, plain | Server Sent Events | Session | Stable | | GET | `/api/logs/watcher` | Stream selected Watcher log channels | Query: tail, tags, plain | Server Sent Events | Session | Stable | #### Watchlist tool | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ----------------------------- | ------------------------------- | ----------------------------------------- | -------------------------- | ------- | --------- | | GET | `/api/watchlist` | Return consolidated watchlist | Query: overview, locale, limit, max\_meta | Watchlist rows and counts | Session | Stable | | GET | `/api/watchlist/` | Trailing slash alias | Same as /api/watchlist | Watchlist rows and counts | Session | Stable | | DELETE | `/api/watchlist/{key}` | Delete one watchlist item | Query: provider, provider\_instance | Per provider delete result | Session | Stable | | POST | `/api/watchlist/delete` | Delete multiple watchlist items | JSON: provider, provider\_instance, keys | Batch result | Session | Stable | | POST | `/api/watchlist/delete_batch` | Legacy batch delete alias | Same as /api/watchlist/delete | Batch result | Session | Stable | #### Playlists | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ---------------------------------------------- | ------------------------------------------- | ----------------------------- | ----------------------------------------- | ------- | --------- | | GET | `/api/playlists/providers` | List playlist capable providers | None | Provider capabilities | Session | Stable | | GET | `/api/playlists/resources` | List playlists or collections at a provider | Query: provider, instance | Provider resources | Session | Stable | | GET | `/api/playlists/overview` | Return playlist synchronization overview | None | Endpoints, mappings, results and activity | Session | Stable | | GET | `/api/playlists/endpoints` | List configured playlist endpoints | None | Endpoint list | Session | Stable | | POST | `/api/playlists/endpoints` | Create or update a playlist endpoint | JSON endpoint definition | Saved endpoint | Session | Stable | | DELETE | `/api/playlists/endpoints/{endpoint_id}` | Delete a playlist endpoint | None | Deletion result | Session | Stable | | POST | `/api/playlists/endpoints/{endpoint_id}/sync` | Refresh one endpoint from provider | None | Endpoint sync result | Session | Stable | | GET | `/api/playlists/activity` | Return playlist activity | None | Activity rows | Session | Stable | | GET | `/api/playlists/rulesets` | List playlist rulesets | None | Ruleset summaries | Session | Stable | | GET | `/api/playlists/rulesets/{ruleset_id}` | Return one playlist ruleset | None | Ruleset | Session | Stable | | POST | `/api/playlists/rulesets` | Create or update a ruleset | JSON ruleset | Saved ruleset | Session | Stable | | POST | `/api/playlists/rulesets/validate` | Validate a ruleset | JSON ruleset | Validation errors and normalized rules | Session | Stable | | POST | `/api/playlists/rulesets/{ruleset_id}/clone` | Clone a ruleset | Optional JSON changes | Cloned ruleset | Session | Stable | | DELETE | `/api/playlists/rulesets/{ruleset_id}` | Delete a ruleset | None | Deletion result | Session | Stable | | GET | `/api/playlists/mappings` | List playlist mappings | None | Mapping list | Session | Stable | | POST | `/api/playlists/mappings` | Create or update a mapping | JSON mapping | Saved mapping | Session | Stable | | DELETE | `/api/playlists/mappings/{mapping_id}` | Delete a mapping | None | Deletion result | Session | Stable | | POST | `/api/playlists/mappings/{mapping_id}/preview` | Preview mapping execution | Optional JSON runtime options | Plan and warnings | Session | Stable | | POST | `/api/playlists/mappings/{mapping_id}/run` | Run a playlist mapping | Query: dry\_run | Run result or accepted status | Session | Stable | | GET | `/api/playlists/mappings/{mapping_id}/result` | Return latest mapping result | None | Result summary | Session | Stable | | GET | `/api/playlists/pairs/{pair_id}/mappings` | List mappings associated with a sync pair | None | Mapping list | Session | Stable | #### Editor | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------ | ------- | --------- | | GET | `/api/editor/playlists/endpoints` | List playlist endpoints available to Editor | None | Endpoint list | Session | Stable | | GET | `/api/editor/playlists/{endpoint_id}` | Load one playlist into Editor | None | Editable playlist | Session | Stable | | POST | `/api/editor/playlists/{endpoint_id}` | Save edited playlist | JSON playlist items and options | Save result | Session | Stable | | GET | `/api/editor/tracker/workspaces` | List local CrossWatch tracker workspaces | None | Workspace list | Session | Stable | | GET | `/api/editor/state/providers` | List provider state available to Editor | None | Provider and feature map | Session | Stable | | GET | `/api/editor` | Load an Editor dataset | Query: kind, snapshot, source, provider, provider\_instance, endpoint, workspace | Editable dataset | Session | Stable | | POST | `/api/editor` | Save generic Editor changes | JSON: kind, source, items and provider specific options | Save result | Session | Stable | | GET | `/api/editor/state/manual/export` | Download manual policy state | None | JSON attachment | Session | Stable | | POST | `/api/editor/state/manual/import` | Import manual policy state | Query: mode merge or replace, multipart file | Import result | Session | Stable | | GET | `/api/editor/state/import/providers` | List providers available for live state import | None | Provider list | Session | Debug | | POST | `/api/editor/state/import` | Import live provider state | JSON: provider, provider\_instance, features, mode, dry\_run | Import plan or result | Session | Debug | #### Manual actions | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ----------------------- | ------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- | ------- | --------- | | GET | `/api/manual/providers` | List providers supported by manual actions | None | Provider capabilities | Session | Stable | | POST | `/api/manual/watched` | Apply manual watched, watchlist or rating actions | JSON: item, providers, actions, date\_mode, watched\_on, rating | Per provider results, HTTP 200 may contain failures | Session | Stable | #### Captures | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ----------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------- | ------- | --------- | | GET | `/api/snapshots/manifest` | Return capture feature manifest | None | Manifest | Session | Stable | | GET | `/api/snapshots/list` | List captures | None | Capture list | Session | Stable | | GET | `/api/snapshots/read` | Read a capture | Query: path | Capture JSON | Session | Stable | | GET | `/api/snapshots/diff` | Calculate basic diff | Query: a, b, limit, max\_changes | Diff summary and changes | Session | Stable | | GET | `/api/snapshots/diff/extended` | Calculate filtered extended diff | Query: a, b, feature, kind, q, offset, limit, max\_changes, max\_depth | Paged extended diff | Session | Stable | | POST | `/api/snapshots/create` | Create a capture | JSON: provider, instance or instance\_id, feature, label, progress\_id, background or async | Capture or background job result | Session | Stable | | GET | `/api/snapshots/capture-progress/{progress_id}` | Return capture or restore progress | None | Progress state | Session | Stable | | POST | `/api/snapshots/restore` | Restore a capture | JSON: path, mode, instance, progress\_id, background | Restore result or background job | Session | Stable | | POST | `/api/snapshots/delete` | Delete a capture | JSON: path, delete\_children | Deletion result | Session | Stable | | POST | `/api/snapshots/clear` | Clear captures | Optional JSON filters | Clear result | Session | Stable | | POST | `/api/snapshots/tools/clear` | Clear provider capture data | JSON: provider, instance, features, progress\_id, background | Clear result | Session | Stable | #### Backups | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- | --------- | | GET | `/api/backups/list` | List backups | None | Backup list | Session | Stable | | POST | `/api/backups/create` | Create backup archive | JSON: scope, label, include\_snapshots, include\_reports, include\_cache | Backup metadata | Session | Stable | | GET | `/api/backups/download` | Download backup ZIP | Query: path | ZIP archive | Session | Stable | | POST | `/api/backups/validate` | Validate backup archive | JSON: path | Validation report | Session | Stable | | POST | `/api/backups/restore` | Restore backup archive | JSON: path, restart | Restore report, optional restart | Session | Stable | | POST | `/api/backups/delete` | Delete backup archive | JSON: path | Deletion result | Session | Stable | | POST | `/api/backups/upload` | Upload backup ZIP | Multipart file | Stored backup metadata | Session | Stable | | GET | `/api/backups/schedule` | Return backup schedule | None | Schedule configuration | Session | Stable | | POST | `/api/backups/schedule` | Save backup schedule | JSON: enabled, scope, at, days, label\_template, retention\_days, max\_backups, auto\_delete\_old, include\_snapshots, include\_reports, include\_cache | Saved schedule | Session | Stable | | POST | `/api/backups/retention` | Apply backup retention | JSON: retention\_days, max\_backups | Deleted and retained backups | Session | Stable | #### Maintenance | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | -------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------- | ------- | ----------- | | POST | `/api/maintenance/clear-metadata-cache` | Delete metadata and artwork cache | None | Before, after and removed entries | Session | Destructive | | GET | `/api/maintenance/crosswatch-tracker` | Inspect local CrossWatch tracker storage | None | Paths, files and counts | Session | Destructive | | GET | `/api/maintenance/crosswatch-tracker/export` | Export CrossWatch tracker storage | None | ZIP archive | Session | Destructive | | POST | `/api/maintenance/crosswatch-tracker/import` | Import CrossWatch tracker archive | Multipart file | Import result | Session | Destructive | | POST | `/api/maintenance/clear-state` | Delete orchestrator state.json | None | Deletion result | Session | Destructive | | POST | `/api/maintenance/crosswatch-tracker/clear` | Clear tracker state and or snapshots | JSON: clear\_state, clear\_snapshots | Clear result | Session | Destructive | | POST | `/api/maintenance/clear-cache` | Clear top level provider cache files | None | Before, after and removed entries | Session | Destructive | | POST | `/api/maintenance/clear-provider-sync-cache` | Clear provider sync cache | Optional JSON filters | Clear result | Session | Destructive | | GET | `/api/maintenance/provider-cache` | Inspect provider cache | None | Path, files and counts | Session | Destructive | | GET | `/api/maintenance/action-status/{action}` | Return background maintenance action status | None | Action state | Session | Destructive | | POST | `/api/maintenance/events-health` | Check event database health | None | Health report | Session | Destructive | | POST | `/api/maintenance/events-optimize` | Optimize event database | None | Optimization report | Session | Destructive | | POST | `/api/maintenance/events-rebuild` | Rebuild event database | JSON: confirm true | Rebuild report | Session | Destructive | | POST | `/api/maintenance/reset-all-default` | Reset application configuration to defaults | Optional JSON: restart | Reset result, optional restart | Session | Destructive | | POST | `/api/maintenance/restart` | Hard restart CrossWatch | None | {ok}, process exits shortly afterwards | Session | Destructive | | POST | `/api/maintenance/reset-currently-watching` | Delete currently\_watching state | None | Deletion result | Session | Destructive | | POST | `/api/maintenance/clear-activity-log` | Clear activity log | None | Clear result | Session | Destructive | | POST | `/api/maintenance/clear-recent-scrobbles` | Clear recent scrobble state | None | Clear result | Session | Destructive | | POST | `/api/maintenance/reset-stats` | Purge and optionally recalculate statistics | JSON: recalc, purge\_file, purge\_state, purge\_reports, purge\_insights | Purge and recalculation report | Session | Destructive | #### Anime mapping | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ---------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------- | ------- | --------- | | GET | `/api/anime-mapping/status` | Return anime mapping data status | None | Status and installed release | Session | Stable | | POST | `/api/anime-mapping/settings` | Save anime mapping settings | JSON: enabled, auto\_update, provider, release\_tag, refresh\_hours, stale\_after\_days, use\_for\_pairs | Saved settings | Session | Stable | | POST | `/api/anime-mapping/update` | Download or refresh anime mapping release | JSON: release\_tag, force | Update result | Session | Stable | | POST | `/api/anime-mapping/rebuild-index` | Rebuild local anime mapping index | JSON: release\_tag | Rebuild result | Session | Stable | #### Playback progress | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | ------- | --------- | | GET | `/api/playback_progress/providers` | List playback progress providers | None | Provider capabilities | Session | Stable | | GET | `/api/playback_progress/settings` | Return playback progress settings | None | Settings | Session | Stable | | POST | `/api/playback_progress/settings` | Save playback progress settings | JSON settings | Saved settings | Session | Stable | | GET | `/api/playback_progress/items` | Search resumable playback items | Query: provider, instance\_id, media\_type, progress\_min, progress\_max, age, rating\_min, search, sort, page, page\_size, force\_refresh | Paged items | Session | Stable | | POST | `/api/playback_progress/actions/remove` | Remove playback progress | JSON target items and provider context | Per item results | Session | Stable | | POST | `/api/playback_progress/actions/mark_watched` | Mark playback items watched | JSON target items and provider context | Per item results | Session | Stable | | POST | `/api/playback_progress/actions/update_progress` | Set playback progress | JSON target items, progress and provider context | Per item results | Session | Stable | | POST | `/api/playback_progress/actions/bulk` | Run bulk playback action | JSON action, items and provider context | Batch results | Session | Stable | #### Analyzer | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | ----------------------------- | -------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------- | ------- | --------- | | GET | `/api/analyzer/state` | Return normalized state rows | Query: pairs CSV, offset, limit | counts, items, total and paging | Session | Stable | | GET | `/api/analyzer/problems` | Analyze state problems | Query: pairs CSV, include\_system, include\_hints | problems, summary, pair stats and timings | Session | Stable | | GET | `/api/analyzer/system` | Run system diagnostics | Query: pairs ignored | problems and timings | Session | Stable | | GET | `/api/analyzer/pair-activity` | Return last state update per pair | None | Pair ids and last\_run\_ns | Session | Stable | | GET | `/api/analyzer/detail` | Return details for one state item | Query: provider, feature, key, pairs | targets, hints and target show info | Session | Stable | | GET | `/api/analyzer/ratings-audit` | Audit rating state | Query: pairs | Rating audit | Session | Stable | | GET | `/api/analyzer/cw-state` | Inspect provider side state artifacts | Query: pairs | CW state artifact summary | Session | Stable | | POST | `/api/analyzer/patch` | Patch IDs and optionally rekey an item | Query: pairs, JSON: provider, feature, key, ids, merge\_peer\_ids?, rekey? | ok and new\_key | Session | Stable | | POST | `/api/analyzer/suggest` | Suggest IDs or mapping for an item | Query: pairs, JSON: provider, feature, key | Suggestions | Session | Stable | | POST | `/api/analyzer/fix` | Apply a supported analyzer fix | Query: pairs, JSON: type, provider, feature, key and fix fields | Fix result | Session | Stable | | PATCH | `/api/analyzer/item` | Edit item title, year or IDs | Query: pairs, JSON: provider, feature, key, updates | ok and new\_key | Session | Stable | | DELETE | `/api/analyzer/item` | Delete item from local state | Query: pairs, JSON: provider, feature, key | {ok} | Session | Stable | #### Exports | Method | Endpoint | Purpose | Main request input | Main response | Auth | Stability | | ------ | --------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------- | ------- | --------- | | GET | `/api/export/options` | Return export providers, counts, formats and capabilities | None | Export option payload | Session | Stable | | GET | `/api/export/sample` | Preview export rows | Query: provider, provider\_instance, feature, format, media\_types, include\_watched\_date, limit, q | Items, totals, warnings and validation | Session | Stable | | GET | `/api/export/file` | Download export file | Query: provider, provider\_instance, feature, format, media\_types, include\_watched\_date, q, ids | CSV file | Session | Stable | ### Core workflow examples #### Read health and version
Show cURL example ```bash curl -sS "$BASE_URL/api/health" curl -sS -b cookies.txt "$BASE_URL/api/version" ```
#### Read redacted configuration
Show cURL example ```bash curl -sS -b cookies.txt "$BASE_URL/api/config" ```
The response masks secrets. Posting a masked secret back through `POST /api/config` preserves the stored secret rather than replacing it with the mask. #### List and create provider profiles
Show cURL example ```bash curl -sS -b cookies.txt "$BASE_URL/api/provider-instances" curl -sS -b cookies.txt \ -X POST \ -H "Content-Type: application/json" \ -d '{"copy_from":"default"}' \ "$BASE_URL/api/provider-instances/plex/next" ```
Profile deletion can return HTTP 409 when the profile is referenced by a pair, Watcher route, webhook profile or another active configuration. #### Create a sync pair
Show cURL example ```bash curl -sS -b cookies.txt \ -X POST \ -H "Content-Type: application/json" \ -d '{ "name": "Plex to Trakt", "source": "PLEX", "source_instance": "default", "target": "TRAKT", "target_instance": "default", "mode": "one_way", "enabled": true, "features": { "watchlist": {"enabled": true, "add": true, "remove": false}, "history": {"enabled": true, "add": true, "remove": false}, "ratings": {"enabled": false} } }' \ "$BASE_URL/api/pairs" ```
The exact normalized result depends on current pair defaults and provider capabilities. Start with removal disabled, inspect the plan, then enable removal only when the baseline is trusted. #### Trigger one sync pair
Show cURL example ```bash curl -sS -b cookies.txt \ -X POST \ -H "Content-Type: application/json" \ -d '{"pair_id":"PAIR_ID"}' \ "$BASE_URL/api/run" ```
Read the latest result:
Show cURL example ```bash curl -sS -b cookies.txt "$BASE_URL/api/run/summary" curl -sS -b cookies.txt "$BASE_URL/api/run/unresolved" ```
#### Stream sync progress
Show cURL example ```bash curl -N -b cookies.txt "$BASE_URL/api/run/summary/stream" ```
The connection remains open and emits Server Sent Events. Clients must support reconnects and ignore `ping` events. #### Start and inspect Watcher
Show cURL example ```bash curl -sS -b cookies.txt -X POST "$BASE_URL/api/watch/start" curl -sS -b cookies.txt "$BASE_URL/api/watch/status" curl -sS -b cookies.txt "$BASE_URL/api/watch/currently_watching" ```
Watcher configuration is managed through `/api/scrobbler/routes`, `/api/scrobbler/settings` and the profile webhook routes. Runtime start and stop routes do not replace configuration. #### Stream Watcher logs
Show cURL example ```bash curl -N -b cookies.txt "$BASE_URL/api/logs/watcher?tail=200&plain=true" ```
#### Create a capture
Show cURL example ```bash curl -sS -b cookies.txt \ -X POST \ -H "Content-Type: application/json" \ -d '{ "provider": "TRAKT", "instance": "default", "feature": "history", "label": "Before migration", "background": false }' \ "$BASE_URL/api/snapshots/create" ```
#### Create and validate a backup
Show cURL example ```bash curl -sS -b cookies.txt \ -X POST \ -H "Content-Type: application/json" \ -d '{ "scope": "app_state", "label": "Before upgrade", "include_snapshots": true, "include_reports": true, "include_cache": false }' \ "$BASE_URL/api/backups/create" ```
Use `/api/backups/validate` before restore. Backup restore and restart operations should not run during an active synchronization or capture. #### Manual watched action
Show cURL example ```bash curl -sS -b cookies.txt \ -X POST \ -H "Content-Type: application/json" \ -d '{ "item": { "type": "movie", "title": "Example Movie", "year": 2025, "ids": {"tmdb": 12345} }, "providers": [ {"provider": "TRAKT", "instance": "default"} ], "actions": {"history": true, "watchlist": false, "rating": false}, "date_mode": "today" }' \ "$BASE_URL/api/manual/watched" ```
This route can return HTTP 200 with a mix of successful and failed provider results. Inspect every entry in `results`. #### Export data
Show cURL example ```bash curl -sS -b cookies.txt \ "$BASE_URL/api/export/options" curl -sS -b cookies.txt \ -o crosswatch-export.csv \ "$BASE_URL/api/export/file?provider=TRAKT&provider_instance=all&feature=history&format=yamtrack&media_types=movie,show" ```
### Webhook reference #### Canonical webhook routes | Source | Route | Accepted payloads | | ----------------- | --------------------------- | ---------------------------------------------------- | | Plex playback | `POST /webhook/plex` | Plex multipart payload, URL encoded payload or JSON. | | Jellyfin playback | `POST /webhook/jellyfin` | JSON or URL encoded payload. | | Emby playback | `POST /webhook/emby` | JSON or URL encoded payload. | | Plex ratings | `POST /webhook/plexwatcher` | Plex rating webhook payload. | The `plextrakt`, `jellyfintrakt` and `embytrakt` routes are legacy aliases. #### Acknowledgement behavior Webhook handlers intentionally acknowledge malformed, ignored, duplicate, filtered and internally failed events with HTTP 200 in many cases. This prevents the media server from retrying the same event indefinitely. The JSON body is the authoritative processing result. #### Generated URLs Use `GET /api/scrobbler/overview` after saving configuration. It returns the effective generated webhook URLs. Do not construct tokens manually. ### Server Sent Events CrossWatch has three primary SSE routes: | Route | Use | | ----------------------------- | ------------------------------------------- | | `GET /api/run/summary/stream` | Synchronization progress and final summary. | | `GET /api/logs/stream` | One selected log channel. | | `GET /api/logs/watcher` | Multiple Watcher related log channels. | SSE clients should: 1. Send the application session cookie. 2. Disable response buffering in the reverse proxy. 3. Process `ping` keepalive events. 4. Reconnect after network interruption. 5. Avoid opening several duplicate streams per browser tab. ### Destructive operations The following groups can delete local data or restore previous data: 1. `/api/maintenance/*` 2. `/api/backups/restore` 3. `/api/backups/delete` 4. `/api/snapshots/restore` 5. `/api/snapshots/delete` 6. `/api/snapshots/clear` 7. `/api/events/clear` 8. `/api/activity/history` with DELETE 9. `/api/analyzer/item` with DELETE 10. Provider disconnect and profile deletion routes Maintenance operations primarily remove CrossWatch local files, not provider data. A later synchronization can still produce provider changes because local baselines and caches have been rebuilt. Run a dry run after state or cache resets. ### Runtime OpenAPI FastAPI exposes the runtime schema through `/openapi.json`, with interactive documentation normally available through `/docs` and `/redoc`. These routes follow the normal application access controls. Export the live schema:
Show cURL example ```bash curl -sS -b cookies.txt "$BASE_URL/openapi.json" -o crosswatch-openapi.json ```
The live schema is useful for client generation, but it does not replace this reference because many handlers use generic dictionary bodies and dynamic service registration. ### API design findings #### The current wiki page is incomplete The current API page documents the base URL and a few common provider instance, Watcher and insights routes. The implementation exposes a much larger operational surface. #### No stable external API version There is no `/api/v1` namespace. A UI refactor can therefore change an integration route without an explicit API version transition. #### Session authentication is browser oriented The general API uses an application cookie. A dedicated service token with explicit scopes would be more suitable for automation, monitoring and external integrations. #### Request and response schemas are uneven Several handlers accept `dict[str, Any]`. OpenAPI can identify the route but cannot always document required fields, constraints or response variants. Explicit request and response models would improve generated documentation and client validation. #### HTTP status semantics are mixed Some failures use 4xx or 5xx statuses, while others return HTTP 200 with `ok: false`. Webhook acknowledgement is intentional. Provider and operational routes would benefit from a more consistent error envelope. #### Aliases and duplicate route registration need clear deprecation Legacy webhook aliases remain active. Plex user discovery is registered by more than one module. Deprecation metadata and a removal target would reduce ambiguity. #### Destructive scopes should be explicit Maintenance, restore and clear routes should remain clearly separated from read only routes. A future service token design should use scopes such as `read`, `sync`, `configure`, `webhook`, `maintenance` and `restore`. ### Recommended documentation structure For the public wiki, use this structure: 1. API overview, base URL, authentication, errors and OpenAPI. 2. Core automation, profiles, pairs, runs, summaries and scheduling. 3. Watcher and webhooks. 4. Provider authentication flows. 5. Playlists, Editor, Analyzer, captures, backups and exports. 6. Maintenance and destructive operations. 7. Complete generated endpoint inventory. The endpoint inventory should be generated or checked in CI from FastAPI routes. Hand maintained endpoint lists will drift because CrossWatch registers routes from `api/`, `services/` and dynamic registration functions. ### Source map Primary route registration and implementation locations: | Area | Source | | ------------------------------------ | ----------------------------------------------------- | | Main app, middleware, files and logs | `crosswatch.py` | | Router registration | `api/__init__.py` | | Application sessions | `api/appAuthAPI.py`, `api/authPlexAPI.py` | | Provider authentication | `api/authenticationAPI.py` | | Synchronization and pairs | `api/syncAPI.py` | | Watcher and webhooks | `api/scrobbleAPI.py`, `api/scrobblerManagementAPI.py` | | Metadata | `api/metaAPI.py` | | Events and activity | `api/eventsAPI.py`, `api/activityAPI.py` | | Scheduling | `api/schedulingAPI.py` | | Playlists | `api/playlistsAPI.py` | | Editor and manual actions | `api/editorAPI.py`, `api/manualAPI.py` | | Captures and backups | `api/snapshotsAPI.py`, `api/backupsAPI.py` | | Maintenance | `api/maintenanceAPI.py` | | Analyzer | `services/analyzer.py` | | Exports | `services/export.py` |
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.crosswatch.app/crosswatch/advanced-and-api/api-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.