API Reference
Trending
Calendar
Redirect
Sync
Changes
Remove from History
Removes items from the user’s watched history. Body shape is identical to POST /sync/history — the same movies[], shows[], and granularity rules apply.
Granularity
What you send determines what gets removed.
Movie or show with no seasons and no episodes — the item is removed from the user’s library entirely (any watch history AND the watchlist entry). Equivalent to the user clicking “Remove from list” on the title page.
{ "shows": [{ "ids": {...} }] }
Show with seasons[] entries that omit episodes — every episode in those seasons is unmarked as watched. The show stays in the user’s library.
{ "shows": [{ "ids": {...}, "seasons": [{ "number": 2 }] }] }
Show with seasons[].episodes[] — only the listed episodes are unmarked. The show stays in the user’s library.
{
"shows": [{
"ids": {...},
"seasons": [{
"number": 1,
"episodes": [{ "number": 1 }, { "number": 2 }]
}]
}]
}
Show with top-level episodes[] shorthand — treated as seasons: [{ number: 1, episodes: [...] }]. Convenient for single-season shows; otherwise prefer the explicit form.
{ "shows": [{ "ids": {...}, "episodes": [{ "number": 1 }] }] }
Response shape
Status: 201 Created.
{
"deleted": {
"movies": <number of movies removed>,
"shows": <number of shows removed from library>,
"episodes": <number of episodes unmarked>
},
"not_found": {
"movies": [<items Simkl could not match>],
"shows": [<items Simkl could not match>]
}
}
not_found only has movies and shows — there’s no not_found.episodes array even when you tried to remove specific episodes. If the parent show isn’t matchable, the show object lands in not_found.shows and no episodes are touched. If the show is matchable but a specific episode number doesn’t exist, the call still counts as success and episodes in deleted reflects only the episodes that were actually unmarked.
Anime titles go in shows[] (with anime-only IDs like anidb / mal / anilist inside each item’s ids object). There is no top-level anime[] array on this endpoint — items sent under one are silently ignored. See Anime under shows[].
POST /sync/history
The mirror endpoint that adds history. Same body shape; this page is the removal side.
Sync guide — full walkthrough
Two-phase model (initial pull → activities-checked delta loop), deletion reconciliation, and reference implementations.
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 /sync/history and /sync/history/remove. 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.
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
}
Top-level convenience array for marking episode-level history without nesting. The server wraps each entry into a synthetic single-season show. Each item carries the same shape as items under shows[].seasons[].episodes[] plus the parent show reference.
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
Counts of items affected, plus any IDs Simkl could not match.
Counts of items removed plus any IDs Simkl could not match.
Hide child attributes
Hide child attributes
Number of movies removed from the user's library.
1
Number of shows removed from the user's library entirely (only counts items where you sent the show without seasons/episodes).
0
Number of individual episodes unmarked as watched. The parent show stays in the user's library.
4
Per-type lists of input items Simkl could not match. There is no not_found.episodes array — even when you targeted specific episodes, only the parent movie/show object lands here if the lookup failed.
Was this page helpful?