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

# SIMKL

SIMKL adapter notes for syncing watchlist, history, ratings, and progress.

SIMKL adapter lets CrossWatch sync with SIMKL. It supports watchlist, ratings, history, and progress, including anime.

{% hint style="info" %}
Connect SIMKL first. Use: [SIMKL (Authentication provider)](https://wiki.crosswatch.app/crosswatch/settings/connections/trackers/simkl.md).
{% endhint %}

### What CrossWatch can sync

| Feature    | Read | Write | Notes                                                                                                                                              |
| ---------- | ---- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Watchlist  | Yes  | Yes   | Movies, shows and anime in Plan to Watch.                                                                                                          |
| History    | Yes  | Yes   | Movies and episodes. Optional rewatch support requires Pro or VIP.                                                                                 |
| Ratings    | Yes  | Yes   | Movies and shows, including anime.                                                                                                                 |
| Progress   | Yes  | Yes   | Resume positions for movies and episodes.                                                                                                          |
| Playlists  | Yes  | Yes   | Status lists and owned regular custom lists are writable. Custom lists need PRO/VIP. Status-list removals also remove library entries and ratings. |
| Collection | No   | No    | Unsupported.                                                                                                                                       |

**Read** brings data into CrossWatch; **Write** sends changes to this provider. Enable only features supported by both sides.

### Watchlist behavior (PTW)

* Read: incremental list reads per bucket (`movies`, `shows`, `anime`)
* Write: add/remove items to PTW

{% hint style="warning" %}
SIMKL Plan To Watch (PTW) is part of its internal status workflow, NOT a static watchlist. Titles can leave PTW when their status changes. Sync results may therefore differ from expected watchlist.
{% endhint %}

{% hint style="info" %}
SIMKL writes mainly use movies/shows payloads. CrossWatch still reads the anime bucket for indexing.
{% endhint %}

### Playlist behavior

The writable status endpoints are **Plan To Watch**, **Watching**, **On Hold**, **Dropped**, and **Completed**.

Removing an item from a status bucket removes it from the SIMKL library and clears its rating. Use Exact copy carefully.

Custom lists require **PRO or VIP** and compatible authorization. Your own regular custom lists support creation, rename, deletion, item changes, ordering and privacy changes. Choose **Movies**, **Shows** or **Anime** when creating one; its type cannot be changed later. Privacy defaults to **Public**, with **Unlisted** and **Private** also available.

Custom-list removals remove membership only; they do not remove library history or ratings. Automatic, recommendation, followed, shared and other users' lists remain read-only, including collaborative lists.

Reconnect the selected SIMKL account if custom-list writes request fresh authorization. List and item limits are enforced by SIMKL. See [Playlists](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md#simkl) for setup and [List privacy](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/playlists.md#list-privacy) for the controls.

If only status lists appear, check that the selected SIMKL account has PRO or VIP and access to the custom list. Reconnect if requested, then refresh the list picker.

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

### Ratings behavior

* Read: incremental ratings feed (movies/shows/anime)
* Write: upsert and remove ratings

{% hint style="info" %}
Writing anime ratings depends on how the source provider represents anime.
{% endhint %}

### History behavior

* Read: incremental watched state for movies/shows/anime
* Write: mark watched or unwatch

Anime writes can add `use_tvdb_anime_seasons=true` to help season mapping.

### Settings (advanced)

<details>

<summary>Headers sent to SIMKL</summary>

* `simkl-api-key: <client id>`
* `Authorization: Bearer <access token>`
* `User-Agent: CrossWatch/3.x (SIMKL)` (override with `CW_UA`)
* `Accept: application/json`
* `Content-Type: application/json`

</details>

<details>

<summary>Delta syncing: date_from and watermarks</summary>

SIMKL uses per-feature watermarks stored under:

* `/config/.cw_state/simkl.watermarks.&lt;pair&gt;.json`

For each feature, CrossWatch picks `date_from` in this order:

1. Stored watermark
2. `SIMKL_<FEATURE>_DATE_FROM`
3. `SIMKL_DATE_FROM`
4. `simkl.date_from`
5. `1970-01-01T00:00:00Z`

Watermarks only move forward.

</details>

<details>

<summary>Health check</summary>

SIMKL health is probed with:

* `POST /sync/activities`

It also acts as an “activities gate” to skip work when nothing changed.

</details>

<details>

<summary>State files (per pair)</summary>

All state lives in `/config/.cw_state/`:

* `simkl.watermarks.<pair>.json`
* `simkl.watchlist.shadow.<pair>.json`
* `simkl.watchlist.unresolved.<pair>.json`
* `simkl.ratings.shadow.<pair>.json`
* `simkl_ratings.unresolved.<pair>.json`
* `simkl.history.shadow.<pair>.json`
* `simkl_history.unresolved.<pair>.json`
* `simkl.show.map.<pair>.json`

Deleting these forces rebuilds and usually increases API calls next run.

</details>

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

### Unknown watch dates

Normal History sync can read and write watched states whose dates are unknown. With **Rewatches** enabled, undated watches are skipped while supported dated plays can still sync. See [Unknown watch dates](https://wiki.crosswatch.app/crosswatch/settings/configure-pairs/features/history.md#unknown-watch-dates) for destination support and the optional SIMKL date-conversion setting.


---

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