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

# Movies by genre

> <Warning>
**Not for TV / console / 10-foot apps.** The V1 genre-browse endpoints return a thin per-item shape (`title`, `year`, `poster`, `ids`, `ratings`, `rank`). Building a TV-app grid that shows overview text, full ratings, networks, runtimes, recommendations, or trailers would force one per-item refetch against the detail endpoint per visible card. **Wait for the V2 Beta API**, which returns the richer per-item shape TV-app surfaces need in a single call. If you're targeting TV / console / streaming-box clients, please hold off integrating these endpoints.
</Warning>

<Tip>
**Just need this month's most watched titles in a genre? Use the [trending genre files](/api-reference/trending#by-genre-this-month) instead.** They are free: they don't count against any [rate limit](/resources/rate-limits#what-does-not-count) or a user's daily allowance, and they need no user token. Every call to this endpoint does count — against the user's daily allowance under [AUTH V2](/api-reference/auth-v2), where it also needs a user token, or your app's allowance under AUTH V1.

A genre file is one cached request with no paging, and every item comes in the full trending shape (overview, trailer, ratings, runtime) rather than the thin shape above. Call this endpoint only for what the files don't cover: other sorts, the country / network / year filters, or anything beyond this month.
</Tip>

Browse movies filtered by genre, country, year, and sort order. Path is `/movies/genres/{genre}/{type}/{country}/{year}/{sort}` — all segments **required** (use `all` as the wildcard).

The `type` segment is reserved — always pass the literal value `movies`.

| Path param | Values |
|---|---|
| `genre` | `all`, `action`, `adventure`, `animation`, `comedy`, `crime`, `documentary`, `drama`, `erotica`, `family`, `fantasy`, `history`, `horror`, `music`, `mystery`, `romance`, `science-fiction`, `thriller`, `tv-movie`, `war`, `western` |
| `type` | `movies` (literal) |
| `country` | `all` or ISO 3166-1 alpha-2 (`us`, `gb`, `jp`, …) |
| `year` | `all`, single year (`2019`), or decade (`2010s`, `2000s`) |
| `sort` | `popular-this-week`, `popular-this-month`, `popular-all-time`, `rank`, `release-date`, `voted`, `watched` |

Items always carry `ids.tmdb` — the discover query filters out movies without a TMDB-linked record.

#### Pagination

| Param | Default | Notes |
|---|---|---|
| `page` | `1` | Hard-capped server-side at `20`. Higher values clamp silently. |
| `limit` | `60` | Hard-capped server-side at `60`. Higher values clamp silently. Returned `X-Pagination-Limit` reflects the clamped value. |

`X-Pagination-*` headers on every response — see [Pagination](/conventions/pagination).

#### Silent fallbacks

Bad path segments DO NOT return errors:

| Bad input | What happens |
|---|---|
| Unknown `genre` slug (`zzz`) | Top-level response is `null` (NOT `[]`). |
| Unknown `year` (e.g. `zzz`) | Silently treated as `all` — full result set. |
| Unknown `sort` (`zzzsortzzz`) | Silently treated as default sort order. |
| Unknown `country` / `network` | Silently treated as `all`. |

#### Errors

| Status | When |
|---|---|
| `412 client_id_failed` | Missing or invalid `client_id` |
| `500` | Server error |

No `400` or `404` — bad segments fall back silently or return `null`.




## OpenAPI

````yaml /openapi.json get /movies/genres/{genre}/{type}/{country}/{year}/{sort}
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 V2
    description: >-
      Standards-compliant OAuth 2.0 with PKCE, scopes and refresh tokens. The
      recommended way to authenticate new apps.
  - 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 (adjustable per call with `?min_progress=`) Simkl marks the
      item as watched automatically; below that 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.
  - name: Lists
    description: >-
      Custom lists, read-only and in beta. Requires a Simkl PRO or VIP access
      token.
externalDocs:
  description: Simkl API documentation
  url: https://api.simkl.org
paths:
  /movies/genres/{genre}/{type}/{country}/{year}/{sort}:
    get:
      tags:
        - Movies
      summary: Movies by genre
      description: >
        <Warning>

        **Not for TV / console / 10-foot apps.** The V1 genre-browse endpoints
        return a thin per-item shape (`title`, `year`, `poster`, `ids`,
        `ratings`, `rank`). Building a TV-app grid that shows overview text,
        full ratings, networks, runtimes, recommendations, or trailers would
        force one per-item refetch against the detail endpoint per visible card.
        **Wait for the V2 Beta API**, which returns the richer per-item shape
        TV-app surfaces need in a single call. If you're targeting TV / console
        / streaming-box clients, please hold off integrating these endpoints.

        </Warning>


        <Tip>

        **Just need this month's most watched titles in a genre? Use the
        [trending genre files](/api-reference/trending#by-genre-this-month)
        instead.** They are free: they don't count against any [rate
        limit](/resources/rate-limits#what-does-not-count) or a user's daily
        allowance, and they need no user token. Every call to this endpoint does
        count — against the user's daily allowance under [AUTH
        V2](/api-reference/auth-v2), where it also needs a user token, or your
        app's allowance under AUTH V1.


        A genre file is one cached request with no paging, and every item comes
        in the full trending shape (overview, trailer, ratings, runtime) rather
        than the thin shape above. Call this endpoint only for what the files
        don't cover: other sorts, the country / network / year filters, or
        anything beyond this month.

        </Tip>


        Browse movies filtered by genre, country, year, and sort order. Path is
        `/movies/genres/{genre}/{type}/{country}/{year}/{sort}` — all segments
        **required** (use `all` as the wildcard).


        The `type` segment is reserved — always pass the literal value `movies`.


        | Path param | Values |

        |---|---|

        | `genre` | `all`, `action`, `adventure`, `animation`, `comedy`,
        `crime`, `documentary`, `drama`, `erotica`, `family`, `fantasy`,
        `history`, `horror`, `music`, `mystery`, `romance`, `science-fiction`,
        `thriller`, `tv-movie`, `war`, `western` |

        | `type` | `movies` (literal) |

        | `country` | `all` or ISO 3166-1 alpha-2 (`us`, `gb`, `jp`, …) |

        | `year` | `all`, single year (`2019`), or decade (`2010s`, `2000s`) |

        | `sort` | `popular-this-week`, `popular-this-month`,
        `popular-all-time`, `rank`, `release-date`, `voted`, `watched` |


        Items always carry `ids.tmdb` — the discover query filters out movies
        without a TMDB-linked record.


        #### Pagination


        | Param | Default | Notes |

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

        | `page` | `1` | Hard-capped server-side at `20`. Higher values clamp
        silently. |

        | `limit` | `60` | Hard-capped server-side at `60`. Higher values clamp
        silently. Returned `X-Pagination-Limit` reflects the clamped value. |


        `X-Pagination-*` headers on every response — see
        [Pagination](/conventions/pagination).


        #### Silent fallbacks


        Bad path segments DO NOT return errors:


        | Bad input | What happens |

        |---|---|

        | Unknown `genre` slug (`zzz`) | Top-level response is `null` (NOT
        `[]`). |

        | Unknown `year` (e.g. `zzz`) | Silently treated as `all` — full result
        set. |

        | Unknown `sort` (`zzzsortzzz`) | Silently treated as default sort
        order. |

        | Unknown `country` / `network` | Silently treated as `all`. |


        #### Errors


        | Status | When |

        |---|---|

        | `412 client_id_failed` | Missing or invalid `client_id` |

        | `500` | Server error |


        No `400` or `404` — bad segments fall back silently or return `null`.
      operationId: get-movies-genres
      parameters:
        - name: genre
          in: path
          required: true
          schema:
            type: string
          example: action
          description: Movie genre slug, or `all`. See description for the full set.
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - movies
          example: movies
          description: Reserved — always pass the literal value `movies`.
        - name: country
          in: path
          required: true
          schema:
            type: string
          example: us
          description: ISO 3166-1 alpha-2 country code (e.g. `us`, `gb`, `jp`) or `all`.
        - name: year
          in: path
          required: true
          schema:
            type: string
          example: 2010s
          description: >-
            `all`, single year (`2019`), or decade (`2010s`, `2000s`). Bogus
            values silently fall back to `all`.
        - name: sort
          in: path
          required: true
          schema:
            type: string
            enum:
              - popular-this-week
              - popular-this-month
              - popular-all-time
              - rank
              - release-date
              - voted
              - watched
          example: popular-this-month
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitGenresParam'
        - $ref: '#/components/parameters/ClientIdQuery'
        - $ref: '#/components/parameters/AppNameQuery'
        - $ref: '#/components/parameters/AppVersionQuery'
        - $ref: '#/components/parameters/UserAgentHeader'
      responses:
        '200':
          description: OK
          headers:
            X-Pagination-Page:
              schema:
                type: string
              description: Current page (after clamp).
            X-Pagination-Limit:
              schema:
                type: string
              description: Items per page (after clamp; max 60).
            X-Pagination-Page-Count:
              schema:
                type: string
              description: Total number of pages.
            X-Pagination-Item-Count:
              schema:
                type: string
              description: Total number of items across all pages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenresResponse'
              examples:
                movies_action_us_popular_month:
                  summary: Action movies, US, popular this month (top 2)
                  value:
                    - title: 'Avengers: Endgame'
                      year: 2019
                      date: '2019-04-24T00:00:00-05:00'
                      url: /movies/430306/avengers-endgame
                      poster: 78/7850544702b693f1f
                      fanart: 78/7867760c274aa5240
                      ids:
                        simkl_id: 430306
                        slug: avengers-endgame
                        tmdb: '299534'
                      rank: 126
                      ratings:
                        simkl:
                          rating: 8.3
                          votes: 10198
                        imdb:
                          rating: 8.4
                          votes: 1446869
                    - title: Interstellar
                      year: 2014
                      date: '2014-11-05T00:00:00-05:00'
                      url: /movies/250822/interstellar
                      poster: 20/2052598c2716ef054
                      fanart: 17/1720484cee8bec79f
                      ids:
                        simkl_id: 250822
                        slug: interstellar
                        tmdb: '157336'
                      rank: 31
                      ratings:
                        simkl:
                          rating: 8.7
                          votes: 12036
                        imdb:
                          rating: 8.7
                          votes: 2530240
                movies_drama_gb_2010s_rank:
                  summary: British dramas from the 2010s sorted by rank (top 1)
                  value:
                    - title: The Phantom of the Opera at the Royal Albert Hall
                      year: 2011
                      date: '2011-09-27T00:00:00-05:00'
                      url: >-
                        /movies/161614/the-phantom-of-the-opera-at-the-royal-albert-hall
                      poster: 15/15249069a77e4555e5
                      fanart: 12/12549615b75d07856e
                      ids:
                        simkl_id: 161614
                        slug: the-phantom-of-the-opera-at-the-royal-albert-hall
                        tmdb: '76115'
                      rank: 37
                      ratings:
                        simkl:
                          rating: 8.5
                          votes: 128
                        imdb:
                          rating: 8.8
                          votes: 10845
                movies_bogus_genre_returns_null:
                  summary: Unknown genre slug — top-level `null` (NOT `[]`)
                  value: null
        '412':
          $ref: '#/components/responses/ClientIdFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - clientId: []
      x-codeSamples:
        - lang: Shell
          label: movies_action_us_popular_month
          source: |-
            curl -H "User-Agent: my-app-name/1.0" \
              "https://api.simkl.com/movies/genres/action/movies/us/all/popular-this-month?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0&limit=10"
        - lang: Shell
          label: movies_drama_gb_2010s_rank
          source: |-
            curl -H "User-Agent: my-app-name/1.0" \
              "https://api.simkl.com/movies/genres/drama/movies/gb/2010s/rank?client_id=YOUR_CLIENT_ID&app-name=my-app-name&app-version=1.0&limit=10"
components:
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      description: Page number for paginated endpoints (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
        maximum: 20
    LimitGenresParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 60
        default: 60
      description: Items per page. Capped at 60.
    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:
    GenresResponse:
      title: Discover response
      oneOf:
        - type: array
          items:
            $ref: '#/components/schemas/GenresItem'
          title: Array of items
        - type: 'null'
          title: No match
          description: >-
            Returned (status 200) when a path segment matches no records — most
            commonly an unknown `genre` slug.
    GenresItem:
      title: Discover entry
      type: object
      description: >-
        A single entry from any of the genre-filter endpoints (/movies/genres/*,
        /tv/genres/*, /anime/genres/*). All three share this shape via the same
        server-side handler. Per-type variations: anime items carry
        `anime_type`; movie items carry `ids.tmdb`.
      properties:
        title:
          type: string
          description: Display title.
        year:
          type:
            - integer
            - 'null'
          description: >-
            Premiere year (from the release date). **Type 4 null** when the
            catalog has no release date on file. See [Null and missing
            values](/conventions/null-values#type-4).
        date:
          type:
            - string
            - 'null'
          description: >-
            Release / first-air timestamp with the catalog's timezone offset
            (e.g. `2014-11-05T00:00:00-05:00` for US releases, `+09:00` for
            anime). **Type 4 null** when no release date is on file. See [Null
            and missing values](/conventions/null-values#type-4).
        url:
          type: string
          description: >-
            Relative simkl.com path with slug. Prepend `https://simkl.com` to
            deep-link. Each catalog uses its own prefix:
            `/movies/{simkl_id}/{slug}` for movies, `/tv/{simkl_id}/{slug}` for
            TV, `/anime/{simkl_id}/{slug}` for anime.
          example: /movies/430306/avengers-endgame
        poster:
          type:
            - string
            - 'null'
          description: >-
            Image path fragment. Combine with the prefixes in [Image
            conventions](/conventions/images) — for example
            `https://wsrv.nl/?url=https://simkl.in/posters/{poster}_m.webp&q=90`.
            **Type 4 null** when no poster on file. See [Null and missing
            values](/conventions/null-values#type-4).
        fanart:
          type:
            - string
            - 'null'
          description: >-
            Image path fragment for fanart. Combine with the prefixes in [Image
            conventions](/conventions/images) — for example
            `https://wsrv.nl/?url=https://simkl.in/fanart/{fanart}_medium.webp&q=90`.
            **Type 4 null** when no fanart on file. See [Null and missing
            values](/conventions/null-values#type-4).
        rank:
          type:
            - integer
            - 'null'
          description: >-
            Simkl popularity rank. **Type 4 null** when the item is not yet
            ranked or the catalog sentinel value (>= 999999) is present. See
            [Null and missing values](/conventions/null-values#type-4).
        ratings:
          type: object
          description: >-
            Aggregate ratings. Always carries `simkl`. TV / movies additionally
            carry `imdb`; anime carries `mal` instead.
          properties:
            simkl:
              $ref: '#/components/schemas/ExternalRating'
            imdb:
              $ref: '#/components/schemas/ExternalRating'
            mal:
              $ref: '#/components/schemas/ExternalRating'
        ids:
          type: object
          description: >-
            Identifier block. `simkl_id` + `slug` are always present. `tmdb`
            appears on movie items (the discover query requires a TMDB-linked
            record — items without one are filtered out).
          additionalProperties: true
          properties:
            simkl_id:
              type: integer
            slug:
              type: string
            tmdb:
              type: string
              description: Movie items only.
          required:
            - simkl_id
            - slug
        anime_type:
          type: string
          enum:
            - tv
            - movie
            - ova
            - ona
            - special
            - music
          description: '**Anime items only.** Catalog format.'
      required:
        - title
        - url
        - 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
    ExternalRating:
      type: object
      description: External-source rating.
      properties:
        rating:
          type: number
          minimum: 0
          maximum: 10
          description: Rating value (0–10).
        votes:
          type: integer
          description: Number of votes contributing to the rating.
  responses:
    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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.