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

# Changelog

> What's new across the Simkl API and these docs.

**[Discord](https://discord.gg/MJsWNE4)** 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**](https://twitter.com/Simkl) on X.

Use the **filter** in the right rail to narrow this changelog by tag.

<Update label="2026-05-25" description="Trending SDK with live preview" tags={["Documentation"]}>
  <Badge color="purple" icon="book">Docs</Badge>

  **Trending SDK with live preview**

  A new [Trending SDK](/api-reference/trending) 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](/api-reference/trending) for the embedded CodePen, or open the page to see the full recipe reference.
</Update>

<Update label="2026-05-22" description="Rewatches API" tags={["Major launch"]}>
  <Badge color="green" icon="rocket">Major launch</Badge>

  **Rewatches via `?allow_rewatch=yes`**

  `POST /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**](/guides/rewatches). Quick mention also in the [Sync guide → Record a rewatch](/guides/sync#record-a-rewatch-simkl-pro-vip-only) and [Mark as watched → Record a rewatch](/guides/mark-as-watched#record-a-rewatch-simkl-pro-vip) accordions.
</Update>

<Update label="2026-05-22" description="API Analytics: live per-app request log" tags={["Major launch"]}>
  <Badge color="green" icon="rocket">Major launch</Badge>

  **API Analytics: live per-app request log**

  Every registered Simkl app now has a built-in Analytics view at [/debug/api-analytics](/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/](https://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](/debug/api-analytics).
</Update>

<Update label="2026-05-22" description="Docs revamp: new home at api.simkl.org" tags={["Major launch"]}>
  <Badge color="purple" icon="book">Docs</Badge>

  **Docs revamp**

  [Apiary](https://simkl.docs.apiary.io/) 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](https://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](/guides/sync), [Scrobble](/guides/scrobble), [Search](/guides/search), [Anime](/guides/anime), [Deep linking](/guides/deep-linking), [Mark as watched](/guides/mark-as-watched), and the new [Rewatches](/guides/rewatches) guide.
  * **All three auth flows properly walked through** at [Authentication](/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](/conventions/headers), [Pagination](/conventions/pagination), [Dates](/conventions/dates), [Watchlist statuses](/conventions/list-statuses), [Null values](/conventions/null-values), [Images](/conventions/images), [Standard media objects](/conventions/standard-media-objects), [Extended info](/conventions/extended-info), and [CORS](/conventions/cors).
  * **Flat [Errors and status codes](/conventions/errors)** 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`](/llms.txt) and [`llms-full.txt`](/llms-full.txt) are published.
  * **Full [OpenAPI 3.1 spec](/openapi.json)**: every endpoint and every response shape verified against the live API. Point your SDK generator at it.
  * **One-page [endpoint index](/all-endpoints)** 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.
</Update>

<Update label="2026-04-22" description="Required app identification" tags={["Breaking change"]}>
  <Badge color="red" icon="triangle-exclamation">Breaking</Badge>

  **`app-name` and `app-version` are now required**

  Every 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](/quickstart) and [Headers and conventions](/conventions/headers).
</Update>

<Update label="2026-03-10" description="API terminology: List → Watchlist" tags={["Documentation"]}>
  <Badge color="purple" icon="book">Docs</Badge>

  **Renamed 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.
</Update>

<Update label="2026-02-10" description="Trending data files" tags={["New feature"]}>
  <Badge color="blue" icon="sparkles">New feature</Badge>

  **New: Pre-built trending JSON files**

  We'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](/api-reference/trending).
</Update>

<Update label="2026-01-31" description="New endpoint: /scrobble/checkin" tags={["New feature"]}>
  <Badge color="blue" icon="sparkles">New feature</Badge>

  **Manual "fire-and-forget" tracking**

  New endpoint: [`POST /scrobble/checkin`](/api-reference/simkl/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`](/api-reference/simkl/scrobble-start) / [`/pause`](/api-reference/simkl/scrobble-pause) / [`/stop`](/api-reference/simkl/scrobble-stop).

  |                   | `/scrobble/checkin` (manual)        | `/scrobble/start` / `/pause` / `/stop` (real-time) |
  | ----------------- | ----------------------------------- | -------------------------------------------------- |
  | **Purpose**       | Simple "watching now" status        | Active player tracking                             |
  | **When to call**  | Once, when the user starts watching | On real player events (start, pause, stop, resume) |
  | **Auto-complete** | Yes (marks watched on expiry)       | No — requires explicit `/stop`                     |
  | **`progress`**    | Optional                            | Required                                           |

  Use cases: cinema apps, live-TV trackers, social "watching now" status updates. See [Scrobble guide](/guides/scrobble).
</Update>

<Update label="2026-01-15" description="PIN flow polling clarified" tags={["Improvement"]}>
  <Badge color="gray" icon="wrench">Improvement</Badge>

  **PIN poll response — two distinct shapes**

  The `/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](/api-reference/pin) for the response schemas.
</Update>

<Update label="2025-10-08" description="Scrobble and Playback APIs launch" tags={["Major launch"]}>
  <Badge color="green" icon="rocket">Major launch</Badge>

  **Major: real-time scrobble + cross-device playback**

  Two big additions for media-player integrations:

  * **Scrobble API** — [`POST /scrobble/start`](/api-reference/simkl/scrobble-start), [`/pause`](/api-reference/simkl/scrobble-pause), and [`/stop`](/api-reference/simkl/scrobble-stop) for real-time playback tracking with progress percentages. See the [Scrobble guide](/guides/scrobble).
  * **Playback API** — [`GET /sync/playback/{type}`](/api-reference/simkl/get-playback-sessions) and [`DELETE /sync/playback/{id}`](/api-reference/simkl/delete-playback) to read and clean up paused sessions across devices.
  * [`GET /sync/activities`](/api-reference/simkl/get-activities) now includes a `playback` timestamp per type, so you know when to refetch playback state.
  * New web UI: [Playback progress manager](https://simkl.com/my/history/playback-progress-manager/) — users can now manage their saved sessions in-product.

  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.
</Update>

<Update label="2025-08-15" description="Calendar files expanded" tags={["New feature"]}>
  <Badge color="blue" icon="sparkles">New feature</Badge>

  **Monthly archive endpoints**

  The [Calendar JSON](/api-reference/calendar) 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.
</Update>

<Update label="2025-06-01" description="Image proxy via wsrv.nl" tags={["Documentation"]}>
  <Badge color="purple" icon="book">Docs</Badge>

  **Recommended image hosting: wsrv.nl**

  We now recommend serving Simkl image paths through [wsrv.nl](https://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](/conventions/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).
</Update>

<Update label="2025-05-29" description="runtime field on /sync/all-items" tags={["Improvement"]}>
  <Badge color="gray" icon="wrench">Improvement</Badge>

  **`runtime` (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.

  ```json theme={"theme":{"light":"github-light","dark":"vesper"}}
  {
    "runtime": 40
  }
  ```
</Update>

<Update label="2025-02-25" description="simkl_type and anime_type in /sync/history response" tags={["Improvement"]}>
  <Badge color="gray" icon="wrench">Improvement</Badge>

  **`simkl_type` and `anime_type` in `/sync/history` response**

  The per-item `response` object inside `added.statuses` now includes `simkl_type` (`movie` / `tv` / `anime`) and `anime_type` (`tv` / `special` / `ova` / `movie` / `music video` / `ona`).

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

<Update label="2025-02-05" description="/sync/history: status field + use_tvdb_anime_seasons" tags={["Improvement"]}>
  <Badge color="gray" icon="wrench">Improvement</Badge>

  **Complete a show in one call**

  Two 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:

  ```json theme={"theme":{"light":"github-light","dark":"vesper"}}
  {
    "added": {
      "movies": 0,
      "shows": 1,
      "episodes": 0,
      "statuses": [
        {
          "request": { "ids": { "simkl": 39687 }, "status": "completed" },
          "response": { "status": "watching" }
        }
      ]
    }
  }
  ```

  See [`POST /sync/history`](/api-reference/simkl/add-to-history).
</Update>