GET /api/v1/users/{nick}/lists

userLists

needs people:read

curl https://api.acyka.cc/api/v1/users/someone/lists?status=watching&limit=10 \
  -H "Authorization: Bearer $ACYKA_TOKEN"

Asking #

In the address

field	type	what it is
`nick`	`string`	a nickname the account answers to, current or past

Narrowing it

field	type	what it is
`status` may be absent	`string \| undefined`	narrow to one shelf: `planned` \| `watching` \| `rewatching` \| `paused` \| `done` \| `dropped`
`limit` may be absent	`number \| undefined`	how many rows, 1-100; 30 by default
`offset` may be absent	`number \| undefined`	where to carry on from

Answering #

200 Page<ListEntry> a page: items, and total beside it

It pages by limit and offset. Every library has a paginator that walks it — see Paging, which is also where the reason it stops on a short page rather than on total is written down.

The shapes #

`ListEntry` #

One row of somebody's list.

One shape for a caller's own list and for somebody else's, because it is one thing. Two shapes differing by a field would be two unwrappers in every SDK for a row that means exactly the same in both places.

field	type	what it is
`shikimori_id`	`number`
`title`	`string`
`poster` may be absent	`string \| undefined`
`status`	`string`	`planned` \| `watching` \| `rewatching` \| `paused` \| `done` \| `dropped`
`episode`	`number`	how many they have watched
`episodes` may be absent	`number \| undefined`	How many the catalogue holds, so a counter knows where the series stops. Absent where the catalogue does not carry it or does not know — an announcement, and a good half of what is airing — and absent means "no ceiling" rather than "none".
`score` may be absent	`number \| undefined`	what they thought of it; null for a title they have not judged
`at`	`string`	RFC 3339, and a string rather than a timestamp type for a reason that is about having one shape: this row comes from two places, and the site's own reader already formats it. A parse on this side to fit a stricter type would need something to do when it failed, and every honest answer to that is a lie about when somebody watched something.

When it says no #

A refusal is { "message": "errors.something" } — a phrase name and never a sentence, because one screen can be read in five languages. Every library turns the name into a type, so you catch the class you can do something about. Errors has the list.