Add or reorder titles in 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.
Adds titles, moves them and sets their notes — one request for all three. The body is the /sync/history shape: movies, shows and anime arrays, up to 1000 titles.
Returns 201 when at least one title was added, otherwise 200, with counters: added, updated (moved, or a note changed) and existing (already there, untouched), plus not_found, wrong_type and the list’s new counts.
Order
- New titles go to the end, in the order posted.
- Titles already on the list stay where they are — a note edit or a re-post never moves them.
user_positionputs a title at that place (1-based); the rest shift down. Past the end means the end.- With
?allow_reorder=yesthe posted order counts too: a title posted after one that sits later moves to right after it. Posting C then A to a list ordered A, B, C gives B, C, A.
Types
The list holds one media type. A title of another type is not added; it comes back in wrong_type with its Simkl ID and real type. An anime posted under shows is still anime. For anime, season or seasons adds the entry that covers that season; a season no entry covers puts the title in not_found.
Who may write
The owner, or a collaborator with add (new titles), rearrange (moving titles already there, with user_position or allow_reorder), public_notes and edit_private_notes (notes). Auto lists take no titles (400 list_error). Plan limits apply to the owner’s plan: 2,000 titles per list on PRO, 10,000 on VIP (403 max_items), and a total across all lists (403 max_items_total).
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
Response
Nothing was added (titles moved, notes changed, or nothing changed).