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.

If your app already has external IDs (IMDb, TMDB, TVDB, AniDB, …) — typical for watchlist importers, media-server plugins (Plex / Jellyfin / Kodi), browser extensions, and any app that maintains its own catalog of titles — you don’t need to call the Simkl JSON API just to send a user to the matching Simkl page. The GET /redirect endpoint takes any identifier you have and 301-redirects to the right URL on simkl.com. No Authorization token required. No JSON parsing. The browser (or any HTTP client) follows the redirect automatically.

Redirect & deep-linking — full API reference

Two use cases (linking + ID resolution), every accepted parameter, all action modes (to=simkl/trailer/twitter/watched), curl/JS/Python recipes for resolving an external ID into a Simkl ID for follow-up API calls.
In a newsletter, a browser-extension menu, a “View on Simkl” button, or any other surface where you want a clickable link, the /redirect URL is the href. The browser hits it, gets a 301, follows it to simkl.com. No JS, no fetch, no parsing. 
<!-- IMDB ID → Simkl TV page -->
<a href="https://api.simkl.com/redirect?to=simkl&imdb=tt0944947&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0">
  View Game of Thrones on Simkl
</a>
That’s the entire integration. Just remember to URL-encode any query-string values that need it (titles with spaces, special characters).

​
Recipes by what you have

Pass every identifier you have — not just the cheapest one. /redirect resolves the best match by considering all the data you send. Combining an ID with title and year is more reliable than the ID alone: if a catalog ever re-issues or merges an ID, the title and year keep your link pointing at the right item. The examples below show realistic combined payloads, not minimum-required calls.
# IMDb IDs are unambiguous across types (the `tt` prefix is unique), so no `type` needed.
# Title and year are extra signal that helps when an ID is ambiguous or stale.
curl -I "https://api.simkl.com/redirect?to=simkl\
&imdb=tt0944947&title=Game%20of%20Thrones&year=2011\
&client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0"

# Response:
# HTTP/1.1 301 Moved Permanently
# Location: https://simkl.com/tv/17465/game-of-thrones
The to= parameter controls what the redirect lands on. Default is simkl (the item’s detail page).
to= valueWhere the user lands
simkl (default)The Simkl page for the item (or season / episode if you also passed season/episode).
trailerThe trailer URL (typically YouTube). Great for “Watch trailer” buttons.
twitterA pre-filled tweet (twitter.com/intent/tweet?...) with the title and a Simkl link. Use for “Share on Twitter” / “Share on X” buttons.
watchedMarks the item as watched on the user’s account, then lands them on the page. If the user isn’t signed in, Simkl first redirects through /oauth/authorize, completes the action, then lands them on the page.
<a href="https://api.simkl.com/redirect?to=trailer&imdb=tt0944947&client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0">
  ▶ Watch trailer
</a>

<a href="https://api.simkl.com/redirect?to=twitter&type=movie&title=Inception&year=2010&client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0">
  Share on X
</a>

<a href="https://api.simkl.com/redirect?to=watched&imdb=tt0944947&client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0">
  ✓ Mark as watched on Simkl
</a>

​
When you already have a Simkl ID

If you’ve already called /movies/:id, /tv/:id, /anime/:id, or any sync endpoint, the response includes ids.simkl_id (or ids.simkl) and ids.slug on every item. Build the URL yourself — it’s faster than another /redirect round-trip:
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 libraryhttps://simkl.com/{username}/{tv|movies|anime}/
Always include the slug when you have it. The slug is technically optional, but skipping it forces Simkl to run a title lookup and 301-redirect to the slugged URL anyway — that’s a wasted round-trip on both sides. The slug is returned in ids.slug on every standard media object — store it alongside the Simkl ID and reuse.

​
Need the Simkl ID for an API call?

/redirect is also the cheapest way to resolve an external ID into a Simkl ID — much lighter than GET /search/id. Issue a HEAD request, parse the Location header for the numeric ID, then call /movies/{id} / /tv/{id} / /anime/{id} to get the full record. The follow-up call is Cloudflare-cached by Simkl ID, so repeat lookups of the same title cost almost nothing.

External ID → Simkl ID — full reference

Step-by-step recipes in bash, JS, and Python for resolving an external ID into a Simkl ID via /redirect’s Location header, then fetching the full record from the cached detail endpoint. Includes the regex for extracting the ID and a caching recommendation.
The /redirect response always returns Cache-Control: no-store, so don’t try to HTTP-cache the redirect itself. But the resolved URL (everything after the 301) doesn’t change unless a Simkl admin re-slugs the title — extremely rare. If your app does the resolution once and renders many links to the same item, cache the result locally and skip the redirect for the next render.

​
Required parameters

Like every Simkl endpoint, requests to /redirect must include client_id, app-name, app-version as URL parameters and a User-Agent header. See Headers and required parameters for the full convention. /redirect does not require an Authorization token — except for to=watched, which signs the user in if they aren’t already.

​
Reference

Redirect & deep-linking

The full API reference — every accepted parameter, all action modes, and recipes for the advanced “external ID → Simkl ID → detail-endpoint call” workflow.

GET /redirect

Endpoint reference with the parameter schema and interactive playground.

Standard media objects

Where the ids.simkl_id and ids.slug fields come from. You’ll see them on every API response.

Supported ID keys

The complete list of external catalog identifiers and slugs you can pass to /redirect, with format examples for each.