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.
Kinds of List
Section titled “Kinds of List”kind | Holds | Limit |
|---|---|---|
assetList | Individual Assets (community images) | 1,000 images |
mediaList | Shows, Movies and Collections, each with one chosen image per position | 500 titles |
gameList | Games, each with one chosen image per position | 500 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.
| Route | Returns |
|---|---|
GET /account/lists | The user’s own Lists, then their subscriptions, cursor-paged |
GET /account/lists/membership?entity=movie:603 | Which 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.
Create and edit
Section titled “Create and edit”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}'| Route | Body |
|---|---|
POST /account/lists | name (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/remove | The 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
Section titled “Errors”Errors use the shared format. Besides the shared codes, List routes return:
| Code | Status | Meaning |
|---|---|---|
list.invalidInput | 400 | A field isn’t valid; see issues |
list.notFound | 404 | No List with this ID that the user owns or follows |
list.itemUnavailable | 404 | The title or Asset no longer exists |
list.itemIneligible | 409 | That item can’t go in this List |
list.kindMismatch | 409 | Wrong route for this kind of List |
list.subscriptionInvalid | 409 | You can’t subscribe to your own List; a private one is list.notFound |
list.limit.lists | 409 | The user already has 100 Lists |
list.limit.subscriptions | 409 | The user already follows 500 Lists |
list.limit.images | 409 | The Asset List is full |
list.limit.entities | 409 | The Media or Game List is full |
Every List response is Cache-Control: private, no-store.