List library works
const url = 'https://example.com/api/v1/libraries/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/works?sort=title&played=unplayed&matchState=matched';const options = {method: 'GET', headers: {cookie: 'kivo_session=<kivo_session>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/api/v1/libraries/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/works?sort=title&played=unplayed&matchState=matched' \ --cookie kivo_session=<kivo_session>The library’s top-level items, sorted and filtered. A movies library lists movies, with versions never shown separately; a shows library lists series; a videos library lists videos; an audiobooks library lists books.
A grid, paged by offset, with total on every page; works with
the same sort key are listed by title. The first page (offset 0) of
the title sort also has letters.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A UUIDv7.
Query Parameters
Section titled “Query Parameters”The order of a library’s grid (listLibraryWorks).
Default title. Each sort has one direction: title A to Z
ignoring leading articles, author A to Z by the first author’s
name (an audiobooks library; then by title, books with no author
first), runtime shortest first, the rest newest or highest
first. lastEpisodeAddedAt puts the series whose newest episode in
the library was added most recently first (a shows library; then
by title). rating is the community rating weighted by its vote
count (as if 50 more votes of 6.5 were cast), so a root work few
people rated ranks below a well-rated one many people rated;
myRating is the user’s own rating. Works without the rating
come last, by title.
Works by the user’s state for them, as the grid’s filter asks.
Any of these genres.
The first year, inclusive.
The last year, inclusive.
Any of these content ratings (see WorkSummary.contentRating).
Any of these resolutions.
Any of these dynamic ranges.
Only the user’s favorites.
A UUIDv7.
The books this person narrated.
Whether a work is identified: identifying is provisional, its first
identification pending, and unmatched provisional with no confident
match. Provisional items are playable.
Admins only (ignored for others). Only unmatched is taken, for unmatched items only.
How many items to skip from the start.
Page size. The default and the most a page holds depend on the listing.
Responses
Section titled “Responses”A page of summaries.
A page of a grid of works.
object
The work’s summary, with its artwork; absent for a work the admin may not see.
object
A UUIDv7.
What a work is: video an item of a videos library and book an
item of an audiobooks library. Skip kinds you don’t know.
The default version’s duration.
TMDb’s community rating of a movie, series or episode: the average of its users’ votes, 0 to 10. Absent when it has no votes.
How many votes communityRating averages.
The content rating for the server’s content rating country, such as
PG-13 or TV-MA; absent when unrated. On the detail page, a
season or episode without one has its series’.
Whether a work is identified: identifying is provisional, its first
identification pending, and unmatched provisional with no confident
match. Provisional items are playable.
False when every version’s folder is unreachable.
object
Fetch with GET /api/v1/images/{id}?width=….
object
A UUIDv7.
The largest stored width.
Fetch with GET /api/v1/images/{id}?width=….
object
A UUIDv7.
The largest stored width.
An episode’s or video’s frame, for landscape cards.
object
A UUIDv7.
The largest stored width.
Fetch with GET /api/v1/images/{id}?width=….
object
A UUIDv7.
The largest stored width.
The user’s state for a work. For a series or season, played means every episode is.
object
The resume position, when in progress.
The version last played, which positionMs is on; it may be
gone. Resume continues its edition, and a version of another
edition starts from the beginning.
object
The label the movie’s folder’s edition tag gives it, such as Final Cut. Shown after the title wherever it appears.
object
Detail only.
Unplayed episodes.
In Recently Added, the episodes this summary bundles.
Detail only. Documented values aired, dvd, absolute, or group:<provider episode group ID>.
Detail only. The episode the primary button plays.
object
A UUIDv7.
What a work is: video an item of a videos library and book an
item of an audiobooks library. Skip kinds you don’t know.
The default version’s duration.
TMDb’s community rating of a movie, series or episode: the average of its users’ votes, 0 to 10. Absent when it has no votes.
How many votes communityRating averages.
The content rating for the server’s content rating country, such as
PG-13 or TV-MA; absent when unrated. On the detail page, a
season or episode without one has its series’.
Whether a work is identified: identifying is provisional, its first
identification pending, and unmatched provisional with no confident
match. Provisional items are playable.
False when every version’s folder is unreachable.
object
Fetch with GET /api/v1/images/{id}?width=….
object
A UUIDv7.
The largest stored width.
Fetch with GET /api/v1/images/{id}?width=….
object
A UUIDv7.
The largest stored width.
An episode’s or video’s frame, for landscape cards.
object
A UUIDv7.
The largest stored width.
Fetch with GET /api/v1/images/{id}?width=….
object
A UUIDv7.
The largest stored width.
The user’s state for a work. For a series or season, played means every episode is.
object
The resume position, when in progress.
The version last played, which positionMs is on; it may be
gone. Resume continues its edition, and a version of another
edition starts from the beginning.
object
The label the movie’s folder’s edition tag gives it, such as Final Cut. Shown after the title wherever it appears.
object
0 is Specials.
A UUIDv7.
How many episodes the season lists. Set in its series’ season list and on its detail.
object
0 is Specials.
The last episode a multi-episode file covers (E1 to E2).
A UUIDv7.
A UUIDv7.
Detail only. The previous episode in the series’ order, across seasons, with specials last. Absent for the first.
Detail only. The next episode in the series’ order, across seasons, with specials last. Absent for the last.
A season’s episode list only. The episode’s synopsis, absent when it has none.
object
What an extra is.
The movie, series or season it belongs to.
object
In credit order; the first is the primary author.
object
A UUIDv7.
object
A UUIDv7.
The series the book is in, the primary first.
object
A UUIDv7.
The book’s position as written, such as 1, 1.5 or 1-3; absent for none.
Detail only.
Detail only.
Detail only, as its source gives it.
Detail only; absent when unknown.
Detail only. YYYY, YYYY-MM or YYYY-MM-DD.
The library this work is in. Absent when the user doesn’t see it.
In the unmatched list only: the folder a series or book was parsed from, else the file, as found in its library. Absent when it has no file there.
object
0 is Specials.
A UUIDv7.
How many episodes the season lists. Set in its series’ season list and on its detail.
object
0 is Specials.
The last episode a multi-episode file covers (E1 to E2).
A UUIDv7.
A UUIDv7.
Detail only. The previous episode in the series’ order, across seasons, with specials last. Absent for the first.
Detail only. The next episode in the series’ order, across seasons, with specials last. Absent for the last.
A season’s episode list only. The episode’s synopsis, absent when it has none.
object
What an extra is.
The movie, series or season it belongs to.
object
In credit order; the first is the primary author.
object
A UUIDv7.
object
A UUIDv7.
The series the book is in, the primary first.
object
A UUIDv7.
The book’s position as written, such as 1, 1.5 or 1-3; absent for none.
Detail only.
Detail only.
Detail only, as its source gives it.
Detail only; absent when unknown.
Detail only. YYYY, YYYY-MM or YYYY-MM-DD.
The library this work is in. Absent when the user doesn’t see it.
In the unmatched list only: the folder a series or book was parsed from, else the file, as found in its library. Absent when it has no file there.
On the first page (offset 0) of the title sort. See LetterStart.
Where a letter of a grid’s letter rail starts, in the grid’s order.
A work files under the first character of its sort title, so
leading articles are skipped, and a person or series under the
first character of their sort name: A to Z, or # for digits
and anything else. A letter is listed once, at its first item;
letters without items are left out.
object
A to Z, or #.
The index of the letter’s first item in the grid.
Example
{ "items": [ { "kind": "movie", "matchState": "matched", "series": { "nextUp": { "kind": "movie", "matchState": "matched", "extra": { "type": "trailer" } } }, "extra": { "type": "trailer" } } ]}The request is malformed or a field is invalid (code invalidRequest).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}No valid session or API key (code unauthenticated), or a failed sign-in (code invalidCredentials).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}No such resource, or the caller may not see it (code notFound).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}default
Section titled “default”A server-side failure: 500 (code internal, or transcodeFailed
for a play’s media), or 503
for something unavailable (codes providerUnavailable and
transcodeBusy, for now; notConfigured, until an admin configures
it).
An RFC 9457 problem document. code is stable and is what clients
translate.
object
A URI naming the problem type; about:blank when only code matters.
A short English summary, for logs.
English detail for logs and developers; never internal error text.
A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.
The request ID, also in the X-Request-Id header and the server log.
For transcodeBusy and notPlayable, why. For transcodeBusy:
transcodeLimit or storageFull. For notPlayable: noTracks,
fileUnplayable, subtitleUnplayable, transcodeFailed,
keyframeIndexMissing or downloadsNotAllowed.
For fileUnplayable, the capability the file failed.
object
The declared value, lists joined by commas; absent when the client declared none.
For throttled and rateLimited, the Retry-After header’s value.
For invalidRequest, what’s wrong with which field.
object
A JSON pointer into the body, or a parameter name.
What’s wrong with a field: tooLarge for a file or list over its
size, unsupported for a file in a format the server doesn’t take,
unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list
for the series, and notABook for a work edited with books that
isn’t one.
For streamLimit, the user’s plays, to show what is playing where.
One of the user’s plays, for the stream limit.
object
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by.
For playEnded, the admin’s words to the viewer, when they gave any.
For quotaUsed, when the quota resets, when the provider said.
Example
{ "code": "invalidRequest", "reason": "noTracks", "errors": [ { "code": "required" } ]}