Add to History

Record watch events. The unit is the watch event — adding “I watched The Walking Dead S01E01 at 8pm” — not list membership (use POST /sync/add-to-list for that, or set status per-item here to do both at once).

Granularity — when does the server expand “implicit all”?

The body shape determines whether you mark a single episode, a season, or a whole show.

One movie — single movie completion.

{ "movies": [{ "ids": {...} }] }

Whole show — every episode marked. “I finished this whole series.” Send status: "completed" with no seasons / episodes.

{ "shows": [{ "ids": {...}, "status": "completed" }] }

Whole season — every episode of one season. “I finished season 2.” Send seasons[] without an inner episodes.

{ "shows": [{ "ids": {...}, "seasons": [{ "number": 2 }] }] }

Specific episodes only — per-event scrobbling, manual tick-off.

{
 "shows": [{
 "ids": {...},
 "seasons": [{
 "number": 1,
 "episodes": [{ "number": 1 }, { "number": 2 }]
 }]
 }]
}

Top-level episodes[] shorthand — auto-wraps to seasons: [{ number: 1,... }]. Useful for anime sequential numbering and single-season shows.

{ "shows": [{ "ids": {...}, "episodes": [{ "number": 1 }] }] }

The response always reports the actual count of episodes affected in added.episodes, so apps can verify the server expanded correctly.

Memo-only updates (and “add to watchlist + memo” in one call)

This endpoint is the only way to set a memo on an item. POST /sync/add-to-list accepts the memo field in the request body and echoes it back in the response, but does not persist it — silently discarded.

To set or update a memo without recording a watch event, send ids + status + memo:

{
 "movies": [{
 "ids": { "simkl": 53536 },
 "status": "plantowatch",
 "memo": { "text": "Remind me why I added this", "is_private": true }
 }]
}

Two behaviors worth knowing:

• Memos attach to watchlist items only. The item has to be in one of the five statuses (watching / plantowatch / hold / dropped / completed) for the memo to stick. Sending status makes this explicit.
• The endpoint auto-adds items. If the item isn’t on the user’s watchlist yet, this same call creates the watchlist row at the specified status AND saves the memo in one shot. added.movies / added.shows reports the count of newly-added items (0 when the item was already there and you only changed memo/status).

To read memos back, call GET /sync/all-items?memos=yes — see the Sync guide.

Per-item options

Rewatches

Re-posting an already-watched episode is a no-op by default — the server detects the duplicate and skips. To insert a rewatch session, send ?allow_rewatch=yes as a query parameter. The server then creates a separate rewatch row that doesn’t double-count the original watch.

Simkl PRO / VIP only. Free-tier callers with ?allow_rewatch=yes get a silent no-op (added: { movies: 0, shows: 0, episodes: 0 }) that still consumes a rate-limit slot. Check account.type from GET /users/settings at sign-in and gate the flag on "pro" / "vip". Cache the value; refetch only when activities.settings.all from GET /sync/activities bumps. Full pattern in Rewatches guide → PRO / VIP gate.

For backup/restore tools that always want to insert (even when the auto-detect heuristic can’t fire), set is_rewatch: true per-item AND pass the query param.

Response: added and not_found

{
 "added": {
 "movies": <int count>,
 "shows": <int count>,
 "episodes": <int count>,
 "statuses": [
 {
 "request": { /* echo of input item, with type added */ },
 "response": {
 "status": "completed",
 "simkl_type": "tv" | "anime" | "movie",
 "anime_type": "tv" | "movie" | "ova" | null
 }
 }
 ]
 },
 "not_found": {
 "movies": [...],
 "shows": [...],
 "episodes": [...]
 }
}

added.statuses[*].response.status is the resolved Watchlist status the server placed the item on — e.g. a "completed" write on a still-airing show is silently downgraded to "watching" and reflected here. You don’t need a follow-up POST /sync/add-to-list — this call already moves the item; chaining would just overwrite the server’s smarter decision.

added.statuses[*].response.simkl_type tells you which catalog the item resolved to (useful when you sent ambiguous IDs — TMDB IDs can be either movie or tv on Simkl). Always inspect to know what got created.

not_found carries the verbatim input for items the resolver couldn’t match (typo, fuzzy-title miss, ID not in Simkl’s catalog yet). Apps should:

• Show “we couldn’t track: …” UI for these
• Offer manual ID-entry fallback
• Don’t infer success from the 201 status alone — branch on not_found.movies.length === 0 && not_found.shows.length === 0 && not_found.episodes.length === 0

Errors

400 empty_field if a per-item required field is missing. 400 wrong_parameter for invalid enum values. Empty body {} returns 201 with zero counts (NOT 400) — that’s a known asymmetry vs /scrobble/start which 400s on empty body.

When to use /sync/history vs /sync/add-to-list