Archive API

Everything dealing with Archives.

Get all Archives

get

Returns a list of all archives in the database. You can use the IDs of this JSON with the other endpoints.

Responses

200

Array of archives

application/json

JSON object for archive metadata for most API responses

arcidstring · min: 40 · max: 40Required

Unique identifier for the archive

titlestringRequired

Title of the archive

filenamestringRequired

Filename of the archive

tagsstringRequired

Comma-separated list of tags associated with the archive

summarystringOptional

Summary description of the archive

isnewbooleanRequired

Whether the archive is newly added

extensionstringRequired

File extension of the archive

progressintegerRequired

Reading progress (page number)

pagecountintegerRequired

Total number of pages in the archive

lastreadtimeintegerRequired

Unix timestamp of when the archive was last read

sizeintegerRequired

Size of the archive in bytes

tocarrayRequired

Table of contents for the archive

get

/archives

HTTPcURLJavaScriptPython

GET /api/archives HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*

200

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 all untagged archives

get

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.

Responses

200

Array of archive IDs

application/json

string[]Optional

get

/archives/untagged

HTTPcURLJavaScriptPython

GET /api/archives/untagged HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*

200

Array of archive IDs

[
  "d1858d5dc36925aa66be072a97817650d39de166",
  "c3458d5dc36925da93be072a97817650d39de166",
  "28697b96f0ac5858be2614ed10ca47742c9522fd"
]

🔑 Upload Archive

put

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.

Authorizations

api_key

AuthorizationstringRequired

Use Authorization: Bearer <base64(api_key)>

Body

multipart/form-data

filestring · binaryRequired

Archive file to upload

file_checksumstringOptional

SHA1 checksum of the archive for in-transit validation.

Pattern: ^[a-fA-F0-9]{40}$

category_idstring · min: 14 · max: 14Optional

Category ID you'd want the archive to be added to.

tagsstringOptional

Set of tags you want to insert in the database alongside the archive.

titlestringOptional

Title of the Archive.

summarystringOptional

Summary of the Archive.

Responses

200

Archive uploaded successfully

application/json

operationstringRequired

Name of operation

Example: upload

successinteger · enumRequired

Returns 1 if operation was successful, else 0

Possible values:

idstring · min: 40 · max: 40Required

ID of the uploaded archive

400

Bad request

application/json

409

Duplicate archive

application/json

415

Unsupported file

application/json

417

Checksum mismatch

application/json

422

Unprocessable Entity

application/json

423

Locked resource response

application/json

500

Internal Server Error

application/json

put

/archives/upload

HTTPcURLJavaScriptPython

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 archive

delete

Delete both the archive metadata and the file stored on the server. 🙏 Please ask your user for confirmation before invoking this endpoint.

Authorizations

api_key

AuthorizationstringRequired

Use Authorization: Bearer <base64(api_key)>

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Responses

200

Archive deleted response

application/json

operationstring · enumOptional

Name of the operation

Possible values:

idstring · min: 40 · max: 40Optional

ID of the archive

filenamestringOptional

Filename of the deleted archive

successinteger · enumOptional

Returns 1 if operation was successful, else 0

Possible values:

400

No archive ID response

application/json

423

Locked resource response

application/json

delete

/archives/{id}

HTTPcURLJavaScriptPython

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 archive metadata

get

Get Metadata (title, tags) for a given Archive.

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Responses

200

Archive metadata

application/json

JSON object for archive metadata for most API responses

arcidstring · min: 40 · max: 40Required

Unique identifier for the archive

titlestringRequired

Title of the archive

filenamestringRequired

Filename of the archive

tagsstringRequired

Comma-separated list of tags associated with the archive

summarystringOptional

Summary description of the archive

isnewbooleanRequired

Whether the archive is newly added

extensionstringRequired

File extension of the archive

progressintegerRequired

Reading progress (page number)

pagecountintegerRequired

Total number of pages in the archive

lastreadtimeintegerRequired

Unix timestamp of when the archive was last read

sizeintegerRequired

Size of the archive in bytes

tocarrayRequired

Table of contents for the archive

400

No archive ID response

application/json

get

/archives/{id}/metadata

HTTPcURLJavaScriptPython

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 archive metadata

put

Update tags and title for the given Archive. Data supplied to the server through this method will overwrite the previous data.

Authorizations

api_key

AuthorizationstringRequired

Use Authorization: Bearer <base64(api_key)>

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Query parameters

titlestringOptional

New Title of the Archive.

tagsstringOptional

New Tags of the Archive.

summarystringOptional

New Summary of the Archive.

Responses

200

Archive metadata updated

application/json

operationstringRequired

Name of operation

errorstringOptional

Error message if any

successMessagestringOptional

Success message if any

successinteger · enumRequired

Returns 1 if operation was successful, else 0

Possible values:

400

No archive ID response

application/json

423

Locked resource response

application/json

put

/archives/{id}/metadata

HTTPcURLJavaScriptPython

PUT /api/archives/{id}/metadata HTTP/1.1
Host: lrr.tvc-16.science
Authorization: YOUR_API_KEY
Accept: */*

{
  "operation": "update_metadata",
  "success": 1
}

Get archive thumbnail

get

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.

Path parameters

idstring · min: 40 · max: 40Required

ID of the archive to process

Query parameters

no_fallbackstring · enumOptional

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)

Possible values:

pageintegerOptional

Specify which page you want to get a thumbnail for. Defaults to the cover, aka page 1.

Responses

200

If the thumbnail was already extracted, you get it directly.

application/octet-stream

string · binaryOptional

202

The thumbnail is queued for extraction. Use /api/minion/:jobid to track when your thumbnail is ready.

application/json

400

No archive ID response

application/json

get

/archives/{id}/thumbnail

HTTPcURLJavaScriptPython

GET /api/archives/{id}/thumbnail HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*

binary

🔑 Update archive thumbnail

put

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

Authorizations

api_key

AuthorizationstringRequired

Use Authorization: Bearer <base64(api_key)>

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Query parameters

pageintegerOptional

Page you want to make the thumbnail out of. Defaults to 1.

Responses

200

Archive thumbnail updated

application/json

operationstring · enumOptional

Name of operation

Possible values:

successinteger · enumOptional

Returns 1 if operation was successful, else 0

Possible values:

new_thumbnailstringOptional

New thumbnail URL

400

No archive ID response

application/json

put

/archives/{id}/thumbnail

HTTPcURLJavaScriptPython

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 entry to Archive Table of Contents

put

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.

Authorizations

api_key

AuthorizationstringRequired

Use Authorization: Bearer <base64(api_key)>

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Query parameters

pageintegerRequired

Page number where the chapter/section starts.

titlestringRequired

Title of the chapter/section.

Responses

200

Archive TOC updated

application/json

operationstringRequired

Name of operation

errorstringOptional

Error message if any

successMessagestringOptional

Success message if any

successinteger · enumRequired

Returns 1 if operation was successful, else 0

Possible values:

400

No archive ID response or other error

application/json

423

Locked resource response

application/json

put

/archives/{id}/toc

HTTPcURLJavaScriptPython

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

🔑 Remove entry from Archive Table of Contents

delete

Delete an entry from the Table of Contents of a given Archive.

Authorizations

api_key

AuthorizationstringRequired

Use Authorization: Bearer <base64(api_key)>

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Query parameters

pageintegerRequired

Page number of the chapter/section to delete.

Responses

200

Archive TOC updated

application/json

operationstringRequired

Name of operation

errorstringOptional

Error message if any

successMessagestringOptional

Success message if any

successinteger · enumRequired

Returns 1 if operation was successful, else 0

Possible values:

400

No archive ID response or other error

application/json

423

Locked resource response

application/json

delete

/archives/{id}/toc

HTTPcURLJavaScriptPython

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 archive categories

get

Get all the Categories which currently refer to this Archive ID.

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Responses

200

Archive categories

application/json

operationstring · enumOptional

Name of the operation

Possible values:

successinteger · enumOptional

Returns 1 if operation was successful, else 0

Possible values:

400

No archive ID response

application/json

get

/archives/{id}/categories

HTTPcURLJavaScriptPython

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 archive tankoubons

get

Get all the Tankoubons which currently refer to this Archive ID.

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Responses

200

Archive tankoubons

application/json

tankoubonsstring[]Optional

Array of tankoubon IDs

operationstring · enumOptional

Name of the operation

Possible values:

successinteger · enumOptional

Returns 1 if operation was successful, else 0

Possible values:

400

No archive ID response

application/json

get

/archives/{id}/tankoubons

HTTPcURLJavaScriptPython

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 archive

get

Download an Archive from the server.

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to download.

Responses

200

Archive file

application/octet-stream

string · binaryOptional

400

No archive ID response

application/json

get

/archives/{id}/download

HTTPcURLJavaScriptPython

GET /api/archives/{id}/download HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*

binary

Extract an Archive

get

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

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Query parameters

forcebooleanOptional

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.

Responses

200

You get page URLs, and the ID of the background extract job.

application/json

jobintegerOptional

ID of the background extract job

pagesstring[]Optional

Page URLs

400

No archive ID response

application/json

get

/archives/{id}/files

HTTPcURLJavaScriptPython

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

Extract page thumbnails

post

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.

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Query parameters

forcebooleanOptional

Whether to force regeneration of all thumbnails even if they already exist.

Responses

200

If thumbnails are already extracted and force=0

application/json

messagestringOptional

operationstring · enumOptional

Name of operation

Possible values:

successstring · enumOptional

Returns 1 if operation was successful, else 0

Possible values:

202

The thumbnails are queued for extraction. You can use /api/minion/:jobid to track progress, by looking at notes->progress and notes->pages.

application/json

400

No archive ID response

application/json

post

/archives/{id}/files/thumbnails

HTTPcURLJavaScriptPython

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

get

Get an archive page. This call is mainly used alongside /api/archives/files.

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to download.

Query parameters

pathanyRequired

Path to the image.

Responses

200

Archive page

application/octet-stream

string · binaryOptional

400

No archive ID response

application/json

get

/archives/{id}/page

HTTPcURLJavaScriptPython

GET /api/archives/{id}/page HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*

binary

Update reading progression

put

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

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

pageintegerRequired

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.

Responses

200

Success response

application/json

idstring · min: 40 · max: 40Optional

ID of the archive updated

operationstring · enumOptional

Name of the operation

Possible values:

pageintegerOptional

Updated reading progress

lastreadtimeintegerOptional

Last read time in epoch seconds

successinteger · enumOptional

Returns 1 if successful, else 0

Possible values:

400

Generic error response

application/json

423

Locked resource response

application/json

put

/archives/{id}/progress/{page}

HTTPcURLJavaScriptPython

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
}

🔑 Set Archive New flag

put

Sets/Restores the "New!" flag on an archive.

Authorizations

api_key

AuthorizationstringRequired

Use Authorization: Bearer <base64(api_key)>

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Responses

200

Successful response

application/json

operationstringRequired

Name of operation

errorstringOptional

Error message if any

successMessagestringOptional

Success message if any

successinteger · enumRequired

Returns 1 if operation was successful, else 0

Possible values:

400

No archive ID response

application/json

423

Locked resource response

application/json

put

/archives/{id}/isnew

HTTPcURLJavaScriptPython

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
}

Clear Archive New flag

delete

Clears the "New!" flag on an archive.

Path parameters

idstring · min: 40 · max: 40Required

ID of the Archive to process.

Responses

200

Successful response

application/json

idstring · min: 40 · max: 40Required

ID of the archive

operationstring · enumRequired

Name of the operation

Possible values:

successinteger · enumRequired

Returns 1 if successful, else 0

Possible values:

400

No archive ID response

application/json

423

Locked resource response

application/json

delete

/archives/{id}/isnew

HTTPcURLJavaScriptPython

DELETE /api/archives/{id}/isnew HTTP/1.1
Host: lrr.tvc-16.science
Accept: */*

{
  "id": "text",
  "operation": "clear_new",
  "success": 0
}