Whether this server holds a usable Simkl token, without revealing it.

Delete the stored Simkl token from this machine.

This does not revoke the app on Simkl's side -- do that at simkl.com/settings/apps.

Timestamps of the user's most recent list changes.

The cheapest call in the API and the gate for every sync: if all has not moved since the last recorded value, nothing needs fetching.

Read the watch history and watchlists.

type: shows, movies or anime. Omit for all three in one call. status: watching, plantowatch, hold, completed or dropped. Omit for all. date_from: an ISO timestamp from get_activities, passed back byte-for-byte. With it you get only what changed since; without it, the full library.

Deletions never appear in a delta. When activities' removed_from_list moves, call get_library_ids and diff instead.

Returns normalized items plus skipped, the number of entries that carried no Simkl ID. A non-zero skipped is a hole in the exclusion guarantee and must be reported to the user, not hidden.

Every Simkl ID in the library, and nothing else.

The cheap half of deletion reconciliation: IDs present locally but absent here have been removed from Simkl, and any rating stored for them is gone too (Simkl wipes the rating on removal).

Ask Simkl directly whether specific titles are already in the library.

items: a list like [{"simkl": 54130}, {"imdb": "tt0110912"}] -- any mix of supported ID keys. Simkl returns a parallel array with each item's library status and last-watched time.

This is the server-side check behind re-com-video's "never already seen" guarantee. It is independent of the local mirror, so it catches anything watched since the last sync.

The titles the user has rated themselves.

type: movies, shows or anime. rating: 1-10, or omit for every rating. Ratings 8-10 are the strong positive seeds for "what should I watch tonight"; 1-4 are the negative signal (PLAN.md 5.1).

Full detail record for one title, including its viewer-based neighbours.

type: movie, tv or anime -- Simkl's own classification, which can change for a given title; follow it rather than assuming.

The record carries users_recommendations: titles suggested from what this title's viewers also watched. That is the viewer signal re-com-video ranks on, and the count varies enormously by title.

Turn an external ID into a Simkl ID -- the cheapest way in.

A TMDB ID needs type ('movie' or 'show'): TMDB IDs are not unique across movies and TV, so a bare TMDB ID is ambiguous and is refused here.

Reads the 301's Location header without following it, as Simkl requires.

Search Simkl by title.

type: movie, tv or anime. Omit to search everything.

Titles collide constantly -- "The Bear" is seven distinct works. Treat every result as a candidate to disambiguate by year and type, never as the answer. Prefer resolve_id whenever an external ID is available.

Record that the user watched these titles.

items: [{"ids": {"simkl": 54130}}, ...]. Add "watched_at" (ISO, UTC) if the date is known; omit it for "now". For "a long time ago, don't remember", Simkl's placeholder is 1970-01-01T00:00:01Z -- store that, and never display it as a literal 1970 date.

type: movie, tv or anime. Anime goes in the shows[] envelope.

Simkl serialises sync writes per user behind a 20-second lock, so batch rather than sending one call per title.

Move titles into a watchlist status.

status: watching, plantowatch, hold, completed or dropped.

Two behaviours worth knowing: movies have no watching or hold, and writing completed for a still-airing show silently becomes watching.

Rate titles 1-10.

Rating something that is on no list auto-files it: a released movie becomes completed, an unreleased one plan-to-watch, a single-episode show completed, anything else watching. That move is intended -- read the next delta as authoritative rather than trying to predict it.

Remove titles from the watch history.

Removing an item also wipes its Simkl rating. Anything removed here stops being excluded from recommendations, which is usually the point.