# Read and edit Lists

> Read a user's Lists, check which hold a title, and create, edit and fill Lists for them.

The List routes act on the connected user's Lists under
`https://api.mediux.io/account/lists`. Reading needs the `lists:read`
[permission](https://docs-preview.mediux.io/api/authentication.md#permissions); 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](https://docs-preview.mediux.io/api/reference/lists.md).

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

## Read

| 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](https://docs-preview.mediux.io/api/pagination.md#protected-lists). Other reads take no query
string. Each route has a full page in the [Your Lists reference](https://docs-preview.mediux.io/api/reference/account-lists/list.md).

## Create and edit

```sh
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

Errors use the [shared format](https://docs-preview.mediux.io/api/errors.md#errors). 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`.
