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

# Add favorites

> **Beta, PRO and VIP.** Needs an [AUTH V2](/api-reference/auth-v2) token with the `media:write` [scope](/api-reference/oauth2-scopes), belonging to a Simkl **PRO or VIP** account. A free account gets `403 premium_only` here — a real error, unlike the `200` upgrade card that `GET /lists/{id}` returns. Full walkthrough: [Edit a custom list](/guides/custom-lists#edit-a-custom-list).

Favorites without a list ID — the heart on simkl.com. Each title goes to the caller's favorite list **of its own media type**, so one request may mix `movies`, `shows` and `anime`. A first favorite of a type creates that list (private if the account is private).

Same body and ordering rules as [adding to a list](/api-reference/simkl/add-list-items), including `user_position` and `?allow_reorder=yes`. The response carries a `lists` object — the favorite list of each type you touched, `null` for the others — instead of `list`. Favorites move the `favorites` bucket in [`/sync/activities`](/api-reference/simkl/get-activities).



## OpenAPI

````yaml /openapi.json post /lists/favorites
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, create and edit them. In beta. Requires an AUTH V2
      token for a Simkl PRO or VIP account.
externalDocs:
  description: Simkl API documentation
  url: https://api.simkl.org
paths:
  /lists/favorites:
    post:
      tags:
        - Lists
      summary: Add favorites
      description: >-
        **Beta, PRO and VIP.** Needs an [AUTH V2](/api-reference/auth-v2) token
        with the `media:write` [scope](/api-reference/oauth2-scopes), belonging
        to a Simkl **PRO or VIP** account. A free account gets `403
        premium_only` here — a real error, unlike the `200` upgrade card that
        `GET /lists/{id}` returns. Full walkthrough: [Edit a custom
        list](/guides/custom-lists#edit-a-custom-list).


        Favorites without a list ID — the heart on simkl.com. Each title goes to
        the caller's favorite list **of its own media type**, so one request may
        mix `movies`, `shows` and `anime`. A first favorite of a type creates
        that list (private if the account is private).


        Same body and ordering rules as [adding to a
        list](/api-reference/simkl/add-list-items), including `user_position`
        and `?allow_reorder=yes`. The response carries a `lists` object — the
        favorite list of each type you touched, `null` for the others — instead
        of `list`. Favorites move the `favorites` bucket in
        [`/sync/activities`](/api-reference/simkl/get-activities).
      operationId: add-favorites
      parameters:
        - name: allow_reorder
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'yes'
              - 'true'
              - '1'
          description: As on `POST /lists/{id}/items`.
        - $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/CustomListItemsRequest'
            examples:
              add_favorite:
                summary: Favorite a movie
                value:
                  movies:
                    - ids:
                        simkl: 53992
      responses:
        '200':
          description: Nothing was added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomListFavoritesResult'
        '201':
          description: At least one title was added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomListFavoritesResult'
              examples:
                add_favorite:
                  summary: Favorite a movie
                  description: >-
                    This account had no favorite movies list, so the request
                    created one; `tv` and `anime` are `null` because no title of
                    those types was sent.
                  value:
                    added: 1
                    updated: 0
                    existing: 0
                    not_found: []
                    wrong_type: []
                    lists:
                      movies:
                        id: 239308
                        counts:
                          items: 1
                          likes: 0
                          followers: 0
                          comments: 0
                          collaborators: 0
                        updated_at: '2026-11-13T16:58:42Z'
                      tv: null
                      anime: null
        '400':
          description: As for adding to a list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: empty_field
                code: 400
                message: Send movies, shows or anime
        '401':
          description: >-
            No usable token. `user_token_required` — no bearer from an AUTH V2
            app; `user_token_failed` — no bearer from an AUTH V1 app;
            `invalid_token` — the token expired or was revoked (refresh it).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: user_token_required
                code: 401
                message: This client_id requires a user access token on every request
        '403':
          description: >-
            Refused. `premium_only` — the account is free (or, when adding
            collaborators, not VIP). `oauth2_token_required` — an AUTH V1 token.
            `insufficient_scope` — the token lacks `media:write`. `max_items` —
            the favorite list is full for the plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: premium_only
                code: 403
                message: >-
                  Custom lists over the API are available to Simkl Pro and VIP
                  members only.
        '404':
          description: The path is not a list route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: url_failed
                code: 404
                message: This page is not found
        '405':
          description: >-
            Wrong verb for this path. The `Allow` header lists the right ones
            (`POST`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: method_not_allowed
                code: 405
                message: Use POST
          headers:
            Allow:
              description: The verbs this path accepts.
              schema:
                type: string
                example: POST
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: curl
          label: add_favorite
          source: >-
            curl -X POST
            'https://api.simkl.com/lists/favorites?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' \
              -H 'Content-Type: application/json' \
              -d '{
              "movies": [
                {
                  "ids": {
                    "simkl": 53992
                  }
                }
              ]
            }'
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:
    CustomListItemsRequest:
      type: object
      additionalProperties: false
      description: >-
        Up to 1000 titles per request across the three arrays. A title of the
        wrong media type for the list is not added; it is reported in
        `wrong_type`. `episodes` and `seasons` buckets are refused — lists hold
        whole titles.
      properties:
        movies:
          type: array
          items:
            $ref: '#/components/schemas/CustomListItemWrite'
        shows:
          type: array
          items:
            $ref: '#/components/schemas/CustomListItemWrite'
        anime:
          type: array
          items:
            $ref: '#/components/schemas/CustomListItemWrite'
    CustomListFavoritesResult:
      type: object
      required:
        - added
        - updated
        - existing
        - not_found
        - wrong_type
        - lists
      properties:
        added:
          type: integer
          description: Titles put on the list.
        updated:
          type: integer
          description: Titles already on the list that moved or got a changed note.
        existing:
          type: integer
          description: Titles already on the list that this request did not change.
        not_found:
          type: array
          items:
            type: object
          description: Titles that matched nothing, echoed as you sent them.
        wrong_type:
          type: array
          items:
            $ref: '#/components/schemas/CustomListWrongTypeItem'
        lists:
          type: object
          required:
            - movies
            - tv
            - anime
          description: >-
            The favorite list of each media type the request touched. See [Null
            and missing values](/conventions/null-values).
          properties:
            movies:
              oneOf:
                - $ref: '#/components/schemas/CustomListBlock'
                - type: 'null'
              description: '**Type 4 null** — the request had no movies title for that list.'
            tv:
              oneOf:
                - $ref: '#/components/schemas/CustomListBlock'
                - type: 'null'
              description: '**Type 4 null** — the request had no tv title for that list.'
            anime:
              oneOf:
                - $ref: '#/components/schemas/CustomListBlock'
                - type: 'null'
              description: '**Type 4 null** — the request had no anime title for that list.'
    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
    CustomListItemWrite:
      type: object
      description: >-
        One title, in the same shape `POST /sync/history` takes. Needs `ids`, or
        a `title` (with `year` to disambiguate).
      properties:
        ids:
          type: object
          description: >-
            Any ID Simkl knows: `simkl` (or `simkl_id`, as `GET /lists/{id}`
            returns it), `tmdb`, `imdb`, `tvdb`, `mal`, `anidb`, `anilist`,
            `kitsu`, and the rest of the [supported
            IDs](/conventions/standard-media-objects). `0` and `""` count as
            missing.
          additionalProperties:
            type:
              - string
              - integer
          properties:
            simkl:
              type: integer
              example: 53992
            simkl_id:
              type: integer
            tmdb:
              type:
                - string
                - integer
            imdb:
              type: string
        title:
          type: string
        year:
          type: integer
        user_position:
          type: integer
          minimum: 1
          description: >-
            Put the title at this place in the list's own order, 1-based — the
            number `GET /lists/{id}` returns as `user_position`. Past the end
            means the end; the titles after it shift down.
        season:
          type: integer
          minimum: 0
          description: >-
            **Anime only.** Add the entry that covers this season instead of the
            base title. `0` means no hint. Ignored for TV and movies.
        seasons:
          type: array
          maxItems: 100
          items:
            type: object
            properties:
              number:
                type: integer
                minimum: 0
          description: >-
            **Anime only.** Several seasons at once; each becomes its own entry,
            in season order.
        note:
          type: object
          description: >-
            Notes on this title. Trimmed, HTML removed, up to 4096 characters
            each. A note equal to the stored one is no change.
          properties:
            public:
              type: string
              description: Shown to everyone who can see the list.
            private:
              type: string
              description: >-
                Returned by `GET /lists/{id}` only to the owner and to
                collaborators with a notes permission.
    CustomListWrongTypeItem:
      type: object
      description: >-
        A posted title whose media type does not match the list, as posted plus
        the resolved Simkl ID and its `type`.
      properties:
        ids:
          type: object
          additionalProperties: true
          properties:
            simkl:
              type: integer
        type:
          type: string
          enum:
            - movie
            - tv
            - anime
          description: What the title actually is (singular, unlike a list's `media_type`).
      required:
        - ids
        - type
    CustomListBlock:
      type: object
      required:
        - id
        - counts
        - updated_at
      description: The list after the write.
      properties:
        id:
          type: integer
        counts:
          $ref: '#/components/schemas/CustomListCounts'
        updated_at:
          type: string
          format: date-time
          description: UTC. Unchanged when the request changed nothing.
    CustomListCounts:
      type: object
      description: >-
        Totals for the whole list, independent of the page you requested.
        `items` is the list's real size -- compare it with
        `pagination.total_items`, which reflects the current query.
      required:
        - items
        - likes
        - followers
        - comments
        - collaborators
      properties:
        items:
          type: integer
          description: Titles in the list.
          example: 222
        likes:
          type: integer
          description: Likes the list has received.
          example: 95
        followers:
          type: integer
          description: Users following the list.
          example: 104
        comments:
          type: integer
          description: Comments on the list.
          example: 0
        collaborators:
          type: integer
          description: Users who can edit the list besides the owner.
          example: 1
  responses:
    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
  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: >-
        A user `access_token`, sent as `Authorization: Bearer ...`. Required for
        endpoints that read or modify the user's library, scrobble session,
        ratings, settings, or playbacks. Every flow returns the same kind of
        token. See [Set up authentication](/api-reference/auth).
      x-default: YOUR_ACCESS_TOKEN

````

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