curl -H "User-Agent: my-app-name/1.0" \
  "https://api.simkl.com/search/movie?q=john+wick&limit=2&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"

[
  {
    "title": "John Wick",
    "year": 2014,
    "endpoint_type": "movies",
    "poster": "30/3002370dbc564e5d8",
    "ids": {
      "simkl_id": 342994,
      "slug": "john-wick",
      "tmdb": "245891"
    }
  },
  {
    "title": "John Wick: Chapter 4",
    "year": 2023,
    "endpoint_type": "movies",
    "poster": "13/13693559ce304eb6f6",
    "ids": {
      "simkl_id": 1098350,
      "slug": "john-wick-chapter-4",
      "tmdb": "603692"
    }
  }
]

Search by text query

Never call search before scrobbling or marking something watched.

This is the most common wasted request we see. Apps look the title up here first to get a Simkl ID, then send that ID to the write endpoint. The lookup is unnecessary. Every write endpoint resolves the item itself, from whatever you already have:

{
  "movie": {
    "title": "Dune: Part Two",
    "year": 2024,
    "ids": { "imdb": "tt15239678", "tmdb": "693134" }
  }
}

Pass any combination of IDs, plus title and year as fallbacks, in the same request that records the watch. Simkl matches it server-side. A Simkl ID is never required.

That applies to /scrobble/*, POST /sync/history, POST /sync/add-to-list and POST /sync/ratings alike.

Searching first doubles your request count for no benefit, burns rate limit you’ll want later, and picks the wrong title whenever the search ranking disagrees with the IDs you already hold. One call, not two.

Use search only when you have no usable IDs at all: a title the user typed, a file name, or a random pick.

Full-text search over the Simkl catalog. Pick a type (movie, tv, or anime) and pass a search term like john wick or john wick 2014.

Heads up: movie becomes "movies" in the response.

You call /search/movie (no s) but each item in the response has endpoint_type: "movies" (with an s). TV and anime don’t change.

You call	Each item’s `endpoint_type` is
`/search/movie`	`"movies"` ← note the extra `s`
`/search/tv`	`"tv"`
`/search/anime`	`"anime"`

Every item in a single response has the same endpoint_type — you never get a mixed list back.

Path parameter

Param	Values
`type`	`movie`, `tv`, `anime`

Query parameters

Param	Default	Notes
`q`	—	Required. Text query (matches `title` and `all_titles[]`). For external-ID lookups (IMDb / TMDB / TVDB / etc.), use `/redirect` or `/search/id` instead.
`page`	`1`	Hard-capped server-side at `20`. Higher values silently clamp.
`limit`	`10`	Hard-capped server-side at `50`. Higher values silently clamp.
`extended`	`simple`	`full` adds `all_titles[]`, `url`, `ep_count` (TV/anime), `rank` (nullable), `status` (TV/anime), and a `ratings` block.

Returns paginated results with X-Pagination-* headers — see Pagination for the standard paginator pattern.

Per-item fields by mode

Field	`simple`	`extended=full`	Notes
`title`	✓	✓	Display title in the user’s locale.
`title_en`	—	—	Anime only, optional even on anime — only when an English-localized title is on file.
`title_romaji`	anime only	anime only	Anime only, always present on anime items. Currently mirrors `title` for the romaji slot.
`year`	✓	✓	Premiere year.
`endpoint_type`	✓	✓	`"movies"` / `"tv"` / `"anime"`. Same value on every item in one response.
`type`	anime only	anime only	Anime only: `tv`, `movie`, `ova`, `ona`, `special`, `music`.
`poster`	✓	✓	Image path fragment — see Image conventions for the full URL pattern (`https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90`).
`ids`	✓	✓	`{ simkl_id, slug, tmdb? }`. `tmdb` only present when a TMDB link is on file.
`all_titles`	—	movies/anime	Aliases / localized variants. Anime sees the most entries. TV items typically don’t carry this even on `extended=full`.
`url`	—	✓	Relative simkl.com URL (with slug).
`ep_count`	—	TV/anime	Total episode count when known.
`rank`	—	✓	Simkl popularity rank. Nullable — see below.
`status`	—	TV/anime	Closed enum: `tba`, `ended`, `airing`.
`ratings.simkl`	—	✓	`{ rating, votes }` — only present when votes > 0.
`ratings.imdb`	—	✓	`{ rating, votes }` — only present when an IMDb rating record exists.
`ratings.mal`	—	anime only	`{ rating, votes, rank }` — anime only, only when a MAL record exists.

Nulls — what they mean

Field	When null	Type
`rank`	Item not yet ranked, or rank value ≥ 999999 sentinel	Type 4
`ep_count`	TV/anime item with no episode count on file yet	Type 4
`poster`	No poster image on file	Type 4

Error responses

Status	When
`412 client_id_failed`	Missing or invalid `client_id`
`500`	Server error

No 400 — invalid page / limit silently clamp to the server caps. No 404 — empty result is [] with status 200.

Which IDs can I send/expect? All accepted input identifiers and the keys you’ll see echoed back in responses are listed at Standard media objects → Supported ID keys. Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: slug is response-only (never send it on a request).

GET

{type}

curl -H "User-Agent: my-app-name/1.0" \
  "https://api.simkl.com/search/movie?q=john+wick&limit=2&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"

[
  {
    "title": "John Wick",
    "year": 2014,
    "endpoint_type": "movies",
    "poster": "30/3002370dbc564e5d8",
    "ids": {
      "simkl_id": 342994,
      "slug": "john-wick",
      "tmdb": "245891"
    }
  },
  {
    "title": "John Wick: Chapter 4",
    "year": 2023,
    "endpoint_type": "movies",
    "poster": "13/13693559ce304eb6f6",
    "ids": {
      "simkl_id": 1098350,
      "slug": "john-wick-chapter-4",
      "tmdb": "603692"
    }
  }
]

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.

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

Search type.

Available options:

tv,

anime,

movie

Query Parameters

string

required

Required. The search term — matches title and all_titles[] across the chosen catalog (movies / TV / anime).

Examples: john wick, john wick 2014, breaking bad, cowboy bebop.

page

integer

default:1

Page number for paginated endpoints (1-based).

Required range: 1 <= x <= 20

limit

integer

default:10

Items per page. Capped at 50.

Required range: 1 <= x <= 50

extended

enum<string>

full adds overview, ratings, and genres to each match.

Available options:

simple,

full

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

Movie result
TV result
Anime result

One movie search result. endpoint_type is the constant "movies" (plural even though the path is /search/movie). Extended fields (all_titles, url, rank, ratings) only appear when the call includes extended=full.

title

string

required

year

integer

required

endpoint_type

enum<string>

required

Constant for movie search results.

Available options:

movies

poster

string | null

required

Image path fragment. Combine with the prefixes in Image conventions — for example https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90. Type 4 null — null when no poster image is on file. See Null and missing values.

ids

object

required

ID block returned on every search result item. simkl_id and slug are always present; tmdb is only present when a TMDB link record exists for the title.

Hide child attributes

ids.simkl_id

integer

required

Canonical Simkl ID for the title.

ids.slug

string

required

URL slug parsed from the simkl.com canonical URL (everything after the last /). Response-only — never send on requests.

ids.tmdb

string

TMDB ID, when a link record exists. For TV/anime this is the TMDB TV ID; for movies it's the TMDB movie ID.

all_titles

string[]

Aliases / localized variants. Extended mode only, and only when the catalog has more than one title.

url

string

Relative simkl.com URL. Extended mode only.

rank

integer | null

Simkl popularity rank. Type 4 null — null when the item is not yet ranked or the catalog sentinel value (≥ 999999) is present. See Null and missing values.

ratings

object

External-source ratings block. Each sub-key is present only when the corresponding rating record exists.

Hide child attributes

ratings.simkl

object

External-source rating.

Hide child attributes

ratings.simkl.rating

number

Rating value (0–10).

Required range: 0 <= x <= 10

ratings.simkl.votes

integer

Number of votes contributing to the rating.

ratings.imdb

object

External-source rating.

Hide child attributes

ratings.imdb.rating

number

Rating value (0–10).

Required range: 0 <= x <= 10

ratings.imdb.votes

integer

Number of votes contributing to the rating.

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Custom Lists

Search

TV

Anime

Movies

Ratings

Users

Changes

Search by text query

Path parameter

Query parameters

Per-item fields by mode

Nulls — what they mean

Error responses

Authorizations

Headers

Path Parameters

Query Parameters

Response