Skip to main content
POST

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.

Body

application/json

Body for POST /sync/add-to-list. Moves items into one of the user's Watchlist statuses. Items go under movies[], shows[], or anime[] — Simkl resolves anime titles correctly under either shows[] or anime[], so match the field to your data type when known. Set the status once with a top-level to, or per item with to on each item (an item's own to wins).

to
enum<string>

User watchlist status. Movies skip watching and hold — see /conventions/list-statuses.

Available options:
watching,
plantowatch,
hold,
completed,
dropped
movies
object[]

Standard movie object. See the Standard Media Objects guide. Identify the title by ids, or — in a request — by title (with year to tell remakes apart).

shows
object[]

Standard show object. May include nested seasons/episodes for partial sync. Identify the title by ids, or — in a request — by title (with year to tell remakes apart).

anime
object[]

Array of anime entries (same shape as shows[]).

Standard show object. May include nested seasons/episodes for partial sync. Identify the title by ids, or — in a request — by title (with year to tell remakes apart).

Response

OK

Response from POST /sync/add-to-list.

added
object
not_found
object

Items Simkl could not match. Inspect this to surface diagnostics back to your users. Anime entries that fail to resolve land in shows regardless of which top-level array they were sent under — there is no separate anime bucket in not_found.