Skip to main content

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.

GET /redirect is a passive helper that 301-redirects to a Simkl URL given any combination of identifiers. It’s designed for two distinct situations — pick the one that matches your job.

​
Two use cases

1. Link to Simkl without an API call

You have an external ID or a title and you just want to send the user to the matching Simkl page (or trailer / share / mark-watched action). No client_id, no JSON parsing.

2. Cheapest external ID → Simkl ID

You have an IMDB / TMDB / TVDB / MAL ID and need the Simkl ID so you can call /movies/:id, /tv/:id, or /anime/:id. /redirect is the lowest-overhead way to get there — read one header, no JSON parsing.
Always returns 301 Moved Permanently with a Location header and Cache-Control: no-store. The type=show value matches both tv and anime. 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.
Do not follow the 301. This applies to HTTP clients, scrapers, server-side fetchers, automated tools, AI agents, and LLM-driven workflows alike — the information you need is in the Location response header, never in the destination body. The destination is one of:
  • A human-facing simkl.com page (HTML),
  • A YouTube trailer page,
  • A twitter.com/intent/tweet URL,
  • A /oauth/authorize URL (for to=watched flows when the user isn’t signed in).
None of those contain API data. Fetching them wastes bandwidth, can break (CORS / auth / rate limits on the destination host), and gives you nothing useful. The Simkl URL you want — and the simkl_id you can parse out of its path — is in the redirect target string, available without ever following the redirect.Configure your HTTP client to stop at the 301 and read the header:
Tool / languageHow to stop at the 301
curlcurl -I <url> (HEAD request) or curl --max-redirs 0 -s -D - <url>
Python requestsrequests.get(url, allow_redirects=False) then r.headers['location']
Python httpxhttpx.get(url, follow_redirects=False)
Node fetchfetch(url, { redirect: 'manual' }) then r.headers.get('location')
Node axiosaxios.get(url, { maxRedirects: 0, validateStatus: s => s === 301 })
Go net/httpSet client.CheckRedirect = func(...) error { return http.ErrUseLastResponse }
This is the canonical way to use /redirect — not a perf optimisation. Following the redirect defeats the endpoint’s purpose.What to do after reading the Location header — pick one:
  • You only need the Simkl ID. Parse it out of the URL path and stop here. Don’t call anything else. Example: Location: https://simkl.com/tv/17465/game-of-thrones → simkl_id = 17465. You’re done.
  • You also need the full record (title, overview, poster, fanart, ratings, trailers, etc.). Use the parsed Simkl ID to call the matching detail endpoint, which is Cloudflare-cached by Simkl ID — popular titles come straight from edge cache and are near-free:
Two HTTP requests max (one to /redirect for the ID, one to the cached detail endpoint for the data). Never follow the 301 from /redirect itself.
You’re rendering a clickable link in a newsletter, a browser-extension menu, a “Share” button, or any external surface, and you’d rather not call the JSON API yourself. Hand /redirect whatever identifier you have on hand and it sends the user to the right place.

​
Action modes (to=)

ModeRedirects to
simkl (default)The Simkl page for the resolved item.
trailerThe trailer URL (typically YouTube).
twitterA twitter.com/intent/tweet URL with the title and a Simkl link prefilled.
watchedMarks the item watched on the user’s account. If the user isn’t signed in, Simkl first redirects through /oauth/authorize, then performs the action and lands them on the page.

​
Recipes

curl -I "https://api.simkl.com/redirect?to=simkl&imdb=tt0944947&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0"
# 301 Location: https://simkl.com/tv/17465/game-of-thrones

​
Building the Simkl URL yourself

If you already have the Simkl ID and slug (returned in ids.simkl_id and ids.slug on every standard media object), you don’t need /redirect at all — assemble the URL directly:
ResourceURL pattern
Moviehttps://simkl.com/movies/{simkl_id}/{slug}
TV showhttps://simkl.com/tv/{simkl_id}/{slug}
Animehttps://simkl.com/anime/{simkl_id}/{slug}
TV seasonhttps://simkl.com/tv/{simkl_id}/{slug}/season-{N}
TV episodehttps://simkl.com/tv/{simkl_id}/{slug}/season-{N}/episode-{M}
Anime episodehttps://simkl.com/anime/{simkl_id}/{slug}/episode-{M}
User profilehttps://simkl.com/{username}
User statshttps://simkl.com/{username}/stats/
User library`https://simkl.com/{username}/{tvmoviesanime}/`
The slug is technically optional, but always include it when you have it. If you skip it, Simkl runs an extra title lookup and 301-redirects to the slugged URL anyway — wasted server time on Simkl’s side and an extra round-trip on yours. The slug is returned in ids.slug on every standard media object — store it alongside the Simkl ID and reuse.

​
Use case 2 — Resolve an external ID to a Simkl ID

You have an external ID (IMDB, TMDB, TVDB, MAL, AniDB, AniList, Kitsu, etc.) and you need the Simkl ID so you can fetch the full record from /movies/{id}, /tv/{id}, or /anime/{id}. This is the recommended path — /redirect returns a tiny redirect with the Simkl ID baked into the URL, and the detail endpoints are aggressively cached on Cloudflare by Simkl ID.

​
How /redirect resolves an ID

The response is a 301 with a Location header pointing at the canonical Simkl URL, e.g. https://simkl.com/tv/17465/game-of-thrones. Parse out 17465 and pass it to /tv/17465 to get the full record from Cloudflare cache.
  • Tiny payload — just HTTP headers, no JSON to parse.
  • Cached path — the follow-up detail call (/movies/{id}, /tv/{id}, /anime/{id}) hits Cloudflare’s edge cache, so it stays cheap for repeat lookups of the same title.
  • Same required params as every Simkl endpoint — see Headers and required parameters.

​
How to extract the Simkl ID from the redirect

The Location header looks like one of: 
https://simkl.com/movies/{simkl_id}/{slug}
https://simkl.com/tv/{simkl_id}/{slug}
https://simkl.com/anime/{simkl_id}/{slug}
The numeric segment immediately after /movies/, /tv/, or /anime/ is the Simkl ID. Then call the summary endpoint of your choice with that ID.

​
Recipes

PARAMS="client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0"
UA="my-app-name/1.0"

SIMKL_URL=$(curl -sI "https://api.simkl.com/redirect?to=simkl&imdb=tt0944947&$PARAMS" \
  -H "User-Agent: $UA" \
  | awk -v IGNORECASE=1 '/^location:/ {print $2}' | tr -d '\r\n')
SIMKL_ID=$(echo "$SIMKL_URL" | awk -F/ '{print $5}')

curl "https://api.simkl.com/tv/$SIMKL_ID?$PARAMS" \
  -H "User-Agent: $UA"
Cache the resolved Simkl ID. External IDs map to Simkl IDs once and rarely change. Store the mapping locally so the next request goes straight to /movies/{id} / /tv/{id} / /anime/{id} without a round-trip through /redirect.

​
What you can pass

/redirect accepts a wide set of identifiers — pass any combination, the more the better:

External IDs

Any of the supported ID keys — simkl, imdb, tmdb (pair with type=movie or type=tv — TMDB has no anime type), tvdb, mal, anidb, crunchyroll, etc. Most stand alone.

Title + year

title=...&year=...&type=.... Title-based fallback for when you have nothing else.

Episode targeting

season (defaults to 1) and episode. Setting either one excludes movies from the search.

Tweet text

ep_title is used when to=twitter to include the episode title in the tweet body.

​
Endpoint reference

GET /redirect

Full parameter list, response codes, and an interactive playground.

Standard media objects

Where the ids.simkl_id and ids.slug fields come from.

Detail endpoints

Once you have the Simkl ID, fetch the full record from /movies/{id}, /tv/{id}, or /anime/{id} (Cloudflare-cached by ID).

OAuth flow

to=watched first redirects through /oauth/authorize for unauthenticated users.