Archive API
Everything dealing with Archives.
Returns a list of all Archives in the database. This doesn't include Tankoubons by design. You can use the IDs of this JSON with the other endpoints.
Array of archives
JSON object for archive metadata for most API responses
Unique identifier for the archive (40-char SHA1) or tankoubon (15-char TANK_* ID)
^[0-9a-f]{40}$^TANK_[0-9]{10}$Title of the archive
Filename of the archive
Comma-separated list of tags associated with the archive
Summary description of the archive
Whether the archive is newly added.
File extension of the archive
Reading progress (page number)
Total number of pages in the archive
Unix timestamp of when the archive was last read
Size of the archive in bytes
Table of contents for the archive
GET /api/archives HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
Array of archives
[
{
"arcid": "28697b96f0ac5858be2614ed10ca47742c9522fd",
"isnew": false,
"extension": "rar",
"pagecount": 34,
"progress": 3,
"tags": "parody:fate grand order, group:wadamemo, artist:wada rco, artbook, full color",
"lastreadtime": 1337038281,
"title": "Fate GO MEMO",
"filename": "Fate GO MEMO",
"summary": null,
"size": 1234567,
"toc": [
{
"name": "Chapter 1",
"page": 1
},
{
"name": "Chapter 2",
"page": 13
},
{
"name": "Chapter 3",
"page": 25
}
]
}
]Get Archives that don't have any tags recorded. This follows the same rules as the Batch Tagging filter and will include Archives that have parody:, date_added:, series: or artist: tags.
Array of archive IDs
GET /api/archives/untagged HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
Array of archive IDs
[
"d1858d5dc36925aa66be072a97817650d39de166",
"c3458d5dc36925da93be072a97817650d39de166",
"28697b96f0ac5858be2614ed10ca47742c9522fd"
]Upload an Archive to the server. If a SHA1 checksum of the Archive is included, the server will perform an optional in-transit, file integrity validation, and reject the upload if the server-side checksum does not match.
Use Authorization: Bearer <base64(api_key)>
Archive file to upload
SHA1 checksum of the archive for in-transit validation.
^[a-fA-F0-9]{40}$Category ID you'd want the archive to be added to.
Set of tags you want to insert in the database alongside the archive.
Title of the Archive.
Summary of the Archive.
Archive uploaded successfully
Name of operation
uploadReturns 1 if operation was successful, else 0
ID of the uploaded archive
Bad request
Duplicate archive
Unsupported file
Checksum mismatch
Unprocessable Entity
Locked resource response
Internal Server Error
PUT /api/archives/upload HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 107
{
"file": "binary",
"file_checksum": "text",
"category_id": "text",
"tags": "text",
"title": "text",
"summary": "text"
}{
"operation": "upload",
"success": 1,
"id": "text"
}Delete both the archive metadata and the file stored on the server. 🙏 Please ask your user for confirmation before invoking this endpoint.
Use Authorization: Bearer <base64(api_key)>
ID of the Archive to process.
Archive deleted response
Name of the operation
ID of the archive
Filename of the deleted archive
Returns 1 if operation was successful, else 0
No archive ID response
Locked resource response
DELETE /api/archives/{id} HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Accept: */*
{
"operation": "delete_archive",
"success": 1,
"id": "75d18ce470dc99f83dc355bdad66319d1f33c82b",
"filename": "big_chungus.zip"
}Get Metadata (title, tags) for a given Archive.
ID of the Archive to process.
Archive metadata
JSON object for archive metadata for most API responses
Unique identifier for the archive (40-char SHA1) or tankoubon (15-char TANK_* ID)
^[0-9a-f]{40}$^TANK_[0-9]{10}$Title of the archive
Filename of the archive
Comma-separated list of tags associated with the archive
Summary description of the archive
Whether the archive is newly added.
File extension of the archive
Reading progress (page number)
Total number of pages in the archive
Unix timestamp of when the archive was last read
Size of the archive in bytes
Table of contents for the archive
No archive ID response
GET /api/archives/{id}/metadata HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"arcid": "28697b96f0ac5858be2614ed10ca47742c9522fd",
"isnew": false,
"extension": "rar",
"pagecount": 34,
"progress": 3,
"tags": "parody:fate grand order, group:wadamemo, artist:wada rco, artbook, full color",
"lastreadtime": 1337038281,
"title": "Fate GO MEMO",
"filename": "Fate GO MEMO",
"summary": null,
"size": 1234567,
"toc": [
{
"name": "Chapter 1",
"page": 1
},
{
"name": "Chapter 2",
"page": 13
},
{
"name": "Chapter 3",
"page": 25
}
]
}Update tags and title for the given Archive. Data supplied to the server through this method will overwrite the previous data.
Use Authorization: Bearer <base64(api_key)>
ID of the Archive to process.
New Title of the Archive.
New Tags of the Archive.
New Summary of the Archive.
Archive metadata updated
Name of operation
Error message if any
Success message if any
Returns 1 if operation was successful, else 0
No archive ID response
Locked resource response
PUT /api/archives/{id}/metadata HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Accept: */*
{
"operation": "update_metadata",
"success": 1
}Get a Thumbnail image for a given Archive. This endpoint will return a placeholder image if it doesn't already exist. If you want to queue generation of the thumbnail in the background, you can use the no_fallback query parameter. This will give you a background job ID instead of the placeholder.
ID of the archive to process
Disables the placeholder image, queues the thumbnail for extraction and returns a JSON with code 202. This parameter does nothing if the image already exists. (You will get the image with code 200 no matter what)
Specify which page you want to get a thumbnail for. Defaults to the cover, aka page 1.
If the thumbnail was already extracted, you get it directly.
The thumbnail is queued for extraction. Use /api/minion/:jobid to track when your thumbnail is ready.
No archive ID response
GET /api/archives/{id}/thumbnail HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
binaryUpdate the cover thumbnail for the given Archive. You can specify a page number to use as the thumbnail, or you can use the default thumbnail.
Use Authorization: Bearer <base64(api_key)>
ID of the Archive to process.
Page you want to make the thumbnail out of. Defaults to 1.
Archive thumbnail updated
Name of operation
Returns 1 if operation was successful, else 0
New thumbnail URL
No archive ID response
PUT /api/archives/{id}/thumbnail HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Accept: */*
{
"operation": "update_thumbnail",
"success": 0,
"new_thumbnail": "text"
}Add an entry to the Table of Contents of a given Archive. The ToC is stored as a JSON-encoded key-value array mapping a page to a title for the chapter/section starting at that page.
Use Authorization: Bearer <base64(api_key)>
ID of the Archive to process.
Page number where the chapter/section starts.
Title of the chapter/section.
Archive TOC updated
Name of operation
Error message if any
Success message if any
Returns 1 if operation was successful, else 0
No archive ID response or other error
Locked resource response
PUT /api/archives/{id}/toc?page=1&title=text HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Accept: */*
{
"operation": "update_toc",
"success": 1,
"successMessage": "Added ToC entry for page 143."
}Delete an entry from the Table of Contents of a given Archive.
Use Authorization: Bearer <base64(api_key)>
ID of the Archive to process.
Page number of the chapter/section to delete.
Archive TOC updated
Name of operation
Error message if any
Success message if any
Returns 1 if operation was successful, else 0
No archive ID response or other error
Locked resource response
DELETE /api/archives/{id}/toc?page=1 HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Accept: */*
{
"operation": "remove_toc",
"success": 1,
"successMessage": "Removed ToC entry for page 143."
}Get all the Categories which currently refer to this Archive ID.
ID of the Archive to process.
^[0-9a-f]{40}$^TANK_[0-9]{10}$Archive categories
Name of the operation
Returns 1 if operation was successful, else 0
No archive ID response
GET /api/archives/{id}/categories HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"operation": "find_arc_categories",
"success": 1,
"categories": [
{
"id": "SET_1613080290",
"name": "My great category",
"pinned": 0,
"search": null,
"archives": [
"0d50858d727723d856d2ab78564bb8e906e65f14",
"7f03b8b1f337e1e42b2c2890533c0de7479d41ca"
]
},
{
"id": "SET_1613080294",
"name": "My other category",
"pinned": 1,
"search": null,
"archives": [
"0d50858d727723d856d2ab78564bb8e906e65f14",
"75d18ce470dc99f83dc355bdad66319d1f33c82b"
]
}
]
}Get all the Tankoubons which currently refer to this Archive ID.
ID of the Archive to process.
Archive tankoubons
Array of tankoubon IDs
Name of the operation
Returns 1 if operation was successful, else 0
No archive ID response
GET /api/archives/{id}/tankoubons HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"operation": "find_arc_tankoubons",
"success": 1,
"tankoubons": [
"TANK_1688616437",
"TANK_1688693913"
]
}Download an Archive from the server.
ID of the Archive to download.
Archive file
No archive ID response
GET /api/archives/{id}/download HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
binaryGet a list of URLs pointing to the images contained in an archive. If necessary, this endpoint also launches a background Minion job to extract the archive so it is ready for reading.
ID of the Archive to process.
Force a full background re-extraction of the Archive. Existing cached files might still be used in subsequent /api/archives/:id/page calls until the Archive is fully re-extracted.
You get page URLs, and the ID of the background extract job.
ID of the background extract job
Page URLs
No archive ID response
GET /api/archives/{id}/files HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"job": 561,
"pages": [
".\\/api\\/archives\\/28697b96f0ac5858be2614ed10ca47742c9522fd\\/page&path=00.jpg",
".\\/api\\/archives\\/28697b96f0ac5858be2614ed10ca47742c9522fd\\/page&path=01.jpg"
]
}Create thumbnails for every page of a given Archive. This endpoint will queue generation of the thumbnails in the background.
If all thumbnails are detected as already existing, the call will return HTTP code 200. This endpoint can be called multiple times -- If a thumbnailing job is already in progress for the given ID, it'll just give you the ID for that ongoing job.
ID of the Archive to process.
Whether to force regeneration of all thumbnails even if they already exist.
If thumbnails are already extracted and force=0
Name of operation
Returns 1 if operation was successful, else 0
The thumbnails are queued for extraction. You can use /api/minion/:jobid to track progress, by looking at notes->progress and notes->pages.
No archive ID response
POST /api/archives/{id}/files/thumbnails HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"message": "No job queued, all thumbnails already exist.",
"operation": "generate_page_thumbnails",
"success": 1
}Get an archive page. This call is mainly used alongside /api/archives/files.
ID of the Archive to download.
Path to the image.
Archive page
No archive ID response
GET /api/archives/{id}/page?path=text HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
binaryTell the server which page of this Archive you're currently showing/reading, so that it updates its internal reading progression accordingly. This endpoint will also update the date this Archive was last read, using the current server timestamp.
You should call this endpoint only when you're sure the user is currently reading the page you present. Don't use it when preloading images off the server.
Whether to make reading progression regressible or not is up to the client. (The web client will reduce progression if the user starts reading previous pages) Consider however removing the "New!" flag from an archive when you start updating its progress - The web client won't display any reading progression if the new flag is still set.
⚠ If the server is configured to use clientside progress tracking, this API call will return an error!
Make sure to check using /api/info whether the server tracks reading progression or not before calling this endpoint.
ID of the Archive to process.
Current page to update the reading progress to.
Must be a positive integer, and inferior or equal to the total page number of the archive.
Success response
ID of the archive updated
Name of the operation
Updated reading progress
Last read time in epoch seconds
Returns 1 if successful, else 0
Generic error response
Authentication required when authprogress is enabled
Locked resource response
PUT /api/archives/{id}/progress/{page} HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"id": "75d18ce470dc99f83dc355bdad66319d1f33c82b",
"operation": "update_progress",
"page": 34,
"lastreadtime": 123943543,
"success": 1
}Sets/Restores the "New!" flag on an archive.
Use Authorization: Bearer <base64(api_key)>
ID of the Archive to process.
Successful response
Name of operation
Error message if any
Success message if any
Returns 1 if operation was successful, else 0
No archive ID response
Locked resource response
PUT /api/archives/{id}/isnew HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Accept: */*
{
"operation": "text",
"error": "text",
"successMessage": "text",
"success": 0
}Clears the "New!" flag on an archive.
ID of the Archive to process.
Successful response
ID of the archive
Name of the operation
Returns 1 if successful, else 0
No archive ID response
Locked resource response
DELETE /api/archives/{id}/isnew HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"id": "text",
"operation": "clear_new",
"success": 0
}Get pages that contain at least one stamp in the archive.
ID of the archive.
Success response
Error response
GET /api/archives/{id}/stamps HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"result": [
"text"
]
}Get the stamps linked to the page.
ID of the archive.
Page of the archive.
Success response
Error response
GET /api/archives/{id}/stamps/{index} HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*
{
"result": [
{
"position": "12,34",
"content": "Lorem ipsum dolore"
}
]
}Add a new Stamp to the page at the given coordinates.
Use Authorization: Bearer <base64(api_key)>
ID of the archive.
Page of the archive.
Text of the stamp.
Position of the stamp in the page.
Success response
Stamp ID
Error response
PUT /api/archives/{id}/stamps/{index} HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Accept: */*
{
"operation": "add_stamp",
"stamp_id": "text",
"success": 0
}Last updated