> ## 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.
# 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](/api-reference/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`.
## OpenAPI
````yaml /openapi.json get /movies/genres/{genre}/{type}/{country}/{year}/{sort}
openapi: 3.1.0
info:
title: Simkl API
version: 1.0.0
description: >-
The **Simkl API** lets you build apps that track Movies, TV Shows, and Anime
— scrobble playback, sync watch history, and pull rich metadata.
All requests use HTTPS and return JSON. The base URL is
`https://api.simkl.com`.
**Every request needs three URL parameters and a `User-Agent` header:**
```
/endpoint?client_id=YOUR_CLIENT_ID&app-name=my-app&app-version=1.0
```
See [Headers and required parameters](/conventions/headers) for the full
reference. Endpoints that read or modify a user's data also need an
`Authorization: Bearer ` header — see [OAuth
2.0](/api-reference/oauth) or the [PIN flow](/api-reference/pin).
> ⚠️ **About the auto-rendered cURL examples on each endpoint page:** they
omit `?client_id=…&app-name=…&app-version=…` from the URL for brevity. **You
must add them yourself when copy-pasting**, or use the interactive **"Try
it"** playground (it fills them in for you). This is a Mintlify rendering
convention — every Mintlify-built API doc behaves the same way.
**Get started**
- [Quickstart](/quickstart) — first request in 60 seconds
- [API rules](/api-rules) — what's allowed, what isn't
- [Standard media objects](/conventions/standard-media-objects) — the shapes
every endpoint speaks
- [Errors](/conventions/errors) — every status code Simkl returns
contact:
name: Simkl Developer Support
url: https://support.simkl.com
termsOfService: https://simkl.com/about/policies/terms/
license:
name: Simkl API Terms of Use
url: https://simkl.com/about/policies/terms/
x-logo:
url: https://i.simkl.com/img_tv/apiary_logo_api.png
backgroundColor: '#0E5DAB'
altText: Simkl
servers:
- url: https://api.simkl.com
description: Production API
- url: https://data.simkl.in
description: CDN for static, public data files (Calendar + Trending). No auth required.
security:
- clientId: []
- simklApiKey: []
tags:
- name: OAuth 2.0
description: >-
OAuth 2.0 authorization-code flow for web and mobile apps. The user is
redirected to Simkl, signs in, approves your app, and is redirected back
with a `code` you exchange for an `access_token`. Long-lived tokens — no
refresh-token flow needed.
externalDocs:
description: OAuth 2.0 walkthrough
url: https://api.simkl.org/api-reference/oauth
- name: PIN
description: >-
Device flow for TVs, consoles, smart watches, CLI tools — anywhere typing
a URL is hard. Show a 5-character code; user enters it on simkl.com/pin;
you poll for the access token. **No `client_secret` required.**
externalDocs:
description: PIN flow walkthrough
url: https://api.simkl.org/api-reference/pin
- name: Redirect
description: >-
Helper redirects for one-click "mark as watched", trailers, sharing, and
more.
- name: Search
description: Find shows, movies, and anime by ID, text query, file name, or randomly.
externalDocs:
description: Search guide
url: https://api.simkl.org/guides/search
- name: Movies
description: >-
Browse the Simkl movies catalog: details, premieres, top-of-best, and
genre filters.
- name: TV
description: >-
Browse the Simkl TV catalog: details, episodes, what's airing, premieres,
top-of-best, and genre filters.
- name: Anime
description: >-
Browse the Simkl anime catalog: details, episodes, what's airing,
premieres, top-of-best, and genre filters.
- name: Ratings
description: >-
Read Simkl's average community rating, rank, drop rate, and external
ratings (IMDB, MAL) for any item, or for every item in a user's lists.
- name: Scrobble
description: >-
Report real-time playback to Simkl with `start`, `pause`, and `stop`. At ≥
80 % progress Simkl marks the item as watched automatically; below 80 %
the session is saved as a paused playback the user can resume from any
device.
See [Standard media objects](/conventions/standard-media-objects) for the
supported ID keys.
### Supported ID keys
Inside any `ids` object, pass as many of these as you have. Simkl resolves
to the canonical record.
| ID key | Type | Example |
|---|---|---|
| `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. |
| `imdb` | string | `tt1520211` |
| `tmdb` | integer | `76757` (for TV, specify `type`) |
| `tvdb` | int / string | `153021` or `the-walking-dead` |
| `mal` | integer | `4246` (MyAnimeList) |
| `anidb` | integer | `10846`. Specifying just this is enough for anime
lookups. |
| `anilist` | integer | `21` |
| `kitsu` | integer | `12` |
| `anisearch` | integer | `2227` |
| `animeplanet` | string | `one-piece` |
| `livechart` | integer | `321` |
| `letterboxd` | string | `the-truman-show` |
| `netflix` | integer | `70210890` (movie ID) |
| `traktslug` | string | `john-wick-chapter-4-2023` |
> 📖 Full reference: [Standard media
objects](/conventions/standard-media-objects)
externalDocs:
description: Scrobble guide
url: https://api.simkl.org/guides/scrobble
- name: Sync
description: >-
Use Simkl as a cloud backup for the user's watch history and lists
(Watching, Plan to Watch, On Hold, Dropped, Completed). **Always check
[`/sync/activities`](/api-reference/simkl/get-activities) first** and sync
only the lists that have moved.
All write endpoints accept arrays — batch aggressively. See [Standard
media objects](/conventions/standard-media-objects) for the supported ID
keys.
### Supported ID keys
Inside any `ids` object, pass as many of these as you have. Simkl resolves
to the canonical record.
| ID key | Type | Example |
|---|---|---|
| `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. |
| `imdb` | string | `tt1520211` |
| `tmdb` | integer | `76757` (for TV, specify `type`) |
| `tvdb` | int / string | `153021` or `the-walking-dead` |
| `mal` | integer | `4246` (MyAnimeList) |
| `anidb` | integer | `10846`. Specifying just this is enough for anime
lookups. |
| `anilist` | integer | `21` |
| `kitsu` | integer | `12` |
| `anisearch` | integer | `2227` |
| `animeplanet` | string | `one-piece` |
| `livechart` | integer | `321` |
| `letterboxd` | string | `the-truman-show` |
| `netflix` | integer | `70210890` (movie ID) |
| `traktslug` | string | `john-wick-chapter-4-2023` |
> 📖 Full reference: [Standard media
objects](/conventions/standard-media-objects)
externalDocs:
description: Sync guide
url: https://api.simkl.org/guides/sync
- name: Users
description: User profile, settings, and watch statistics.
externalDocs:
description: Simkl API documentation
url: https://api.simkl.org
paths:
/movies/genres/{genre}/{type}/{country}/{year}/{sort}:
get:
tags:
- Movies
summary: Movies by genre
description: >
**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](/api-reference/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`.
operationId: get-movies-genres
parameters:
- name: genre
in: path
required: true
schema:
type: string
example: action
description: Movie genre slug, or `all`. See description for the full set.
- name: type
in: path
required: true
schema:
type: string
enum:
- movies
example: movies
description: Reserved — always pass the literal value `movies`.
- name: country
in: path
required: true
schema:
type: string
example: us
description: ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`, `jp`) or `all`.
- name: year
in: path
required: true
schema:
type: string
example: 2010s
description: >-
`all`, single year (`2019`), or decade (`2010s`, `2000s`). Bogus
values silently fall back to `all`.
- name: sort
in: path
required: true
schema:
type: string
enum:
- popular-this-week
- popular-this-month
- popular-all-time
- rank
- release-date
- voted
- watched
example: popular-this-month
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitGenresParam'
- $ref: '#/components/parameters/ClientIdQuery'
- $ref: '#/components/parameters/AppNameQuery'
- $ref: '#/components/parameters/AppVersionQuery'
- $ref: '#/components/parameters/UserAgentHeader'
responses:
'200':
description: OK
headers:
X-Pagination-Page:
schema:
type: string
description: Current page (after clamp).
X-Pagination-Limit:
schema:
type: string
description: Items per page (after clamp; max 60).
X-Pagination-Page-Count:
schema:
type: string
description: Total number of pages.
X-Pagination-Item-Count:
schema:
type: string
description: Total number of items across all pages.
content:
application/json:
schema:
$ref: '#/components/schemas/GenresResponse'
examples:
movies_action_us_popular_month:
summary: Action movies, US, popular this month (top 2)
value:
- title: 'Avengers: Endgame'
year: 2019
date: '2019-04-24T00:00:00-05:00'
url: /movies/430306/avengers-endgame
poster: 78/7850544702b693f1f
fanart: 78/7867760c274aa5240
ids:
simkl_id: 430306
slug: avengers-endgame
tmdb: '299534'
rank: 126
ratings:
simkl:
rating: 8.3
votes: 10198
imdb:
rating: 8.4
votes: 1446869
- title: Interstellar
year: 2014
date: '2014-11-05T00:00:00-05:00'
url: /movies/250822/interstellar
poster: 20/2052598c2716ef054
fanart: 17/1720484cee8bec79f
ids:
simkl_id: 250822
slug: interstellar
tmdb: '157336'
rank: 31
ratings:
simkl:
rating: 8.7
votes: 12036
imdb:
rating: 8.7
votes: 2530240
movies_drama_gb_2010s_rank:
summary: British dramas from the 2010s sorted by rank (top 1)
value:
- title: The Phantom of the Opera at the Royal Albert Hall
year: 2011
date: '2011-09-27T00:00:00-05:00'
url: >-
/movies/161614/the-phantom-of-the-opera-at-the-royal-albert-hall
poster: 15/15249069a77e4555e5
fanart: 12/12549615b75d07856e
ids:
simkl_id: 161614
slug: the-phantom-of-the-opera-at-the-royal-albert-hall
tmdb: '76115'
rank: 37
ratings:
simkl:
rating: 8.5
votes: 128
imdb:
rating: 8.8
votes: 10845
movies_bogus_genre_returns_null:
summary: Unknown genre slug — top-level `null` (NOT `[]`)
value: null
'412':
$ref: '#/components/responses/ClientIdFailed'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
security:
- clientId: []
x-codeSamples:
- lang: Shell
label: movies_action_us_popular_month
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/movies/genres/action/movies/us/all/popular-this-month?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0&limit=10"
- lang: Shell
label: movies_drama_gb_2010s_rank
source: |-
curl -H "User-Agent: my-app-name/1.0" \
"https://api.simkl.com/movies/genres/drama/movies/gb/2010s/rank?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0&limit=10"
components:
parameters:
PageParam:
name: page
in: query
required: false
description: Page number for paginated endpoints (1-based).
schema:
type: integer
minimum: 1
default: 1
maximum: 20
LimitGenresParam:
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 60
default: 60
description: Items per page. Capped at 60.
ClientIdQuery:
name: client_id
in: query
required: true
description: >-
Your **`client_id`** from your [Simkl developer
settings](https://simkl.com/settings/developer/). Required on every
request.
schema:
type: string
example: YOUR_CLIENT_ID
AppNameQuery:
name: app-name
in: query
required: true
description: >-
Short, lowercase identifier for your app (e.g. `plex-scrobbler`,
`kodi-bridge`). Helps Simkl identify which apps are using the API.
schema:
type: string
example: my-app
AppVersionQuery:
name: app-version
in: query
required: true
description: >-
Your app's current version (e.g. `1.0`, `2.4.1`). Helps Simkl debug
issues you report.
schema:
type: string
example: '1.0'
UserAgentHeader:
name: User-Agent
in: header
required: true
description: >-
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)`.
schema:
type: string
example: my-app/1.0
schemas:
GenresResponse:
title: Discover response
oneOf:
- type: array
items:
$ref: '#/components/schemas/GenresItem'
title: Array of items
- type: 'null'
title: No match
description: >-
Returned (status 200) when a path segment matches no records — most
commonly an unknown `genre` slug.
GenresItem:
title: Discover entry
type: object
description: >-
A single entry from any of the genre-filter endpoints (/movies/genres/*,
/tv/genres/*, /anime/genres/*). All three share this shape via the same
server-side handler. Per-type variations: anime items carry
`anime_type`; movie items carry `ids.tmdb`.
properties:
title:
type: string
description: Display title.
year:
type:
- integer
- 'null'
description: >-
Premiere year (from the release date). **Type 4 null** when the
catalog has no release date on file. See [Null and missing
values](/conventions/null-values#type-4).
date:
type:
- string
- 'null'
description: >-
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](/conventions/null-values#type-4).
url:
type: string
description: >-
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.
example: /movies/430306/avengers-endgame
poster:
type:
- string
- 'null'
description: >-
Image path fragment. Combine with the prefixes in [Image
conventions](/conventions/images) — for example
`https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90`.
**Type 4 null** when no poster on file. See [Null and missing
values](/conventions/null-values#type-4).
fanart:
type:
- string
- 'null'
description: >-
Image path fragment for fanart. Combine with the prefixes in [Image
conventions](/conventions/images) — for example
`https://wsrv.nl/?url=https://simkl.in/fanart/{fanart}_medium.webp&q=90`.
**Type 4 null** when no fanart on file. See [Null and missing
values](/conventions/null-values#type-4).
rank:
type:
- integer
- 'null'
description: >-
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](/conventions/null-values#type-4).
ratings:
type: object
description: >-
Aggregate ratings. Always carries `simkl`. TV / movies additionally
carry `imdb`; anime carries `mal` instead.
properties:
simkl:
$ref: '#/components/schemas/ExternalRating'
imdb:
$ref: '#/components/schemas/ExternalRating'
mal:
$ref: '#/components/schemas/ExternalRating'
ids:
type: object
description: >-
Identifier block. `simkl_id` + `slug` are always present. `tmdb`
appears on movie items (the discover query requires a TMDB-linked
record — items without one are filtered out).
additionalProperties: true
properties:
simkl_id:
type: integer
slug:
type: string
tmdb:
type: string
description: Movie items only.
required:
- simkl_id
- slug
anime_type:
type: string
enum:
- tv
- movie
- ova
- ona
- special
- music
description: '**Anime items only.** Catalog format.'
required:
- title
- url
- ids
ErrorResponse:
type: object
description: >-
Standard error envelope for 4xx and 5xx responses. Branch on `error`
(machine-readable identifier) — `message`, when present, is
human-readable guidance and is **not stable across releases**.
properties:
error:
type: string
description: >-
Machine-readable error identifier. Stable across responses — use
this for programmatic branching in client code. Examples:
`user_token_failed`, `client_id_failed`, `empty_field`,
`wrong_parameter`, `id_err`, `rate_limit`.
example: user_token_failed
code:
type: integer
description: >-
HTTP status code echoed in the body for convenience — same value as
the response status line. Always an integer.
example: 401
message:
type: string
description: >-
Human-readable error guidance. Optional — present on most errors,
but not guaranteed. May reference the specific field or value that
triggered the error. NOT stable; do not parse.
example: Your client_id is wrong. Try another one
required:
- error
- code
ExternalRating:
type: object
description: External-source rating.
properties:
rating:
type: number
minimum: 0
maximum: 10
description: Rating value (0–10).
votes:
type: integer
description: Number of votes contributing to the rating.
responses:
ClientIdFailed:
description: >-
Your `client_id` is missing, wrong, disabled, or has hit a request
limit. Verify in your [developer
settings](https://simkl.com/settings/developer/).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: client_id_failed
code: 412
message: Your client_id is wrong. Try another one
RateLimited:
description: >-
Too many requests in too short a window. Back off and retry with
exponential backoff — see [Rate limits](/resources/rate-limits) for the
playbook.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: rate_limit
code: 429
ServerError:
description: >-
Something is broken on Simkl's side. Retry after a short delay. If it
persists, report on the [Simkl Discord](https://discord.gg/MJsWNE4).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: internal
code: 500
securitySchemes:
clientId:
type: apiKey
in: query
name: client_id
description: >-
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](/conventions/headers).
x-default: YOUR_CLIENT_ID
simklApiKey:
type: apiKey
in: header
name: simkl-api-key
description: >-
Optional alias for the `client_id` query parameter. Simkl accepts your
`client_id` either as the `simkl-api-key` request header **or** as the
`?client_id=…` query parameter — pick one. The query-parameter form is
preferred because it makes the request fully self-describing in URL
form.
x-default: YOUR_CLIENT_ID
````