> ## 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.

# Deep-linking to Simkl

> Link from your app, newsletter, or extension straight to the right Simkl page — even when you don't have a Simkl ID. Use external IDs (IMDb, TMDB, MAL, …) or title + year as the entry point.

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.

<Card title="Redirect & deep-linking — full API reference" icon="circle-info" href="/api-reference/redirect" horizontal>
  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.
</Card>

## The simplest case — just use the URL as a hyperlink

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.

```html theme={"theme":{"light":"github-light","dark":"vesper"}}
<!-- 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

<Tip>
  **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.
</Tip>

<CodeGroup>
  ```bash IMDb + title + year → Simkl page theme={"theme":{"light":"github-light","dark":"vesper"}}
  # 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
  ```

  ```bash TMDB (TV) + title + year → Simkl page theme={"theme":{"light":"github-light","dark":"vesper"}}
  # TMDB IDs are NOT unique across types — a TMDB movie ID and TMDB TV ID can collide.
  # Always pair TMDB with `type=movie` or `type=tv` — TMDB has no anime type
  # (anime shows are filed under tv on TMDB; Simkl routes them to its anime catalog automatically).
  curl -I "https://api.simkl.com/redirect?to=simkl\
  &type=tv&tmdb=1399&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"

  # Location: https://simkl.com/tv/17465/game-of-thrones
  ```

  ```bash TMDB (movie) + title + year → Simkl page theme={"theme":{"light":"github-light","dark":"vesper"}}
  curl -I "https://api.simkl.com/redirect?to=simkl\
  &type=movie&tmdb=27205&title=Inception&year=2010\
  &client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0" \
    -H "User-Agent: my-app-name/1.0"

  # Location: https://simkl.com/movies/472214/inception
  ```

  ```bash MAL + title + year → Simkl anime page theme={"theme":{"light":"github-light","dark":"vesper"}}
  # Anime catalog IDs (MAL, AniDB, AniList, Kitsu, AniSearch, LiveChart, Anime-Planet)
  # don't need `type` — they're unambiguous.
  curl -I "https://api.simkl.com/redirect?to=simkl\
  &mal=11757&title=Sword%20Art%20Online&year=2012\
  &client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0" \
    -H "User-Agent: my-app-name/1.0"

  # Location: https://simkl.com/anime/37226/sword-art-online
  ```

  ```bash Multiple IDs at once → most reliable theme={"theme":{"light":"github-light","dark":"vesper"}}
  # When your local catalog stores several external IDs per title (common for
  # apps consolidating data from multiple databases), pass them all.
  curl -I "https://api.simkl.com/redirect?to=simkl\
  &imdb=tt0903747&tmdb=1396&tvdb=81189\
  &title=Breaking%20Bad&year=2008\
  &client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0" \
    -H "User-Agent: my-app-name/1.0"

  # Location: https://simkl.com/tv/11121/breaking-bad
  ```

  ```bash Title + year only → fallback when you have no IDs theme={"theme":{"light":"github-light","dark":"vesper"}}
  # Useful for free-text catalogs or rare items not in mainstream databases.
  # Always pair with `type` to disambiguate movies from same-titled shows.
  curl -I "https://api.simkl.com/redirect?to=simkl\
  &type=movie&title=Inception&year=2010\
  &client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0" \
    -H "User-Agent: my-app-name/1.0"

  # Location: https://simkl.com/movies/472214/inception
  ```

  ```bash Specific episode → Simkl episode page theme={"theme":{"light":"github-light","dark":"vesper"}}
  # Add `season=N&episode=M` to any of the above. Setting either parameter
  # excludes movies from the candidate set automatically.
  curl -I "https://api.simkl.com/redirect?to=simkl\
  &imdb=tt0944947&title=Game%20of%20Thrones&year=2011\
  &season=1&episode=3\
  &client_id=$CLIENT_ID&app-name=my-app-name&app-version=1.0" \
    -H "User-Agent: my-app-name/1.0"

  # Location: https://simkl.com/tv/17465/game-of-thrones/season-1/episode-3
  ```
</CodeGroup>

## Action modes — what should clicking the link do?

The `to=` parameter controls what the redirect lands on. Default is `simkl` (the item's detail page).

| `to=` value         | Where the user lands                                                                                                                                                                                            |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `simkl` *(default)* | The Simkl page for the item (or season / episode if you also passed `season`/`episode`).                                                                                                                        |
| `trailer`           | The trailer URL (typically YouTube). Great for "Watch trailer" buttons.                                                                                                                                         |
| `twitter`           | A pre-filled tweet (`twitter.com/intent/tweet?...`) with the title and a Simkl link. Use for "Share on Twitter" / "Share on X" buttons.                                                                         |
| `watched`           | Marks 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. |

```html theme={"theme":{"light":"github-light","dark":"vesper"}}
<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:

| 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}/`             |

<Tip>
  **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.
</Tip>

## 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.

<Card title="External ID → Simkl ID — full reference" icon="bolt" href="/api-reference/redirect#use-case-2-resolve-an-external-id-to-a-simkl-id" horizontal>
  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.
</Card>

## Caching links

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](/conventions/headers#required-url-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

<CardGroup cols={2}>
  <Card title="Redirect & deep-linking" icon="circle-info" href="/api-reference/redirect">
    The full API reference — every accepted parameter, all action modes, and recipes for the advanced "external ID → Simkl ID → detail-endpoint call" workflow.
  </Card>

  <Card title="GET /redirect" icon="arrow-right" href="/api-reference/simkl/redirect">
    Endpoint reference with the parameter schema and interactive playground.
  </Card>

  <Card title="Standard media objects" icon="film" href="/conventions/standard-media-objects">
    Where the `ids.simkl_id` and `ids.slug` fields come from. You'll see them on every API response.
  </Card>

  <Card title="Supported ID keys" icon="hashtag" href="/conventions/standard-media-objects#supported-id-keys">
    The complete list of external catalog identifiers and slugs you can pass to `/redirect`, with format examples for each.
  </Card>
</CardGroup>