Add a library

POST

/api/v1/libraries

curl --request POST \
  --url http://localhost:8080/api/v1/libraries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "path": "example", "komga": { "url": "http://komga:25600", "apiKey": "example", "username": "example", "password": "example", "libraryIds": [ "example" ], "writeProgress": true }, "kavita": { "url": "http://kavita:5000", "apiKey": "example", "libraryIds": [ 1 ], "writeProgress": true }, "extension": { "extensionId": "example" } }'

Admin only. Adds a folder on the server as a library and starts scanning it, adds a Komga or Kavita server as a source library and starts syncing it, or makes a source library that runs on an extension. Send one of path, komga, kavita or extension.

A Komga library reads Komga’s series and books with one Komga account, and serves their pages and files through Komga. The account needs the page streaming and file download roles. The address and credentials are checked before the library is added, and stored on the server; they are never returned.

A Kavita library reads Kavita’s series, volumes and chapters with one Kavita account’s API key, one publication per chapter, and serves their pages and files through Kavita. The account needs Kavita’s download role for files. The address and key are checked and stored the same way.

An extension library runs on an extension the admin installed, and starts empty: follow series into it with POST /api/v1/libraries/{libraryId}/series. It runs on that admin’s install, so readers granted it don’t need the extension. If the admin uninstalls it, the library’s pages and syncs fail with source_unavailable until it’s installed again.

Authorizations

• session
• basic

Request Body^required

Media typeapplication/json

object

name

required

string

>= 1 characters

path

Absolute path of a folder on the server.

string

komga

A Komga server to read, with an API key, or a name and password, for one Komga account. Everyone granted the Chek library reads what that account can see.

object

url

required

Komga’s address, including any path it is served under.

string

Example

http://komga:25600

apiKey

An API key made in Komga for the account.

string

username

The account’s email address, with password.

string

password

string

libraryIds

Komga library ids to read; leave out to read every library the account sees.

Array<string>

writeProgress

Writes your reading progress in this library back to the Komga account, so Komga’s own apps stay in step. Only the admin who adds the library is written back, since every reader shares the one Komga account.

boolean

default: true

kavita

A Kavita server to read, with the API key of one Kavita account, from that account’s settings page in Kavita. Everyone granted the Chek library reads what that account can see.

object

url

required

Kavita’s address, including any path it is served under.

string

Example

http://kavita:5000

apiKey

required

The account’s API key.

string

libraryIds

Kavita library ids to read; leave out to read every library the account sees.

Array<integer>

writeProgress

Writes your reading progress in this library back to the Kavita account, so Kavita’s own readers stay in step. Comics and PDFs are written as a page; a book is written only when finished, since Kavita keeps a book’s place in a form a locator can’t name. Only the admin who adds the library is written back, since every reader shares the one Kavita account.

boolean

default: true

extension

object

extensionId

required

An extension the admin installed.

string

Responses

201

The library was added and its first scan started.

Media typeapplication/json

object

id

required

integer format: int64

name

required

string

kind

required

string

Allowed values: folder source

path

required

The folder on the server, for folder libraries.

string | null

source

Where a source library reads from. Present only on source libraries.

object

type

required

string

Allowed values: komga kavita extension

url

The Komga or Kavita server’s address. Absent for an extension library.

string

extensionId

The extension an extension library runs on.

string

libraryIds

The Komga or Kavita libraries read; absent when every library the account sees is read. Kavita’s numeric ids are returned as strings.

Array<string>

progressUserId

The Chek user whose reading progress is written back to the Komga or Kavita account. Absent when none is.

integer format: int64

scan

required

object

status

required

string

Allowed values: idle scanning failed

error

required

Why the last scan failed.

string | null

finishedAt

required

When the last scan finished, whether or not it succeeded.

string | null format: date-time

createdAt

required

string format: date-time

Example

{
  "kind": "folder",
  "source": {
    "type": "komga"
  },
  "scan": {
    "status": "idle"
  }
}

400

The request was malformed, or Komga or Kavita couldn’t be reached with the settings given (source_check_failed, with the reason).

Media typeapplication/json

object

code

required

string

Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal

message

required

Explains the problem to a developer.

string

Example

{
  "code": "bad_request"
}

401

The request has no valid session token.

Media typeapplication/json

object

code

required

string

Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal

message

required

Explains the problem to a developer.

string

Example

{
  "code": "bad_request"
}

403

The signed-in user may not do this. demo_account when the user is a shared demo account, named in CHEK_DEMO_USERS, which can’t change its password, sessions, sign-in providers, extensions or annotations.

Media typeapplication/json

object

code

required

string

Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal

message

required

Explains the problem to a developer.

string

Example

{
  "code": "bad_request"
}

404

The extension isn’t installed (not_installed).

Media typeapplication/json

object

code

required

string

Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal

message

required

Explains the problem to a developer.

string

Example

{
  "code": "bad_request"
}

500

The server failed; details are in its log.

Media typeapplication/json

object

code

required

string

Allowed values: bad_request unauthorized forbidden not_found unavailable scan_in_progress content_changed already_set_up name_taken last_admin progress_conflict too_many_attempts not_linked identity_taken last_sign_in provider_unavailable too_many_sign_ins repository_exists repository_not_allowed repository_unreadable repository_needs_token repository_needs_password repository_needs_credentials repository_credentials_refused extension_invalid source_failed source_unavailable source_check_failed internal

message

required

Explains the problem to a developer.

string

Example

{
  "code": "bad_request"
}