Skip to content
Kivo

Create user

POST
/api/v1/users
curl --request POST \
  --url https://example.com/api/v1/users \
  --header 'Content-Type: application/json' \
  --cookie kivo_session=<kivo_session> \
  --data '{ "username": "example", "password": "example", "admin": true, "libraries": { "all": true, "libraryIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }, "limits": { "maxStreams": 1, "remoteQualityCapBps": 1 }, "parental": { "maxAge": 1, "blockUnrated": true } }'

Adds a user with a password. A username already in use is 409 with code nameTaken. Neither every library nor any one of them is 400.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
username
required
string
>= 1 characters <= 64 characters
password
required
string
>= 8 characters <= 1024 characters
admin
boolean
libraries
required

The libraries a user sees.

object
all
required

Every library, including ones added later.

boolean
libraryIds
required

The libraries it sees when not all; empty when all.

Array<string>
limits
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
parental
object
maxAge

The highest minimum age (ContentRating.age) the user sees. Absent for no limit.

integer
blockUnrated
required

Hides video with no content rating: movies, series with their seasons and episodes, videos and extras. Books always show.

boolean

Example generated

{
  "username": "example",
  "password": "example",
  "admin": true,
  "libraries": {
    "all": true,
    "libraryIds": [
      "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
    ]
  },
  "limits": {
    "maxStreams": 1,
    "remoteQualityCapBps": 1
  },
  "parental": {
    "maxAge": 1,
    "blockUnrated": true
  }
}

Responses

Section titled “Responses”

201

Section titled “201”

The new user.

Media typeapplication/json

A user, as admins see it.

object
id
required

A UUIDv7.

string format: uuid
username
required
string
admin
required

Manages the server.

boolean
disabled
required

Can’t sign in; its sessions stopped working when it was disabled.

boolean
onlyAdmin
required

The one enabled admin, which can’t lose admin, be disabled or be deleted (409 with code lastAdmin).

boolean
libraries
required

The libraries a user sees.

object
all
required

Every library, including ones added later.

boolean
libraryIds
required

The libraries it sees when not all; empty when all.

Array<string>
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
parental
required
object
maxAge

The highest minimum age (ContentRating.age) the user sees. Absent for no limit.

integer
blockUnrated
required

Hides video with no content rating: movies, series with their seasons and episodes, videos and extras. Books always show.

boolean
createdAt
required
string format: date-time

Example generated

{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "username": "example",
  "admin": true,
  "disabled": true,
  "onlyAdmin": true,
  "libraries": {
    "all": true,
    "libraryIds": [
      "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
    ]
  },
  "limits": {
    "maxStreams": 1,
    "remoteQualityCapBps": 1
  },
  "parental": {
    "maxAge": 1,
    "blockUnrated": true
  },
  "createdAt": "2026-04-15T12:00:00Z"
}

400

Section titled “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"
    }
  ]
}

401

Section titled “401”

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

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

403

Section titled “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).

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

409

Section titled “409”

The resource’s state doesn’t allow this; the code says why.

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

429

Section titled “429”

Sign-in throttled (code throttled), the server too busy checking passwords or with device codes to take another, or too many client error reports (code rateLimited).

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

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait.

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

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