API Reference
Trending
Calendar
Redirect
Sync
Changes
curl --request GET \
--url https://api.simkl.com/redirect \
--header 'User-Agent: <user-agent>' \
--header 'simkl-api-key: <api-key>'This response has no body data.Resolve any ID and redirect to Simkl
A passive helper endpoint that 301-redirects to a Simkl page (or an action) given any combination of IDs or a title.
It’s designed for two situations:
- Linking to Simkl when you don’t have the Simkl ID — turn an IMDB / TMDB / TVDB / MAL / AniDB ID, or a title + year, into a clickable Simkl URL.
- Getting the Simkl ID with minimal info — the cheapest way to translate an external ID into a Simkl ID. Read the
Locationresponse header and parse thesimkl_idout of the URL path — no JSON to parse.
⚠️ Do not follow the 301. Read the
Locationheader directly. Usecurl -I,requests.get(..., allow_redirects=False),fetch(..., { redirect: 'manual' }), or your client’s equivalent. The destination is a public-facing page (simkl.com HTML, YouTube, Twitter intent, or/oauth/authorize) and contains no API data — following the redirect wastes bandwidth and can break (CORS, auth, destination-host rate limits). This applies to HTTP clients, scripts, automated tools, AI agents, and LLM-driven workflows alike.What to do next, after reading the
Locationheader:
- If you only need the Simkl ID — parse it out of the URL path (e.g.
https://simkl.com/tv/17465/...→17465) and stop. Don’t call anything else.- If you also need the full record (title, overview, poster, fanart, ratings, trailers, etc.) — pass the parsed Simkl ID to the matching Cloudflare-cached detail endpoint:
GET /movies/{id},GET /tv/{id},GET /anime/{id},GET /tv/episodes/{id}, orGET /anime/episodes/{id}. Popular titles come straight from edge cache.Full reference table of stop-at-301 invocations for popular HTTP clients in the Redirect overview.
Like every Simkl endpoint, requests must include the required URL parameters (client_id, app-name, app-version) and a User-Agent header. No Authorization token is needed except for to=watched, which signs the user in if they aren’t already.
to= action modes
| Mode | What the redirect points at |
|---|---|
simkl (default) | The matching Simkl page (https://simkl.com/movies/{id}/{slug}, tv/..., anime/...). |
trailer | The trailer URL (typically YouTube). |
twitter | A twitter.com/intent/tweet URL with the title and a Simkl link prefilled. |
watched | Marks the item watched on the user’s account. If the user isn’t signed in, Simkl redirects to /oauth/authorize first. |
Identifier parameters
Pass any combination — the more, the more accurate the match. Most can stand alone:
| Param | Notes |
|---|---|
simkl | Simkl ID. |
imdb | IMDB ID, or a full IMDB URL. |
tmdb | TMDB ID. Requires type=movie or type=tv to disambiguate — TMDB has no anime type (anime shows are filed under tv on TMDB; Simkl routes them to its anime catalog automatically once resolved). |
tvdb | TVDB ID. |
mal, anidb, anilist, kitsu, livechart, anisearch, animeplanet | Anime-specific IDs. |
crunchyroll | Crunchyroll show or episode ID/slug. |
netflix, hulu | Streaming-service IDs (beta). |
title, year | Title-based fallback. Pair with type for best results. |
season, episode | Episode targeting (season defaults to 1). Movies are ignored when either is set. |
ep_title | Episode title used in the tweet text when to=twitter. |
type | movie, tv, or anime. Required for tmdb; optional otherwise (show matches both tv and anime). |
Response
- Status:
301 Moved Permanently Location: the resolved URL (Simkl page, YouTube, Twitter intent, or the OAuth authorize page whento=watchedand the user isn’t signed in).Cache-Control: no-store— never cache the redirect itself; cache the resolved URL on your side if you need to.
Why “lowest cost” for ID resolution
GET /redirect?to=simkl&imdb=… returns a Location header like https://simkl.com/movies/472214/inception. The number after /movies/, /tv/, or /anime/ is the Simkl ID. Compared to GET /search/id:
- No JSON parse — read the
Locationheader, regex out the ID. - Tiny payload — HTTP headers only, no response body.
Use this for “I have an IMDB ID, give me the Simkl ID” lookups when you don’t need the rest of the media object yet.
Which IDs can I send/expect? All accepted input identifiers and the keys you’ll see echoed back in responses are listed at Standard media objects → Supported ID keys. Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: slug is response-only (never send it on a request).
curl --request GET \
--url https://api.simkl.com/redirect \
--header 'User-Agent: <user-agent>' \
--header 'simkl-api-key: <api-key>'This response has no body data.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
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.
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
Action mode. Determines the redirect target. Case-sensitive; must be lowercase. Allowed values: simkl (search fallback), trailer, twitter, watched.
simkl, trailer, twitter, watched TV show, anime, or movie title.
release year.
if set, movies will be ignored. Anime do not have seasons.
if set, movies will be ignored.
hulu_id. All other parameters can be empty if this one specified.
Netflix movieid, this parameter is in beta and may not work.
MyAnimeList id.
TVDB ID. All other parameters can be empty if this one specified.
Required for tmdb, if is searching for a TV Show
show, tv, movie, anime The Movie Database (TMDb) ID. To search TV Shows specify type parameter. All other parameters can be empty if this one specified.
can be IMDB ID or full IMDB URL. All other parameters can be empty if this one specified.
tt1520211, http://www.imdb.com/title/tt1520211/ AniDB ID. All other parameters can be empty if this one specified.
Crunchyroll ID. You can pass episode ID or url ID(sword-art-online)
AniList ID
Kitsu ID
LiveChart ID
aniSearch ID
Anime-Planet ID
Episode title used to compose tweet text when to=twitter. Ignored for other to= values.
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
Permanent redirect to the resolved URL (the primary success path).
Was this page helpful?