Skip to main content
POST

Authorizations

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

Path Parameters

id
integer
required

Numeric list ID.

Required range: x >= 1

Query Parameters

allow_reorder
enum<string>

Let the posted order move titles already on the list: one posted after a title that sits later moves to right after it. Without it, only user_position moves a title.

Available options:
yes,
true,
1
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

Up to 1000 titles per request across the three arrays. A title of the wrong media type for the list is not added; it is reported in wrong_type. episodes and seasons buckets are refused — lists hold whole titles.

movies
object[]
shows
object[]
anime
object[]

Response

Nothing was added (titles moved, notes changed, or nothing changed).

added
integer
required

Titles put on the list.

updated
integer
required

Titles already on the list that moved or got a changed note.

existing
integer
required

Titles already on the list that this request did not change.

not_found
object[]
required

Titles that matched nothing, echoed as you sent them.

wrong_type
object[]
required
list
object
required

The list after the write.