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

# Stop

> Finalizes the user's playback session. The `action` field in the response tells you what Simkl did:

| `progress` | `action` | Result |
|---|---|---|
| **≥ 80** | `scrobble` | Item is marked watched. |
| **< 80** | `pause` | Session is saved as a paused playback. |

When `progress < 80`, the session is kept as a **resumable playback**, retrievable cross-device via [`GET /sync/playback/{type}`](/api-reference/simkl/get-playback-sessions). When `progress ≥ 80`, the item is marked watched and no playback is saved. See the [Playback overview](/api-reference/playback) for retention.

Body shape is identical to [`/scrobble/start`](/api-reference/simkl/scrobble-start).

#### Duplicate prevention

Stopping a session that's already been finalized within the past hour returns **`409 Conflict`** with `watched_at` and `expires_at` so you know when the prior scrobble expires:

```json
{
  "watched_at": "2024-05-01T18:00:00-05:00",
  "expires_at": "2024-05-01T19:00:00-05:00"
}
```

#### Seek and scrub behavior

The ≥80% auto-scrobble rule applies to the `progress` you send with this call — not to anywhere the user temporarily scrubbed during playback. A user who scrubbed to 95% mid-watch but then rewinds and stops at 30% sends `progress: 30`, and the server stores `action: "pause"`. Only the value at the moment of `stop` matters.

> **Note:** A 20-second per-user lock collision returns HTTP `400` with `RATE_LIMIT`, not `429` — the lock failure is treated as a malformed request from a duplicate-fire client.

<Card title="Scrobble guide — full walkthrough" icon="play" href="/guides/scrobble" horizontal>
 Real-time playback tracking — `/start`, `/pause`, `/stop` lifecycle, paused-playback resumption across devices, when scrobble auto-completes, and the difference between `/scrobble/checkin` (fire-and-forget) and `/scrobble/start` (active tracking).
</Card>

Alternative to `episode.season` + `episode.number`: pass `episode.ids` with `tvdb` or `anidb` to identify the exact episode by external episode ID. Useful for Plex / media-server integrations that have a TVDB or AniDB episode ID but not the season/number mapping. (Episode-level `imdb` and `tmdb` IDs are **not** accepted — those exist only at the show/movie level. Use the `show`/`anime` object's `ids` for those.) If both forms are sent, `episode.ids` takes precedence.

<Tip>
**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).
</Tip>



## OpenAPI

````yaml /openapi.json post /scrobble/stop
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 <token>` 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.


      <!-- IDS_TABLE_START -->


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


      <!-- IDS_TABLE_END -->
    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.


      <!-- IDS_TABLE_START -->


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


      <!-- IDS_TABLE_END -->
    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:
  /scrobble/stop:
    post:
      tags:
        - Scrobble
      summary: Stop
      description: >-
        Finalizes the user's playback session. The `action` field in the
        response tells you what Simkl did:


        | `progress` | `action` | Result |

        |---|---|---|

        | **≥ 80** | `scrobble` | Item is marked watched. |

        | **< 80** | `pause` | Session is saved as a paused playback. |


        When `progress < 80`, the session is kept as a **resumable playback**,
        retrievable cross-device via [`GET
        /sync/playback/{type}`](/api-reference/simkl/get-playback-sessions).
        When `progress ≥ 80`, the item is marked watched and no playback is
        saved. See the [Playback overview](/api-reference/playback) for
        retention.


        Body shape is identical to
        [`/scrobble/start`](/api-reference/simkl/scrobble-start).


        #### Duplicate prevention


        Stopping a session that's already been finalized within the past hour
        returns **`409 Conflict`** with `watched_at` and `expires_at` so you
        know when the prior scrobble expires:


        ```json

        {
          "watched_at": "2024-05-01T18:00:00-05:00",
          "expires_at": "2024-05-01T19:00:00-05:00"
        }

        ```


        #### Seek and scrub behavior


        The ≥80% auto-scrobble rule applies to the `progress` you send with this
        call — not to anywhere the user temporarily scrubbed during playback. A
        user who scrubbed to 95% mid-watch but then rewinds and stops at 30%
        sends `progress: 30`, and the server stores `action: "pause"`. Only the
        value at the moment of `stop` matters.


        > **Note:** A 20-second per-user lock collision returns HTTP `400` with
        `RATE_LIMIT`, not `429` — the lock failure is treated as a malformed
        request from a duplicate-fire client.


        <Card title="Scrobble guide — full walkthrough" icon="play"
        href="/guides/scrobble" horizontal>
         Real-time playback tracking — `/start`, `/pause`, `/stop` lifecycle, paused-playback resumption across devices, when scrobble auto-completes, and the difference between `/scrobble/checkin` (fire-and-forget) and `/scrobble/start` (active tracking).
        </Card>


        Alternative to `episode.season` + `episode.number`: pass `episode.ids`
        with `tvdb` or `anidb` to identify the exact episode by external episode
        ID. Useful for Plex / media-server integrations that have a TVDB or
        AniDB episode ID but not the season/number mapping. (Episode-level
        `imdb` and `tmdb` IDs are **not** accepted — those exist only at the
        show/movie level. Use the `show`/`anime` object's `ids` for those.) If
        both forms are sent, `episode.ids` takes precedence.


        <Tip>

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

        </Tip>
      operationId: post-scrobble-stop
      parameters:
        - $ref: '#/components/parameters/ClientIdQuery'
        - $ref: '#/components/parameters/AppNameQuery'
        - $ref: '#/components/parameters/AppVersionQuery'
        - $ref: '#/components/parameters/UserAgentHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrobbleBody'
            examples:
              scrobble_stop_409_repeat:
                summary: 409 Conflict — re-scrobble within rate-limit window
                description: >-
                  When the same item is scrobbled-as-watched within the
                  rate-limit window (~1 hour observed live), repeat stops return
                  `409` with `{watched_at, expires_at}` instead of another
                  history entry. `watched_at` is when the original watch was
                  logged; `expires_at` is when you can re-scrobble. Surface this
                  in client UX as 'already watched a minute ago' rather than
                  treating it as an error.
                value:
                  movie:
                    ids:
                      simkl: 752138
                  progress: 95
              scrobble_stop_movie_pause_threshold:
                summary: Stop with low progress (< 80%) — treated as pause, no history
                description: >-
                  When `progress < 80`, /scrobble/stop is treated as a pause:
                  the user's current playback position is recorded but the watch
                  event is NOT added to history. Use this for accurate resume
                  tracking when a user partially watches and then leaves. May
                  return 409 if the same item was scrobbled too recently — see
                  the 409 example for the rate-limit response shape.
                value:
                  movie:
                    ids:
                      simkl: 53992
                  progress: 30
              scrobble_stop_movie_watched:
                summary: Finalize a movie scrobble at 95% (counts as watched)
                description: >-
                  /stop with `progress >= 80` writes a watch event to the user's
                  history. With `progress < 80`, the same call is treated as a
                  pause (no history entry). The threshold is server-side, not a
                  request param.
                value:
                  movie:
                    ids:
                      simkl: 472214
                  progress: 95
      responses:
        '201':
          description: Created
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrobbleResponse'
              examples:
                scrobble_stop_movie_pause_threshold:
                  summary: >-
                    Stop with low progress (< 80%) — treated as pause, no
                    history
                  description: >-
                    When `progress < 80`, /scrobble/stop is treated as a pause:
                    the user's current playback position is recorded but the
                    watch event is NOT added to history. Use this for accurate
                    resume tracking when a user partially watches and then
                    leaves. May return 409 if the same item was scrobbled too
                    recently — see the 409 example for the rate-limit response
                    shape.
                  value:
                    id: 10916890
                    action: pause
                    progress: 30
                    movie:
                      title: The Matrix
                      year: 1999
                      ids:
                        simkl: 53992
                        slug: the-matrix
                        imdb: tt0133093
                        letterslug: the-matrix
                        traktmslug: the-matrix-1999
                        tmdb: '603'
                        tvdbslug: the-matrix
                        tvdb: '169'
                scrobble_stop_movie_watched:
                  summary: Finalize a movie scrobble at 95% (counts as watched)
                  description: >-
                    /stop with `progress >= 80` writes a watch event to the
                    user's history. With `progress < 80`, the same call is
                    treated as a pause (no history entry). The threshold is
                    server-side, not a request param.
                  value:
                    id: 10916758
                    action: scrobble
                    progress: 95
                    movie:
                      title: Inception
                      year: 2010
                      ids:
                        simkl: 472214
                        slug: inception
                        imdb: tt1375666
                        letterslug: inception
                        traktmslug: inception-2010
                        tmdb: '27205'
                        tvdbslug: inception
                        tvdb: '113'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            if you are trying to stop an already completed scrobble session
            within an hour.
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  watched_at:
                    type: string
                  expires_at:
                    type: string
              examples:
                scrobble_stop_409_repeat:
                  summary: 409 Conflict — re-scrobble within rate-limit window
                  description: >-
                    When the same item is scrobbled-as-watched within the
                    rate-limit window (~1 hour observed live), repeat stops
                    return `409` with `{watched_at, expires_at}` instead of
                    another history entry. `watched_at` is when the original
                    watch was logged; `expires_at` is when you can re-scrobble.
                    Surface this in client UX as 'already watched a minute ago'
                    rather than treating it as an error.
                  value:
                    watched_at: '2026-05-14T23:46:29Z'
                    expires_at: '2026-05-15T00:46:29Z'
        '412':
          $ref: '#/components/responses/ClientIdFailed'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - clientId: []
          bearerAuth: []
        - simklApiKey: []
          bearerAuth: []
components:
  parameters:
    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
  schemas:
    ScrobbleBody:
      type: object
      description: >-
        Request body for the four scrobble endpoints. Send exactly one of
        `movie`, `show`+`episode`, or `anime`+`episode` — all keys are singular
        objects (one item per request). For batch sync writes the keys are
        plural arrays: see
        [`/sync/history`](/api-reference/simkl/add-to-history) etc. `progress`
        is required for `/scrobble/start`, `/scrobble/pause`, and
        `/scrobble/stop`; on `/scrobble/checkin` it is optional and ignored
        server-side.


        **Anime under `show`?** Yes — if you don't know whether a title is anime
        (e.g. you only have TMDB/TVDB data), send it under `show` and Simkl
        resolves it to the correct catalog automatically. The `anime` key is
        only needed when you want to pass `anidb` / `mal` / `anilist` IDs that
        don't exist at the TV-show level.
      oneOf:
        - title: Movie
          required:
            - movie
        - title: TV episode
          required:
            - show
            - episode
        - title: Anime episode
          required:
            - anime
            - episode
      properties:
        progress:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: >-
            Playback percentage 0-100. Up to 2 decimals. Required for
            `/scrobble/start`, `/scrobble/pause`, `/scrobble/stop`. Optional
            (and ignored) for `/scrobble/checkin`.
        movie:
          type: object
          description: >-
            Movie reference. Use `ids` (any one external ID) and optionally
            `title` / `year`. Movies have no `episode` block.
          properties:
            title:
              type: string
              example: Inception
            year:
              type: integer
              example: 2010
            ids:
              $ref: '#/components/schemas/MovieIds'
          required:
            - ids
        show:
          type: object
          description: TV show reference (must be paired with `episode`).
          properties:
            title:
              type: string
              example: Stranger Things
            year:
              type: integer
              example: 2016
            ids:
              $ref: '#/components/schemas/ShowIds'
          required:
            - ids
        anime:
          type: object
          description: >-
            Anime reference. Pair with `episode` for series; an `anime` alone
            (no `episode`) is treated as an anime movie / OVA.
          properties:
            title:
              type: string
              example: Shingeki no Kyojin
            year:
              type: integer
              example: 2013
            ids:
              $ref: '#/components/schemas/AnimeIds'
          required:
            - ids
        episode:
          type: object
          description: >-
            Episode identifier. Use `season` + `number`, OR `ids` with a `tvdb`
            / `anidb` episode ID. If both are sent, `episode.ids` takes
            precedence (matches Plex-style integrations that have an episode ID
            but no season/number mapping).
          oneOf:
            - required:
                - season
                - number
              title: By season + number
            - required:
                - ids
              title: By episode ID
          properties:
            season:
              type: integer
              minimum: 0
              example: 1
              description: Season number. `0` is the specials season.
            number:
              type: integer
              minimum: 1
              example: 3
              description: Episode number within the season.
            ids:
              $ref: '#/components/schemas/EpisodeIds'
    ScrobbleResponse:
      type: object
      description: Response for `/scrobble/start`, `/scrobble/pause`, and `/scrobble/stop`.
      properties:
        action:
          type: string
          enum:
            - start
            - pause
            - scrobble
          description: >-
            `start` for /start, `pause` for /pause and for /stop with
            progress<80, `scrobble` for /stop with progress≥80 (item marked
            watched).
        progress:
          type: number
          description: Echo of the request progress, normalized.
        sid:
          type: string
          description: Internal session ID.
        movie:
          $ref: '#/components/schemas/Movie'
        show:
          $ref: '#/components/schemas/Show'
        anime:
          $ref: '#/components/schemas/Anime'
        episode:
          $ref: '#/components/schemas/Episode'
        tvdb_season:
          type: integer
          description: 'For anime: original TVDB season number when AniDB mapping differs.'
        tvdb_number:
          type: integer
          description: 'For anime: original TVDB episode number when AniDB mapping differs.'
    MovieIds:
      type: object
      description: >-
        External IDs for a movie. Pass any one or more — Simkl resolves the
        canonical record by walking these in priority order. `simkl` is the most
        reliable when you have it.
      properties:
        simkl:
          type: integer
          description: Simkl movie ID.
          example: 472214
        slug:
          type: string
          description: Simkl URL slug (echoed back in responses).
          example: inception
        imdb:
          type: string
          description: IMDb ID, e.g. `tt1375666`.
          example: tt1375666
        tmdb:
          type: integer
          description: TMDb movie ID.
          example: 27205
        netflix:
          type: integer
          description: Netflix movie ID.
        traktslug:
          type: string
          description: Trakt movie slug, e.g. `inception-2010`.
        letterboxd:
          type: string
          description: Letterboxd slug, e.g. `inception`.
        boxd:
          type: string
          description: Letterboxd numeric ID (alternative to `letterboxd`).
      additionalProperties: true
    ShowIds:
      type: object
      description: External IDs for a TV show. Pass any one or more.
      properties:
        simkl:
          type: integer
          description: Simkl show ID.
          example: 548312
        slug:
          type: string
          description: Simkl URL slug (echoed back in responses).
          example: stranger-things
        imdb:
          type: string
          description: IMDb ID, e.g. `tt4574334`.
          example: tt4574334
        tmdb:
          type: integer
          description: TMDb show ID.
          example: 66732
        tvdb:
          description: TVDB show ID (integer) or slug (string).
          oneOf:
            - type: integer
            - type: string
          example: 305288
        netflix:
          type: integer
          description: Netflix show ID.
        hulu:
          type: integer
          description: Hulu show ID.
        traktslug:
          type: string
          description: Trakt show slug.
        zap2it:
          type: string
          description: Zap2it ID.
        tvcom:
          type: string
          description: TV.com ID.
        mdl:
          type: string
          description: MyDramaList slug or ID.
      additionalProperties: true
    AnimeIds:
      type: object
      description: >-
        External IDs for an anime. Any one is enough; `mal` / `anidb` /
        `anilist` / `kitsu` are most useful for anime-only sources, while
        `simkl`, `imdb`, `tmdb`, and `tvdb` work for the cross-domain mapping.
      properties:
        simkl:
          type: integer
          description: Simkl anime ID.
          example: 39687
        slug:
          type: string
          description: Simkl URL slug.
          example: shingeki-no-kyojin
        imdb:
          type: string
          description: IMDb ID.
          example: tt2560140
        tmdb:
          type: integer
          description: TMDb show or movie ID (depending on anime_type).
          example: 1429
        tvdb:
          description: TVDB show ID (integer) or slug (string).
          oneOf:
            - type: integer
            - type: string
          example: 267440
        mal:
          type: integer
          description: MyAnimeList ID.
          example: 16498
        anidb:
          type: integer
          description: AniDB ID. Specifying just this is enough for anime lookups.
          example: 9541
        anilist:
          type: integer
          description: AniList ID.
          example: 16498
        kitsu:
          type: integer
          description: Kitsu ID.
          example: 7442
        anisearch:
          type: integer
          description: aniSearch ID.
        animeplanet:
          type: string
          description: Anime-Planet slug.
        livechart:
          type: integer
          description: LiveChart ID.
        anfo:
          type: integer
          description: AnimeNewsNetwork-style anfo ID.
        ann:
          type: integer
          description: AnimeNewsNetwork ID.
      additionalProperties: true
    EpisodeIds:
      type: object
      description: >-
        External IDs for an episode. Only `tvdb` and `anidb` are accepted as
        scrobble episode-ID lookups. Pass either; if both are sent, `tvdb` is
        tried first.
      properties:
        tvdb:
          type: integer
          description: TVDB episode ID.
          example: 4274616
        anidb:
          type: integer
          description: AniDB episode ID.
          example: 142278
      additionalProperties: false
    Movie:
      type: object
      description: >-
        Standard movie object. See the [Standard Media
        Objects](/conventions/standard-media-objects) guide.
      properties:
        title:
          type: string
          example: 'Terminator 3: Rise of the Machines'
        year:
          type: integer
          example: 2003
        ids:
          $ref: '#/components/schemas/Ids'
      required:
        - ids
    Show:
      type: object
      description: >-
        Standard show object. May include nested seasons/episodes for partial
        sync.
      properties:
        title:
          type: string
          example: The Walking Dead
        year:
          type: integer
          example: 2010
        ids:
          $ref: '#/components/schemas/Ids'
        seasons:
          type: array
          items:
            type: object
            properties:
              number:
                type: integer
              episodes:
                type: array
                items:
                  $ref: '#/components/schemas/Episode'
      required:
        - ids
    Anime:
      type: object
      description: >-
        Standard anime object. Like Show, but may include `anime_type`. Episode
        numbering follows AniDB.
      properties:
        title:
          type: string
          example: Attack on Titan
        year:
          type: integer
          example: 2013
        anime_type:
          $ref: '#/components/schemas/AnimeFormat'
        ids:
          $ref: '#/components/schemas/Ids'
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/Episode'
      required:
        - ids
    Episode:
      type: object
      description: Episode reference. Use `season` + `number`, or `ids`.
      properties:
        season:
          type: integer
          minimum: 0
          example: 1
        number:
          type: integer
          minimum: 1
          example: 2
        watched_at:
          type: string
          format: date-time
          example: '2014-09-01T09:10:11Z'
          description: ISO-8601 GMT timestamp.
        ids:
          $ref: '#/components/schemas/Ids'
    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
    Ids:
      type: object
      description: >-
        External and internal identifiers for an item. Pass as many as you have
        — Simkl resolves to the canonical record.
      properties:
        simkl:
          type: integer
          description: Simkl internal ID. Most reliable.
          example: 53536
        slug:
          type: string
          description: URL-safe slug returned in responses.
          example: attack-on-titan
        imdb:
          type: string
          description: IMDb ID.
          example: tt0181852
        tmdb:
          type: string
          description: TMDb ID.
          example: '296'
        tvdb:
          oneOf:
            - type: integer
            - type: string
          description: TVDB ID or slug.
          example: 153021
        mal:
          type: string
          description: MyAnimeList ID.
          example: '4246'
        anidb:
          type: string
          description: AniDB ID. Specifying just this is enough for anime lookups.
          example: '10846'
        anilist:
          type: string
          description: AniList ID.
          example: '21'
        kitsu:
          type: string
          description: Kitsu ID.
          example: '12'
        anisearch:
          type: string
          description: aniSearch ID.
          example: '2227'
        animeplanet:
          type: string
          description: Anime-Planet slug.
          example: one-piece
        livechart:
          type: string
          description: LiveChart ID.
          example: '321'
        letterboxd:
          type: string
          description: Letterboxd slug.
          example: the-truman-show
        netflix:
          type: string
          description: Netflix movie ID.
          example: '70210890'
        hulu:
          type: string
          description: Hulu episode ID.
        crunchyroll:
          type: string
          description: Crunchyroll episode ID.
        traktslug:
          type: string
          description: Trakt slug.
          example: john-wick-chapter-4-2023
      additionalProperties: true
      example:
        simkl: 53536
        imdb: tt0181852
        tmdb: 296
    AnimeFormat:
      type: string
      enum:
        - tv
        - movie
        - special
        - ova
        - ona
        - music video
      description: >-
        Anime production format. `tv` is the common case; movies, OVAs, ONAs,
        and music videos all surface through the `/anime/*` endpoints with the
        same response shape.
  responses:
    BadRequest:
      description: Bad request — a required field is missing or has the wrong shape.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: empty_field
            code: 400
            message: Missed "to" parameter
    Unauthorized:
      description: >-
        Missing or invalid user access token. Provide a valid `Authorization:
        Bearer <access_token>` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: user_token_failed
            code: 401
    NotFound:
      description: The requested item ID or URL does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: id_err
            code: 404
    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
    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

````