API Reference
Trending
Calendar
Redirect
Sync
Changes
Movies by genre
Not for TV / console / 10-foot apps. The V1 genre-browse endpoints return a thin per-item shape (title, year, poster, ids, ratings, rank). Building a TV-app grid that shows overview text, full ratings, networks, runtimes, recommendations, or trailers would force one per-item refetch against the detail endpoint per visible card. Wait for the V2 Beta API, which returns the richer per-item shape TV-app surfaces need in a single call. If you’re targeting TV / console / streaming-box clients, please hold off integrating these endpoints.
Browse movies filtered by genre, country, year, and sort order. Path is /movies/genres/{genre}/{type}/{country}/{year}/{sort} — all segments required (use all as the wildcard).
The type segment is reserved — always pass the literal value movies.
| Path param | Values |
|---|---|
genre | all, action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western |
type | movies (literal) |
country | all or ISO 3166-1 alpha-2 (us, gb, jp, …) |
year | all, single year (2019), or decade (2010s, 2000s) |
sort | popular-this-week, popular-this-month, popular-all-time, rank, release-date, voted, watched |
Items always carry ids.tmdb — the discover query filters out movies without a TMDB-linked record.
Pagination
| Param | Default | Notes |
|---|---|---|
page | 1 | Hard-capped server-side at 20. Higher values clamp silently. |
limit | 60 | Hard-capped server-side at 60. Higher values clamp silently. Returned X-Pagination-Limit reflects the clamped value. |
X-Pagination-* headers on every response — see Pagination.
Silent fallbacks
Bad path segments DO NOT return errors:
| Bad input | What happens |
|---|---|
Unknown genre slug (zzz) | Top-level response is null (NOT []). |
Unknown year (e.g. zzz) | Silently treated as all — full result set. |
Unknown sort (zzzsortzzz) | Silently treated as default sort order. |
Unknown country / network | Silently treated as all. |
Errors
| Status | When |
|---|---|
412 client_id_failed | Missing or invalid client_id |
500 | Server error |
No 400 or 404 — bad segments fall back silently or return null.
Documentation Index
Fetch the complete documentation index at: https://api.simkl.org/llms.txt
Use this file to discover all available pages before exploring further.
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
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
Movie genre slug, or all. See description for the full set.
Reserved — always pass the literal value movies.
movies ISO 3166-1 alpha-2 country code (e.g. us, gb, jp) or all.
all, single year (2019), or decade (2010s, 2000s). Bogus values silently fall back to all.
popular-this-week, popular-this-month, popular-all-time, rank, release-date, voted, watched Query Parameters
Page number for paginated endpoints (1-based).
1 <= x <= 20Items per page. Capped at 60.
1 <= x <= 60Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
Response
OK
Display title.
Relative simkl.com path with slug. Prepend https://simkl.com to deep-link. Each catalog uses its own prefix: /movies/{simkl_id}/{slug} for movies, /tv/{simkl_id}/{slug} for TV, /anime/{simkl_id}/{slug} for anime.
"/movies/430306/avengers-endgame"
Premiere year (from the release date). Type 4 null when the catalog has no release date on file. See Null and missing values.
Release / first-air timestamp with the catalog's timezone offset (e.g. 2014-11-05T00:00:00-05:00 for US releases, +09:00 for anime). Type 4 null when no release date is on file. See Null and missing values.
Image path fragment. Combine with the prefixes in Image conventions — for example https://simkl.in/posters/{poster}_m.webp. Type 4 null when no poster on file. See Null and missing values.
Image path fragment for fanart. Combine with the prefixes in Image conventions — for example https://simkl.in/fanart/{fanart}_medium.webp. Type 4 null when no fanart on file. See Null and missing values.
Simkl popularity rank. Type 4 null when the item is not yet ranked or the catalog sentinel value (>= 999999) is present. See Null and missing values.
Aggregate ratings. Always carries simkl. TV / movies additionally carry imdb; anime carries mal instead.
Hide child attributes
Hide child attributes
Anime items only. Catalog format.
tv, movie, ova, ona, special, music Was this page helpful?