Get server info

GET

/api/v1/server

curl --request GET \
  --url https://example.com/api/v1/server

• The server itself, under its configured base path (such as `/kivo`).

The server’s ID, name and version, and for a signed-in client its addresses and quality ladder. Signed out, only id, name and version. A client keeps its sign-in under id, which stays the same across restarts and address changes, and tries a local URL first and the public one elsewhere. Signed in, it also gets the quality ladder every client’s quality menu shows.

An app that holds a session sends challenge and probeId before it trusts a plain-HTTP address with its token, and the server answers with its proof that it holds that session.

Authorizations

• None
• cookieAuth
• bearerAuth

Parameters

Query Parameters

challenge

string

>= 22 characters <= 86 characters

16 to 64 random bytes, new for each probe, base64url without padding.

probeId

string

>= 22 characters <= 22 characters

The app’s session’s probe ID, base64url without padding: the first 16 bytes of SHA-256(“kivo-probe-id” ‖ SHA-256(token)).

Responses

200

The server.

Media typeapplication/json

The server, as GET /api/v1/server gives it.

object

id

required

The same across restarts and address changes; apps keep their sign-in under it.

string format: uuid

name

required

The server’s name, from the serverName setting.

string

version

required

string

castProtocol

The version of the contract between Cast senders, the Cast receiver and the server: the load request’s custom data, the receiver’s status and messages, and the cast routes. A receiver that speaks another version says which side to update.

integer

localUrls

Signed in: the server’s addresses on its local networks, without container, VM or VPN interfaces (a VPN only when the asker is on it). The asker’s own network comes first, then addresses in the localNetworks setting, then the rest.

Array<string>

publicUrl

Signed in, when one is set (the publicUrl setting), the address to use away from home.

string

qualityLadder

Signed in: the quality menu’s fixed ladder, highest first, which the quality menu, Home and remote quality and a user’s remote limit offer below Auto and Original. A rung is chosen by sending its bitrate as a limit quality’s maxBitrateBps.

Array<object>

object

bitrateBps

required

integer format: int64

height

required

The height in pixels a transcode at this bitrate is sent at, such as 1080.

integer

proof

With challenge and the probeId of a session the server holds.

object

mac

required

Base64url without padding.

string

host

required

The host the probe reached, as its Host header, or a trusted proxy’s X-Forwarded-Host, names it.

string

local

required

Whether the probe came from a local address, after the trusted proxies, as the localNetworks setting defines one.

boolean

Example ^generated

{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "name": "example",
  "version": "example",
  "castProtocol": 1,
  "localUrls": [
    "example"
  ],
  "publicUrl": "example",
  "qualityLadder": [
    {
      "bitrateBps": 1,
      "height": 1
    }
  ],
  "proof": {
    "mac": "example",
    "host": "example",
    "local": true
  }
}

400

The request is malformed or a field is invalid (code invalidRequest).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

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.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}

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).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

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.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}