Search works
const url = 'https://example.com/api/v1/search?q=example';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/search?q=example' \ --cookie kivo_session=<kivo_session>Searches works, people and collections across the libraries the user
sees.
Matches words: runs of letters and digits, without case or
diacritics, so “spider man” finds Spider-Man. Every word must match a
whole word, except the last, which matches the start of one, as the
query is typed. A query with no words finds nothing. Works match by
their titles, alternative titles or the people credited on them, and
come best first: a title that is the query (a leading “The”, “A” or
“An” ignored), then one starting with it, one holding it as a
phrase, one holding its words, then alternative titles, then people
only; within each, the most voted first. Clients group them by
kind. People match by name, ranked the same way, then by credits,
and collections by name, ranked the same way; a collection is found
when the profile sees one of its root works. There’s no fuzzy matching,
and text without spaces between words, such as Japanese, matches
only from its start. limit applies to works, people and
collections each.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Page size. The default and the most a page holds depend on the listing.
Responses
Section titled “Responses”Matching works and people.
object
Works, best first.
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.
People credited on a work the profile sees, best first.
object
A UUIDv7.
Fetch with GET /api/v1/images/{id}?width=….
object
A UUIDv7.
The largest stored width.
The credit role they have on the most of the root works the profile sees, as Credit.role.
The movies, shows, videos and books the profile sees that they’re credited on, an episode counting as its series; in a library’s authors, the library’s books they wrote.
Collections holding a root work the profile sees, best first.
A movie collection or a videos library’s folder, for its card.
object
A UUIDv7.
Its root works the user sees.
Where a collection comes from: provider a movie collection, folder
a videos-library folder.
Its poster: a movie collection’s own, which its movies’ metadata refreshes fetch, else the poster of its first root work the user sees that has one, in release order.
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.
Example
{ "works": [ { "kind": "movie", "matchState": "matched", "series": { "nextUp": { "kind": "movie", "matchState": "matched", "extra": { "type": "trailer" } } }, "extra": { "type": "trailer" } } ], "collections": [ { "source": "provider" } ]}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" } ]}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" } ]}