Upload a file into a folder library

PUT

/api/v1/libraries/{libraryId}/files/{path}

curl --request PUT \
  --url http://localhost:8080/api/v1/libraries/1/files/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/octet-stream' \
  --data binary

Admin only. The request body is the file’s bytes, up to CHEK_MAX_UPLOAD_BYTES (2 GiB by default). The file is checked against its extension, moved into place and recorded like any file the scan finds. If a scan of the library is running, recording waits for it, and after 20 seconds the response is 202 while recording carries on.

Authorizations

• session
• basic

Parameters

Path Parameters

libraryId

required

integer format: int64

path

required

string

<= 1024 characters

Where to store the file, relative to the library’s folder, with / between folders, such as Saga/Saga 01.cbz. Missing folders are created. Every part must be a plain name (no ., .. or names starting with .), and the file must end in .epub, .pdf, .cbz, .cbr, .cb7 or .cbt. A comic may be any comic archive whatever its comic extension says.

Request Body^required

Media typeapplication/octet-stream

string format: binary

Responses

201

The file was stored and recorded.

Media typeapplication/json

object

id

required

integer format: int64

series

required

object

id

required

integer format: int64

title

required

string

title

required

From the file’s metadata, or its file name when it has none.

string

numberLabel

required

The number in its series as the file’s metadata writes it, such as “3”, “1.5” or “Vol. 3”.

string | null

format

required

Comic archives get their format from their bytes, so a ZIP named .cbr is cbz. A FictionBook zipped as .fb2.zip or .fbz is fb2 too; its file downloads as application/x-zip-compressed-fb2. remote is a chapter from an extension: it has pages but no file. A chapter from an extension whose source reads only EPUBs or only PDFs is epub or pdf, and its file is downloaded through the source.

string

Allowed values: epub pdf cbz cbt cbr cb7 mobi azw3 fb2 txt markdown remote

pageCount

required

Number of pages for comic formats.

integer | null

available

required

False when the file is missing from disk. Missing files are kept so progress survives.

boolean

hasCover

required

Whether /cover has an image for this publication.

boolean

Example

{
  "format": "epub"
}

202

The file was stored and will be recorded once the running scan finishes.

Media typeapplication/json

object

path

required

string

status

required

string

Allowed values: queued

Example

{
  "status": "queued"
}

400

The request was malformed.

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 resource does not exist.

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

409

A file already exists at that path (file_exists), or the server can’t write to the library’s folder (library_read_only).

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

413

The file is larger than CHEK_MAX_UPLOAD_BYTES.

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

422

The file was stored but can’t be read, such as a damaged archive. It stays in the folder like any other unreadable file.

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