Skip to main content
GET
cURL

Authorizations

client_id
string
query
default:YOUR_CLIENT_ID
required

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.

Authorization
string
header
default:YOUR_ACCESS_TOKEN
required

A user access_token, sent as Authorization: Bearer .... Required for endpoints that read or modify the user's library, scrobble session, ratings, settings, or playbacks. Every flow returns the same kind of token. See Set up authentication.

Headers

User-Agent
string
required

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

client_id
string
required

Your client_id from your Simkl developer settings. Required on every request.

app-name
string
required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

app-version
string
required

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. The top-level all now also moves when a custom list changes, so a loop that gates on it will wake for those as well.

all
string<date-time> | null
required

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. This includes custom-list activity, so all can move when only a list changed.

settings
object
required

Top-level settings change marker. Bumped when the user changes any setting at https://simkl.com/settings/ (display name, time zone, privacy, etc.).

tv_shows
object
required

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

anime
object
required

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

movies
object
required

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.

custom_lists
object
required

Custom Lists activity. The timestamps sit under lists rather than directly on this object, leaving room for other custom-list activity to be added alongside them later — so read custom_lists.lists.all, not custom_lists.all.