Skip to main content
GET

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

Path Parameters

type
enum<string>
required

Media-type slice. Use all to fetch every type in one response — this is the canonical "I don't care which type" form. The path segment is required because OpenAPI 3.1 does not permit optional path parameters.

Available options:
movies,
tv,
anime,
all
Example:

"all"

Query Parameters

user_watchlist
enum<string>
default:all
required
Available options:
all,
watching,
plantowatch,
completed,
dropped,
hold
Example:

"1"

fields
string
default:simkl
  • A comma-separated list of additional fields to include in the response.
  • simkl – returns the Simkl rating and votes.
  • ext – includes external ratings such as IMDB or MAL if available.
  • rank – returns the rank within the Simkl service for that media type (movie, tv, anime).
  • release_status – includes the release status of the item.
  • year – includes the year of release.
  • link – includes the title's simkl.com URL.
  • Example: fields=rank,simkl,ext,year. droprate is not a field of its own — it comes inside simkl.
Example:

"simkl,ext,year"

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

object[] | null

OK

id
integer
required

Simkl ID.

type
enum<string>

Only when {type} is all.

Available options:
movie,
tv,
anime

simkl.com URL with slug. Only with fields=link.

release_status
enum<string>

Lower-case release status. released is movies only; returning series is TV and ongoing anime for titles still airing; ended for finished shows and anime. Titles not out yet: upcoming, planned, in production, post production, rumored, canceled. Only with fields=release_status.

Available options:
released,
ended,
returning series,
ongoing,
upcoming,
planned,
in production,
post production,
rumored,
canceled
release_year
integer | null

Type 4 null — no release year on file. See Null and missing values. Only with fields=year.

rank
integer | null

Type 4 null — not ranked yet. See Null and missing values. Simkl rank within the media type. Only with fields=rank.

simkl
object

Simkl rating. Sent by default — fields defaults to simkl — and absent when your fields list leaves it out.

imdb
object

Only with fields=ext, and only when an IMDb rating is on file (Type 2 otherwise).

mal
object

Only with fields=ext, and only when a MyAnimeList rating is on file (Type 2 otherwise).