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.

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)
  • Progress
  • 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.