Skip to main content
Discord is where most API announcements and developer chat happen — join us for new endpoints, breaking changes, and integration help in real time. For broader Simkl product news — apps, features, releases — follow @Simkl on X. Use the filter in the right rail to narrow this changelog by tag.
​
2026-05-25
Documentation
Trending SDK with live preview
DocsTrending SDK with live previewA new Trending SDK page shows how to combine filters and sorts on top of our cached top-500 trending feeds. Drop-in JS file (also ported to Python, Swift, Kotlin, and Dart) plus an embedded CodePen you can fork.
  • 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.
Scroll to “Try it live” on the trending page for the embedded CodePen, or open the page to see the full recipe reference.
​
2026-05-22
Major launch
Rewatches API
Major launchRewatches via ?allow_rewatch=yesPOST /sync/history and GET /sync/all-items now track rewatches as separate sessions when the caller opts in with ?allow_rewatch=yes. Simkl Pro / VIP only.
  • 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.
Walkthrough, state-machine rules, and ready-made code for simkl.com-style UI patterns in the new Rewatches guide. Quick mention also in the Sync guide → Record a rewatch and Mark as watched → Record a rewatch accordions.
​
2026-05-22
Major launch
API Analytics: live per-app request log
Major launchAPI Analytics: live per-app request logEvery registered Simkl app now has a built-in Analytics view at /debug/api-analytics showing exactly what your code sent to api.simkl.com. Up to 24 hours of individual requests, with edge and origin status codes, latency, burst detection, and CSV export.What you can see:
  • 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.
How to open it:
  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.
Useful for diagnosing OAuth wrappers that quietly drop headers, sync loops missing date_from, silent 4xx errors your HTTP client never surfaces, and stale edge-cache hits.Full reference at API Analytics.
​
2026-05-22
Major launch
Docs revamp: new home at api.simkl.org
DocsDocs revampApiary is retired. Oracle is shutting it down in October, and Apiary has been going down for hours at a stretch lately on top of that, so we used the forcing function to redo everything from scratch. The docs now live at api.simkl.org. Most of the content is new: what was supposed to be a content migration turned into a top-to-bottom audit when we found significant drift between the old docs and the actual API.What’s new:
  • 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.
​
2026-04-22
Breaking change
Required app identification
Breakingapp-name and app-version are now requiredEvery API request must now include app-name and app-version URL parameters alongside client_id, plus a descriptive User-Agent header. This lets us help debug issues faster and prevents accidental blocks.
/endpoint?client_id=CLIENT_ID&app-name=my-app-name&app-version=1.0
See the updated Quickstart and Headers and conventions.
​
2026-03-10
Documentation
API terminology: List → Watchlist
DocsRenamed in the docs: “List” → “Watchlist”Simkl’s website introduced Custom Lists — user-created collections of titles. To avoid confusion with the existing 5-status bucket system (Watching, Plan to Watch, Hold, Dropped, Completed), the API docs now refer to that bucket system as the Watchlist instead of “List”.Nothing changed at the API level. The endpoint URL /sync/add-to-list is unchanged, request/response shapes are unchanged. Only the docs use the term “Watchlist” now — e.g., the endpoint is referred to as “Add to Watchlist” in the sidebar and prose.A dedicated Custom Lists API may ship in a future release.
​
2026-02-10
New feature
Trending data files
New featureNew: Pre-built trending JSON filesWe’ve published trending data as static JSON on data.simkl.in — no API key required (User-Agent and attribution still required). Useful for “What’s hot right now” surfaces without paying any per-user request budget.
  • 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
See the full file index in Trending data files.
​
2026-01-31
New feature
New endpoint: /scrobble/checkin
New featureManual “fire-and-forget” trackingNew endpoint: POST /scrobble/checkin. Send one request when the user starts watching; Simkl handles the “watching now” bar, runtime tracking, and auto-completion when runtime elapses. One call, then nothing else — useful when you don’t have real player events to drive /start / /pause / /stop.
/scrobble/checkin (manual)/scrobble/start / /pause / /stop (real-time)
PurposeSimple “watching now” statusActive player tracking
When to callOnce, when the user starts watchingOn real player events (start, pause, stop, resume)
Auto-completeYes (marks watched on expiry)No — requires explicit /stop
progressOptionalRequired
Use cases: cinema apps, live-TV trackers, social “watching now” status updates. See Scrobble guide.
​
2026-01-15
Improvement
PIN flow polling clarified
ImprovementPIN poll response — two distinct shapesThe /oauth/pin/{USER_CODE} polling response now returns one of two explicit JSON shapes (instead of a single shape with mixed semantics): { "result": "KO", "message": "Authorization pending" } while the user hasn’t entered the code yet, and { "result": "OK", "access_token": "..." } once they approve. Simpler client-side state machine — branch on result.See PIN authentication for the response schemas.
​
2025-10-08
Major launch
Scrobble and Playback APIs launch
Major launchMajor: real-time scrobble + cross-device playbackTwo big additions for media-player integrations:Use case: a user pauses an episode at 40% on the living-room TV, switches to their iPad in the bedroom, and the iPad app picks up exactly where they left off.Note: only one playback is stored per show/movie. Starting a new episode replaces any previous paused playback for that title.
​
2025-08-15
New feature
Calendar files expanded
New featureMonthly archive endpointsThe Calendar JSON now includes per-month archives for the last 12 months at the URL pattern https://data.simkl.in/calendar/{YEAR}/{MONTH}/{tv|anime|movie_release}.json. The current month regenerates every 6 hours; previous months once a day.
​
2025-06-01
Documentation
Image proxy via wsrv.nl
DocsRecommended image hosting: wsrv.nlWe now recommend serving Simkl image paths through wsrv.nl, a free image proxy that caches, resizes, and converts on the fly. This minimizes load on Simkl’s image servers and gives you free transformations like WebP conversion.See Images for the URL pattern and size codes. Examples append &q=90 for origin-equivalent quality (wsrv’s default &q=80 reduces filesize and quality).
​
2025-05-29
Improvement
runtime field on /sync/all-items
Improvementruntime (minutes) on shows and movies/sync/all-items responses now include a runtime integer field on show and movie items — minutes per episode for shows, total runtime for movies. Useful for “time to finish”, watch-time stats, and pacing surfaces.
{
  "runtime": 40
}
​
2025-02-25
Improvement
simkl_type and anime_type in /sync/history response
Improvementsimkl_type and anime_type in /sync/history responseThe per-item response object inside added.statuses now includes simkl_type (movie / tv / anime) and anime_type (tv / special / ova / movie / music video / ona).
"response": {
  "status": "completed",
  "simkl_type": "anime",
  "anime_type": "movie"
}
Useful when you’re sending titles by TMDB ID and need to know how Simkl classified the item — e.g., a TMDB movie that Simkl resolved as an anime movie. Also handy for clients that store simkl_type locally so they can later reconcile deletions across types.
​
2025-02-05
Improvement
/sync/history: status field + use_tvdb_anime_seasons
ImprovementComplete a show in one callTwo additions to POST /sync/history:
  • 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.
The response now returns a statuses array showing the resolved per-item status:
{
  "added": {
    "movies": 0,
    "shows": 1,
    "episodes": 0,
    "statuses": [
      {
        "request": { "ids": { "simkl": 39687 }, "status": "completed" },
        "response": { "status": "watching" }
      }
    ]
  }
}
See POST /sync/history.