Get settings

GET

/api/v1/settings

const url = 'https://example.com/api/v1/settings';
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/settings \
  --cookie kivo_session=<kivo_session>

The server’s settings.

Authorizations

cookieAuth
bearerAuth

Responses

200

The current settings.

application/json

object

serverName

required

Shown to clients and on the network.

string

metadataLanguage

required

A BCP 47 tag, such as en-US; a library may have its own.

string

contentRatingCountry

required

An ISO 3166-1 alpha-2 code, such as US; whose content ratings works store and the filter and edit dialog list. A library may have its own.

string

openSubtitlesKey

required

An OpenSubtitles API key; without one, subtitles aren’t searched or downloaded.

string

openSubtitlesUsername

required

An OpenSubtitles account, which raises the daily download quota; empty for none.

string

openSubtitlesPasswordSet

required

Whether the OpenSubtitles account has a password; the password itself is never sent.

boolean

fileWatching

required

Scan a folder as soon as files in it change. Off, changes are found by the scan of every library every 12 hours, or a scan an admin starts.

boolean

playedThreshold

required

The fraction of a work that, once played, marks it played, such as 0.9.

number format: double

localNetworks

required

CIDR ranges whose clients are local. Empty means private (RFC 1918 and unique local), loopback and link-local addresses. Another range, such as Tailscale’s 100.64.0.0/10, is local only once listed.

Array<string>

accelerator

required

The video accelerator transcodes use: auto (the tested accelerators, best first), none (the CPU), or one accelerator’s id from GET /api/v1/accelerators, such as qsv:/dev/dri/renderD128.

string

videoTranscodeLimit

required

Simultaneous video transcodes the server runs; 0 is no limit.

integer

maintenanceStartHour

required

The hour, in the server’s time, the nightly maintenance window opens: the scheduled tasks start then.

integer

<= 23

maintenanceEndHour

required

The hour it closes, after midnight when it’s not after the start. Maintenance work still running then stops, and goes on the next night.

integer

<= 23

previewsAtOnce

required

How many files’ preview thumbnails are made at once, in the maintenance window and outside it.

integer

>= 1 <= 8

markersAtOnce

required

How many files are fingerprinted for intro and credits markers at once, in the maintenance window and outside it.

integer

>= 1 <= 4

publicUrl

required

The address apps use away from home, such as https://kivo.example.com; empty when the server isn’t reachable from outside. Signed-in apps get it from GET /api/v1/server.

string

remoteQualityCapBps

required

The most a stream outside the local networks may use, for a user without a remote streaming limit of their own; 0 is no limit.

integer format: int64

Example ^generated

{
  "serverName": "example",
  "metadataLanguage": "example",
  "contentRatingCountry": "example",
  "openSubtitlesKey": "example",
  "openSubtitlesUsername": "example",
  "openSubtitlesPasswordSet": true,
  "fileWatching": true,
  "playedThreshold": 1,
  "localNetworks": [
    "example"
  ],
  "accelerator": "example",
  "videoTranscodeLimit": 1,
  "maintenanceStartHour": 1,
  "maintenanceEndHour": 1,
  "previewsAtOnce": 1,
  "markersAtOnce": 1,
  "publicUrl": "example",
  "remoteQualityCapBps": 1
}

401

No valid session or API key (code unauthenticated), or a failed sign-in (code invalidCredentials).

application/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

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"
    }
  ]
}

403

Signed in, but this needs an admin (code forbidden); a same-origin request (code crossOrigin); or a device code that was denied (code denied).

application/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

requestId

required

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

string

reason

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

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

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

application/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

requestId

required

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

string

reason

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

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

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"
    }
  ]
}

Get settings

Authorizations

Responses

200

Example generated

401

Example

403

Example

default

Example

Example ^generated