Adapter: MDBList

MDBList adapter lets CrossWatch sync with MDBList. It supports watchlist and ratings. It prefers external IDs for matching.

MDBList has no export/import or rollback for your data. Use writes and deletes carefully.

Use the local backup adapter as a safety net: Adapter: CrossWatch.

What it supports

• Direction: source or target in a pair (one-way or two-way)

• Features:

  • Watchlist (movie/show)

  • Ratings (movies, shows, seasons, episodes)

  • History (not supported)

  • Playlists (not supported)

• Rating scale: 1–10

• Indexing: present-state snapshot (reads “what exists now”)

Connect MDBList first. Use: MDBList (Authentication provider).

MDBList fixed show-level ratings indexing/upserts (2025-11-11).

How matching works

CrossWatch keys items by external IDs whenever possible:

• imdb, tmdb, tvdb

• mdblist when returned by the API

Watchlist writes only send IMDb/TMDb. If an item has only TVDb, CrossWatch can’t write it to MDBList watchlist.

Watchlist behavior

• Reads the current watchlist and normalizes to {type, ids, title, year}.

• Writes add/remove operations for movies and shows.

Ratings behavior

• Reads ratings via a paginated endpoint.

• Normalizes ratings for movies, shows, seasons, and episodes.

• Writes support upsert and “unrate”.

Settings (advanced)

The UI mirrors these under Settings → Synchronization Providers → Pairs (with MDBList).

Endpoints used

Watchlist:

• GET /watchlist/items (supports limit, offset, unified=1)

• POST /watchlist/items/add

• POST /watchlist/items/remove

Ratings:

• GET /sync/ratings (paginated)

• POST /sync/ratings

• POST /sync/ratings/remove

Important config keys

Watchlist:

• watchlist_limit, watchlist_offset

Ratings:

• ratings_per_page (default 200)

• ratings_chunk_size

• ratings_write_delay_ms

• ratings_max_backoff_ms

Diagnostics

Logging and retries

• Logs are prefixed with [MDBLIST:watchlist] and [MDBLIST:ratings].

• Requests use retries with exponential backoff.

• Rate-limit headers and Retry-After are honored.

State and cache files

Watchlist:

• Shadow cache: /config/.cw_state/mdblist_watchlist.shadow.json

• Unresolved: /config/.cw_state/mdblist_watchlist.unresolved.json

Ratings:

• Ratings index cache: /config/.cw_state/mdblist_ratings.index.json

Notes and limitations

• Missing external IDs reduces match quality.

• Ratings are de-duplicated by keeping the newest rated_at per key.

• History and playlists are not implemented for MDBList.