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.

Simkl returns different amounts of data depending on the endpoint. Most lookups now return the rich record by default — you only need the extended parameter on a small set of endpoints, and the accepted values vary per endpoint.

​
At a glance

Endpoint familyDefault responseextended parameter?
GET /movies/:id, GET /tv/:id, GET /anime/:idFull record — title, year, ids, overview, genres, ratings, poster, fanart, trailers, recommendationsNot needed.
GET /tv/episodes/:id, GET /anime/episodes/:idFull episode list with metadataNot needed.
GET /sync/all-items/:type/:statusRich summary — last_watched, last_watched_at, watched_episodes_count, total_episodes_count, next_to_watch, plus a show/movie/anime block with title, poster, runtime, ids.Single value: full, full_anime_seasons, ids_only, or simkl_ids_only (see below).
GET /search/:type (text search)title, year, poster, ids (simkl_id, slug, tmdb), plus title_en / title_romaji / type for anime.extended=full adds all_titles, url, rank, status, ratings, and ep_count (non-movies).
GET /search/id, POST /search/fileMatch metadataextended is not used.

​
Summary endpoints — no extended needed

Calling a summary endpoint returns the full media object out of the box: 
curl "https://api.simkl.com/tv/17465?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0" \
  -H "User-Agent: my-app-name/1.0"
You’ll get back overview, ratings, genres, trailers, recommendations — everything that used to require ?extended=full. The parameter is still accepted for backward compatibility, but it’s a no-op on /movies/:id, /tv/:id, /anime/:id, /tv/episodes/:id, and /anime/episodes/:id.

​
GET /sync/all-items/:type/:status — multiple modes

This is the only endpoint where extended takes one of several distinct mode values (not a comma-separated list). The default response is already rich — extended modes either reduce it to a slimmer ID-only payload (for fast deletion-reconciliation diffs) or enhance it with episode-level data and full metadata.
ValueWhat you get
(omitted)Default rich summary per item: last_watched, last_watched_at, watched_episodes_count, total_episodes_count, not_aired_episodes_count, next_to_watch, added_to_watchlist_at, user_rating, user_rated_at, status, plus a show / movie / anime block with title, poster, year, runtime, and ids.
extended=simkl_ids_onlyReduces to just ids.simkl per item — smallest possible delta payload, ideal for diffing against a local cache.
extended=ids_onlyReduces to the full ids block (Simkl + every external catalog ID) without other metadata.
extended=fullEnhances the default with genres, ratings, full metadata, and a seasons[].episodes[] block for items in watching / plantowatch / hold statuses. Episode entries contain number only — per-episode watched_at requires the separate episode_watched_at=yes parameter.
extended=full_anime_seasonsSame as extended=full, plus anime entries gain a show-level mapped_tvdb_seasons: [n, …] array (each Simkl/AniDB season’s matching TVDB season number) and a per-episode tvdb: { season, episode } block. Not applied to anime movies.
Two query parameters interact with extended on /sync/all-items but are separate flags:
  • include_all_episodes=yes (or =original) — by default, extended=full doesn’t load seasons[].episodes[] for items in completed or dropped buckets. Set include_all_episodes=yes to load episodes on those buckets too (synthesizes virtual episode rows for items without per-episode data). Use =original to load only real per-episode rows, skipping virtual synthesis.
  • episode_watched_at=yes — adds per-episode watched_at timestamps to whatever episodes are loaded. Modifier only — episodes must already be present via extended=full or include_all_episodes=yes. Without this flag, episode entries carry only number.
See the /sync/all-items reference for the full response shape per mode, and the Sync guide for the two-phase model that puts these together. For rewatch-session reads, see the Rewatches guide.

​
Search — only /search/:type uses extended

/search/:type (free-text search) accepts only extended=full (no comma-separated values, no other modes). Default match shape (without extended): title, year, poster, endpoint_type, plus ids (simkl_id, slug, and tmdb when available). Anime entries also include title_en, title_romaji, and type (tv / movie / ova / ona / special / music video). With extended=full the response adds:
  • all_titles — alternate titles / aliases (only when more than one is known for the item)
  • url — canonical simkl.com URL
  • rank — Simkl rank for the type
  • status — running / ended / cancelled / etc.
  • ratings — Simkl + IMDb + MAL aggregate ratings (each present when available)
  • ep_count — episode count, non-movies only (TV and anime)
/search/id and /search/file don’t honour extended — they always return their default match shape. See those endpoints’ pages for the actual response fields.
For /search/id specifically, use the per-catalog ID query parameter that matches what you have (imdb, tmdb, tvdb, mal, etc.). The response shape is fixed; there’s no opt-in extension.