API Reference
Trending
Calendar
Redirect
Sync
Changes
curl "https://api.simkl.com/sync/activities?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
-H "User-Agent: my-app-name/1.0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Get Last Activities
Returns the most recent update timestamps for each of the user’s lists. Always call this first when syncing — compare against your last-saved timestamps and pull only the lists that have moved. This is the cheapest call in the API.
Top-level fields
| Field | Use |
|---|---|
all | Latest update across every domain. Best first-level check. |
settings.all | Updates to account settings (name, time zone, …) at https://simkl.com/settings/. |
tv_shows, anime, movies | Per-domain timestamp groups. |
Per-domain timestamps
| Field | Meaning | Cheapest next call |
|---|---|---|
all | Latest update in this domain. | — |
rated_at | A rating was added, changed, or removed. | GET /sync/ratings/{type}/{rating} with date_from — only the changed ratings. Walkthrough: Phase 2 — Continuous sync. |
playback | A paused playback was added, resumed, or cleared. | GET /sync/playback/{type} with date_from — only the changed sessions. |
plantowatch, watching, completed, hold, dropped | Items moved into/out of these lists, or episodes were marked watched/unwatched. | GET /sync/all-items/{type}/{status} with date_from and extended=full — full delta of modified items. Walkthrough: Phase 2 — Continuous sync. |
removed_from_list | Items were deleted from the library entirely. date_from won’t surface removals — you can only detect them by diffing. | GET /sync/all-items/{type}/{status} with extended=simkl_ids_only — cheapest possible payload (just the IDs) — and diff against your local cache. Walkthrough: Detecting deletions. |
Movies don’t have
watchingorhold— movies are atomic, so those statuses don’t apply.
Auto-move side effects
When a user rates an unrated item, Simkl auto-files it: movies → Completed, shows/anime → Watching. That auto-move bumps the corresponding list timestamp, so the rated item also appears in subsequent /sync/all-itemsdate_from queries.
Recommended sync loop
- On first sync, store every timestamp returned and pull each list once with no
date_from. - Periodically poll this endpoint. If
allhasn’t changed, you’re up to date. - Otherwise, for each domain whose
allmoved, request only the lists whose per-list timestamp changed usingdate_from= your previously-saved value. - Save the new timestamps and repeat.
Removal cascade
When removed_from_list moves, the user actively deleted items from their library. Refetch with extended=simkl_ids_only and diff against your local cache to detect deletions — date_from won’t surface them. Also clear any local rating you stored for those items: Simkl wipes the rating when an item is removed, which is why removals can move both removed_from_list and rated_at.
Sync guide — full walkthrough
Two-phase model (initial pull → activities-checked delta loop), date_from semantics, deletion reconciliation, edge cases, and reference implementations in Node and Python.
curl "https://api.simkl.com/sync/activities?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
-H "User-Agent: my-app-name/1.0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Documentation Index
Fetch the complete documentation index at: https://api.simkl.org/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Preferred form: your client_id as a URL query parameter on every request. Self-describing in logs and curl commands. See Headers and required parameters.
OAuth 2.0 or PIN-flow access_token. Required for endpoints that read or modify the user's library, scrobble session, ratings, settings, or playbacks. See Authentication.
Headers
Descriptive identifier for your app, ideally name/version. Examples: PlexMediaServer/1.43.1.10540, kodi-simkl/0.9.2, MyApp/2.4.1 (https://myapp.com).
Query Parameters
Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
Response
OK
Last-activity envelope returned by GET /sync/activities. Use all as the cheapest first-pass check, then drill into a per-domain block only when its all has moved.
Type 4 null — data not on file in that field's slot. See Null and missing values. Newest timestamp across every domain and bucket. Best first-level check — if this hasn't moved since your last sync, nothing has changed.
Top-level settings change marker. Bumped when the user changes any setting at https://simkl.com/settings/ (display name, time zone, privacy, etc.).
Hide child attributes
Hide child attributes
Type 4 null — data not on file in that field's slot. See Null and missing values. Most recent change to account settings, or null if the user has never changed any setting since signup.
Per-domain timestamps for TV shows and anime. Both types share the full five-status set (watching, plantowatch, hold, dropped, completed). Each timestamp is an ISO-8601 datetime, or null if the user has never had activity in that bucket — a Type 1 null ("never happened yet", see Null-value conventions).
Hide child attributes
Hide child attributes
Type 4 null — data not on file in that field's slot. See Null and missing values. Latest update across this domain. Fast first-pass check before drilling into per-status fields.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped on any rating add/change/remove for this domain. After a bump, call GET /sync/ratings/{type}/{rating} with date_from to fetch only the changed ratings.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped on any scrobble/playback activity. After a bump, call GET /sync/playback/{type} to refresh in-progress sessions.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the plantowatch bucket.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the watching bucket, or when episodes are marked/unmarked watched.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the completed bucket.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the hold bucket.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the dropped bucket.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items are removed from the user's library entirely. date_from won't surface removals — to reconcile, call GET /sync/all-items/{type}/{status} with extended=simkl_ids_only (cheapest payload — just the IDs) and diff against your local cache. Walkthrough: Detecting deletions.
Per-domain timestamps for TV shows and anime. Both types share the full five-status set (watching, plantowatch, hold, dropped, completed). Each timestamp is an ISO-8601 datetime, or null if the user has never had activity in that bucket — a Type 1 null ("never happened yet", see Null-value conventions).
Hide child attributes
Hide child attributes
Type 4 null — data not on file in that field's slot. See Null and missing values. Latest update across this domain. Fast first-pass check before drilling into per-status fields.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped on any rating add/change/remove for this domain. After a bump, call GET /sync/ratings/{type}/{rating} with date_from to fetch only the changed ratings.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped on any scrobble/playback activity. After a bump, call GET /sync/playback/{type} to refresh in-progress sessions.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the plantowatch bucket.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the watching bucket, or when episodes are marked/unmarked watched.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the completed bucket.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the hold bucket.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items move into or out of the dropped bucket.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when items are removed from the user's library entirely. date_from won't surface removals — to reconcile, call GET /sync/all-items/{type}/{status} with extended=simkl_ids_only (cheapest payload — just the IDs) and diff against your local cache. Walkthrough: Detecting deletions.
Per-domain timestamps for movies. Movies are single-session content, so this block does not include watching or hold — those keys are omitted entirely (not null). See Watchlist statuses for the per-type matrix.
Hide child attributes
Hide child attributes
Type 4 null — data not on file in that field's slot. See Null and missing values. Latest update across movies.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped on any movie rating add/change/remove.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped on any movie scrobble/playback activity.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when movies move into or out of plantowatch.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when movies move into or out of completed.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when movies move into or out of dropped.
Type 4 null — data not on file in that field's slot. See Null and missing values. Bumped when movies are removed from the user's library entirely. date_from won't surface removals — call GET /sync/all-items/movies/{status} with extended=simkl_ids_only (cheapest payload — just the IDs) and diff against your local cache. Walkthrough: Detecting deletions.
Was this page helpful?