> 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/mdblist.md).

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

### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                          |
| ---------- | ---- | ----- | -------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Movies and shows.                                              |
| History    | Yes  | Yes   | Movies, shows, seasons and episodes.                           |
| Ratings    | Yes  | Yes   | Movies, shows, seasons and episodes.                           |
| Progress   | Yes  | Yes   | Resume positions for movies and episodes.                      |
| Playlists  | Yes  | Yes   | Manual lists are writable; smart lists are read-only.          |
| Collection | Yes  | Yes   | Movies, shows, seasons and episodes, with optional media info. |

**Read** brings data into CrossWatch; **Write** sends changes to this provider. Enable only features supported by both sides. Collection pairs are one-way only.

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

### How matching works

CrossWatch keys items by external IDs whenever possible:

* `tmdb`, `imdb`, `tvdb`
* `mdblist` when returned by the API

{% hint style="warning" %}
Watchlist writes only send **TMDb/IMDb**. If an item has only TVDb, CrossWatch can’t write it to MDBList watchlist.
{% endhint %}

### Watchlist behavior

* Reads the current watchlist and normalizes to `{type, ids, title, year}`.
* Writes add/remove operations for movies and shows.

### Playlist behavior

When creating a list in Playlists, choose **Private** (default) or **Public**. Eligible owned manual lists can also change privacy later. See [List privacy](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md#list-privacy).

CrossWatch discovers accessible lists through the categories the MDBList integration supports. Supported public lists can also be resolved by link.

Your own writable lists remain distinct from other users’ read-only lists. Smart and dynamic lists can have provider restrictions.

See [Playlists](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md) for setup and list-link guidance.

### Collection behavior

MDBList can be a Collection source or target. Collection sync is one-way only.

The first run creates a baseline. Later runs process changes since that baseline.

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

<details>

<summary>Endpoints used</summary>

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`

</details>

<details>

<summary>Important config keys</summary>

Watchlist:

* `watchlist_page_size` (default 1000)

Ratings:

* `ratings_per_page` (default 1000)
* `ratings_chunk_size`
* `ratings_write_delay_ms`
* `ratings_max_backoff_ms`

</details>

### Diagnostics

<details>

<summary>Logging and retries</summary>

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

</details>

<details>

<summary>State and cache files</summary>

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`

</details>

### Notes and limitations

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

### Account quota

The MDBList provider status tooltip shows the account, plan, remaining daily API calls and reset time when available. If the daily allowance is exhausted, wait for the reset before retrying. Missing quota details do not mean unlimited calls. See [MDBList connection](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/mdblist.md#account-and-api-quota).

### Custom status mapping

For per-pair status rules, enable History and **Status mapping**, then configure **Providers → Status mapping**. See [Status mapping](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/provider-settings/status-mapping.md) for supported movie/show destinations, defaults, and restrictions. Planned stays managed by Watchlist.


---

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