> ## 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. # Get all items of one type in one status bucket > > ## ⚠️ For continuous sync, do NOT call `/sync/all-items` on a timer > > The correct loop, every time you want to check for changes: > > 1. **Call [`GET /sync/activities`](/api-reference/simkl/get-activities) first.** It returns a tiny JSON of `last-modified` timestamps per category — costs almost nothing. > 2. **Compare those timestamps to the ones you saved on your last sync.** If nothing changed, stop here. Do **not** call `/sync/all-items`. > 3. **Only if a timestamp changed**, call `/sync/all-items?date_from=`. The `date_from` makes the server return only the small delta of items that actually changed, not the user's entire library. > > Polling `/sync/all-items` directly on a timer (without checking `/sync/activities` and without `date_from`) downloads the user's whole library every call. It overloads the API server and hurts every other client. > > **Apps that do this will have their `client_id` suspended.** No warning, no appeal — we see the traffic pattern and turn the key off. > > Read the [**Sync guide**](/guides/sync) end-to-end before shipping anything that calls this endpoint. The full two-phase model (initial full sync → activities-checked delta loop) is documented there with reference implementations in Node and Python. The two-phase model (initial pull → activities-checked delta loop), `date_from` semantics, deletion reconciliation, edge cases, and reference implementations in Node and Python. **Required reading** before shipping anything that polls this endpoint. Session lifecycle (`active` / `completed` / `closed`), per-item rewatch fields, episode-level tracking, flag combinations for reading sessions back, and ready-made code for the UI patterns simkl.com uses on every detail page. Required if you set `?allow_rewatch=yes`. The single endpoint that powers watchlist reads. Both `{type}` and `{status}` are optional path segments, and any combination is valid: | Path | Returns | | --- | --- | | `/sync/all-items` | Every type, every status. The full library. | | `/sync/all-items/{type}` | A single type (`shows`, `movies`, or `anime`), every status. | | `/sync/all-items/{type}/{status}` | One type, one status bucket. | The response shape is the same across all three forms: a top-level object keyed by `shows`, `movies`, and `anime`. Filtered calls just include fewer top-level keys; an empty result returns `{}`. See [Per-endpoint shape matrix](/conventions/null-values#per-endpoint-shape-matrix). Pair this endpoint with [`GET /sync/activities`](/api-reference/simkl/get-activities) and the `date_from` query parameter for incremental sync — see the [Sync guide](/guides/sync) for the two-phase model. **Watchlist statuses by type:** | Type | `watching` | `plantowatch` | `hold` | `dropped` | `completed` | |------|:-:|:-:|:-:|:-:|:-:| | `shows` | ✅ | ✅ | ✅ | ✅ | ✅ | | `anime` | ✅ | ✅ | ✅ | ✅ | ✅ | | `movies` | — | ✅ | — | ✅ | ✅ | Movies skip `watching` and `hold` — see [Watchlist statuses](/conventions/list-statuses). #### Useful query parameters A quick map of the params below — see each parameter's full schema later on this page. | Param | What it does | |---|---| | `date_from` | Required on every continuous-sync call. Returns only items modified since this ISO-8601 timestamp. | | `extended=simkl_ids_only` / `=ids_only` / `=full` / `=full_anime_seasons` | Controls response richness — from just `ids.simkl` (smallest) to full metadata + per-episode breakdowns. Pair `=full` and `=full_anime_seasons` with `date_from` — they're significantly larger payloads. | | `include_all_episodes=yes` / `=original` | Loads canonical `seasons[].episodes[]` for items in `completed` and `dropped` (which skip episode load by default). `yes` synthesizes virtual episode rows where per-episode data is missing; `original` returns real rows only. | | `episode_watched_at=yes` | Adds per-episode `watched_at` timestamps to every episode that's been loaded. Modifier — episodes must already be loaded by `extended=full` or `include_all_episodes=yes`. | | `episode_tvdb_id=yes` | Adds `ids.tvdb_id` per episode. | | `next_watch_info=yes` | On `watching` items with a next episode, attaches `next_to_watch_info` (`title`, `season`, `episode`, `date`). | | `memos=yes` | Includes the user's per-item `memo` object (`text` capped at 140 chars). | | `anime_type` | Filter anime entries by anime type (`tv`, `movie`, `ova`, `ona`, `special`, `music video`). | | `language=en` | Force English titles instead of the user's profile language. | | `allow_rewatch=yes` | Synthesize one extra entry per rewatch session alongside the canonical row. **Simkl Pro / VIP only** — gate the flag on `account.type` from [`POST /users/settings`](/api-reference/simkl/get-user-settings) (cache it; refetch only when `activities.settings.all` bumps — see [Rewatches guide → Pro / VIP gate](/guides/rewatches)). Free-tier callers get a silent no-op that still consumes a rate-limit slot. See the [Rewatches guide](/guides/rewatches) for the full pattern. | **Rewatches** (Simkl Pro / VIP). Without the flag, each item — movie, show, or anime — appears once in the response, reflecting the user's current watch state. Set `?allow_rewatch=yes` and any item with saved rewatch sessions appears multiple times: the normal entry, plus one extra entry per rewatch session. The extra entries carry `is_rewatch: true`, `rewatch_id`, `rewatch_status` (`active` / `completed` / `closed`), `last_watched_at`, and `watched_episodes_count`, so you can tell them apart from the main entry and from each other. **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**](/conventions/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). ## OpenAPI ````yaml /openapi.json get /sync/all-items/{type}/{status} openapi: 3.1.0 info: title: Simkl API version: 1.0.0 description: >- The **Simkl API** lets you build apps that track Movies, TV Shows, and Anime — scrobble playback, sync watch history, and pull rich metadata. All requests use HTTPS and return JSON. The base URL is `https://api.simkl.com`. **Every request needs three URL parameters and a `User-Agent` header:** ``` /endpoint?client_id=YOUR_CLIENT_ID&app-name=my-app&app-version=1.0 ``` See [Headers and required parameters](/conventions/headers) for the full reference. Endpoints that read or modify a user's data also need an `Authorization: Bearer ` header — see [OAuth 2.0](/api-reference/oauth) or the [PIN flow](/api-reference/pin). > ⚠️ **About the auto-rendered cURL examples on each endpoint page:** they omit `?client_id=…&app-name=…&app-version=…` from the URL for brevity. **You must add them yourself when copy-pasting**, or use the interactive **"Try it"** playground (it fills them in for you). This is a Mintlify rendering convention — every Mintlify-built API doc behaves the same way. **Get started** - [Quickstart](/quickstart) — first request in 60 seconds - [API rules](/api-rules) — what's allowed, what isn't - [Standard media objects](/conventions/standard-media-objects) — the shapes every endpoint speaks - [Errors](/conventions/errors) — every status code Simkl returns contact: name: Simkl Developer Support url: https://support.simkl.com termsOfService: https://simkl.com/about/policies/terms/ license: name: Simkl API Terms of Use url: https://simkl.com/about/policies/terms/ x-logo: url: https://i.simkl.com/img_tv/apiary_logo_api.png backgroundColor: '#0E5DAB' altText: Simkl servers: - url: https://api.simkl.com description: Production API - url: https://data.simkl.in description: CDN for static, public data files (Calendar + Trending). No auth required. security: - clientId: [] - simklApiKey: [] tags: - name: OAuth 2.0 description: >- OAuth 2.0 authorization-code flow for web and mobile apps. The user is redirected to Simkl, signs in, approves your app, and is redirected back with a `code` you exchange for an `access_token`. Long-lived tokens — no refresh-token flow needed. externalDocs: description: OAuth 2.0 walkthrough url: https://api.simkl.org/api-reference/oauth - name: PIN description: >- Device flow for TVs, consoles, smart watches, CLI tools — anywhere typing a URL is hard. Show a 5-character code; user enters it on simkl.com/pin; you poll for the access token. **No `client_secret` required.** externalDocs: description: PIN flow walkthrough url: https://api.simkl.org/api-reference/pin - name: Redirect description: >- Helper redirects for one-click "mark as watched", trailers, sharing, and more. - name: Search description: Find shows, movies, and anime by ID, text query, file name, or randomly. externalDocs: description: Search guide url: https://api.simkl.org/guides/search - name: Movies description: >- Browse the Simkl movies catalog: details, premieres, top-of-best, and genre filters. - name: TV description: >- Browse the Simkl TV catalog: details, episodes, what's airing, premieres, top-of-best, and genre filters. - name: Anime description: >- Browse the Simkl anime catalog: details, episodes, what's airing, premieres, top-of-best, and genre filters. - name: Ratings description: >- Read Simkl's average community rating, rank, drop rate, and external ratings (IMDB, MAL) for any item, or for every item in a user's lists. - name: Scrobble description: >- Report real-time playback to Simkl with `start`, `pause`, and `stop`. At ≥ 80 % progress Simkl marks the item as watched automatically; below 80 % the session is saved as a paused playback the user can resume from any device. See [Standard media objects](/conventions/standard-media-objects) for the supported ID keys. ### Supported ID keys Inside any `ids` object, pass as many of these as you have. Simkl resolves to the canonical record. | ID key | Type | Example | |---|---|---| | `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. | | `imdb` | string | `tt1520211` | | `tmdb` | integer | `76757` (for TV, specify `type`) | | `tvdb` | int / string | `153021` or `the-walking-dead` | | `mal` | integer | `4246` (MyAnimeList) | | `anidb` | integer | `10846`. Specifying just this is enough for anime lookups. | | `anilist` | integer | `21` | | `kitsu` | integer | `12` | | `anisearch` | integer | `2227` | | `animeplanet` | string | `one-piece` | | `livechart` | integer | `321` | | `letterboxd` | string | `the-truman-show` | | `netflix` | integer | `70210890` (movie ID) | | `traktslug` | string | `john-wick-chapter-4-2023` | > 📖 Full reference: [Standard media objects](/conventions/standard-media-objects) externalDocs: description: Scrobble guide url: https://api.simkl.org/guides/scrobble - name: Sync description: >- Use Simkl as a cloud backup for the user's watch history and lists (Watching, Plan to Watch, On Hold, Dropped, Completed). **Always check [`/sync/activities`](/api-reference/simkl/get-activities) first** and sync only the lists that have moved. All write endpoints accept arrays — batch aggressively. See [Standard media objects](/conventions/standard-media-objects) for the supported ID keys. ### Supported ID keys Inside any `ids` object, pass as many of these as you have. Simkl resolves to the canonical record. | ID key | Type | Example | |---|---|---| | `simkl` | integer | `49108`. Simkl's canonical ID. Most reliable. | | `imdb` | string | `tt1520211` | | `tmdb` | integer | `76757` (for TV, specify `type`) | | `tvdb` | int / string | `153021` or `the-walking-dead` | | `mal` | integer | `4246` (MyAnimeList) | | `anidb` | integer | `10846`. Specifying just this is enough for anime lookups. | | `anilist` | integer | `21` | | `kitsu` | integer | `12` | | `anisearch` | integer | `2227` | | `animeplanet` | string | `one-piece` | | `livechart` | integer | `321` | | `letterboxd` | string | `the-truman-show` | | `netflix` | integer | `70210890` (movie ID) | | `traktslug` | string | `john-wick-chapter-4-2023` | > 📖 Full reference: [Standard media objects](/conventions/standard-media-objects) externalDocs: description: Sync guide url: https://api.simkl.org/guides/sync - name: Users description: User profile, settings, and watch statistics. externalDocs: description: Simkl API documentation url: https://api.simkl.org paths: /sync/all-items/{type}/{status}: get: tags: - Sync summary: Get all items of one type in one status bucket description: >- > ## ⚠️ For continuous sync, do NOT call `/sync/all-items` on a timer > > The correct loop, every time you want to check for changes: > > 1. **Call [`GET /sync/activities`](/api-reference/simkl/get-activities) first.** It returns a tiny JSON of `last-modified` timestamps per category — costs almost nothing. > 2. **Compare those timestamps to the ones you saved on your last sync.** If nothing changed, stop here. Do **not** call `/sync/all-items`. > 3. **Only if a timestamp changed**, call `/sync/all-items?date_from=`. The `date_from` makes the server return only the small delta of items that actually changed, not the user's entire library. > > Polling `/sync/all-items` directly on a timer (without checking `/sync/activities` and without `date_from`) downloads the user's whole library every call. It overloads the API server and hurts every other client. > > **Apps that do this will have their `client_id` suspended.** No warning, no appeal — we see the traffic pattern and turn the key off. > > Read the [**Sync guide**](/guides/sync) end-to-end before shipping anything that calls this endpoint. The full two-phase model (initial full sync → activities-checked delta loop) is documented there with reference implementations in Node and Python. The two-phase model (initial pull → activities-checked delta loop), `date_from` semantics, deletion reconciliation, edge cases, and reference implementations in Node and Python. **Required reading** before shipping anything that polls this endpoint. Session lifecycle (`active` / `completed` / `closed`), per-item rewatch fields, episode-level tracking, flag combinations for reading sessions back, and ready-made code for the UI patterns simkl.com uses on every detail page. Required if you set `?allow_rewatch=yes`. The single endpoint that powers watchlist reads. Both `{type}` and `{status}` are optional path segments, and any combination is valid: | Path | Returns | | --- | --- | | `/sync/all-items` | Every type, every status. The full library. | | `/sync/all-items/{type}` | A single type (`shows`, `movies`, or `anime`), every status. | | `/sync/all-items/{type}/{status}` | One type, one status bucket. | The response shape is the same across all three forms: a top-level object keyed by `shows`, `movies`, and `anime`. Filtered calls just include fewer top-level keys; an empty result returns `{}`. See [Per-endpoint shape matrix](/conventions/null-values#per-endpoint-shape-matrix). Pair this endpoint with [`GET /sync/activities`](/api-reference/simkl/get-activities) and the `date_from` query parameter for incremental sync — see the [Sync guide](/guides/sync) for the two-phase model. **Watchlist statuses by type:** | Type | `watching` | `plantowatch` | `hold` | `dropped` | `completed` | |------|:-:|:-:|:-:|:-:|:-:| | `shows` | ✅ | ✅ | ✅ | ✅ | ✅ | | `anime` | ✅ | ✅ | ✅ | ✅ | ✅ | | `movies` | — | ✅ | — | ✅ | ✅ | Movies skip `watching` and `hold` — see [Watchlist statuses](/conventions/list-statuses). #### Useful query parameters A quick map of the params below — see each parameter's full schema later on this page. | Param | What it does | |---|---| | `date_from` | Required on every continuous-sync call. Returns only items modified since this ISO-8601 timestamp. | | `extended=simkl_ids_only` / `=ids_only` / `=full` / `=full_anime_seasons` | Controls response richness — from just `ids.simkl` (smallest) to full metadata + per-episode breakdowns. Pair `=full` and `=full_anime_seasons` with `date_from` — they're significantly larger payloads. | | `include_all_episodes=yes` / `=original` | Loads canonical `seasons[].episodes[]` for items in `completed` and `dropped` (which skip episode load by default). `yes` synthesizes virtual episode rows where per-episode data is missing; `original` returns real rows only. | | `episode_watched_at=yes` | Adds per-episode `watched_at` timestamps to every episode that's been loaded. Modifier — episodes must already be loaded by `extended=full` or `include_all_episodes=yes`. | | `episode_tvdb_id=yes` | Adds `ids.tvdb_id` per episode. | | `next_watch_info=yes` | On `watching` items with a next episode, attaches `next_to_watch_info` (`title`, `season`, `episode`, `date`). | | `memos=yes` | Includes the user's per-item `memo` object (`text` capped at 140 chars). | | `anime_type` | Filter anime entries by anime type (`tv`, `movie`, `ova`, `ona`, `special`, `music video`). | | `language=en` | Force English titles instead of the user's profile language. | | `allow_rewatch=yes` | Synthesize one extra entry per rewatch session alongside the canonical row. **Simkl Pro / VIP only** — gate the flag on `account.type` from [`POST /users/settings`](/api-reference/simkl/get-user-settings) (cache it; refetch only when `activities.settings.all` bumps — see [Rewatches guide → Pro / VIP gate](/guides/rewatches)). Free-tier callers get a silent no-op that still consumes a rate-limit slot. See the [Rewatches guide](/guides/rewatches) for the full pattern. | **Rewatches** (Simkl Pro / VIP). Without the flag, each item — movie, show, or anime — appears once in the response, reflecting the user's current watch state. Set `?allow_rewatch=yes` and any item with saved rewatch sessions appears multiple times: the normal entry, plus one extra entry per rewatch session. The extra entries carry `is_rewatch: true`, `rewatch_id`, `rewatch_status` (`active` / `completed` / `closed`), `last_watched_at`, and `watched_episodes_count`, so you can tell them apart from the main entry and from each other. **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**](/conventions/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). operationId: get-sync-all-items-type-status parameters: - name: type in: path description: >- One of `shows`, `movies`, `anime`, or `all`. Pass `all` to skip filtering on type even when the runtime accepts the segment-less form, so for spec strictness this is `true`. To call without it in practice, just drop the segment from the URL. schema: type: string enum: - movies - shows - anime - all example: all required: true examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: all phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: all movies_completed_filtered: summary: Path filter — only completed movies value: movies watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: shows extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: shows anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: anime simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: all ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: movies rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: all all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: all - name: status in: path description: >- One of `watching`, `plantowatch`, `hold`, `completed`, `dropped`, or `all`. Movies accept only `plantowatch`, `completed`, `dropped`, and `all`; TV and anime accept all six. Pass `all` to skip filtering on status — `/sync/all-items/{type}/all` returns every status for that type. schema: $ref: '#/components/schemas/WatchlistStatus' enum: - watching - plantowatch - hold - completed - dropped - all example: all required: true examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: all phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: all movies_completed_filtered: summary: Path filter — only completed movies value: completed watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: watching extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: watching anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: completed simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: all ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: completed rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: completed all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: all - name: allow_rewatch in: query required: false schema: type: string enum: - 'yes' - 'no' default: 'no' description: >- Opt into rewatch tracking. When `yes`, `POST /sync/history` records an additional rewatch session instead of being a no-op for already-watched items, and `GET /sync/all-items` returns one extra entry per saved rewatch session alongside the item's normal entry. Available to Simkl **Pro** and **VIP** users — non-Pro callers see no effect even with the flag set. ⚠️ **Do not enable this flag until you've read the [Rewatches guide](/guides/rewatches) end-to-end and implemented the precautions.** Used carelessly (on retries, on every scrobble event, on importer re-runs, without pinning `rewatch_id` after the first write), it will pollute the user's history stats and rewatches panel with phantom sessions. The flag should be gated behind explicit user intent — a dedicated "Rewatch" button — never on background or automated flows. Also expose a per-user *Track rewatches* toggle in your app's settings (default off) — not every user wants the rewatch-session complexity. Limits: up to **50 rewatches per item** (movie, show, or anime), and any two watch events on the **same item** (movie or episode) must be at least **2 days apart** — a new rewatch within 48 hours of the previous watch of that same item collapses into the same session (it's a rewatch, not a rewind 😄). Full walkthrough — session lifecycle (`active` / `completed` / `closed` with bidirectional transitions), episode-level tracking, reading sessions back from `GET /sync/all-items`, and ready-made code for simkl.com-style UI patterns — in the [Rewatches guide](/guides/rewatches). examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'yes' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: 'yes' - name: date_from in: query required: false description: >- ISO-8601 timestamp. Returns only items updated since this time. Use the value saved from `/sync/activities`. schema: type: string format: date-time examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: '' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: '2026-05-14T00:00:00Z' movies_completed_filtered: summary: Path filter — only completed movies value: '' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: '' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: '' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: '' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: '' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: '' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: '' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: '' - name: extended in: query description: '`full` returns more info including a list of watched episodes' schema: type: string enum: - full - full_anime_seasons - simkl_ids_only - ids_only examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: full movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: full anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: full_anime_seasons simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: simkl_ids_only ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: ids_only rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: full all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: full_anime_seasons - name: next_watch_info in: query required: false schema: type: string enum: - 'yes' description: >- When `yes`, attaches a `next_to_watch_info` object to each watched item, indicating the next episode to watch. examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'yes' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: 'yes' - name: episode_tvdb_id in: query required: false schema: type: string enum: - 'yes' description: >- When `yes`, includes TVDB IDs on each episode in episode-bearing responses. examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: 'yes' - $ref: '#/components/parameters/AllItemsLanguageQuery' - $ref: '#/components/parameters/AllItemsAnimeTypeQuery' - name: episode_watched_at in: query description: >- `yes` adds per-episode `watched_at` timestamps to every episode in the response. Modifier only — episodes must already be loaded by `extended=full` / `extended=full_anime_seasons` (or by `include_all_episodes=yes` for completed/dropped statuses). Pair with `date_from` — significantly larger response. schema: type: string const: 'yes' examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'yes' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: 'yes' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'yes' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: 'yes' - name: include_all_episodes in: query description: >- Three-value flag that controls per-episode loading on canonical entries. - `no` *(default)* — Episode lists are loaded only for items in `watching`, `plantowatch`, and `hold` statuses. Items in `completed` and `dropped` skip episode loading entirely. - `yes` — Load episode lists for **every** status. Synthesizes virtual episode rows for completed entries that don't have per-episode data recorded (virtual rows fall back to the show's air-date timestamps). - `original` — Load episode lists for every status, but **skip** virtual-episode synthesis. Completed entries get only their real per-episode rows. Independent of `allow_rewatch=yes` — combine the two when you need both canonical episode lists AND rewatch session episode lists in one response. Pair with `date_from` since the response can be much larger when episodes load for completed-bucket items. schema: type: string enum: - 'yes' - original - 'no' default: 'no' examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: 'yes' - name: memos in: query description: '`yes` returns memos in addition all other data' schema: type: string const: 'yes' examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) value: 'no' phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) value: 'no' movies_completed_filtered: summary: Path filter — only completed movies value: 'no' watching_with_next_to_watch_info: summary: next_watch_info=yes — adds next_to_watch_info for watching items value: 'no' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at value: 'no' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons value: 'no' simkl_ids_only_minimal: summary: extended=simkl_ids_only — smallest payload (incremental sync) value: 'no' ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata value: 'no' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. value: 'no' all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. value: 'yes' - $ref: '#/components/parameters/ClientIdQuery' - $ref: '#/components/parameters/AppNameQuery' - $ref: '#/components/parameters/AppVersionQuery' - $ref: '#/components/parameters/UserAgentHeader' responses: '200': description: >- Top-level dict keyed by `shows`, `movies`, and `anime`. **Keys are present only when there's at least one item in that bucket** — filtered calls (`/movies/completed`) return just that key; an empty library returns `{}`. The per-item shape is `AllItemsEntry` — its fields are gated on the query parameters (`extended`, `memos`, `next_watch_info`, `episode_watched_at`, `episode_tvdb_id`, `allow_rewatch`, etc.). See the schema and the examples below for what each modifier adds. headers: {} content: application/json: schema: $ref: '#/components/schemas/AllItemsResponse' examples: phase1_initial_full_pull: summary: >- Phase 1 — Initial full pull (Sync guide recommendation, run ONCE per user) description: 'Call: `GET /sync/all-items`' value: shows: - added_to_watchlist_at: '2018-02-24T23:55:13Z' last_watched_at: null user_rated_at: null user_rating: null status: plantowatch last_watched: null next_to_watch: S01E01 watched_episodes_count: 0 total_episodes_count: 178 not_aired_episodes_count: 0 show: title: Charmed poster: 24/24273cee77f9d9f year: 1998 ids: simkl: 297 slug: charmed imdb: tt0158552 tvdb: '70626' tmdb: '1981' anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' anime_type: tv phase2_incremental_delta: summary: >- Phase 2 — Incremental delta with date_from + extended=full + episode_watched_at=yes (Sync guide recommendation, the recurring call) description: >- Call: `GET /sync/all-items?date_from=2026-05-14T00:00:00Z&extended=full&episode_watched_at=yes` value: shows: - added_to_watchlist_at: '2026-05-15T00:35:15Z' last_watched_at: '2026-05-15T00:35:15Z' user_rated_at: null user_rating: null status: watching last_watched: S01E01 next_to_watch: null watched_episodes_count: 176 total_episodes_count: 177 not_aired_episodes_count: 0 show: title: The Walking Dead poster: 16/16913426086fc13 year: 2010 ids: simkl: 2090 slug: the-walking-dead imdb: tt1520211 tvdb: '153021' anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: 23 anilist: 1 anime_type: tv movies: - added_to_watchlist_at: '2026-05-14T06:49:56Z' last_watched_at: null user_rated_at: null user_rating: null status: dropped watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: Pulp Fiction poster: 13/13311405613660dcc9 year: 1994 ids: simkl: 54130 slug: pulp-fiction imdb: tt0110912 movies_completed_filtered: summary: Path filter — only completed movies description: 'Call: `GET /sync/all-items/movies/completed`' value: movies: - added_to_watchlist_at: '2026-04-10T20:13:02Z' last_watched_at: '1994-09-01T16:00:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' watching_with_next_to_watch_info: summary: >- next_watch_info=yes — adds next_to_watch_info for watching items description: >- Call: `GET /sync/all-items/shows/watching?next_watch_info=yes` value: shows: - added_to_watchlist_at: '2014-11-12T18:42:53Z' last_watched_at: '2026-05-04T19:40:59Z' user_rated_at: null user_rating: null status: watching last_watched: S08E02 next_to_watch: S08E03 watched_episodes_count: 126 total_episodes_count: 165 not_aired_episodes_count: 11 show: title: Futurama poster: 18/18421459bbf0f06beb year: 1999 ids: simkl: 3407 slug: futurama imdb: tt0149460 tvdb: '73871' next_to_watch_info: title: How the West Was 1010001 season: 8 episode: 3 date: '2023-08-07T00:00:00-05:00' extended_full_with_seasons: summary: >- extended=full + episode_watched_at=yes — runtime + seasons[].episodes[].watched_at description: >- Call: `GET /sync/all-items/shows/watching?extended=full&episode_watched_at=yes` value: shows: - added_to_watchlist_at: '2026-05-15T00:35:15Z' last_watched_at: '2026-05-15T00:35:15Z' user_rated_at: null user_rating: null status: watching last_watched: S01E01 next_to_watch: null watched_episodes_count: 176 total_episodes_count: 177 not_aired_episodes_count: 0 show: title: The Walking Dead poster: 16/16913426086fc13 year: 2010 runtime: 43 ids: simkl: 2090 slug: the-walking-dead imdb: tt1520211 tvdb: '153021' seasons: - number: 1 episodes: - number: 2 watched_at: '2026-05-15T00:32:20Z' - number: 3 watched_at: '2026-05-15T00:32:21Z' anime_with_mapped_tvdb_seasons: summary: extended=full_anime_seasons — anime gets mapped_tvdb_seasons description: >- Call: `GET /sync/all-items/anime/completed?extended=full_anime_seasons` value: anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: 1 anime_type: tv mapped_tvdb_seasons: - 1 simkl_ids_only_minimal: summary: >- extended=simkl_ids_only — smallest payload (incremental sync) description: 'Call: `GET /sync/all-items?extended=simkl_ids_only`' value: shows: - show: ids: simkl: 297 slug: charmed anime: - show: ids: simkl: 37089 slug: cowboy-bebop mal: 1 anidb: 23 anilist: 1 movies: - movie: ids: simkl: 53434 slug: the-godfather ids_only_with_externals: summary: extended=ids_only — all external IDs, no per-show metadata description: >- Call: `GET /sync/all-items/movies/completed?extended=ids_only` value: movies: - movie: ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' rewatches_via_allow_rewatch: summary: >- allow_rewatch=yes + extended=full + episode_watched_at=yes — rewatch rows WITH per-episode data (Simkl Pro / VIP). Without extended=full, rewatch rows return summary-only with watched_episodes_count:0 as sentinel. description: >- Call: `GET /sync/all-items/all/completed?allow_rewatch=yes&extended=full&episode_watched_at=yes` value: shows: - added_to_watchlist_at: '2026-05-15T00:13:18Z' last_watched_at: '2026-05-15T00:13:18Z' user_rated_at: '2026-05-16T14:20:16Z' user_rating: 10 status: completed last_watched: null next_to_watch: null watched_episodes_count: 73 total_episodes_count: 73 not_aired_episodes_count: 0 show: title: Game of Thrones poster: 57/5742576cd8f59fcb0 year: 2011 runtime: 52 ids: simkl: 17465 slug: game-of-thrones imdb: tt0944947 tvdb: '121361' tmdb: '1399' is_rewatch: false - added_to_watchlist_at: '2026-05-16T14:02:10Z' last_watched_at: '2026-05-16T20:00:00Z' user_rated_at: '2026-05-16T14:20:16Z' user_rating: 10 status: completed last_watched: S01E04 next_to_watch: null watched_episodes_count: 4 total_episodes_count: 73 not_aired_episodes_count: 0 show: title: Game of Thrones poster: 57/5742576cd8f59fcb0 year: 2011 runtime: 52 ids: simkl: 17465 slug: game-of-thrones imdb: tt0944947 tvdb: '121361' tmdb: '1399' is_rewatch: true rewatch_id: 7482 rewatch_status: completed seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-16T14:02:10Z' - number: 2 watched_at: '2026-05-16T14:02:10Z' - number: 3 watched_at: '2026-05-16T19:00:00Z' - number: 4 watched_at: '2026-05-16T20:00:00Z' anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' kitsu: '1' anime_type: tv is_rewatch: false - added_to_watchlist_at: '2026-05-16T14:02:10Z' last_watched_at: '2026-05-16T14:02:10Z' user_rated_at: null user_rating: null status: completed last_watched: E2 next_to_watch: null watched_episodes_count: 2 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' kitsu: '1' anime_type: tv is_rewatch: true rewatch_id: 7484 rewatch_status: active seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-16T14:02:10Z' - number: 2 watched_at: '2026-05-16T14:02:10Z' movies: - added_to_watchlist_at: '2026-04-10T20:13:02Z' last_watched_at: '1994-09-01T16:00:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 runtime: 175 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' is_rewatch: false - added_to_watchlist_at: '2026-04-11T11:44:27Z' last_watched_at: '2026-04-11T11:30:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 runtime: 175 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' is_rewatch: true rewatch_id: 2368 rewatch_status: completed all_modifiers_inspection_only: summary: >- INSPECTION ONLY — every modifier on at once. NOT a production default — payload size + Pro-only fields. Use it to see every possible response field in one place. description: >- Call: `GET /sync/all-items?extended=full_anime_seasons&memos=yes&next_watch_info=yes&episode_watched_at=yes&episode_tvdb_id=yes&include_all_episodes=yes&allow_rewatch=yes` value: shows: - added_to_watchlist_at: '2026-05-15T00:13:18Z' last_watched_at: '2026-05-15T00:13:18Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 73 total_episodes_count: 73 not_aired_episodes_count: 0 show: title: Game of Thrones poster: 57/5742576cd8f59fcb0 year: 2011 runtime: 52 ids: simkl: 17465 slug: game-of-thrones imdb: tt0944947 tvdb: '121361' tmdb: '1399' memo: {} is_rewatch: false seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-15T00:13:18Z' ids: tvdb_id: 3254641 - number: 2 watched_at: '2026-05-15T00:13:18Z' ids: tvdb_id: 3436411 - added_to_watchlist_at: '2026-05-16T14:02:10Z' last_watched_at: '2026-05-16T14:02:10Z' user_rated_at: null user_rating: null status: completed last_watched: S01E02 next_to_watch: null watched_episodes_count: 2 total_episodes_count: 73 not_aired_episodes_count: 0 show: title: Game of Thrones poster: 57/5742576cd8f59fcb0 year: 2011 runtime: 52 ids: simkl: 17465 slug: game-of-thrones imdb: tt0944947 tvdb: '121361' tmdb: '1399' memo: {} is_rewatch: true rewatch_id: 7482 rewatch_status: active seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-16T14:02:10Z' ids: tvdb_id: 3254641 - number: 2 watched_at: '2026-05-16T14:02:10Z' ids: tvdb_id: 3436411 anime: - added_to_watchlist_at: '2026-05-15T00:13:09Z' last_watched_at: '2026-05-15T00:13:09Z' user_rated_at: null user_rating: null status: completed last_watched: null next_to_watch: null watched_episodes_count: 26 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' kitsu: '1' memo: {} anime_type: tv mapped_tvdb_seasons: - 1 is_rewatch: false seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-15T00:13:09Z' tvdb: season: 1 episode: 1 ids: tvdb_id: 219121 - number: 2 watched_at: '2026-05-15T00:13:09Z' tvdb: season: 1 episode: 2 ids: tvdb_id: 219122 - added_to_watchlist_at: '2026-05-16T14:02:10Z' last_watched_at: '2026-05-16T14:02:10Z' user_rated_at: null user_rating: null status: completed last_watched: E2 next_to_watch: null watched_episodes_count: 2 total_episodes_count: 26 not_aired_episodes_count: 0 show: title: Cowboy Bebop poster: 36/36842f1bceb6b39 year: 1998 runtime: 25 ids: simkl: 37089 slug: cowboy-bebop mal: '1' anidb: '23' anilist: '1' kitsu: '1' memo: {} anime_type: tv mapped_tvdb_seasons: - 1 is_rewatch: true rewatch_id: 7484 rewatch_status: active seasons: - number: 1 episodes: - number: 1 watched_at: '2026-05-16T14:02:10Z' tvdb: season: 1 episode: 1 ids: tvdb_id: 219121 - number: 2 watched_at: '2026-05-16T14:02:10Z' tvdb: season: 1 episode: 2 ids: tvdb_id: 219122 movies: - added_to_watchlist_at: '2026-04-10T20:13:02Z' last_watched_at: '1994-09-01T16:00:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 runtime: 175 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' memo: {} is_rewatch: false - added_to_watchlist_at: '2026-04-11T11:44:27Z' last_watched_at: '2026-04-11T11:30:00Z' user_rated_at: null user_rating: null status: completed watched_episodes_count: 0 total_episodes_count: 0 not_aired_episodes_count: 0 movie: title: The Godfather poster: 10/102447562f6b49ff3a year: 1972 runtime: 175 ids: simkl: 53434 slug: the-godfather imdb: tt0068646 tmdb: '238' tvdb: '275' memo: {} is_rewatch: true rewatch_id: 2368 rewatch_status: completed '401': $ref: '#/components/responses/Unauthorized' '412': $ref: '#/components/responses/ClientIdFailed' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' security: - clientId: [] bearerAuth: [] - simklApiKey: [] bearerAuth: [] x-codeSamples: - lang: curl label: phase1_initial_full_pull source: >- curl 'https://api.simkl.com/sync/all-items?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: phase2_incremental_delta source: >- curl 'https://api.simkl.com/sync/all-items?extended=full&episode_watched_at=yes&date_from=2026-05-14T00:00:00Z&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: movies_completed_filtered source: >- curl 'https://api.simkl.com/sync/all-items/movies/completed?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: watching_with_next_to_watch_info source: >- curl 'https://api.simkl.com/sync/all-items/shows/watching?next_watch_info=yes&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: extended_full_with_seasons source: >- curl 'https://api.simkl.com/sync/all-items/shows/watching?extended=full&episode_watched_at=yes&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: anime_with_mapped_tvdb_seasons source: >- curl 'https://api.simkl.com/sync/all-items/anime/completed?extended=full_anime_seasons&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: simkl_ids_only_minimal source: >- curl 'https://api.simkl.com/sync/all-items?extended=simkl_ids_only&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: ids_only_with_externals source: >- curl 'https://api.simkl.com/sync/all-items/movies/completed?extended=ids_only&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: rewatches_via_allow_rewatch source: >- curl 'https://api.simkl.com/sync/all-items/all/completed?extended=full&episode_watched_at=yes&allow_rewatch=yes&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' - lang: curl label: all_modifiers_inspection_only source: >- curl 'https://api.simkl.com/sync/all-items?extended=full_anime_seasons&memos=yes&next_watch_info=yes&episode_watched_at=yes&episode_tvdb_id=yes&include_all_episodes=yes&allow_rewatch=yes&client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0' \ -H 'User-Agent: my-app-name/1.0' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' components: schemas: WatchlistStatus: type: string enum: - watching - plantowatch - hold - completed - dropped description: >- User watchlist status. Movies skip `watching` and `hold` — see /conventions/list-statuses. AllItemsResponse: type: object description: >- Top-level dict keyed by `shows`, `movies`, and `anime`. Each key is an array of [AllItemsEntry](#schemas/AllItemsEntry) objects. **Keys are present only when there's at least one item in that bucket** — an empty library returns `{}`; a library with only movies returns `{ movies: [...] }` with no `shows` or `anime` keys. properties: shows: type: array items: $ref: '#/components/schemas/AllItemsEntry' movies: type: array items: $ref: '#/components/schemas/AllItemsEntry' anime: type: array items: $ref: '#/components/schemas/AllItemsEntry' AllItemsEntry: type: object description: >- One item in the user's library. The exact set of fields present depends on the `extended` query parameter: - **no `extended`** (default): metadata fields + `` block with `ids` + watch state - **`extended=simkl_ids_only`**: ONLY `.ids: {simkl, slug}` — smallest payload, ideal for `date_from` deltas - **`extended=ids_only`**: ONLY `.ids` including all external IDs (imdb, tmdb, tvdb, mal, anidb, anilist, kitsu) - **`extended=full`**: adds `.runtime` and (for shows/anime with episodes loaded) `seasons[].episodes[]` - **`extended=full_anime_seasons`**: same as `full` plus `mapped_tvdb_seasons` on anime entries properties: added_to_watchlist_at: type: - string - 'null' format: date-time description: >- ISO-8601 timestamp when the user added this item to their watchlist. **Type 4 null** — `null` for legacy entries without a recorded add-time. See [Null and missing values](/conventions/null-values). example: '2026-05-15T00:35:15Z' last_watched_at: type: - string - 'null' format: date-time description: >- ISO-8601 timestamp of the most recent watch event. **Type 4 null** — `null` if the user has never watched any episode (e.g. `plantowatch` items). See [Null and missing values](/conventions/null-values). example: '2026-05-15T00:35:15Z' user_rated_at: type: - string - 'null' format: date-time description: >- ISO-8601 timestamp when the user set their rating. **Type 4 null** — `null` if not rated. See [Null and missing values](/conventions/null-values). user_rating: type: - integer - 'null' minimum: 1 maximum: 10 description: >- The user's rating (1-10). **Type 4 null** — `null` if not rated. See [Null and missing values](/conventions/null-values). status: type: string enum: - watching - plantowatch - hold - completed - dropped description: >- Current watchlist status. Movies skip `watching` and `hold` per [Watchlist statuses](/conventions/list-statuses). last_watched: type: - string - 'null' description: >- Most recently watched episode marker (e.g. `"S05E16"`). **Type 4 null** — `null` on movies (no episodes) and on shows/anime where no episode has been watched yet. example: S05E16 next_to_watch: type: - string - 'null' description: >- Next episode marker (e.g. `"S08E03"`). **Type 4 null** — `null` when caught up, when status is `completed`/`dropped`, or on movies. example: S08E03 watched_episodes_count: type: integer description: >- Number of episodes the user has watched. `0` for `plantowatch` items and movies. total_episodes_count: type: integer description: Total episodes in the series (including unaired). `0` on movies. not_aired_episodes_count: type: integer description: Episodes that haven't aired yet. `0` on movies and completed series. show: type: object description: >- Present for `shows` and `anime` entries (mutually exclusive with `movie`). properties: title: type: string example: The Walking Dead poster: type: - string - 'null' description: >- Type 4 null — no poster on file for this title. See [Null and missing values](/conventions/null-values). example: 16/16913426086fc13 year: type: - integer - 'null' description: >- Type 4 null — release year not on file. See [Null and missing values](/conventions/null-values). example: 2010 runtime: type: - integer - 'null' description: >- Type 4 null — episode runtime not on file. Present only with `extended=full` or `extended=full_anime_seasons`. See [Null and missing values](/conventions/null-values). example: 43 ids: type: object additionalProperties: true description: >- Always includes `simkl` + `slug`. With `extended=ids_only` or higher, includes all external IDs Simkl has on file (imdb, tmdb, tvdb, mal, anidb, anilist, kitsu, etc.). movie: type: object description: Present for `movies` entries (mutually exclusive with `show`). properties: title: type: string example: The Godfather poster: type: - string - 'null' description: >- Type 4 null — no poster on file for this title. See [Null and missing values](/conventions/null-values). year: type: - integer - 'null' description: >- Type 4 null — release year not on file. See [Null and missing values](/conventions/null-values). runtime: type: - integer - 'null' description: >- Type 4 null — runtime not on file. Present only with `extended=full`. See [Null and missing values](/conventions/null-values). ids: type: object additionalProperties: true description: >- Always includes `simkl` + `slug`. With `extended=ids_only` or higher, includes all external IDs. anime_type: type: - string - 'null' enum: - tv - movie - ova - ona - special - music video - null description: >- Type 4 null — anime_type unknown for this title. Present only on `anime[]` entries. The MyAnimeList-style classification of the anime title. See [Null and missing values](/conventions/null-values). mapped_tvdb_seasons: type: array items: type: integer description: >- Present only on `anime[]` entries with `extended=full_anime_seasons`. TVDB season numbers this anime maps to. memo: oneOf: - title: Public memo type: object description: >- Public memo — visible to other Simkl users on the owner's profile. Returned when `is_private: false`. properties: text: type: string description: >- The memo body. Markdown is not parsed — Simkl stores and returns it as plain text. example: >- Best season of the show — rewatching with friends next month. is_private: type: boolean description: >- `false` for the public branch — anyone visiting the owner's profile can read this memo. enum: - false example: false required: - text - is_private example: text: Best season of the show — rewatching with friends next month. is_private: false - title: Private memo type: object description: >- Private memo — only the owner can see this. Returned when `is_private: true`. Other Simkl users hitting the owner's profile won't see the `text`. properties: text: type: string description: The memo body. Plain text. Hidden from other users. example: Remember to email Mom about ep 7 before she watches it. is_private: type: boolean description: >- `true` for the private branch — only the owner sees this memo. enum: - true example: true required: - text - is_private example: text: Remember to email Mom about ep 7 before she watches it. is_private: true - title: No memo set type: object description: >- Empty object `{}` — returned when the user has not set a memo on this item. The key is still present in the response so client code can check `memo` without a guard. additionalProperties: false example: {} description: >- Present only with `memos=yes`. The user's per-item memo, or an empty object `{}` when no memo is set. See [`POST /sync/history`](/api-reference/simkl/add-to-history) for setting memos. next_to_watch_info: type: object description: >- Present only with `next_watch_info=yes` AND `status: watching` AND there is a next episode to watch. properties: title: type: string example: How the West Was 1010001 season: type: integer description: Omitted for anime entries. episode: type: integer date: type: - string - 'null' format: date-time description: >- Type 4 null — release date not on file for the next episode. Format is ISO-8601 with timezone offset. See [Null and missing values](/conventions/null-values). seasons: type: array description: >- Per-season breakdown. Present only with `extended=full` (or `extended=full_anime_seasons`) AND the item is `watching` (or `include_all_episodes=yes` for `completed`/`dropped`). items: type: object properties: number: type: integer episodes: type: array items: type: object properties: number: type: integer watched_at: type: string format: date-time description: >- Per-episode watch timestamp. Present only with `episode_watched_at=yes`. tvdb: type: object description: >- Present only with `extended=full_anime_seasons` on anime entries. properties: season: type: integer episode: type: integer ids: type: object description: Present only with `episode_tvdb_id=yes`. properties: tvdb_id: type: integer is_rewatch: type: boolean description: >- Present only with `allow_rewatch=yes`. `true` on synthesized rewatch-session entries; `false` on the canonical entry. See the [Rewatches guide](/guides/rewatches). Simkl Pro / VIP feature. rewatch_id: type: integer description: 'Present only on rewatch entries (`is_rewatch: true`).' rewatch_status: type: string enum: - active - completed - closed description: Present only on rewatch entries. additionalProperties: true ErrorResponse: type: object description: >- Standard error envelope for 4xx and 5xx responses. Branch on `error` (machine-readable identifier) — `message`, when present, is human-readable guidance and is **not stable across releases**. properties: error: type: string description: >- Machine-readable error identifier. Stable across responses — use this for programmatic branching in client code. Examples: `user_token_failed`, `client_id_failed`, `empty_field`, `wrong_parameter`, `id_err`, `rate_limit`. example: user_token_failed code: type: integer description: >- HTTP status code echoed in the body for convenience — same value as the response status line. Always an integer. example: 401 message: type: string description: >- Human-readable error guidance. Optional — present on most errors, but not guaranteed. May reference the specific field or value that triggered the error. NOT stable; do not parse. example: Your client_id is wrong. Try another one required: - error - code parameters: AllItemsLanguageQuery: name: language in: query required: false schema: type: string example: en description: Force English titles. Defaults to the user's profile language. AllItemsAnimeTypeQuery: name: anime_type in: query required: false schema: type: string enum: - movies description: >- When `movies`, restricts the `anime` results to anime-movie subtype only. ClientIdQuery: name: client_id in: query required: true description: >- Your **`client_id`** from your [Simkl developer settings](https://simkl.com/settings/developer/). Required on every request. schema: type: string example: YOUR_CLIENT_ID AppNameQuery: name: app-name in: query required: true description: >- Short, lowercase identifier for your app (e.g. `plex-scrobbler`, `kodi-bridge`). Helps Simkl identify which apps are using the API. schema: type: string example: my-app AppVersionQuery: name: app-version in: query required: true description: >- Your app's current version (e.g. `1.0`, `2.4.1`). Helps Simkl debug issues you report. schema: type: string example: '1.0' UserAgentHeader: name: User-Agent in: header required: true description: >- 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)`. schema: type: string example: my-app/1.0 responses: Unauthorized: description: >- Missing or invalid user access token. Provide a valid `Authorization: Bearer ` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: user_token_failed code: 401 ClientIdFailed: description: >- Your `client_id` is missing, wrong, disabled, or has hit a request limit. Verify in your [developer settings](https://simkl.com/settings/developer/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: client_id_failed code: 412 message: Your client_id is wrong. Try another one RateLimited: description: >- Too many requests in too short a window. Back off and retry with exponential backoff — see [Rate limits](/resources/rate-limits) for the playbook. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: rate_limit code: 429 ServerError: description: >- Something is broken on Simkl's side. Retry after a short delay. If it persists, report on the [Simkl Discord](https://discord.gg/MJsWNE4). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: internal code: 500 securitySchemes: clientId: type: apiKey in: query name: client_id description: >- 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](/conventions/headers). x-default: YOUR_CLIENT_ID simklApiKey: type: apiKey in: header name: simkl-api-key description: >- Optional alias for the `client_id` query parameter. Simkl accepts your `client_id` either as the `simkl-api-key` request header **or** as the `?client_id=…` query parameter — pick one. The query-parameter form is preferred because it makes the request fully self-describing in URL form. x-default: YOUR_CLIENT_ID bearerAuth: type: http scheme: bearer description: >- 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](/authentication). x-default: YOUR_ACCESS_TOKEN ````