Adapter: SIMKL

SIMKL adapter notes for syncing watchlist/history/ratings using activity watermarks and batching.

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

Connect SIMKL first. Use: SIMKL (Authentication provider).

CrossWatch rate-limits SIMKL calls to reduce 429 Too Many Requests.

Default: 10 GET/sec, 1 write/sec.

Tuning: Provider rate limiting

Be kind to SIMKL’s API. Don’t schedule SIMKL runs more often than every 12 hours. Daily is better.

What it supports

• Direction: source or target in a pair (one-way or two-way)

• Features:

  • Watchlist → SIMKL PTW (“Plan To Watch”)

  • Ratings (1–10)

  • History (watched movies + watched episodes)

  • Playlists (not supported)

• Delta sync: uses SIMKL activities and watermarks to avoid full downloads

• IDs: works best with simkl, imdb, tmdb, tvdb

  • Anime can also use mal, anilist, kitsu, anidb when available

SIMKL PTW is a status list, not a “save for later” watchlist. Items can leave PTW due to SIMKL status changes.

Watchlist behavior (PTW)

• Read: incremental list reads per bucket (movies, shows, anime)

• Write: add/remove items to PTW

SIMKL writes mainly use movies/shows payloads. CrossWatch still reads the anime bucket for indexing.

Ratings behavior

• Read: incremental ratings feed (movies/shows/anime)

• Write: upsert and remove ratings

Writing anime ratings depends on how the source provider represents anime.

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)

Headers sent to SIMKL

• 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

Delta syncing: date_from and watermarks

SIMKL uses per-feature watermarks stored under:

• /config/.cw_state/simkl.watermarks.<pair>.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.

Health check

SIMKL health is probed with:

• POST /sync/activities

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

State files (per pair)

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.