# Protected API

> Read and manage one user's Lists, follows and notifications with their permission.

The Protected API lets your app act for one Mediux user, within the
[permissions](https://docs-preview.mediux.io/api/authentication.md#permissions) they approved. Routes live on
`https://api.mediux.io` under `/account`, `/notifications` and `/relationships`.

## Before you start

1. [Register your app and connect a user](https://docs-preview.mediux.io/api/authentication.md).
2. Call from your server or native app with
   `Authorization: Bearer ACCESS_TOKEN`. Never send Mediux cookies.
3. Keep tokens out of logs, source control and web pages.

Each request checks the connection, the granted permission and that the user
owns what you touch. You always act as the user who approved the token: an ID in
the request never changes whose data you change.

Apps can't publish or change artwork, Sets, Boxsets or Loadouts, delete Lists,
Like anything or manage the account. Owners do those on mediux.io.

Responses are `Cache-Control: private, no-store`, and errors use the
[shared error format](https://docs-preview.mediux.io/api/errors.md#errors). Send only the fields you change;
omitted fields stay as they are.

## Routes

| Area          | Routes                                                          | Permission                                     |
| ------------- | --------------------------------------------------------------- | ---------------------------------------------- |
| Identity      | [`GET /account`](https://docs-preview.mediux.io/api/reference/account-identity/get.md)          | Any                                            |
| Relationships | [Follows and hides](#all-operations) below                      | `relationships:read` or `relationships:manage` |
| Lists         | `/account/lists`, see [Read and edit Lists](https://docs-preview.mediux.io/api/guides/lists.md) | `lists:read` or `lists:write`                  |
| Notifications | [`GET /notifications`](https://docs-preview.mediux.io/api/reference/notifications/list.md), [`POST /notifications/read`](https://docs-preview.mediux.io/api/reference/notifications/mark-read.md) | `notifications:read` |

### Notifications

`GET /notifications` lists the user's notifications, newest first, paged with
`?after=` and `?limit=` (see [protected lists](https://docs-preview.mediux.io/api/pagination.md#protected-lists)).
`POST /notifications/read` marks them read: send `{ "ids": [...] }` with 1 to 100
IDs, or `{ "all": true }`. It answers `{ "data": { "markedRead": 3 } }`. IDs that
aren't the user's change nothing.

## All operations

### Relationships

- `GET /relationships`: [List relationships](https://docs-preview.mediux.io/api/reference/relationships/list.md)
- `PUT /relationships/{username}`: [Follow or hide a User](https://docs-preview.mediux.io/api/reference/relationships/set.md)
- `DELETE /relationships/{username}`: [Clear a relationship](https://docs-preview.mediux.io/api/reference/relationships/clear.md)

### Identity

- `GET /account`: [Get the connected User](https://docs-preview.mediux.io/api/reference/account-identity/get.md)

### Your Lists

- `GET /account/lists`: [List your Lists](https://docs-preview.mediux.io/api/reference/account-lists/list.md)
- `POST /account/lists`: [Create a List](https://docs-preview.mediux.io/api/reference/account-lists/create.md)
- `GET /account/lists/membership`: [Find your Lists holding a title](https://docs-preview.mediux.io/api/reference/account-lists/membership.md)
- `GET /account/lists/{id}`: [Get one of your Lists](https://docs-preview.mediux.io/api/reference/account-lists/retrieve.md)
- `PATCH /account/lists/{id}`: [Edit one of your Lists](https://docs-preview.mediux.io/api/reference/account-lists/update.md)
- `GET /account/lists/{id}/titles/{family}/{entity}`: [Get a title in one of your Lists](https://docs-preview.mediux.io/api/reference/account-lists/retrieve-title.md)
- `POST /account/lists/{id}/titles`: [Add titles to a List](https://docs-preview.mediux.io/api/reference/account-lists/add-titles.md)
- `POST /account/lists/{id}/titles/remove`: [Remove titles from a List](https://docs-preview.mediux.io/api/reference/account-lists/remove-titles.md)
- `POST /account/lists/{id}/assets`: [Add Assets to an Asset List](https://docs-preview.mediux.io/api/reference/account-lists/add-assets.md)
- `POST /account/lists/{id}/assets/remove`: [Remove Assets from an Asset List](https://docs-preview.mediux.io/api/reference/account-lists/remove-assets.md)
- `PUT /account/lists/{id}/subscription`: [Subscribe to or leave a Public List](https://docs-preview.mediux.io/api/reference/account-lists/set-subscription.md)

### Notifications

- `GET /notifications`: [List your Notifications](https://docs-preview.mediux.io/api/reference/notifications/list.md)
- `POST /notifications/read`: [Mark Notifications read](https://docs-preview.mediux.io/api/reference/notifications/mark-read.md)
