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.

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-22
New feature
Rewatches API
New featureRewatches via ?allow_rewatch=yesPOST /sync/history and GET /sync/all-items now support tracking rewatches as separate sessions when the caller opts in via ?allow_rewatch=yes. Available to Simkl Pro and VIP subscribers.
  • On POST /sync/history: a watch event on an already-Completed item creates a new rewatch session instead of being a no-op. The server auto-detects rewatches (treats a write as one when the item is already Completed and the add was a no-op, or when a payload includes episodes and none of them were new), or you can force it with is_rewatch: true on the item.
  • On GET /sync/all-items: any item (movie, show, or anime) with saved rewatch sessions appears multiple times in the response — its normal entry, plus one extra entry per rewatch session. The extra entries carry is_rewatch: true, rewatch_id, rewatch_status (active / completed / closed), last_watched_at, and watched_episodes_count. Without the flag, every item appears once and none of those fields are emitted.
  • Per-item write fields (all optional): is_rewatch, rewatch_id (resume an existing session), rewatch_status, last_watched_at.
  • Limits: up to 50 rewatches per item (movie, show, or anime); any two watch events on the same item (movie or episode) must be at least 2 days apart — it’s a rewatch, not a rewind 😄.
Full walkthrough in the new Rewatches guide — session lifecycle, episode tracking, reading sessions back, and ready-made code for simkl.com-style UI patterns. Quick mention also in the Sync guide → Record a rewatch and Mark as watched → Record a rewatch accordions.
​
2026-05-22
New feature
API Analytics: live per-app request log
New featureAPI 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
Documentation
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 launchNew feature
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-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.