Changelog

• GET /tv/episodes/{id} and GET /anime/episodes/{id} — on every episode.
• GET /sync/all-items — add episode_runtime=yes (with extended=full) to get it on each episode row.
• Calendar v2 files — on every calendar[].episode. This is an integer, unlike the show-level metadata.runtime display string ("22m").

• GET /lists/{id} returns collection — the sibling lists this one belongs with, such as a franchise split into Movies and TV Shows, or null. See Lists that belong together, and Custom List Collections for how users create one.
• GET /lists/user/{userId} gives every list a role — owner, collaborator or follower — so followed and shared lists can be told apart.
• Auto lists set to random order are not available through the API and return 400; see the FAQ.

"custom_lists": {
  "lists": {
    "all":             "2026-09-21T20:53:09Z",
    "regular":         "2026-09-21T20:53:09Z",
    "favorites":       "2026-09-21T20:50:07Z",
    "recommendations": "2026-09-21T20:51:26Z",
    "auto":            "2026-09-21T20:52:45Z"
  }
}

• It is nested one level deeper than the other blocks: custom_lists.lists.all, not custom_lists.all.
• The bucket is favorites (plural) while a list’s own type field is favorite (singular). They do not match.
• auto does not move when an auto list’s contents are rebuilt — only when the user edits its settings. Auto lists regenerate about once a day, so refresh those on your own schedule rather than waiting for a signal that will not come.

​

AUTH V2 is here, and every app needs a new client_id

​

What you get

​

Request quotas are now counted per user

​

Decide what happens before sign-in

​

The work, in order

​

Token and permission changes

​

Three behaviours that each cost an afternoon

1. Omitting scope grants read-only, and so does misspelling it. An unrecognised scope string is silently treated as read-only rather than rejected, so the failure surfaces much later as a 403 on your first write. Read the scope in the token response rather than assuming you got what you asked for.
2. A failed token exchange consumes the authorization code. Once the request passes client authentication, the code is burned before the grant is validated, so you cannot correct the request and retry the same code. The one exception is 401 invalid_client — client authentication runs first, so a wrong secret leaves the code alive and you can retry it inside the 10-minute window.
3. Refreshing invalidates the previous access token immediately. Two processes that independently refresh the same grant will keep cutting each other off. Either nominate one refresh owner that writes the new token to shared storage, or give each instance its own authorization.

• On stop the rewatch is immediate, but only when progress is 80 or higher, the same threshold that marks the item watched in the first place. A stop below 80 resolves to action: "pause", marks nothing, and returns no rewatch fields at all, flag or no flag. The response gains rewatch_id and rewatch_status. Branch on the status, never on the id: a session that is already running reports its id even when it rejected your watch. active / completed / closed mean it saved. first_watch, too_soon, not_eligible, pro_required and null explain why it didn’t. Note this is a superset of the three-value rewatch_status on /sync/all-items, so widen your enum if you share one.
• On checkin it is deferred. A check-in marks nothing watched at request time, so Simkl stores the opt-in and applies it when the check-in matures at the end of the item’s runtime. The response carries no rewatch fields, so read the session back from GET /sync/all-items?allow_rewatch=yes if you need to confirm it. The PRO / VIP check runs at check-in time, and the choice is frozen once the check-in is recorded.

https://data.simkl.in/calendar/v2/tv.json
https://data.simkl.in/calendar/v2/anime.json
https://data.simkl.in/calendar/v2/movie_release.json
https://data.simkl.in/calendar/v2/{YEAR}/{MONTH}/{tv|anime|movie_release}.json

• Split payload. Each file is now one object with two keys instead of a flat array — calendar (one entry per airing or release, chronological) and metadata (one record per distinct title, keyed by Simkl ID). A show airing 12 episodes this month appears 12 times in calendar but only once in metadata, so titles, posters, IDs, ratings, and genres are stored once rather than repeated on every airing. Join the two on simkl_id.
• All timestamps are UTC. Every date is now ISO 8601 with a trailing Z. The old files carried per-catalog offsets (-05:00 for US TV, +09:00 for anime), which forced clients to normalize before sorting or comparing.
• Finale markers. A new finale_type field flags mid-season (1), season (2), and series (3) finales so you can badge them, null otherwise.
• Much richer metadata. Each title now carries alternate titles, fanart, popularity rank, drop rate, watched and plan-to-watch counts, ratings from Simkl plus IMDb or MAL, country, original language, runtime, status, network, genres, and trailer — plus title_romaji and anime_type on anime, and dvd_date on movies.

• Two CDN fetches → full home screen — combined movies + TV + anime in one round-trip, plus DVD releases.
• 55 default catalog rows ready to render with attribution-correct titles — Trending Today, Most Watchlisted, Top Rated, Hidden Gems, Just Premiered, Movies This Year, Best of Netflix / HBO / Disney+ / Prime / Apple TV, Best Action / Drama / Sci-Fi movies, Best of the 2020s / 2010s / 2000s / 90s, Marathon-Worthy TV, Quick Watches, Anime Movies and OVAs, and more.
• Tunable recipes (hiddenGems, bestOfNetwork, bestOfGenre, bestOfDecade, currentYear, justReleased, marathonWorthy, …) — override knobs per row via recipe_opts or supply a custom transform closure.
• Persistent cache (localStorage in browsers, file in Node), conditional 304 revalidation, retry with backoff, request dedup, reactive subscribe / get API. No build step, no framework.
• Works as-is in browsers, Node 22+, Deno, Bun, React Native, and Cloudflare Workers.

• Write: post episodes (or whole items) the user is rewatching. The server auto-detects rewatch intent, or you can force it with is_rewatch: true. Each session has its own rewatch_id, rewatch_status (active / completed / closed), and per-episode timestamps.
• Read: any item with saved sessions appears multiple times in the response — its normal entry plus one rewatch row per session, each carrying is_rewatch: true and the session fields above.

• Per-request rows with method, path, query string, edge HTTP status, origin HTTP status, origin latency, cache status, country, and User-Agent. Each row has a Link column that re-fires the same GET in a new tab so you can read the live response body.
• Burst detector that flags 3+ requests from the same IP in one second with a red BURST badge. Helps you catch retry loops and runaway timers before the auto-blocker fires.
• Filters with equals, contains, starts with, ends with, and in operators over every column. Common recipe: Origin contains 4 to surface 4xx failures.
• CSV export of the current filtered view for sharing with support or attaching to bug reports.
• One-click mask for sensitive params: hit a button to redact code, access_token, refresh_token, pin, and similar values as *** before screenshotting or sharing the view.

1. Open simkl.com/settings/developer/ while logged in.
2. Click your app’s row.
3. Click Debug (top-right of the app card). The analytics view opens in a new tab.

• Detailed workflow guides: Sync, Scrobble, Search, Anime, Deep linking, Mark as watched, and the new Rewatches guide.
• All three auth flows properly walked through at Authentication: OAuth 2.0 for server-side web apps, Public PKCE for mobile, SPAs, browser extensions and desktop binaries, and PIN flow for TVs, consoles, CLIs, and media-server plugins.
• Conventions pages for the cross-cutting topics Apiary never covered: Headers, Pagination, Dates, Watchlist statuses, Null values, Images, Standard media objects, Extended info, and CORS.
• Flat Errors and status codes page grouped by HTTP status with cause / fix / example for each.
• Interactive try-it-now playground on all 48 endpoints across 14 categories. Drop in your token, hit Send, get a real response back.
• Copy-paste examples in 16 languages: curl, Python, JS/TS, Kotlin, Swift, Java, Go, C#, Ruby, PowerShell, C/C++, and more.
• LLM-friendly: every page can be copied as raw markdown or opened straight in Claude / ChatGPT / Cursor / VSCode. Full-site llms.txt and llms-full.txt are published.
• Full OpenAPI 3.1 spec: every endpoint and every response shape verified against the live API. Point your SDK generator at it.
• One-page endpoint index with all 48 endpoints across 14 categories at a glance.
• Default three-column layout site-wide (left sidebar, content, right-rail TOC) so every page has navigable section anchors.

• Top 100 and Top 500 lists
• Today, This Week, and This Month timeframes
• Combined, Movies, TV Shows, and Anime categories
• Latest popular DVD releases list
• Full title info with multiple IDs

• Scrobble API — POST /scrobble/start, /pause, and /stop for real-time playback tracking with progress percentages. See the Scrobble guide.
• Playback API — GET /sync/playback/{type} and DELETE /sync/playback/{id} to read and clean up paused sessions across devices.
• GET /sync/activities now includes a playback timestamp per type, so you know when to refetch playback state.
• New web UI: Playback progress manager — users can now manage their saved sessions in-product.

• status: "completed" — pass on a show item to set the watchlist status directly. If the show is still airing, Simkl keeps it in Watching instead and reflects the resolved status in the response.
• use_tvdb_anime_seasons: true — pair with status: "completed" on anime to auto-mark every season watched, using TVDB/TMDB seasonal numbering. Lets clients that index against TVDB skip the AniDB season-mapping step.

{
  "added": {
    "movies": 0,
    "shows": 1,
    "episodes": 0,
    "statuses": [
      {
        "request": { "ids": { "simkl": 39687 }, "status": "completed" },
        "response": { "status": "watching" }
      }
    ]
  }
}