Create a custom list
Beta, PRO and VIP. Needs an AUTH V2 token with the media:write scope, 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.
Creates a list owned by the caller. name and media_type are required; media_type cannot change later.
Returns 201 with the new list: the same fields as GET /lists/{id} (without items), plus tags, private_tags, note and collaborators. Add titles with POST /lists/{id}/items.
Plan limits apply when the list is created: 30 lists on PRO, 1,000 on VIP (403 max_lists). See Account limits.
Authorizations
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
Body
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.
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.
public, unlisted, private "public"
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.
1 - 2 elementsPublic 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.
20100Replaces 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.
10Response
Created.
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.
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.
regular, auto, favorite, voting, tier, import, recommendations "regular"
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.
public, unlisted, private "public"
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.
5The 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.
2 elementsType 4 null — withheld from a caller without the private_tags permission. See Null and missing values. Private tag names.
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.
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.
owner, collaborator, follower "owner"
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.
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.
false