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

# TMDb

TMDb (Sync) links your TMDb account so CrossWatch can sync your TMDb watchlist, ratings and lists.

It is separate from **Metadata → TMDb**, which is only used for ID matching and cover art.

### What CrossWatch can sync

**Read** brings data into CrossWatch; **Write** sends changes to this provider.

| 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.                                                              |

**Live scrobbling:** Not supported.

See the [synchronization guide](https://wiki.crosswatch.app/crosswatch/settings/synchronization/trackers/tmdb.md) for matching rules and feature restrictions.

### What you need

| Credential                     | Needed for            | Where to find it                                             |
| ------------------------------ | --------------------- | ------------------------------------------------------------ |
| **API Key** (v3)               | Watchlist and ratings | [TMDb API settings](https://www.themoviedb.org/settings/api) |
| **API Read Access Token** (v4) | Lists (playlists)     | Same page, below the API Key                                 |

The Read Access Token is optional. You need it to use TMDb lists in **Playlists**. A v3-only connection is insufficient.

{% hint style="info" %}
Copy the API Key and the Read Access Token from the **same** TMDb API settings page. CrossWatch checks that both belong to the same TMDb app.
{% endhint %}

### Connect TMDb (Sync)

1. Create a TMDb account and request an API key on the [TMDb API settings](https://www.themoviedb.org/settings/api) page.
2. In CrossWatch, open **Settings → Connections → Trackers → TMDb (Sync)**.
3. Paste your **API Key (v3)**.
4. Optional: paste your **API Read Access Token (v4, optional)** to use TMDb lists.
5. Click **Connect TMDb**.
6. Approve the request in the TMDb tab that opens.
7. Go back to CrossWatch. It checks the approval automatically and shows **Connected** with your TMDb username.

If you added the Read Access Token, the **Session ID** is created for you as well. You do not need a separate v3 login.

### Use TMDb lists as playlists

TMDb lists can be used as a playlist source or target in **Playlists**. Lists support movies and shows.

* In Playlists, choose **Private** (default) or **Public** when creating a list. Eligible owned lists can change privacy through the list picker.
* Seasons and episodes cannot be added to TMDb lists. They are skipped and reported as unresolved.
* TMDb lists have no custom order, so **Preserve order** is not available for TMDb targets.
* Your own v4 lists are readable and writable for movies and shows.
* Accessible public lists from other users can be added by a supported link as read-only sources.

#### Already connected before lists were supported?

Your existing connection keeps working for watchlist and ratings. To use lists:

1. Open **TMDb (Sync)**.
2. Paste the **API Read Access Token (v4, optional)**.
3. Click **Connect TMDb** again and approve on TMDb.

Until you do this, TMDb shows a reconnect message in **Playlists** and on the TMDb card.

### Connection instances

Each TMDb instance has its own API Key, Read Access Token, and login. Pick the instance at the top of the TMDb card before you connect.

The picker discovers lists from the connected TMDb account. Supported linked public lists can belong to another user and are read-only sources. If an instance uses a different TMDb account than the default instance, connect it with its own Read Access Token to use its lists.

### Disconnect

Open **TMDb (Sync)** and click **Delete**. This removes the API Key, Read Access Token, and login for the selected instance.

### Troubleshooting

| Problem                                                                 | Fix                                                                                                                                      |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| The TMDb tab does not open                                              | Check your popup blocker, then click **Connect TMDb** again.                                                                             |
| Stuck on **Pending approval**                                           | Approve the request in the TMDb tab, then go back to CrossWatch. If it is still pending after two minutes, click **Connect TMDb** again. |
| TMDb did not return a session id                                        | The request was not approved or has expired. Click **Connect TMDb** again.                                                               |
| Use the TMDb API Key (v3 auth), not the API Read Access Token           | You pasted the Read Access Token in the API Key field. Swap them.                                                                        |
| Invalid TMDb API Read Access Token                                      | Paste the long token from TMDb API settings, not the API Key.                                                                            |
| The API Read Access Token and the API Key belong to different TMDb apps | Copy both from the same TMDb API settings page.                                                                                          |
| Playlists says TMDb lists need a reconnect                              | Add the Read Access Token and click **Connect TMDb** again.                                                                              |
| Verify keeps failing                                                    | Make sure the CrossWatch server can reach `api.themoviedb.org`.                                                                          |

### Security

The API Key, Read Access Token, access token and session are stored in the CrossWatch config. Treat them as secrets.

### For power users

Config keys are stored under `tmdb_sync`. Extra instances use `tmdb_sync.instances.<instance>`.

| Key                 | Description                                  |
| ------------------- | -------------------------------------------- |
| `api_key`           | v3 API Key                                   |
| `session_id`        | v3 session, created after approval           |
| `account_id`        | v3 account ID, filled in automatically       |
| `read_token`        | v4 API Read Access Token                     |
| `access_token`      | v4 user access token, created after approval |
| `account_object_id` | v4 account ID, filled in automatically       |
| `v4_account_id`     | The v3 account the v4 token belongs to       |

Metadata TMDb uses `tmdb.api_key` instead. Configure it separately under **Connections → Metadata** for artwork, search, matching and Tracker checks. The TMDb Sync connection alone does not enable those features.

The UI uses these endpoints. You can call them yourself for a headless setup. Add `?instance=<instance>` to target an instance.

* `POST /api/tmdb_sync/connect/start`: body `{"api_key": "...", "read_token": "..."}`. `read_token` is optional. Returns `auth_url` to approve.
* `GET /api/tmdb_sync/verify`: finishes the login once approved. Returns `connected`, `pending` and `lists_ready`.
* `POST /api/tmdb_sync/connect/finish`
* `POST /api/tmdb_sync/disconnect`


---

# 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/connections/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.
