API Reference
Trending
Calendar
Redirect
Sync
Changes
Add to Watchlist
Move an item into one of the user’s Watchlist statuses. The body’s per-item to field selects the destination:
Most apps prefer POST /sync/history for sync flows. Use this endpoint (/sync/add-to-list) when your app has explicit “Add to Plan to Watch” / “Move to Hold” UI buttons — i.e. you’re setting watchlist status without recording a watch event. For backfill from another tracker, scrobbling, or marking-watched UI, send to /sync/history instead (which carries status, rating, memo, AND the watch event in one shape). See the Sync guide for the two-phase pull/delta pattern.
This endpoint does not save memos. If you include a memo field per item, the request succeeds and the memo is echoed back in the response — but the value is not persisted; reading the item with ?memos=yes afterwards returns memo: {}. To set or update a memo, send the item to POST /sync/history with ids + status + memo. /sync/history also auto-adds the item to the watchlist if it wasn’t there yet, so a single call covers both “add the item” and “set the memo”.
to value | Destination |
|---|---|
watching | Currently watching. (For movies, automatically becomes completed since movies are atomic.) |
plantowatch | Plan to watch. |
hold | On hold. |
dropped | Dropped. |
completed | Completed. |
to is per-item (each entry in the array carries its own destination). The legacy top-level to shape is not accepted — the server returns 400 empty_field (Missed "to" parameter) when to only appears at the top level.
You don’t need a Simkl ID. The server resolves any combination of identifiers via its internal Search — pass whatever IDs your app already has and skip the /redirect lookup step. Identifier slots accepted on each item:
| Slot | Notes |
|---|---|
ids.simkl | Simkl internal ID. Always wins when present. |
ids.imdb | IMDb ID (e.g. tt1375666). Works for movies and shows. |
ids.tmdb | TMDB ID. Works for movies and shows. |
ids.tvdb | TVDB ID. Most-used canonical for TV in media-server stacks (Plex, Sonarr, Jellyfin, Kodi). |
ids.mal / ids.anidb / ids.anilist / ids.kitsu | Anime catalogs. Send any/all you have. |
ids.slug | URL slug — useful when you only have a Simkl-shaped link. |
title + year (no ids at all) | Text fallback. Fuzzy match; ambiguous titles may miss — inspect not_found in the response. |
Send everything you have. The server picks the first identifier that resolves and accepts the extras. This is the canonical shape for migrations from another tracker (Trakt → Simkl, IMDb-list import, Letterboxd export, etc.) — just forward whatever the source carried.
{
"movies": [
{
"to": "completed",
"title": "Inception",
"year": 2010,
"ids": {
"simkl": 472214,
"imdb": "tt1375666",
"tmdb": "27205"
}
}
],
"shows": [
{
"to": "watching",
"title": "Game of Thrones",
"year": 2011,
"ids": {
"simkl": 17465,
"slug": "game-of-thrones",
"imdb": "tt0944947",
"tmdb": "1399",
"tvdb": "121361"
}
}
]
}
Optional per-item fields: watched_at, added_at.
To remove an item, use POST /sync/history/remove. This endpoint operates on the Watchlist (the five statuses above); the canonical un-track / delete-from-list path is /sync/history/remove, which writes to the same backing store and returns the same kind of result envelope. A legacy to: "remove" value is accepted by this endpoint for backwards compatibility, but it is undocumented and should not be used in new integrations — Simkl reserves the right to change its behavior without notice.
Response: added and not_found
The response always returns 201 (even on partial failures) with two arrays per media-type:
{
"added": {
"movies": [{ "to": "completed", "ids": {...}, "type": "movie" }],
"shows": [{ "to": "watching", "ids": {...}, "type": "show" }]
},
"not_found": {
"movies": [{ "title": "Definitely Not A Real Movie", "year": 9999 }],
"shows": []
}
}
Items the server’s resolver matched land in added. Items it couldn’t match (typos, fuzzy title misses, IDs not in Simkl’s catalog yet) land in not_found — verbatim copies of the input so you can show “we couldn’t add: …” in your UI. Always inspect both arrays after a bulk call.
Errors: 400 empty_field if to is missing on an item; 400 wrong_parameter if to is not one of the values above.
Silent to rewrites
The server may downgrade your requested to value when an item isn’t in a state where that status applies:
- Movies with
to: "watching"→ silently rewritten tocompleted(movies are atomic; you can’t “be watching” a movie). - Shows that aren’t ready for
completed(still airing, or pre-release) get rewritten towatchingorplantowatchrespectively, depending on whether any episode has aired.
The rewrites happen server-side; the consumer just sees the actual stored value in added.<type>[i].to. There is no error code surfaced for the rewrite — the only way to detect it is to compare the value you sent against the value that came back.
Note: this endpoint operates on the Simkl Watchlist (the five canonical statuses above). Custom user-created lists will get their own API in a future release.
Sync guide — full walkthrough
Two-phase model (initial pull → activities-checked delta loop), date_from semantics, deletion reconciliation, edge cases, and reference implementations in Node and Python.
Anime titles: can go in either the anime[] array OR the shows[] array — both are accepted. The server normalizes anime into the response’s shows array with "type": "show" per-item, since anime are TV-like in the cross-catalog data model. AniDB-specific IDs (mal, anidb, anilist, kitsu) belong inside each item’s ids object regardless of which array it lives in. See Anime under shows[].
Which IDs can I send/expect? All accepted input identifiers and the keys you’ll see echoed back in responses are listed at Standard media objects → Supported ID keys. Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: slug is response-only (never send it on a request).
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.
Authorizations
Preferred form: your client_id as a URL query parameter on every request. Self-describing in logs and curl commands. See Headers and required parameters.
OAuth 2.0 or PIN-flow access_token. Required for endpoints that read or modify the user's library, scrobble session, ratings, settings, or playbacks. See Authentication.
Headers
Descriptive identifier for your app, ideally name/version. Examples: PlexMediaServer/1.43.1.10540, kodi-simkl/0.9.2, MyApp/2.4.1 (https://myapp.com).
Query Parameters
Your client_id from your Simkl developer settings. Required on every request.
Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.
Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.
Body
Body for POST /sync/add-to-list. Moves items into one of the user's Watchlist statuses. Items go under movies[], shows[], or anime[] — Simkl resolves anime titles correctly under either shows[] or anime[], so match the field to your data type when known.
User watchlist status. Movies skip watching and hold — see /conventions/list-statuses.
watching, plantowatch, hold, completed, dropped Hide child attributes
Hide child attributes
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
"Terminator 3: Rise of the Machines"
2003
Hide child attributes
Hide child attributes
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
"The Walking Dead"
2010
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
x >= 01
x >= 12
ISO-8601 GMT timestamp.
"2014-09-01T09:10:11Z"
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
Array of anime entries (same shape as shows[]).
Hide child attributes
Hide child attributes
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
"The Walking Dead"
2010
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
x >= 01
x >= 12
ISO-8601 GMT timestamp.
"2014-09-01T09:10:11Z"
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
Response
OK
Response from POST /sync/add-to-list.
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
"The Walking Dead"
2010
User watchlist status. Movies skip watching and hold — see /conventions/list-statuses.
watching, plantowatch, hold, completed, dropped Echoed IDs from the request.
Hide child attributes
Hide child attributes
"The Walking Dead"
2010
User watchlist status. Movies skip watching and hold — see /conventions/list-statuses.
watching, plantowatch, hold, completed, dropped Echoed IDs from the request.
Hide child attributes
Hide child attributes
"The Walking Dead"
2010
User watchlist status. Movies skip watching and hold — see /conventions/list-statuses.
watching, plantowatch, hold, completed, dropped Echoed IDs from the request.
Items Simkl could not match. Inspect this to surface diagnostics back to your users. Anime entries that fail to resolve land in shows regardless of which top-level array they were sent under — there is no separate anime bucket in not_found.
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
"Terminator 3: Rise of the Machines"
2003
Hide child attributes
Hide child attributes
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
"The Walking Dead"
2010
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
x >= 01
x >= 12
ISO-8601 GMT timestamp.
"2014-09-01T09:10:11Z"
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
Hide child attributes
Hide child attributes
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
"The Walking Dead"
2010
Hide child attributes
Hide child attributes
Hide child attributes
Hide child attributes
x >= 01
x >= 12
ISO-8601 GMT timestamp.
"2014-09-01T09:10:11Z"
External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.
Hide child attributes
Hide child attributes
Simkl internal ID. Most reliable.
53536
URL-safe slug returned in responses.
"attack-on-titan"
IMDb ID.
"tt0181852"
TMDb ID.
"296"
TVDB ID or slug.
153021
MyAnimeList ID.
"4246"
AniDB ID. Specifying just this is enough for anime lookups.
"10846"
AniList ID.
"21"
Kitsu ID.
"12"
aniSearch ID.
"2227"
Anime-Planet slug.
"one-piece"
LiveChart ID.
"321"
Letterboxd slug.
"the-truman-show"
Netflix movie ID.
"70210890"
Hulu episode ID.
Crunchyroll episode ID.
Trakt slug.
"john-wick-chapter-4-2023"
{
"simkl": 53536,
"imdb": "tt0181852",
"tmdb": 296
}
Was this page helpful?