API Reference
Trending
Calendar
Redirect
Sync
Changes
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
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).
Query Parameters
Finds random TV Show, Anime or Movie.
simkl, netflix, crunchy, hulu Restricts the random pick to one domain. Omit to let the server pick a domain first (movie / tv / anime — uniform random across all three).
movie, tv, anime 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
max value is 10. Random search for TV Shows and Movies will be performed using IMDB ratings. Anime are based on MAL ratings.
maximum rank allowed
First released movie starts from 1920.
if >0 specified it returns 2 dimensional array with multiple results
ISO 3166-1 alpha-2 country code (e.g. us, jp). Restricts results to titles released in that country.
Your 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 — single object (when limit omitted), array (when limit set), or not-found object.
- Single item (no limit) · object
- Single item (no limit) · object[]
- No matches · object
Discriminator is shape-based (no type field on this endpoint): object with simkl_id → single item; array → multiple items; object with error → no match.
Simkl ID of the random title.
Canonical Simkl URL (with slug).
Netflix title ID — present when service=netflix and the title has a Netflix link.
Netflix watch URL — present when service=netflix and link exists.
Crunchyroll slug — present when service=crunchy and link exists.
Crunchyroll watch URL — present when service=crunchy and link exists.
Hulu title ID — present when service=hulu and link exists.
Hulu watch URL — present when service=hulu and link exists.
Was this page helpful?