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.

Custom Lists are user-curated collections of titles — themed groupings like “Best 90s sci-fi”, “Watched with my kids”, or “Recommended by Anna” — created by users in the simkl.com web UI at simkl.com/lists/. They are distinct from the five-status Watchlist (watching, plantowatch, hold, dropped, completed) that the API has always exposed. A title can be on the user’s Watchlist with a status AND on one or more Custom Lists at the same time, independently.
Custom Lists are not yet available via the API. They’re served by Simkl V2 Beta, an in-development backend that isn’t publicly callable yet. There is no public endpoint to read, create, or modify Custom Lists, and no firm ETA.Until V2 Beta ships, use the existing Watchlist sync endpoints (below) for everything library-related. We’ll announce Custom Lists on the changelog and in the Discord #api channel the moment they’re callable.

​
What to use today

For “fetch the user’s library” use cases, the Watchlist sync endpoints already cover what most apps need — every movie / show / anime the user has tracked, with status, ratings, watched-episode counts, last-watched timestamps, and rewatch sessions.

GET /sync/all-items

Full library snapshot. See the Sync guide for two-phase fetch and date_from semantics.

POST /sync/add-to-list

Move items between the five Watchlist statuses.

GET /sync/activities

Per-bucket timestamps for cheap “is there anything new?” polling.

POST /sync/history

Record watch events — single episode, whole season, or whole show.
These give you the same library data Simkl shows at simkl.com/<user>/ — organized by status bucket rather than by user-defined list, but the underlying items are the same.

​
When V2 Beta ships

When Custom Lists become available via the public API, we’ll publish endpoints to:
  • List the user’s Custom Lists with metadata (name, description, public/private, item count).
  • Read a specific Custom List’s items.
  • Create, update, and delete Custom Lists.
  • Add and remove items within a Custom List.
  • Read public Custom Lists by user or list slug — the same lists currently visible in the web UI at simkl.com/<user>/lists/<list-slug>.
The Watchlist sync endpoints will continue to work unchanged — Custom Lists are a new layer on top, not a replacement.

​
Common questions

The web UI calls internal endpoints that are part of Simkl’s V2 Beta backend. They aren’t documented or stable, and they’re tied to Simkl’s own session cookies rather than OAuth tokens. Don’t scrape them — they’ll break under you without notice, and we may rate-limit or block clients that hit them. Wait for the public API.
Not on the Simkl side. The only grouping primitive the public API exposes today is the five-status Watchlist. If your app needs custom grouping right now, store the grouping client-side (your own DB keyed by Simkl ID) and overlay it on top of /sync/all-items data. When the Custom Lists API ships, you’ll be able to migrate that data into real Simkl Custom Lists.
Yes. The Watchlist endpoints (/sync/all-items, /sync/add-to-list, /sync/history, …) will continue to work unchanged. Custom Lists are a separate, additive concept — a title can be on the user’s Watchlist with a status (e.g. completed) AND on one or more Custom Lists at the same time, independently.
Public Custom Lists are viewable in the web UI at simkl.com/<user>/lists/<list-slug>, but there’s no API for them yet. Public-list read access is planned to ship alongside the rest of the Custom Lists API.
Once shipped, yes — they’ll use the same rate-limit pool as the other /sync/* endpoints. Plan your polling accordingly: a Custom-Lists-heavy app should batch reads where possible and use /sync/activities (or its eventual Custom-Lists equivalent) to detect change rather than polling list contents on a fixed cadence.

​
Reference

Sync guide

Two-phase model, date_from semantics, deletion reconciliation.

Watchlist statuses

The five status values, per-type rules, and the legacy notinteresting → dropped rename.

Mark as watched

Simple “the user finished this” recipes.

Rewatches

Separate sessions for items the user already finished.