Redirect & deep-linking

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 / language	How to stop at the 301
`curl`	`curl -I <url>` (HEAD request) or `curl --max-redirs 0 -s -D - <url>`
Python `requests`	`requests.get(url, allow_redirects=False)` then `r.headers['location']`
Python `httpx`	`httpx.get(url, follow_redirects=False)`
Node `fetch`	`fetch(url, { redirect: 'manual' })` then `r.headers.get('location')`
Node `axios`	`axios.get(url, { maxRedirects: 0, validateStatus: s => s === 301 })`
Go `net/http`	Set `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:
- Movies → GET /movies/{simkl_id}
- TV shows → GET /tv/{simkl_id}
- Anime → GET /anime/{simkl_id}
- Episode lists → GET /tv/episodes/{simkl_id} or GET /anime/episodes/{simkl_id}

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.

Use case 1 — Link to Simkl when you don’t have a Simkl ID

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=`)

Mode	Redirects to
`simkl` (default)	The Simkl page for the resolved item.
`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 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

curl -I "https://api.simkl.com/redirect?to=simkl&type=movie&tmdb=27205&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/movies/472214/inception

```bash TMDB → Simkl page (TV — type is required) curl -I “https://api.simkl.com/redirect?to=simkl&type=tv&tmdb=1399&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0”
-H “User-Agent: my-app-name/1.0”

```bash TMDB → specific episode
curl -I "https://api.simkl.com/redirect?to=simkl&type=tv&tmdb=1399&season=1&episode=3&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/.../season-1/episode-3

curl -I "https://api.simkl.com/redirect?to=simkl&mal=11757&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/anime/37226/sword-art-online

curl -I "https://api.simkl.com/redirect?to=simkl&type=movie&title=Inception&year=2010&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/movies/472214/inception

curl -I "https://api.simkl.com/redirect?to=trailer&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://www.youtube.com/watch?v=...

curl -I "https://api.simkl.com/redirect?to=twitter&type=movie&title=Inception&year=2010&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://twitter.com/intent/tweet?text=...

curl -I "https://api.simkl.com/redirect?to=watched&imdb=tt0944947&season=1&episode=3&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/oauth/authorize?...   (returns to the action after login)

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:

Resource	URL pattern
Movie	`https://simkl.com/movies/{simkl_id}/{slug}`
TV show	`https://simkl.com/tv/{simkl_id}/{slug}`
Anime	`https://simkl.com/anime/{simkl_id}/{slug}`
TV season	`https://simkl.com/tv/{simkl_id}/{slug}/season-{N}`
TV episode	`https://simkl.com/tv/{simkl_id}/{slug}/season-{N}/episode-{M}`
Anime episode	`https://simkl.com/anime/{simkl_id}/{slug}/episode-{M}`
User profile	`https://simkl.com/{username}`
User stats	`https://simkl.com/{username}/stats/`
User library	`https://simkl.com/{username}/{tv	movies	anime}/`

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"

const PARAMS  = `client_id=${CLIENT_ID}&app-name=my-app-name&app-version=1.0`;
const HEADERS = { 'User-Agent': 'my-app-name/1.0' };

const loc = await fetch(
  `https://api.simkl.com/redirect?to=simkl&imdb=tt1375666&${PARAMS}`,
  { redirect: 'manual', headers: HEADERS }
).then(r => r.headers.get('location'));

// loc === "https://simkl.com/movies/472214/inception"
const simklId = loc.match(/\/(?:movies|tv|anime)\/(\d+)\//)[1];

const movie = await fetch(
  `https://api.simkl.com/movies/${simklId}?${PARAMS}`,
  { headers: HEADERS }
).then(r => r.json());

import re, requests

PARAMS = {
    'client_id':   CLIENT_ID,
    'app-name':    'my-app-name',
    'app-version': '1.0',
}
HEADERS = {'User-Agent': 'my-app-name/1.0'}

# 1. Resolve MAL ID to a Simkl URL — read the Location header, no JSON parse
loc = requests.get(
    'https://api.simkl.com/redirect',
    params={**PARAMS, 'to': 'simkl', 'mal': 11757},
    headers=HEADERS,
    allow_redirects=False,
).headers['location']

# 2. Extract the Simkl ID from the URL path
simkl_id = int(re.search(r'/(?:movies|tv|anime)/(\d+)/', loc).group(1))

# 3. Pull the full anime record (summary endpoints auto-include extended data)
anime = requests.get(
    f'https://api.simkl.com/anime/{simkl_id}',
    params=PARAMS,
    headers=HEADERS,
).json()

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.

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Search

TV

Anime

Movies

Ratings

Users

Changes

Redirect & deep-linking

Two use cases

1. Link to Simkl without an API call

2. Cheapest external ID → Simkl ID

Use case 1 — Link to Simkl when you don’t have a Simkl ID

Action modes (`to=`)

Recipes

Building the Simkl URL yourself

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

How `/redirect` resolves an ID

How to extract the Simkl ID from the redirect

Recipes

What you can pass

External IDs

Title + year

Episode targeting

Tweet text

Endpoint reference

GET /redirect

Standard media objects

Detail endpoints

OAuth flow

​Two use cases

1. Link to Simkl without an API call

2. Cheapest external ID → Simkl ID

​Use case 1 — Link to Simkl when you don’t have a Simkl ID

​Action modes (to=)

​Recipes

​Building the Simkl URL yourself

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

​How /redirect resolves an ID

​How to extract the Simkl ID from the redirect

​Recipes

​What you can pass

External IDs

Title + year

Episode targeting

Tweet text

​Endpoint reference

GET /redirect

​Related

Standard media objects

Detail endpoints

OAuth flow

Two use cases

Use case 1 — Link to Simkl when you don’t have a Simkl ID

Action modes (`to=`)

Recipes

Building the Simkl URL yourself

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

How `/redirect` resolves an ID

How to extract the Simkl ID from the redirect

Recipes

What you can pass

Endpoint reference

Related