> 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 lets CrossWatch sync with MDBList. It supports watchlist, ratings, and history. It prefers external IDs for matching.

{% hint style="warning" %}
Use writes and deletes carefully.

Keep a current MDBList backup or export before larger changes.

If you want a CrossWatch rollback point, create a [Capture](/crosswatch/main-dashboard/navigation/captures.md) first.

You can also sync MDBList into [Adapter: CrossWatch](/crosswatch/settings/synchronization/others/cw.md) as a local safety net.
{% endhint %}

### What it supports

* Direction: source or target in a pair (one-way or two-way)
* Features:
  * **Watchlist** (movie/show)
  * **Ratings** (movies, shows, seasons, episodes)
  * **History** (movies, shows, seasons, episodes)
  * **Playlists** (not supported)
* Rating scale: **1–10**
* Indexing: present-state snapshot (reads “what exists now”)

{% hint style="info" %}
Connect MDBList first. Use: [MDBList (Authentication provider)](/crosswatch/settings/connections/trackers/mdblist.md).
{% endhint %}

{% hint style="success" %}
MDBList fixed show-level ratings indexing/upserts (2025-11-11).
{% endhint %}

{% hint style="info" %}
CrossWatch rate-limits MDBList calls to reduce `429 Too Many Requests`.

Defaults match SIMKL (`10` GET/sec, `1` write/sec).

Tuning: [Provider rate limiting](/crosswatch/advanced-and-api/rate-limiting-and-retries.md)
{% endhint %}

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

### 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_limit`, `watchlist_offset`

Ratings:

* `ratings_per_page` (default 200)
* `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.


---

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