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

# Edit a custom list

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

Changes a list's details. **Send only what changes** — keys you leave out are kept, and an edit that changes nothing is still a `200`. `media_type` cannot be changed. Titles are edited with [`POST /lists/{id}/items`](/api-reference/simkl/add-list-items), not here.

<Note>
**`tags`, `private_tags` and `collaborators` replace the whole set.** Sending `"tags": ["new"]` leaves only `new`. To add one, read the current set from [`GET /lists/{id}`](/api-reference/simkl/get-list) and send it back with the addition.
</Note>

**Who may edit.** The owner, or a collaborator with the permission for each key sent: `name` needs `title`, `privacy` → `privacy`, `description` → `description`, `note` → `edit_private_notes`, `display_number` → `list_type` or `add`, `sort` → `default_sort`, `tags` → `public_tags`, `private_tags` → `private_tags`, `collaborators` → `full`. A missing permission is `403 no_access` naming the key.

**List types.** A recommendation list keeps its name and takes no collaborators; a favorite list takes no collaborators; an auto list keeps its own sort. Each is `400 list_error`.

**Activity.** Any change moves `custom_lists` in [`/sync/activities`](/api-reference/simkl/get-activities); an edit that changes nothing does not. Save the new timestamps after writing, so your next check does not refetch the list you just changed — see [Syncing lists from a background service](/guides/custom-lists#syncing-lists-from-a-service).



## OpenAPI

````yaml /openapi.json post /lists/{id}
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/{id}:
    post:
      tags:
        - Lists
      summary: Edit a custom list
      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).


        Changes a list's details. **Send only what changes** — keys you leave
        out are kept, and an edit that changes nothing is still a `200`.
        `media_type` cannot be changed. Titles are edited with [`POST
        /lists/{id}/items`](/api-reference/simkl/add-list-items), not here.


        <Note>

        **`tags`, `private_tags` and `collaborators` replace the whole set.**
        Sending `"tags": ["new"]` leaves only `new`. To add one, read the
        current set from [`GET /lists/{id}`](/api-reference/simkl/get-list) and
        send it back with the addition.

        </Note>


        **Who may edit.** The owner, or a collaborator with the permission for
        each key sent: `name` needs `title`, `privacy` → `privacy`,
        `description` → `description`, `note` → `edit_private_notes`,
        `display_number` → `list_type` or `add`, `sort` → `default_sort`, `tags`
        → `public_tags`, `private_tags` → `private_tags`, `collaborators` →
        `full`. A missing permission is `403 no_access` naming the key.


        **List types.** A recommendation list keeps its name and takes no
        collaborators; a favorite list takes no collaborators; an auto list
        keeps its own sort. Each is `400 list_error`.


        **Activity.** Any change moves `custom_lists` in
        [`/sync/activities`](/api-reference/simkl/get-activities); an edit that
        changes nothing does not. Save the new timestamps after writing, so your
        next check does not refetch the list you just changed — see [Syncing
        lists from a background
        service](/guides/custom-lists#syncing-lists-from-a-service).
      operationId: update-list
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
          description: Numeric list ID.
          example: 239084
        - $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/CustomListWriteRequest'
            examples:
              edit_list:
                summary: Rename, make private, change the order and clear the tags
                value:
                  name: Movies to rewatch in 2027
                  privacy: private
                  display_number: 'false'
                  sort:
                    - position
                    - asc
                  description:
                    short: Next year's comfort films
                  tags: []
                  note: ''
      responses:
        '200':
          description: The list after the edit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomListWriteResponse'
              examples:
                edit_list:
                  summary: Rename, make private, change the order and clear the tags
                  description: >-
                    Only the keys sent change: `description.full` and
                    `private_tags` are kept. `tags: []` cleared the tags and
                    `note: ""` the note.
                  value:
                    id: 239498
                    name: Movies to rewatch in 2027
                    slug: movies-to-rewatch-in-2027
                    description:
                      short: Next year's comfort films
                      full: Films I come back to every year.
                    media_type: movies
                    type: regular
                    privacy: private
                    display_number: false
                    user:
                      id: 8199460
                      name: testweek
                      avatar: https://us.simkl.in/img_tv/ico_profile_guest.png
                    counts:
                      items: 0
                      likes: 0
                      followers: 0
                      comments: 0
                      collaborators: 0
                    top_items: []
                    sort:
                      - position
                      - asc
                    updated_at: '2026-11-14T06:10:24Z'
                    created_at: '2026-11-14T06:10:23Z'
                    tags: []
                    private_tags:
                      - weekend
                    note: null
                    collaborators: []
        '400':
          description: >-
            The body was refused; nothing changed. `empty_field` — the body is
            empty. `wrong_parameter` — as for create, plus `media_type cannot be
            changed`. `list_error` — not allowed on this kind of list.
            `invalid_request` — the body is not JSON. `rate_limit` — *Your lists
            are being updated, try again in a minute*: another write for this
            user is still running. Writes for one user run one at a time; retry
            after a moment, never in parallel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: wrong_parameter
                code: 400
                message: media_type cannot be changed
        '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`. `private_list`
            — a private list you are not on. `no_access` — a collaborator
            without the permission for a key (the message names it).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: no_access
                code: 403
                message: No permission to change name
        '404':
          description: No such list (`List not found`), or the path is not a list route.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: url_failed
                code: 404
                message: List not found
        '405':
          description: >-
            Wrong verb for this path. The `Allow` header lists the right ones
            (`GET, POST, DELETE`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: method_not_allowed
                code: 405
                message: Use GET, POST, DELETE
          headers:
            Allow:
              description: The verbs this path accepts.
              schema:
                type: string
                example: GET, POST, DELETE
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: curl
          label: edit_list
          source: >-
            curl -X POST
            'https://api.simkl.com/lists/239084?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 '{
              "name": "Movies to rewatch in 2027",
              "privacy": "private",
              "display_number": "false",
              "sort": [
                "position",
                "asc"
              ],
              "description": {
                "short": "Next year'\''s comfort films"
              },
              "tags": [],
              "note": ""
            }'
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:
    CustomListWriteRequest:
      type: object
      additionalProperties: false
      description: >-
        Body of `POST /lists` and `POST /lists/{id}`. On create, `name` and
        `media_type` are required. On an edit, send only what changes; every
        other key is left as it is. An unknown key is a `400` naming it. Text is
        trimmed and HTML tags are removed.
      properties:
        name:
          type: string
          maxLength: 255
          description: The list's title. **Required on create.**
          example: Movies to rewatch
        media_type:
          type: string
          enum:
            - movies
            - tv
            - anime
          description: >-
            **Create only, required.** What the list holds, lower-case. It
            cannot change: sending it on an edit is a `400`.
          example: movies
        privacy:
          type: string
          enum:
            - public
            - unlisted
            - private
          description: >-
            Who can read the list. **Public is the default:** a list created
            without `privacy` is public, and your create form should preselect
            Public too. `unlisted` and `private` are for when the user picks
            them. On an edit, leaving it out keeps the current value. See [What
            `privacy`
            controls](/guides/custom-lists#what-privacy-actually-controls).
          example: public
        description:
          type: object
          additionalProperties: false
          description: Send either key alone; the other is kept. `""` clears one.
          properties:
            short:
              type: string
              maxLength: 140
              description: One line, up to 140 characters.
            full:
              type: string
              description: Longer text.
        note:
          type: string
          description: >-
            The owner's private note on the whole list — never shown to other
            users. `""` clears it.
        display_number:
          oneOf:
            - type: boolean
            - type: string
              enum:
                - 'true'
                - 'false'
          description: >-
            Show rank numbers beside the titles. A JSON boolean, or the strings
            `"true"` / `"false"`.
          example: true
        sort:
          type: array
          minItems: 1
          maxItems: 2
          items:
            type: string
          description: >-
            The list's own order, `[token, direction]` — direction `asc` (the
            default) or `desc`. `["position", "asc"]` is the manual order you
            set with `POST /lists/{id}/items`. **The token is not checked
            against the sorts simkl.com offers**: any short lower-case token
            (`a-z`, `0-9`, `_`, `-`) is saved, and one that means nothing orders
            the list by a fallback. Refused on auto lists.
          example:
            - rating
            - desc
        tags:
          type: array
          maxItems: 20
          items:
            type: string
            maxLength: 100
          description: >-
            Public tags. **Replaces the whole set** — send every tag the list
            should keep; `[]` removes them all. Up to 20, each up to 100
            characters, without emoji, quotes, `<`, `>` or commas. Case and
            accents are ignored when matching, so `Dup` and `dup` are one tag.
          example:
            - comfort
        private_tags:
          type: array
          maxItems: 20
          items:
            type: string
            maxLength: 100
          description: >-
            Tags only the owner (and collaborators with `private_tags`) see.
            Same rules as `tags`, and also **replaces the whole set**.
          example:
            - weekend
        collaborators:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/CustomListCollaboratorWrite'
          description: >-
            **Replaces the whole set**: anyone left out is removed, `[]` removes
            everyone. Re-sending a collaborator with other permissions changes
            them in place. Adding someone new needs a **VIP** account and that
            you follow them. Refused on favorite and recommendation lists. Up to
            10.
    CustomListWriteResponse:
      allOf:
        - $ref: '#/components/schemas/CustomList'
        - $ref: '#/components/schemas/CustomListDetails'
    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
    CustomListCollaboratorWrite:
      type: object
      required:
        - user
      additionalProperties: false
      properties:
        user:
          type: integer
          minimum: 1
          description: >-
            Simkl user ID. Not the owner, and someone the caller follows on
            Simkl.
          example: 8199460
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/CustomListPermission'
          description: >-
            What they may do. Omitted or `[]` = read access only (they can open
            a private list).
          example:
            - add
            - rearrange
    CustomList:
      type: object
      description: >-
        A custom list's metadata. Returned on its own inside `lists[]` by `GET
        /lists/user/{userId}`, and merged alongside `pagination` and `items` by
        `GET /lists/{id}`.
      required:
        - id
        - name
        - slug
        - description
        - media_type
        - type
        - privacy
        - display_number
        - user
        - counts
        - top_items
        - sort
        - updated_at
        - created_at
      properties:
        id:
          type: integer
          description: Numeric list ID -- the value to pass to `GET /lists/{id}`.
          example: 216282
        name:
          type: string
          description: The list's title.
          example: Regular TV list
        slug:
          type: string
          description: >-
            URL-safe form of the name, for building a link to the list on
            simkl.com.
          example: regular-tv-list
        description:
          $ref: '#/components/schemas/CustomListDescription'
        media_type:
          type: string
          enum:
            - movies
            - tv
            - anime
            - manga
            - characters
            - companies
          description: >-
            What kind of title the list holds. A list is single-type. `movies`,
            `tv` and `anime` are the values you will see through the API today;
            the rest exist on Simkl but are not yet exposed here.
          example: tv
        type:
          type: string
          enum:
            - regular
            - auto
            - favorite
            - voting
            - tier
            - import
            - recommendations
          description: >-
            How the list is built. `regular` is hand-curated. `auto` is a saved
            Discover filter, so its contents change on their own and its
            `counts.items` can be very large. The rest are specialised list
            kinds.
          example: regular
        privacy:
          type: string
          enum:
            - public
            - unlisted
            - private
          description: >-
            Who can read the list.


            | Value | Global browse | `GET /lists/user/{userId}` | Read by ID |

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

            | `public` | listed | anyone | anyone |

            | `unlisted` | hidden | **owner only** | anyone holding the ID |

            | `private` | hidden | owner and collaborators | owner and
            collaborators, else `403 private_list` |


            **`unlisted` means reachable by link but not enumerable.** Someone
            with the list ID can read it, but it will not appear when you list
            that user's lists -- only the owner sees their own unlisted lists
            there. So a library view built from `GET /lists/user/{userId}` shows
            public lists for other people, and public plus unlisted plus private
            for the signed-in user.
          example: public
        display_number:
          type: boolean
          description: >-
            Whether the owner wants positions shown as visible rank numbers when
            the list is displayed. Presentation only -- it does not affect
            ordering.
          example: false
        user:
          $ref: '#/components/schemas/CustomListUser'
        counts:
          $ref: '#/components/schemas/CustomListCounts'
        top_items:
          type: array
          description: >-
            Up to **five** preview entries for rendering a list card, in list
            order. Populated by `GET /lists/user/{userId}`; **always empty on
            `GET /lists/{id}`**, which returns the real `items` array instead.


            Fewer than five entries means fewer than five of the list's titles
            can be previewed -- a title with no poster on file is skipped rather
            than returned without one. `top_items` is a preview strip, not a
            count of anything: use `counts` for totals.
          items:
            $ref: '#/components/schemas/CustomListTopItem'
          maxItems: 5
        sort:
          type: array
          description: >-
            The ordering actually used for this response, as `[token,
            direction]`. With no `?sort` this is the list's own stored order.
            Note that an unrecognised `?sort` token is echoed back here
            verbatim, so this field confirms what you asked for rather than what
            was applied.
          minItems: 2
          maxItems: 2
          items:
            type: string
          example:
            - position
            - asc
        updated_at:
          type: string
          format: date-time
          description: When the list was last modified, UTC.
          example: '2026-08-27T23:49:29Z'
        created_at:
          type: string
          format: date-time
          description: When the list was created, UTC.
          example: '2025-02-03T14:41:56Z'
        role:
          type: string
          enum:
            - owner
            - collaborator
            - follower
          description: >-
            **Only on `GET /lists/user/{userId}`.** How `{userId}` relates to
            this list: they own it, collaborate on it, or follow it. Followed
            and collaborated lists both carry another person's `user`, so this
            is the way to tell them apart.


            `collaborator` is only reported with `collaborants=true`. A list the
            user both collaborates on and follows reads `follower` when only
            `followed=true` is set.
          example: owner
        collection:
          oneOf:
            - $ref: '#/components/schemas/CustomListCollection'
            - type: 'null'
          description: >-
            **Only on `GET /lists/{id}`.** The collection this list belongs to —
            its sibling lists sharing the same title, as described in [Custom
            List
            Collections](https://docs.simkl.org/how-to-use-simkl/core-features/watchlists-and-custom-lists/custom-lists/custom-list-collections).
            **Type 4 null** — `null` when the list stands alone. See [Null and
            missing values](/conventions/null-values).
        pinned:
          type: boolean
          description: >-
            Whether the owner has pinned this list. **Type 2 null** -- this
            field is omitted entirely unless you are reading your own library,
            so treat a missing `pinned` as "not applicable" rather than `false`.
            See [Null and missing values](/conventions/null-values).
          example: false
    CustomListDetails:
      type: object
      required:
        - tags
        - private_tags
        - note
        - collaborators
      description: >-
        Returned by `GET /lists/{id}` and by create and edit — not by `GET
        /lists/user/{userId}`. What you see depends on who you are: the owner
        sees everything; a collaborator sees `private_tags` with the
        `private_tags` (or `full`) permission and `note` with a notes
        permission; anyone else sees the public `tags` and who the collaborators
        are, without their permissions.
      properties:
        tags:
          type: array
          items:
            type: string
          description: Public tag names.
        private_tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >-
            Type 4 null — withheld from a caller without the `private_tags`
            permission. See [Null and missing values](/conventions/null-values).
            Private tag names.
        note:
          type:
            - string
            - 'null'
          description: >-
            Type 4 null — no note is set, or it is withheld from a caller
            without a notes permission. See [Null and missing
            values](/conventions/null-values). The owner's note on the list.
        collaborators:
          type: array
          items:
            $ref: '#/components/schemas/CustomListCollaborator'
          description: Everyone the list is shared with.
    CustomListPermission:
      type: string
      enum:
        - full
        - privacy
        - list_type
        - default_sort
        - title
        - description
        - public_tags
        - private_tags
        - background
        - add
        - suggest
        - delete
        - rearrange
        - import
        - public_notes
        - read_private_notes
        - edit_private_notes
        - comments
      description: >-
        One collaborator permission.


        | Permission | Grants |

        |---|---|

        | `full` | Everything the owner can do, including deleting the list and
        managing collaborators. |

        | `privacy` | Change `privacy`. |

        | `list_type` | Change `display_number` (so does `add`). |

        | `default_sort` | Change `sort`. |

        | `title` | Rename the list. |

        | `description` | Change `description`. |

        | `public_tags` | Change `tags`. |

        | `private_tags` | Change and read `private_tags`. |

        | `background` | Change the list's background on simkl.com. |

        | `add` | Add titles. |

        | `suggest` | Suggest titles on simkl.com. |

        | `delete` | Remove titles. |

        | `rearrange` | Change the order of titles already on the list. |

        | `import` | Import titles on simkl.com. |

        | `public_notes` | Write public item notes. |

        | `read_private_notes` | Read the list's `note`. |

        | `edit_private_notes` | Write the list's `note` and private item notes.
        |

        | `comments` | Moderate comments on simkl.com. |
    CustomListDescription:
      type: object
      description: >-
        The list's blurb, in two lengths. Both are independently optional -- a
        list can have a short description and no full one, or neither.
      required:
        - short
        - full
      properties:
        short:
          type:
            - string
            - 'null'
          description: >-
            Type 4 null -- the owner has not written a short description. See
            [Null and missing values](/conventions/null-values).
          example: >-
            Some anime entertain. These ones break your brain, reconstruct it,
            then break it again.
        full:
          type:
            - string
            - 'null'
          description: >-
            Type 4 null -- the owner has not written a full description. See
            [Null and missing values](/conventions/null-values). May contain
            newlines.
          example: >-
            Ever watched an anime that left you staring at the screen in shock?


            From psychological labyrinths to existential nightmares, these anime
            are designed to mess with your mind.
    CustomListUser:
      type: object
      description: >-
        The list's owner. On `GET /lists/user/{userId}` a followed or
        collaborated list carries its own owner here, not the user whose library
        you asked for.
      required:
        - id
        - name
        - avatar
      properties:
        id:
          type: integer
          description: The owner's Simkl user ID.
          example: 5
        name:
          type: string
          description: The owner's display name.
          example: SIMKL
        avatar:
          type: string
          description: >-
            Absolute URL to the owner's avatar at 100px. Users with no avatar of
            their own get the shared placeholder.
          example: https://simkl.in/avatars/5/5_100.jpg?1682980938
    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
    CustomListTopItem:
      type: object
      description: >-
        A poster-only preview entry, enough to render a list card without
        fetching the list itself.
      required:
        - id
        - type
        - poster
      properties:
        id:
          type: integer
          description: Simkl ID of the title.
          example: 50250
        type:
          type: string
          enum:
            - movie
            - tv
            - anime
          description: Media type of this title.
          example: anime
        poster:
          type: string
          description: >-
            Poster path -- see [Images](/conventions/images) for how to turn it
            into a URL. Never null here: an item with no poster on file is
            skipped rather than returned with an empty one, so every entry in
            `top_items` is renderable.
          example: 83/83063509ab6ef28d2
    CustomListCollection:
      type: object
      description: >-
        A set of the owner's lists that belong together — the buttons shown
        above a list on simkl.com. A user builds one by giving their lists the
        same title, each ending in a different label in parentheses: `Star Wars
        Franchise (Movies)` and `Star Wars Franchise (TV Shows)`. The label can
        be anything — a media type, a year, a genre. For a favourites list, the
        collection is the owner's other favourites lists. See [Custom List
        Collections](https://docs.simkl.org/how-to-use-simkl/core-features/watchlists-and-custom-lists/custom-lists/custom-list-collections)
        for how users create them.
      properties:
        name:
          type: string
          description: The collection's name.
          example: Star Wars Franchise
        lists:
          type: array
          description: Every list in the collection, **including the one you requested**.
          items:
            type: object
            properties:
              id:
                type: integer
                description: List id — fetch it with `GET /lists/{id}`.
                example: 2731
              name:
                type: string
                description: >-
                  This list's label within the collection — the text in
                  parentheses at the end of its title, not the list's full name.
                example: Movies
              media_type:
                type: string
                enum:
                  - movies
                  - tv
                  - anime
                example: movies
    CustomListCollaborator:
      type: object
      required:
        - user
        - permissions
      properties:
        user:
          $ref: '#/components/schemas/CustomListUser'
        permissions:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CustomListPermission'
          description: >-
            Type 4 null — withheld from a caller who is not on the list. See
            [Null and missing values](/conventions/null-values). What this
            collaborator may do.
  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.