> ## 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. # Random pick > Returns a random title — perfect for "What should I watch?" features, daily-pick widgets, or seeding recommendation flows. Optionally filter by type, genre, year range, rating, popularity rank, or streaming service availability. #### Query / body parameters All filters can be sent as either query parameters or a JSON body — both forms work. When `type` is omitted, the server picks one of `movie` / `tv` / `anime` at random first, then returns a random item from that domain. | Param | Notes | |---|---| | `service` | `simkl` (default), `netflix`, `crunchy`, `hulu`. When set to anything but `simkl`, results are restricted to titles available on that service AND the response includes `{service}_id` + `{service}_url` (e.g. `netflix_id`, `netflix_url`). | | `type` | `movie`, `tv`, or `anime`. **Omit to let the server pick a random domain first.** | | `genre` | Comma-separated genre slugs (e.g. `action,thriller`). Genre slugs differ by type — see the per-type lists below. | | `country` | ISO 3166-1 alpha-2 country code (movies / TV). | | `year_from` | Default `1990`. | | `year_to` | Optional. | | `rank_limit` | Maximum rank to consider (lower = more popular). | | `rating_from` | Floor rating, 0–10. For TV / movies this filters on IMDb; for anime, on MAL. | | `rating_to` | Ceiling rating, 0–10. | | `limit` | Number of items, capped at `50`. **Single object when omitted; array when set.** | #### Response shapes | Shape | When | |---|---| | `{ simkl_id, simkl_url }` | `limit` omitted → single random item. | | `[{ simkl_id, simkl_url }, ...]` | `limit` set → array of up to `limit` items. | | `{ error: "not_found" }` | Filters matched nothing. Still status `200` (no 404). | When `service != simkl` and a matching service link exists, the item gains `{service}_id` and `{service}_url`. When no link exists, the item still returns but without those extra keys. #### Genre slugs by type Slugs are lowercase with spaces normalized to hyphens. **Movies** (20): action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western **TV** (38): action, adventure, animation, awards-show, children, comedy, crime, documentary, drama, erotica, family, fantasy, food, game-show, history, home-and-garden, horror, indie, korean-drama, martial-arts, mini-series, musical, mystery, news, podcast, reality, romance, science-fiction, soap, special-interest, sport, suspense, talk-show, thriller, travel, video-game-play, war, western **Anime** (46): action, adventure, comedy, drama, ecchi, educational, fantasy, gag-humor, gore, harem, historical, horror, idol, isekai, josei, kids, magic, martial-arts, mecha, military, music, mystery, mythology, parody, psychological, racing, reincarnation, romance, samurai, school, sci-fi, seinen, shoujo, shoujo-ai, shounen, shounen-ai, slice-of-life, space, sports, strategy-game, super-power, supernatural, thriller, vampire, yaoi, yuri ## OpenAPI ````yaml /openapi.json post /search/random 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: /search/random: post: tags: - Search summary: Random pick description: > Returns a random title — perfect for "What should I watch?" features, daily-pick widgets, or seeding recommendation flows. Optionally filter by type, genre, year range, rating, popularity rank, or streaming service availability. #### Query / body parameters All filters can be sent as either query parameters or a JSON body — both forms work. When `type` is omitted, the server picks one of `movie` / `tv` / `anime` at random first, then returns a random item from that domain. | Param | Notes | |---|---| | `service` | `simkl` (default), `netflix`, `crunchy`, `hulu`. When set to anything but `simkl`, results are restricted to titles available on that service AND the response includes `{service}_id` + `{service}_url` (e.g. `netflix_id`, `netflix_url`). | | `type` | `movie`, `tv`, or `anime`. **Omit to let the server pick a random domain first.** | | `genre` | Comma-separated genre slugs (e.g. `action,thriller`). Genre slugs differ by type — see the per-type lists below. | | `country` | ISO 3166-1 alpha-2 country code (movies / TV). | | `year_from` | Default `1990`. | | `year_to` | Optional. | | `rank_limit` | Maximum rank to consider (lower = more popular). | | `rating_from` | Floor rating, 0–10. For TV / movies this filters on IMDb; for anime, on MAL. | | `rating_to` | Ceiling rating, 0–10. | | `limit` | Number of items, capped at `50`. **Single object when omitted; array when set.** | #### Response shapes | Shape | When | |---|---| | `{ simkl_id, simkl_url }` | `limit` omitted → single random item. | | `[{ simkl_id, simkl_url }, ...]` | `limit` set → array of up to `limit` items. | | `{ error: "not_found" }` | Filters matched nothing. Still status `200` (no 404). | When `service != simkl` and a matching service link exists, the item gains `{service}_id` and `{service}_url`. When no link exists, the item still returns but without those extra keys. #### Genre slugs by type Slugs are lowercase with spaces normalized to hyphens. **Movies** (20): action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western **TV** (38): action, adventure, animation, awards-show, children, comedy, crime, documentary, drama, erotica, family, fantasy, food, game-show, history, home-and-garden, horror, indie, korean-drama, martial-arts, mini-series, musical, mystery, news, podcast, reality, romance, science-fiction, soap, special-interest, sport, suspense, talk-show, thriller, travel, video-game-play, war, western **Anime** (46): action, adventure, comedy, drama, ecchi, educational, fantasy, gag-humor, gore, harem, historical, horror, idol, isekai, josei, kids, magic, martial-arts, mecha, military, music, mystery, mythology, parody, psychological, racing, reincarnation, romance, samurai, school, sci-fi, seinen, shoujo, shoujo-ai, shounen, shounen-ai, slice-of-life, space, sports, strategy-game, super-power, supernatural, thriller, vampire, yaoi, yuri operationId: post-search-random parameters: - name: service in: query description: Finds random TV Show, Anime or Movie. schema: type: string default: simkl enum: - simkl - netflix - crunchy - hulu - name: type in: query description: >- Restricts the random pick to one domain. Omit to let the server pick a domain first (movie / tv / anime — uniform random across all three). required: false schema: type: string enum: - movie - tv - anime example: tv - name: genre in: query description: >- TV Shows, Anime and Movies have their own genres. **Movies**: action, adventure, animation, comedy, crime, documentary, drama, erotica, family, fantasy, foreign, history, horror, music, mystery, romance, science-fiction, thriller, tv-movie, war, western **TV:** action, adventure, animation, awards-show, children, comedy, crime, documentary, drama, erotica, family, fantasy, food, game-show, history, home-and-garden, horror, indie, korean-drama, martial-arts, mini-series, musical, mystery, news, podcast, reality, romance, science-fiction, soap, special-interest, sport, suspense, talk-show, thriller, travel, war, western **Anime:** action, adventure, cars, comedy, dementia, demons, drama, ecchi, fantasy, game, harem, historical, horror, josei, kids, magic, martial-arts, mecha, military, music, mystery, parody, police, psychological, romance, samurai, school, sci-fi, seinen, shoujo, shoujo-ai, shounen, shounen-ai, slice-of-life, space, sports, super-power, supernatural, thriller, vampire, yaoi, yuri schema: type: string example: comedy - name: rating_from in: query description: >- max value is 10. Random search for TV Shows and Movies will be performed using IMDB ratings. Anime are based on MAL ratings. schema: type: integer default: 1 example: '5' - name: rating_to in: query description: '' schema: type: integer example: '10' - name: rank_limit in: query description: maximum rank allowed schema: type: integer example: '2000' - name: year_from in: query description: First released movie starts from 1920. schema: type: integer example: '2004' - name: year_to in: query description: '' schema: type: integer example: '2010' - name: limit in: query description: if >0 specified it returns 2 dimensional array with multiple results schema: type: integer example: '10' - name: country in: query required: false schema: type: string description: >- ISO 3166-1 alpha-2 country code (e.g. `us`, `jp`). Restricts results to titles released in that country. - $ref: '#/components/parameters/ClientIdQuery' - $ref: '#/components/parameters/AppNameQuery' - $ref: '#/components/parameters/AppVersionQuery' - $ref: '#/components/parameters/UserAgentHeader' requestBody: required: false description: Body is optional — pass filters as query parameters or as a JSON body. content: application/json: examples: default_no_params_random_domain: summary: >- No params — server picks a random domain (movie/tv/anime), returns single item value: {} type_movie: summary: type=movie — random movie value: {} type_tv: summary: type=tv — random TV show value: {} type_anime: summary: type=anime — random anime value: {} limit_3_array_form: summary: limit=3 — array form (max 50) value: {} year_range_movie: summary: Genre + year-range filter value: {} service_netflix_with_link: summary: >- service=netflix — adds netflix_id + netflix_url when the title has a Netflix link value: {} filters_match_nothing_not_found: summary: >- Filters match nothing — `{error: "not_found"}` (still 200, NOT 404) value: {} responses: '200': description: >- OK — single object (when `limit` omitted), array (when `limit` set), or not-found object. content: application/json: schema: oneOf: - $ref: '#/components/schemas/SearchRandomItem' - $ref: '#/components/schemas/SearchRandomItemArray' - $ref: '#/components/schemas/SearchRandomNotFound' description: >- Discriminator is shape-based (no `type` field on this endpoint): object with `simkl_id` → single item; array → multiple items; object with `error` → no match. examples: default_no_params_random_domain: summary: >- No params — server picks a random domain (movie/tv/anime), returns single item value: simkl_id: 427406 simkl_url: >- https://simkl.com/anime/427406/shimoneta-to-iu-gainen-ga-sonzai-shinai-taikutsu-na-sekai type_movie: summary: type=movie — random movie value: simkl_id: 421160 simkl_url: https://simkl.com/movies/421160/uninvited type_tv: summary: type=tv — random TV show value: simkl_id: 2277797 simkl_url: https://simkl.com/tv/2277797/compromising-situations type_anime: summary: type=anime — random anime value: simkl_id: 2613914 simkl_url: >- https://simkl.com/anime/2613914/kanpekisugite-kawaige-ga-nai-to-konyaku-haki-sareta-seijo-wa-ringoku-ni-urareru limit_3_array_form: summary: limit=3 — array form (max 50) value: - simkl_id: 2413564 simkl_url: >- https://simkl.com/anime/2413564/nanatsu-no-taizai-mokushiroku-no-yonkishi - simkl_id: 36852 simkl_url: https://simkl.com/anime/36852/silent-mobius - simkl_id: 40776 simkl_url: >- https://simkl.com/anime/40776/sentou-yousei-yukikaze-faf-koukuu-senshi year_range_movie: summary: Genre + year-range filter value: simkl_id: 1360484 simkl_url: https://simkl.com/movies/1360484/min-far-er-bokser service_netflix_with_link: summary: >- service=netflix — adds netflix_id + netflix_url when the title has a Netflix link value: simkl_id: 30721 simkl_url: https://simkl.com/tv/30721/ripper-street netflix_id: '70270745' netflix_url: http://www.netflix.com/title/70270745 filters_match_nothing_not_found: summary: >- Filters match nothing — `{error: "not_found"}` (still 200, NOT 404) value: error: not_found '412': $ref: '#/components/responses/ClientIdFailed' '500': $ref: '#/components/responses/ServerError' security: - clientId: [] - simklApiKey: [] - clientId: [] bearerAuth: [] - simklApiKey: [] bearerAuth: [] x-codeSamples: - lang: Shell label: default_no_params_random_domain source: |- curl -X POST -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/search/random?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" - lang: Shell label: type_movie source: |- curl -X POST -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/search/random?type=movie&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" - lang: Shell label: type_tv source: |- curl -X POST -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/search/random?type=tv&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" - lang: Shell label: type_anime source: |- curl -X POST -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/search/random?type=anime&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" - lang: Shell label: limit_3_array_form source: |- curl -X POST -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/search/random?limit=3&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" - lang: Shell label: year_range_movie source: |- curl -X POST -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/search/random?type=movie&year_from=2000&year_to=2010&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" - lang: Shell label: service_netflix_with_link source: |- curl -X POST -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/search/random?service=netflix&type=tv&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" - lang: Shell label: filters_match_nothing_not_found source: |- curl -X POST -H "User-Agent: my-app-name/1.0" \ "https://api.simkl.com/search/random?type=movie&year_from=1900&year_to=1901&rating_from=10&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" components: parameters: 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: SearchRandomItem: title: Single item (no limit) type: object description: >- Single random item — returned when `limit` is omitted. Service-specific keys (`{service}_id`, `{service}_url`) are included when `service != simkl` AND the matched title has a link record for that service. additionalProperties: true properties: simkl_id: type: integer description: Simkl ID of the random title. simkl_url: type: string format: uri description: Canonical Simkl URL (with slug). netflix_id: type: string description: >- Netflix title ID — present when `service=netflix` and the title has a Netflix link. netflix_url: type: string format: uri description: Netflix watch URL — present when `service=netflix` and link exists. crunchy_id: type: string description: Crunchyroll slug — present when `service=crunchy` and link exists. crunchy_url: type: string format: uri description: >- Crunchyroll watch URL — present when `service=crunchy` and link exists. hulu_id: type: string description: Hulu title ID — present when `service=hulu` and link exists. hulu_url: type: string format: uri description: Hulu watch URL — present when `service=hulu` and link exists. required: - simkl_id - simkl_url SearchRandomItemArray: title: Array of items (limit set) type: array description: Array form — returned when `limit` is set. Capped server-side at 50. items: $ref: '#/components/schemas/SearchRandomItem' SearchRandomNotFound: title: No matches type: object description: Returned (status 200) when no item matches the supplied filters. properties: error: type: string enum: - not_found description: Constant `"not_found"`. required: - error 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 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 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 bearerAuth: type: http scheme: bearer description: >- OAuth 2.0 or PIN-flow `access_token`. Required for endpoints that read or modify the user's library, scrobble session, ratings, settings, or playbacks. See [Authentication](/authentication). x-default: YOUR_ACCESS_TOKEN ````