MDBList

MDBList adapter notes for syncing watchlist, history, ratings, and progress.

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

Use writes and deletes carefully.

Keep a current MDBList backup or export before larger changes.

If you want a CrossWatch rollback point, create a Capture first.

You can also sync MDBList into Adapter: CrossWatch as a local safety net.

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 (movies, shows, seasons, episodes)
  • Progress
  • 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).

CrossWatch rate-limits MDBList calls to reduce 429 Too Many Requests.

Defaults match SIMKL (10 GET/sec, 1 write/sec).

Tuning: Provider rate limiting

How matching works

CrossWatch keys items by external IDs whenever possible:

• tmdb, imdb, tvdb
• mdblist when returned by the API

Watchlist writes only send TMDb/IMDb. 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”.

History behavior

• Reads history for movies, shows, seasons, and episodes.
• Supports incremental history sync from a date watermark.
• Writes support watched upserts and removals.

Settings (advanced)

The UI shows these in Synchronization on the pair that uses 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], [MDBLIST:ratings], and [MDBLIST:history].
• 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

History:

• History index cache: /config/.cw_state/mdblist_history.index.json

Notes and limitations

• Missing external IDs reduces match quality.
• Ratings are de-duplicated by keeping the newest rated_at per key.