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

# Adapter: MDBList

MDBList adapter lets CrossWatch sync with MDBList. It supports watchlist, ratings, and history. It prefers external IDs for matching.

{% hint style="warning" %}
MDBList has **no export/import or rollback** for your data. Use writes and deletes carefully.

Use the local backup adapter as a safety net: [Adapter: CrossWatch](/crosswatch/providers/synchronization/adapter-crosswatch.md).
{% 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/providers/authentication/auth-trackers/auth-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/provider-rate-limiting.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 mirrors these under **Settings → Synchronization Providers → Pairs (with 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:

```
GET https://wiki.crosswatch.app/crosswatch/providers/synchronization/adapter-mdblist.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.