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:
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, anime, or all for all three at once — 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" |
/search/all | each item’s own type: "movies", "tv" or "anime" |
With movie, tv or anime, every item in the response has that endpoint_type. all mixes them — see Searching all types below.
Path parameter
| Param | Values |
|---|---|
type | movie, tv, anime, or all for all three at once (see Searching all types below) |
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. |
sort | relevance | Result order: relevance, release-date, last-air-date (TV and anime only), title or rank — see Sorting below. Any other value is a 400. |
Returns paginated results with X-Pagination-* headers — see Pagination for the standard paginator pattern.
Sorting
sort changes the order of the matches, not which titles match, and paging keeps it — page 2 continues where page 1 stopped.
sort | Order |
|---|---|
relevance (default) | Best match first, then the more popular title. |
release-date | Newest release first. Upcoming titles come before released ones. |
last-air-date | Most recently aired first. TV and anime only — on /search/movie it returns 400. |
title | A–Z. Titles that start with punctuation or a number come before A. |
rank | Simkl rank, most popular first. |
Values are case-insensitive, and an empty sort= means relevance. Any other value returns 400 wrong_parameter, with the accepted values listed in message.
Searching all types
Use all as the type to search movies, TV shows and anime in one request:
all is lower-case only (/search/ALL returns null), and the path always needs a type — /search on its own returns 404.
- Results mix types. Each item carries its own
endpoint_type—movies,tvoranime— so branch on it per item, not per response. Every item has the fields it would have in a search of its own type. - The query parameters work the same —
q,page,limit,extended,sort. All five sorts are accepted,last-air-dateincluded, but movies have no air dates, so their place in that order isn’t meaningful; preferrelease-datewhen the results include movies. - If your app shows only one kind of title, use that type instead of
all. You get only that type, and theX-Pagination-*counts cover only those matches.
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 |
|---|---|
400 wrong_parameter | sort is not one of the values above, or last-air-date on /search/movie |
401 user_token_required | AUTH V2 app called without the user’s token |
412 client_id_failed | Missing or invalid client_id |
500 | Server error |
Invalid page / limit never return 400 — they silently clamp to the server caps. No 404 — empty result is [] with status 200.
Authorizations
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
Path Parameters
Query Parameters
Result order. relevance (default) puts the best match first; release-date newest first; last-air-date most recently aired first — TV and anime only: a 400 on movie, and accepted with all but not meaningful for the movies in those results; title A–Z; rank most popular first. Case is ignored, and an empty value means relevance. Any other value returns 400 wrong_parameter.
relevance, release-date, last-air-date, title, rank Your client_id from your Simkl developer settings. Required on every request.
Response
OK
- 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.
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.
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.