Adapter: TMDb

TMDb adapter lets CrossWatch sync with your TMDb account. It supports watchlist and ratings.

Connect TMDb first. Use: TMDb.

What it supports

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

• Features:

  • Watchlist (movies and shows)

  • Ratings (movies, shows, and episodes)

  • History / Playlists (not supported)

• Rating scale: 1–10

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

How matching works

TMDb writes need a TMDb media ID.

CrossWatch resolves IDs in this order:

1. ids.tmdb (best)

2. ids.imdb via TMDb /find

3. ids.tvdb via TMDb /find (TV only)

CrossWatch UI features like Insights/Overview depend on ids.imdb.

So the TMDb adapter will also do an external lookup when it has a TMDb ID.

It calls TMDb external_ids and attaches ids.imdb when available.

If an item has no tmdb, imdb, or tvdb ID, it can’t be written to TMDb.

Watchlist behavior

• Read: your TMDb watchlist for movies and TV.

• Write: add/remove items from the watchlist.

CrossWatch does not sync TMDb custom lists.

Ratings behavior

• Read: your rated movies and TV shows.

• Write: set or clear ratings.

Ratings are integers from 1 to 10.

TMDb has API support for episode ratings. CrossWatch may index them. Some UIs hide episode rating writes based on feature gates.

Settings (advanced)

TMDb (Sync) stores credentials under tmdb_sync.

Important config keys

• tmdb_sync.api_key (TMDb v3 API key)

• tmdb_sync.session_id (session from the connect flow)

• tmdb_sync.account_id (optional, auto-discovered if missing)

• tmdb_sync.timeout (seconds)

• tmdb_sync.max_retries

Endpoints used (for debugging)

Watchlist:

• GET /account/{account_id}/watchlist/movies

• GET /account/{account_id}/watchlist/tv

• POST /account/{account_id}/watchlist

Ratings:

• GET /account/{account_id}/rated/movies

• GET /account/{account_id}/rated/tv

• GET /account/{account_id}/rated/tv/episodes (episode ratings)

• POST /movie/{id}/rating and DELETE /movie/{id}/rating

• POST /tv/{id}/rating and DELETE /tv/{id}/rating

• POST /tv/{show}/season/{s}/episode/{e}/rating and DELETE .../rating

ID resolution:

• GET /find/{external_id} (imdb_id / tvdb_id)

ID enrichment (adds ids.imdb / ids.tvdb when TMDb provides them):

• GET /{media_type}/{tmdb_id}/external_ids

Diagnostics

• Logs include TMDB and the feature name (example: watchlist, ratings).

• Health check probes GET /account.

Common unresolved reasons:

• Missing IDs for writes.

• Invalid rating (must be 1–10).

• Episode rating missing season or episode.

State and caching (advanced)

TMDb sync uses local state files under /config/.cw_state/.

These files are typically scoped per pair run, so different pairs don’t collide.

Scope details: Scope.

Notes and limitations

• TMDb has no history sync. It is watchlist + ratings only.

• For better matching, enable Meta: TMDb.

• Start one-way + dry run. Add removals only once runs are clean.

Deep dive (module-level): TMDb module.