curl --request POST \
  --url 'https://api.simkl.com/sync/history/remove?client_id=' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --data '{}'

{
  "deleted": {
    "movies": 1,
    "shows": 0,
    "episodes": 0
  },
  "not_found": {
    "movies": [],
    "shows": []
  }
}

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

POST

sync

history

remove

curl --request POST \
  --url 'https://api.simkl.com/sync/history/remove?client_id=' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: <user-agent>' \
  --data '{}'

{
  "deleted": {
    "movies": 1,
    "shows": 0,
    "episodes": 0
  },
  "not_found": {
    "movies": [],
    "shows": []
  }
}

Authorizations

client_id

string

query

default:YOUR_CLIENT_ID

required

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.

Authorization

string

header

default:YOUR_ACCESS_TOKEN

required

A user access_token, sent as Authorization: Bearer .... Required for endpoints that read or modify the user's library, scrobble session, ratings, settings, or playbacks. Every flow returns the same kind of token. See Set up authentication.

Headers

User-Agent

string

required

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

client_id

string

required

Your client_id from your Simkl developer settings. Required on every request.

app-name

string

required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

app-version

string

required

Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.

Body

application/json

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.

movies

object[]

Hide child attributes

movies.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

movies.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

movies.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

movies.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

movies.ids.tmdb

string

TMDb ID.

Example:

"296"

movies.ids.tvdb

string

TVDB ID or slug.

Example:

"153021"

movies.ids.mal

string

MyAnimeList ID.

Example:

"4246"

movies.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

movies.ids.anilist

string

AniList ID.

Example:

"21"

movies.ids.kitsu

string

Kitsu ID.

Example:

"12"

movies.ids.anisearch

string

aniSearch ID.

Example:

"2227"

movies.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

movies.ids.livechart

string

LiveChart ID.

Example:

"321"

movies.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

movies.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

movies.ids.hulu

string

Hulu episode ID.

movies.ids.crunchyroll

string

Crunchyroll episode ID.

movies.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": "296"
}

movies.title

string

Example:

"Terminator 3: Rise of the Machines"

movies.year

integer

Example:

2003

shows

object[]

Hide child attributes

shows.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

shows.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

shows.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

shows.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

shows.ids.tmdb

string

TMDb ID.

Example:

"296"

shows.ids.tvdb

string

TVDB ID or slug.

Example:

"153021"

shows.ids.mal

string

MyAnimeList ID.

Example:

"4246"

shows.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

shows.ids.anilist

string

AniList ID.

Example:

"21"

shows.ids.kitsu

string

Kitsu ID.

Example:

"12"

shows.ids.anisearch

string

aniSearch ID.

Example:

"2227"

shows.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

shows.ids.livechart

string

LiveChart ID.

Example:

"321"

shows.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

shows.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

shows.ids.hulu

string

Hulu episode ID.

shows.ids.crunchyroll

string

Crunchyroll episode ID.

shows.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": "296"
}

shows.title

string

Example:

"The Walking Dead"

shows.year

integer

Example:

2010

shows.seasons

object[]

Hide child attributes

shows.seasons.number

integer

shows.seasons.episodes

object[]

Hide child attributes

shows.seasons.episodes.season

integer

Required range: x >= 0

Example:

1

shows.seasons.episodes.number

integer

Required range: x >= 1

Example:

2

shows.seasons.episodes.watched_at

string<date-time>

ISO-8601 GMT timestamp.

Example:

"2014-09-01T09:10:11Z"

shows.seasons.episodes.ids

object

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

shows.seasons.episodes.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

shows.seasons.episodes.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

shows.seasons.episodes.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

shows.seasons.episodes.ids.tmdb

string

TMDb ID.

Example:

"296"

shows.seasons.episodes.ids.tvdb

string

TVDB ID or slug.

Example:

"153021"

shows.seasons.episodes.ids.mal

string

MyAnimeList ID.

Example:

"4246"

shows.seasons.episodes.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

shows.seasons.episodes.ids.anilist

string

AniList ID.

Example:

"21"

shows.seasons.episodes.ids.kitsu

string

Kitsu ID.

Example:

"12"

shows.seasons.episodes.ids.anisearch

string

aniSearch ID.

Example:

"2227"

shows.seasons.episodes.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

shows.seasons.episodes.ids.livechart

string

LiveChart ID.

Example:

"321"

shows.seasons.episodes.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

shows.seasons.episodes.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

shows.seasons.episodes.ids.hulu

string

Hulu episode ID.

shows.seasons.episodes.ids.crunchyroll

string

Crunchyroll episode ID.

shows.seasons.episodes.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": "296"
}

episodes

object[]

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.

anime

object[]

Array of anime entries (same shape as shows[]).

Hide child attributes

anime.ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

anime.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

anime.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

anime.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

anime.ids.tmdb

string

TMDb ID.

Example:

"296"

anime.ids.tvdb

string

TVDB ID or slug.

Example:

"153021"

anime.ids.mal

string

MyAnimeList ID.

Example:

"4246"

anime.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

anime.ids.anilist

string

AniList ID.

Example:

"21"

anime.ids.kitsu

string

Kitsu ID.

Example:

"12"

anime.ids.anisearch

string

aniSearch ID.

Example:

"2227"

anime.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

anime.ids.livechart

string

LiveChart ID.

Example:

"321"

anime.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

anime.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

anime.ids.hulu

string

Hulu episode ID.

anime.ids.crunchyroll

string

Crunchyroll episode ID.

anime.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": "296"
}

anime.title

string

Example:

"The Walking Dead"

anime.year

integer

Example:

2010

anime.seasons

object[]

Hide child attributes

anime.seasons.number

integer

anime.seasons.episodes

object[]

Hide child attributes

anime.seasons.episodes.season

integer

Required range: x >= 0

Example:

1

anime.seasons.episodes.number

integer

Required range: x >= 1

Example:

2

anime.seasons.episodes.watched_at

string<date-time>

ISO-8601 GMT timestamp.

Example:

"2014-09-01T09:10:11Z"

anime.seasons.episodes.ids

object

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

anime.seasons.episodes.ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

anime.seasons.episodes.ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

anime.seasons.episodes.ids.imdb

string

IMDb ID.

Example:

"tt0181852"

anime.seasons.episodes.ids.tmdb

string

TMDb ID.

Example:

"296"

anime.seasons.episodes.ids.tvdb

string

TVDB ID or slug.

Example:

"153021"

anime.seasons.episodes.ids.mal

string

MyAnimeList ID.

Example:

"4246"

anime.seasons.episodes.ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

anime.seasons.episodes.ids.anilist

string

AniList ID.

Example:

"21"

anime.seasons.episodes.ids.kitsu

string

Kitsu ID.

Example:

"12"

anime.seasons.episodes.ids.anisearch

string

aniSearch ID.

Example:

"2227"

anime.seasons.episodes.ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

anime.seasons.episodes.ids.livechart

string

LiveChart ID.

Example:

"321"

anime.seasons.episodes.ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

anime.seasons.episodes.ids.netflix

string

Netflix movie ID.

Example:

"70210890"

anime.seasons.episodes.ids.hulu

string

Hulu episode ID.

anime.seasons.episodes.ids.crunchyroll

string

Crunchyroll episode ID.

anime.seasons.episodes.ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "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.

deleted

object

required

Hide child attributes

deleted.movies

integer

required

Number of movies removed from the user's library.

Example:

1

deleted.shows

integer

required

Number of shows removed from the user's library entirely (only counts items where you sent the show without seasons/episodes).

Example:

0

deleted.episodes

integer

required

Number of individual episodes unmarked as watched. The parent show stays in the user's library.

Example:

4

not_found

object

required

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.

Hide child attributes

not_found.movies

object[]

required

Input movie objects Simkl could not match.

not_found.shows

object[]

required

Input show/anime objects Simkl could not match.

⌘I

API Reference

Trending

Calendar

Redirect

Auth

Scrobble

Playback

Sync

Custom Lists

Search

TV

Anime

Movies

Ratings

Users

Changes

Remove from History

Granularity

Response shape

POST /sync/history

Sync guide — full walkthrough

Authorizations

Headers

Query Parameters

Body

Response