Update current user

PATCH

/api/v1/users/me

const url = 'https://example.com/api/v1/users/me';
const options = {
  method: 'PATCH',
  headers: {cookie: 'kivo_session=<kivo_session>', 'Content-Type': 'application/json'},
  body: '{"playback":{"audioLanguage":"example","subtitleLanguage":"example","subtitleMode":"none","rememberTracks":true,"autoplayNext":true,"bookSpeed":1},"libraries":[{"id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","pinned":true}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://example.com/api/v1/users/me \
  --header 'Content-Type: application/json' \
  --cookie kivo_session=<kivo_session> \
  --data '{ "playback": { "audioLanguage": "example", "subtitleLanguage": "example", "subtitleMode": "none", "rememberTracks": true, "autoplayNext": true, "bookSpeed": 1 }, "libraries": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "pinned": true } ] }'

Changes the caller’s preferences. Every client of the user gets the change: playback applies the languages, subtitle mode and rememberTracks to the next play, and libraries orders the library list and Home. A library the user doesn’t see, or one listed twice, is 400.

Authorizations

cookieAuth
bearerAuth

Request Body^required

application/json

object

playback

Fields as in PlaybackPreferences; an empty language sets it back to its default.

object

audioLanguage

string

<= 35 characters

subtitleLanguage

string

<= 35 characters

subtitleMode

When subtitles show: none never; forced a forced track in the audio’s language; smart full subtitles in the subtitle language when the audio isn’t in it, else as forced; always full subtitles in the subtitle language, else as forced.

string

Allowed values: none forced smart always

rememberTracks

boolean

autoplayNext

boolean

bookSpeed

number format: double

>= 0.5 <= 3

libraries

The libraries the user sees, in the order it wants them, each pinned or not; it replaces the last order. A library left out is pinned after the listed ones, in the order libraries were added, as every library is until the user sets this.

Array<object>

object

required

A UUIDv7.

string format: uuid

pinned

required

Shown in the sidebar and with a Recently Added row on Home.

boolean

Responses

200

The updated user.

application/json

The signed-in user, with its limits and playback preferences.

object

required

A UUIDv7.

string format: uuid

username

required

string

admin

required

boolean

limits

required

object

maxStreams

Simultaneous streams. Absent for no limit.

integer

>= 1

remoteQualityCapBps

The most a stream outside the local networks may use. Absent for no cap of the user’s own, when the server’s remote streaming limit applies. The signed-in user’s own (GET /api/v1/users/me) is the limit that applies to them, theirs or the server’s.

integer format: int64

>= 1

playback

required

How the user’s plays start, when the request doesn’t choose tracks. An episode starts with the languages last chosen for its series when rememberTracks is on.

object

audioLanguage

The preferred audio language (BCP 47), played when the version has it. Absent for the original language: the version’s default track.

string

subtitleLanguage

The preferred subtitle language (BCP 47). Absent for the server’s metadata language.

string

subtitleMode

required

string

Allowed values: none forced smart always

rememberTracks

required

Whether an episode starts with the audio and subtitle languages last chosen for its series, and choosing tracks for an episode remembers them. Off, each episode starts from these preferences.

boolean

autoplayNext

required

Whether up next plays the next episode by itself, counting down near the end of an episode. Off, up next shows the next episode without counting down, and playback stops at the end.

boolean

bookSpeed

required

The speed books play at, which the audio player sets; 1 is normal. Video always plays at normal speed.

number format: double

>= 0.5 <= 3

Example

{
  "playback": {
    "subtitleMode": "none"
  }
}

400

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

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

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

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

Update current user

Authorizations

Request Bodyrequired

Responses

200

Example

400

Example

401

Example

default

Example

Request Body^required