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.

Pick the right entry point for your situation — searching by user-typed text, by filename, by external ID, or just browsing the catalog.

By external ID

GET /redirect — already have an IMDB / TMDB / TVDB / MAL / AniDB / etc. ID? Resolve it to a Simkl ID, then fetch from the cached detail endpoint. Faster and cheaper than text search.

By text

GET /search/{type} — full-text search over titles. type is movie, tv, or anime.

By file name

POST /search/file — pass a video file name and Simkl matches it to a title and episode.

Random

POST /search/random — surprise me. Useful for “What should I watch?” features.
Writes don’t need a Simkl ID at all. /scrobble/*, /sync/history, /sync/add-to-list, and /sync/ratings accept any supported ID (IMDB, TMDB, TVDB, MAL, AniDB, …) directly and resolve server-side. The resolve-then-fetch pattern above is only needed when you want to read the Simkl record for a known external ID.

​
When to use each

You have an IMDB / TMDB / TVDB / MAL / AniDB / AniList / Kitsu / etc. ID and want the matching Simkl record. Call GET /redirect, read the Location header, parse the Simkl ID, then hit the cached detail endpoint:
curl -sI "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" | grep -i ^location:
# → location: https://simkl.com/tv/17465/game-of-thrones

curl "https://api.simkl.com/tv/17465?extended=full&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0"
Both calls are cheap: /redirect is just an HTTP redirect (no JSON body); the detail endpoint is Cloudflare-cached by Simkl ID with automatic server-side cache invalidation. See the Redirect guide for the full stop-at-301 recipe.
Best for user-typed search bars. Pass q (the query) and pick the type:
curl "https://api.simkl.com/search/tv?q=stranger+things&extended=full&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0"
Pass a file name like Stranger.Things.S01E03.1080p.WEB.x264-GROUP.mkv and Simkl will identify the show and episode. Ideal for indexing a local library.
Returns a random title, optionally filtered by genre, year, or watchlist status. Great for “next pick” buttons.

​
Browse & discover

For browsing the catalog rather than running a query — top-rated lists, premieres, what’s airing, or filtering by genre — use the dedicated browse endpoints:
SurfaceEndpoints
Top-rated / most-watched/tv/best/{filter}, /anime/best/{filter}
Premieres/tv/premieres/{param}, /anime/premieres/{param}
Airing now/tv/airing, /anime/airing
Filter by genre/movies/genres/..., /tv/genres/..., /anime/genres/...
For trending and calendar surfaces, prefer the CDN-cached data files on data.simkl.in — no per-user cost.