GET /api/v1/lists

listMyList

needs lists:read

It used to answer the whole thing, which is the bug this api's own rules already name: a caller with four hundred titles got four hundred rows and a caller with four thousand got four thousand, and the only reason nobody was hurt by it is that nobody was using this door. `total` is beside the items because the paging is by offset, which is exactly when a caller has to know how far the list goes.

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

Asking #

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 #