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

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

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.

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.

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.