Skip to main content
POST
edit_list

Authorizations

Authorization
string
header
default:YOUR_ACCESS_TOKEN
required

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.

Headers

User-Agent
string
required

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

Path Parameters

id
integer
required

Numeric list ID.

Required range: x >= 1

Query Parameters

client_id
string
required

Your client_id from your Simkl developer settings. Required on every request.

app-name
string
required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

app-version
string
required

Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.

Body

application/json

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.

name
string

The list's title. Required on create.

Maximum string length: 255
Example:

"Movies to rewatch"

media_type
enum<string>

Create only, required. What the list holds, lower-case. It cannot change: sending it on an edit is a 400.

Available options:
movies,
tv,
anime
Example:

"movies"

privacy
enum<string>

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.

Available options:
public,
unlisted,
private
Example:

"public"

description
object

Send either key alone; the other is kept. "" clears one.

note
string

The owner's private note on the whole list — never shown to other users. "" clears it.

display_number

Show rank numbers beside the titles. A JSON boolean, or the strings "true" / "false".

Example:

true

sort
string[]

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.

Required array length: 1 - 2 elements
Example:
tags
string[]

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.

Maximum array length: 20
Maximum string length: 100
Example:
private_tags
string[]

Tags only the owner (and collaborators with private_tags) see. Same rules as tags, and also replaces the whole set.

Maximum array length: 20
Maximum string length: 100
Example:
collaborators
object[]

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.

Maximum array length: 10

Response

The list after the edit.

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.

id
integer
required

Numeric list ID -- the value to pass to GET /lists/{id}.

Example:

216282

name
string
required

The list's title.

Example:

"Regular TV list"

slug
string
required

URL-safe form of the name, for building a link to the list on simkl.com.

Example:

"regular-tv-list"

description
object
required

The list's blurb, in two lengths. Both are independently optional -- a list can have a short description and no full one, or neither.

media_type
enum<string>
required

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.

Available options:
movies,
tv,
anime,
manga,
characters,
companies
Example:

"tv"

type
enum<string>
required

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.

Available options:
regular,
auto,
favorite,
voting,
tier,
import,
recommendations
Example:

"regular"

privacy
enum<string>
required

Who can read the 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.

Available options:
public,
unlisted,
private
Example:

"public"

display_number
boolean
required

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
object
required

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.

counts
object
required

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.

top_items
object[]
required

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.

Maximum array length: 5
sort
string[]
required

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.

Required array length: 2 elements
Example:
updated_at
string<date-time>
required

When the list was last modified, UTC.

Example:

"2026-08-27T23:49:29Z"

created_at
string<date-time>
required

When the list was created, UTC.

Example:

"2025-02-03T14:41:56Z"

tags
string[]
required

Public tag names.

private_tags
string[] | null
required

Type 4 null — withheld from a caller without the private_tags permission. See Null and missing values. Private tag names.

note
string | null
required

Type 4 null — no note is set, or it is withheld from a caller without a notes permission. See Null and missing values. The owner's note on the list.

collaborators
object[]
required

Everyone the list is shared with.

role
enum<string>

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.

Available options:
owner,
collaborator,
follower
Example:

"owner"

collection
object | null

Only on GET /lists/{id}. The collection this list belongs to — its sibling lists sharing the same title, as described in Custom List Collections. Type 4 null — null when the list stands alone. See Null and missing values.

pinned
boolean

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.

Example:

false