> 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/settings/synchronization/trackers/tmdb.md).

# TMDb

TMDb adapter notes for syncing TMDb account data (watchlist/ratings) via TMDb (Sync).

{% hint style="info" %}
Connect TMDb first. See [TMDb (Sync) connection](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/tmdb.md).
{% endhint %}

#### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                                     |
| ---------- | ---- | ----- | ------------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Movies and shows in your TMDb account.                                    |
| History    | No   | No    | Unsupported.                                                              |
| Ratings    | Yes  | Yes   | Movies, shows and episodes.                                               |
| Progress   | No   | No    | Unsupported.                                                              |
| Playlists  | Yes  | Yes   | Movies and shows; requires the API Read Access Token. No custom ordering. |
| Collection | No   | No    | Unsupported.                                                              |

**Read** brings data into CrossWatch; **Write** sends changes to this provider. Enable only features supported by both sides.

Ratings use half points from 0.5 to 10.

Connect the provider first: [TMDb setup](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/tmdb.md).

#### How matching works

TMDb writes need a TMDb media ID. CrossWatch resolves it in this order:

1. `ids.tmdb` (best)
2. `ids.imdb` via TMDb `/find`
3. `ids.tvdb` via TMDb `/find` (TV only)

CrossWatch features such as Insights and Overview rely on `ids.imdb`. When an item has a TMDb ID, the adapter calls TMDb `external_ids` to add `ids.imdb` and `ids.tvdb` when available.

{% hint style="warning" %}
Items without a `tmdb`, `imdb` or `tvdb` ID cannot be written to TMDb.
{% endhint %}

#### Watchlist behavior

* **Read:** TMDb watchlist for movies and TV.
* **Write:** add or remove items.

#### Ratings behavior

* **Read:** rated movies, TV shows and episodes.
* **Write:** set or clear ratings.
* Ratings keep half points, for example 7.5. Values are rounded to the nearest half point between 0.5 and 10.

{% hint style="info" %}
TMDb supports episode ratings and CrossWatch can index them. Some pair settings hide episode rating writes depending on what the other provider supports.
{% endhint %}

#### Playlists behavior

TMDb lists can be a playlist source or target. Set them up in **Playlists**.

* **Needs:** the **API Read Access Token (v4)** on the TMDb connection. Without it, TMDb shows a reconnect message in Playlists. Watchlist and ratings keep working.
* **Read:** your own TMDb lists, public and private.
* **Write:** add or remove movies and shows.
* **Privacy:** new lists default to **Private**; **Public** is also available. Eligible owned lists can change privacy through the list picker.
* **Not supported:**
  * Seasons and episodes. They are skipped and reported as unresolved.
  * Custom order. **Preserve order** is not available for TMDb targets.
* **Profiles:** each TMDb profile only uses lists from its own TMDb account.

#### Settings (advanced)

Credentials are stored under `tmdb_sync`. Profiles are stored under `tmdb_sync.instances.<profile>`.

<details>

<summary>Important config keys</summary>

* `tmdb_sync.api_key`: TMDb v3 API Key
* `tmdb_sync.session_id`: v3 session, from the connect flow
* `tmdb_sync.account_id`: optional, found automatically when missing
* `tmdb_sync.read_token`: v4 API Read Access Token, needed for lists
* `tmdb_sync.access_token`: v4 user access token, from the connect flow
* `tmdb_sync.account_object_id`: v4 account ID, filled in automatically
* `tmdb_sync.v4_account_id`: the v3 account the v4 token belongs to
* `tmdb_sync.timeout`: request timeout in seconds
* `tmdb_sync.max_retries`

</details>

<details>

<summary>Endpoints used (for debugging)</summary>

**Watchlist (v3)**

* `GET /account/{account_id}/watchlist/movies`
* `GET /account/{account_id}/watchlist/tv`
* `POST /account/{account_id}/watchlist`

**Ratings (v3)**

* `GET /account/{account_id}/rated/movies`
* `GET /account/{account_id}/rated/tv`
* `GET /account/{account_id}/rated/tv/episodes`
* `POST` and `DELETE` on `/movie/{id}/rating`, `/tv/{id}/rating` and `/tv/{id}/season/{s}/episode/{e}/rating`

**Lists (v4)**

* `GET /4/account/{account_object_id}/lists`
* `GET /4/list/{list_id}`
* `POST /4/list`
* `POST /4/list/{list_id}/items`
* `DELETE /4/list/{list_id}/items`

**ID resolution and enrichment**

* `GET /find/{external_id}` (`imdb_id` / `tvdb_id`)
* `GET /{media_type}/{tmdb_id}/external_ids`

</details>

#### Diagnostics

* Logs include `TMDB` and the feature name, for example `watchlist`, `ratings` or `playlists`.
* The health check calls `GET /account`.
* Common unresolved reasons:
  * `missing_tmdb_id`: no usable ID for a write
  * `missing_rating`: no valid rating value
  * `missing_season_episode`: episode rating without `season` or `episode`
  * `unsupported_type`: a season or episode sent to a TMDb list
* **TMDb lists need the v4 login:** add the API Read Access Token and reconnect TMDb in Connections.

#### State and caching (advanced)

Local state files live under `/config/.cw_state/`. They are usually scoped per pair run, so pairs do not overwrite each other.

#### Notes and limitations

* No history sync.
* Lists need the API Read Access Token. Seasons and episodes cannot be added to lists.
* For better matching, enable TMDb in Metadata.
* Start with one-way and a dry run. Add removals once runs look clean.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/tmdb.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
