> 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

{% tabs %}
{% tab title="End users" %}

<figure><img src="/files/IGiRLyZe08Z8h8EcNGXj" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you only want ID matching and cover arts then you want **Metadata → TMDb**, not TMDb (Sync).
{% endhint %}

### Connect TMDb (Sync)

{% stepper %}
{% step %}

### Create a TMDb API key (v3)

1. Create a TMDb account.
2. Request an API key: <https://www.themoviedb.org/settings/api>
   {% endstep %}

{% step %}

### Connect in CW

1. Open **Settings → TMDb (Sync)**.
2. Paste your **TMDb API Key (v3)**.
3. Click **Connect**.
4. A TMDb tab opens. Approve the request.
5. Return to CW. Wait for “Connected”.

If it stays pending, click **Verify** once.
{% endstep %}
{% endstepper %}

### Disconnect

1. Open **Settings → TMDb (Sync)**.
2. Click **Disconnect**.

### Troubleshooting

* Auth tab didn’t open: disable popup blockers for CW.
* Stuck on “Pending approval”: approve in the TMDb tab, then click **Verify**.
* “TMDb did not return a session id”: restart the flow with **Connect** and approve again.
* Verify keeps failing: the server must reach `https://api.themoviedb.org/3`.
* Key issues: the key must be a valid TMDb **v3 API key**.

### Security notes

Treat your TMDb **API key** and **session** as secrets.

They are stored in CW config on disk.
{% endtab %}

{% tab title="Power users" %}

### Config keys used

TMDb (Sync) stores values under:

* `tmdb_sync.api_key`
* `tmdb_sync.session_id`

Metadata stores a separate key under:

* `tmdb.api_key`

### API endpoints (manual flow)

<details>

<summary>Start / Verify / Finish / Disconnect</summary>

CW exposes a small API used by the UI.

These are useful for debugging or headless setup.

#### Start (opens the approval URL)

`POST /api/tmdb_sync/connect/start`

```bash
curl -X POST http://localhost:PORT/api/tmdb_sync/connect/start \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_KEY"}'
```

Open the returned `auth_url` and approve.

#### Verify (auto-finish after approval)

`GET /api/tmdb_sync/verify`

```bash
curl http://localhost:PORT/api/tmdb_sync/verify
```

#### Finish (optional explicit completion)

`POST /api/tmdb_sync/connect/finish`

```bash
curl -X POST http://localhost:PORT/api/tmdb_sync/connect/finish \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_KEY","request_token":"REQUEST_TOKEN"}'
```

#### Disconnect

`POST /api/tmdb_sync/disconnect`

```bash
curl -X POST http://localhost:PORT/api/tmdb_sync/disconnect
```

</details>
{% endtab %}
{% endtabs %}


---

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.