Skip to content
MediuxDocs

Read and edit Lists

The List routes act on the connected user’s Lists under https://api.mediux.io/account/lists. Reading needs the lists:read permission; changing anything needs lists:write, which includes read. Every request sends Authorization: Bearer ACCESS_TOKEN.

Apps never delete, clone or reorder a List, choose a title’s images, add a whole Set or handle Set suggestions, and can’t Like anything: the owner does those on mediux.io. Anyone’s Public Lists are also readable without a token through the public List endpoints.

kindHoldsLimit
assetListIndividual Assets (community images)1,000 images
mediaListShows, Movies and Collections, each with one chosen image per position500 titles
gameListGames, each with one chosen image per position500 titles

A user can own 100 Lists and subscribe to 500. List IDs are UUIDs. A title is { "kind": "show" | "movie" | "collection" | "game", "id": 1399 }, with its Mediux ID.

RouteReturns
GET /account/listsThe user’s own Lists, then their subscriptions, cursor-paged
GET /account/lists/membership?entity=movie:603Which of their Media and Game Lists hold a title
GET /account/lists/{list}One List, private ones included, in the public List shape
GET /account/lists/{list}/titles/{family}/{id}One title in a List; family is shows, movies, collections or games

Page GET /account/lists with ?after= and ?limit=; see protected lists. Other reads take no query string. Each route has a full page in the Your Lists reference.

Terminal window
curl --request POST https://api.mediux.io/account/lists \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"name": "Watching", "kind": "mediaList", "isPublic": false}'
RouteBody
POST /account/listsname (up to 80 characters), kind, optional description (up to 500) and isPublic (default false)
PATCH /account/lists/{list}Any of name, description and isPublic
POST /account/lists/{list}/titles{ "titles": [...] }: add up to 500 titles (16 KiB body) to a Media or Game List
POST /account/lists/{list}/titles/remove{ "titles": [...] }: remove them
POST /account/lists/{list}/assets{ "items": [{ "kind": "asset", "id": "..." }] }: add up to 100 Assets to an Asset List
POST /account/lists/{list}/assets/removeThe same shape: remove them
PUT /account/lists/{list}/subscription{ "subscribed": true } to follow someone else’s Public List, false to leave it

A title added to a Media or Game List starts with no image chosen; the owner picks images on mediux.io. If any title in the request isn’t on Mediux yet, the whole request is refused with 404 list.itemUnavailable and nothing is added.

Add and remove requests answer only the change: { "added": 2, "existing": 1 } or { "removed": 2 }. A subscription answers { "subscribed", "changed", "subscriberCount" }, and create and edit answer the List, whose itemCount and subscriberCount give the current totals.

Making a List public or private takes effect straight away. Other changes to a Public List can take up to an hour to show on the public endpoints.

Errors use the shared format. Besides the shared codes, List routes return:

CodeStatusMeaning
list.invalidInput400A field isn’t valid; see issues
list.notFound404No List with this ID that the user owns or follows
list.itemUnavailable404The title or Asset no longer exists
list.itemIneligible409That item can’t go in this List
list.kindMismatch409Wrong route for this kind of List
list.subscriptionInvalid409You can’t subscribe to your own List; a private one is list.notFound
list.limit.lists409The user already has 100 Lists
list.limit.subscriptions409The user already follows 500 Lists
list.limit.images409The Asset List is full
list.limit.entities409The Media or Game List is full

Every List response is Cache-Control: private, no-store.