List plays
const url = 'https://example.com/api/v1/plays';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/plays \ --cookie kivo_session=<kivo_session>What’s playing now, for Now playing. Every user’s plays, oldest first, with their decisions and transcode diagnostics.
Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”The plays.
object
A play with its diagnostics, for Now playing.
object
A UUIDv7.
A UUIDv7.
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.
A UUIDv7.
A UUIDv7.
The name of the session or API key it was started by, such as “Living Room”.
The client’s IP address, through trusted proxies.
What the player is doing, as the last heartbeat reported it.
Where playback is, as the last heartbeat reported it.
The version’s duration, every part’s.
The stream’s bitrate, a video transcode’s target or else the source’s, when known.
The client’s measured download rate, as its last heartbeat reported it.
The app and device that started it, as its requests identify them.
object
The app, such as kivo-android or kivo-web.
What a client runs on.
The device’s model, coarse, such as SHIELD Android TV, iPhone16,2 or Firefox 132.
How a play’s media is fetched: file is the original, each part’s
url with range requests; stream is the HLS playlist at url.
Where the video is transcoded, accelerator when an accelerator encodes it; absent when the video isn’t transcoded.
Every track of the version and the subtitle choice off, as PlayStarted.tracks gives them.
One choice of a play: a track of its version, or the subtitle choice
off, and how it shows.
object
A track’s id, or off.
A track’s type.
True for the tracks the play shows; absent otherwise.
Absent when choosing it starts a new play.
The codec it’s delivered as, such as hevc, aac or webvtt.
The video’s HDR as delivered; absent for SDR.
What a transcoded track becomes.
object
Video only; what encodes it, the accelerator’s name as GET /api/v1/accelerators gives it, such as Intel Quick Sync (QSV), or CPU.
Why the track isn’t delivered unchanged in the file, or why choosing it starts a new play, when there’s a reason to give.
The capability that failed: its field (such as maxLevel, codec
or containers), what the client declared, and what the track has.
object
The declared value, lists joined by commas; absent when the client declared none.
For file, the track’s stream index, to select it in the player.
For external, the file, relative to the API root.
For an ass subtitle delivered external, the URLs of the
fonts it uses, each once, relative to the API root:
GET /api/v1/fonts/{sha256}, cacheable for good. Load them
before drawing.
The selected source tracks, titled as a version’s tracks are.
An audio, video or subtitle track. Kind-specific data is under its type’s name.
object
The track’s ID; chooses it in a play request. An embedded track keeps its ID while its file is unchanged, and a subtitle file keeps its own while it stays at its path, so adding or removing one never changes another track’s ID.
A track’s type.
A BCP 47 tag.
The track’s title as the file gives it, such as “Commentary by the
director” or “Signs & Songs”; for a downloaded subtitle, the release
OpenSubtitles says it was made for, such as
Modern.Family.S03E16.480p.BluRay.x264-mSD.
Subtitles only, marked as forced (they show only lines in another language than the audio); absent when not.
Marked as for the deaf and hard of hearing (SDH); absent when not.
Marked as commentary, or titled with the word; absent when not.
Audio only: in the work’s original language, as the metadata provider gives it, where the work also has audio in another language; never a commentary. Absent when not.
object
A video’s resolution class, by its width, since wide films are short:
4k from 3200 pixels, 1080p from 1700, 720p from 1200, else sd.
The library’s resolution filter classes videos the same way.
As the codec names it, such as “Main 10”.
Its HDR format, hdr10, hlg or dolbyVision; absent for SDR. An HDR10+ video’s is hdr10.
object
The channel layout as main and LFE channels, such as “2.0”, “4.0”, “5.1” or “7.1”; absent when the file doesn’t say.
What the audio’s profile says beyond its codec: atmos for Dolby
Atmos on TrueHD or E-AC-3, dtsX, dtsHdMa or dtsHdHra for DTS;
absent for any other.
object
Where a subtitle lives: embedded in the media, external a
subtitle file next to the video in the library, downloaded from
OpenSubtitles. How a play delivers it is the track’s delivery, where
external means a subtitle sent to the client as its own file.
An HLS play’s ffmpeg job, for display only.
object
Absent when no job is running.
Where the job’s segments reach on the version’s timeline.
Seconds of media the job makes a second while it works, pauses left out; 1.8 is 1.8× realtime. Absent until its first segment.
The ffmpeg command line, to reproduce it by hand.
The tail of ffmpeg’s error output.
After each of the play’s recent seeks, the time to the first frame the client reported, oldest first.
Example
{ "items": [ { "work": { "kind": "movie", "matchState": "matched", "series": { "nextUp": { "kind": "movie", "matchState": "matched", "extra": { "type": "trailer" } } }, "extra": { "type": "trailer" } }, "state": "playing", "device": { "platform": "androidTv" }, "delivery": "file", "videoProcessing": "accelerator", "tracks": [ { "type": "video", "delivery": "file", "hdr": "hdr10", "reason": "containerUnsupported" } ], "sourceTracks": [ { "type": "video", "video": { "resolution": "4k", "hdr": "hdr10" }, "audio": { "profile": "atmos" }, "subtitle": { "source": "embedded" } } ], "transcode": { "state": "running" } } ]}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" } ]}Signed in, but this needs an admin (code forbidden); a
same-origin request (code crossOrigin); or a device code that was
denied (code denied).
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" } ]}