档案 API

29 endpoints.

批量删除档案（DELETE /archives，请求体 {ids: [...]}）

DELETEhttp://localhost:3000/api/archives

尚未在此参考中描述。这个端点会被列出，是因为服务端确实注册了它，但它的请求与响应形状还没有写下来。

下面这段是 handler 自己的文档注释（crates/lanrurugi-api/src/archives.rs:618）的译文；原文以源码为准。

DELETE /archives（issue #63），请求体 {ids: [...]}——沿用本代码库已有的「复数资源 + 用 JSON 请求体指明操作对象」这一形态（见 activity.rs::bulk_delete_activity 的 DELETE /activity），而不是 POST .../batch-delete 那种动作式路径；按 RFC 9110，DELETE 可以带请求体（虽然一些较旧的代理/客户端在实践中会静默丢掉它，但 Axum 和本项目自己的前端都处理得很好，而且本仓库已有先例）。Batch 页面自己的「删除档案」操作此前是在前端按选中的档案逐个发 DELETE /archives/{id}，就是一个普通的顺序循环（没有原子性，没有统一的审计点，而且——由于每个请求只报告自己的成功/失败——调用方除非在操作前后对比整个书库，否则无法知道哪些 id 失败了）。这里把同样的逐 id 工作（delete_one_archive，与单条删除端点完全相同的清理）放到服务端一个请求里完成，并返回逐 id 的结果列表，让前端能准确展示发生了什么，而不是假定全部成功。

仅限会话调用（route_policy.csv 拒绝所有令牌角色以及 anonymous）——刻意比本文件里其他所有会修改档案的端点都更严格，那些端点 Token（Admin 或 Guest）都能调用。一个泄露或被写错的 API 令牌就能在一个请求里抹掉任意规模的库内容，其影响范围远大于令牌访问本来就允许的任何一个单目标端点；而本项目对批量删除并不存在像脚本化上传或元数据编辑那样的正当自动化场景——所以这条额外限制不会破坏任何真实工作流。

响应

200该端点已响应；其确切结构尚未记录，见 crates/lanrurugi-api/src/archives.rs:209 处的 handler。

该响应没有示例数据。

服务器地址

该端点只接受网页会话（登录本站所用实例后浏览器自动携带的 cookie）。API 令牌会被服务端拒绝，因此这里不提供令牌输入框，上面的命令行也不带 Authorization 头。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

获取全部档案

GEThttp://localhost:3000/api/archives

返回数据库中全部档案的列表。按设计不包含 Tankoubon。 这个 JSON 里的 ID 可以用在其他端点上。

权限差异

• 访客和匿名调用者完全不可达。 这是无范围的列表：它返回书库中的全部档案，不做任何分类范围限制——给访客开放它等于绕过 /api/search 强制的那套「访客可见」限制。访客请走 /api/search。

响应

200档案数组

[
  {
    "arcid": "28697b96f0ac5858be2614ed10ca47742c9522fd",
    "extension": "rar",
    "filename": "Fate GO MEMO",
    "isnew": false,
    "lastreadtime": 1337038281,
    "pagecount": 34,
    "progress": 3,
    "size": 1234567,
    "summary": null,
    "tags": "parody:fate grand order,  group:wadamemo,  artist:wada rco,  artbook,  full color",
    "title": "Fate GO MEMO",
    "toc": [
      {
        "name": "Chapter 1",
        "page": 1
      },
      {
        "name": "Chapter 2",
        "page": 13
      },
      {
        "name": "Chapter 3",
        "page": 25
      }
    ]
  }
]

服务器地址API 令牌

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

删除档案

DELETEhttp://localhost:3000/api/archives/{id}

同时删除档案元数据和服务器上存储的文件。
🙏 调用这个端点前请先向用户确认。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

响应

200档案已删除的响应

{
  "filename": "big_chungus.zip",
  "id": "75d18ce470dc99f83dc355bdad66319d1f33c82b",
  "operation": "delete_archive",
  "success": 1
}

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

423资源被锁定的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpath

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

获取档案所属分类

GEThttp://localhost:3000/api/archives/{id}/categories

获取当前引用了该档案 ID 的全部分类。

路径参数

idstring必填

要处理的档案 ID。

响应

200档案所属分类

{
  "categories": [
    {
      "archives": [
        "0d50858d727723d856d2ab78564bb8e906e65f14",
        "7f03b8b1f337e1e42b2c2890533c0de7479d41ca"
      ],
      "id": "SET_1613080290",
      "name": "My great category",
      "pinned": 0,
      "search": null
    },
    {
      "archives": [
        "0d50858d727723d856d2ab78564bb8e906e65f14",
        "75d18ce470dc99f83dc355bdad66319d1f33c82b"
      ],
      "id": "SET_1613080294",
      "name": "My other category",
      "pinned": 1,
      "search": null
    }
  ],
  "operation": "find_arc_categories",
  "success": 1
}

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpath

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

下载档案

GEThttp://localhost:3000/api/archives/{id}/download

从服务端下载一个档案。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要下载的档案 ID。

响应

200档案文件

该响应没有示例数据。

400没有档案 ID 的响应

{
  "error": "No archive ID specified.",
  "operation": "download_archive",
  "success": 0
}

服务器地址API 令牌

idpath

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

提取档案

GEThttp://localhost:3000/api/archives/{id}/files

获取指向档案内各图片的 URL 列表。 如有必要，这个端点还会启动一个后台 Minion 任务来解压该档案，使其可供阅读。

权限差异

• 对不在访客可见范围内的档案，这里返回 404 而不是 403——刻意与「档案不存在」不可区分，因此这个响应无法被用来探测访客范围之外的档案是否存在。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

查询参数

forceboolean可选

强制在后台完整重新提取该档案。在该档案完全重新提取完成之前，后续的 /api/archives/:id/page 调用仍可能用到已有的缓存文件。

响应

200会返回页面 URL，以及后台提取任务的 ID。

{
  "job": 561,
  "pages": [
    ".\\/api\\/archives\\/28697b96f0ac5858be2614ed10ca47742c9522fd\\/page&path=00.jpg",
    ".\\/api\\/archives\\/28697b96f0ac5858be2614ed10ca47742c9522fd\\/page&path=01.jpg"
  ]
}

400没有档案 ID 的响应

{
  "error": "No archive ID specified.",
  "operation": "get_file_list",
  "success": 0
}

服务器地址API 令牌

idpathforcequery

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

提取页面缩略图

POSThttp://localhost:3000/api/archives/{id}/files/thumbnails

为指定档案的每一页生成缩略图。 这个端点会把缩略图生成排入后台队列。

如果检测到全部缩略图都已存在，调用会返回 HTTP 200。
这个端点可以重复调用——如果该 ID 的缩略图任务已经在进行中，它只会把那个进行中任务的 ID 给你。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

查询参数

forceboolean可选

是否强制重新生成全部缩略图，即使它们已经存在。

响应

200缩略图已提取且 `force=0` 时

{
  "message": "No job queued, all thumbnails already exist.",
  "operation": "generate_page_thumbnails",
  "success": 1
}

202缩略图已排入提取队列。可以用 `/api/minion/:jobid` 跟踪进度，查看 `notes->progress` 与 `notes->pages`。

{
  "job": 0,
  "operation": "",
  "success": 1
}

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpathforcequery

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

清除档案的「新」标记

DELETEhttp://localhost:3000/api/archives/{id}/isnew

清除档案上的「新！」标记。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

响应

200成功响应

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

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

423资源被锁定的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpath

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

设置档案的「新」标记

PUThttp://localhost:3000/api/archives/{id}/isnew

设置/恢复档案上的「新！」标记。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

响应

200成功响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

423资源被锁定的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpath

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

获取档案元数据

GEThttp://localhost:3000/api/archives/{id}/metadata

获取指定档案的元数据（标题、标签）。

权限差异

• 对不在访客可见范围内的档案，这里返回 404 而不是 403——刻意与「档案不存在」不可区分，因此这个响应无法被用来探测访客范围之外的档案是否存在。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

响应

200档案元数据

{
  "arcid": "28697b96f0ac5858be2614ed10ca47742c9522fd",
  "extension": "rar",
  "filename": "Fate GO MEMO",
  "isnew": false,
  "lastreadtime": 1337038281,
  "pagecount": 34,
  "progress": 3,
  "size": 1234567,
  "summary": null,
  "tags": "parody:fate grand order,  group:wadamemo,  artist:wada rco,  artbook,  full color",
  "title": "Fate GO MEMO",
  "toc": [
    {
      "name": "Chapter 1",
      "page": 1
    },
    {
      "name": "Chapter 2",
      "page": 13
    },
    {
      "name": "Chapter 3",
      "page": 25
    }
  ]
}

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpath

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

更新档案元数据

PUThttp://localhost:3000/api/archives/{id}/metadata

更新指定档案的标签与标题。
通过这个方法提交给服务端的数据会覆盖原有数据。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

查询参数

titlestring可选

档案的新标题。

tagsstring可选

档案的新标签。

summarystring可选

档案的新摘要。

响应

200档案元数据已更新

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

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

423资源被锁定的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpathtitlequerytagsquerysummaryquery

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

获取档案的某一页

GEThttp://localhost:3000/api/archives/{id}/page

获取档案的某一页。这个调用主要与 /api/archives/files 配合使用。

权限差异

• 对不在访客可见范围内的档案，这里返回 404 而不是 403——刻意与「档案不存在」不可区分，因此这个响应无法被用来探测访客范围之外的档案是否存在。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要下载的档案 ID。

查询参数

pathstring必填

图片路径。

响应

200档案页面

该响应没有示例数据。

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpathpathquery

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

返回前 N 页的自然像素宽高

GEThttp://localhost:3000/api/archives/{id}/page-dimensions

尚未在此参考中描述。这个端点会被列出，是因为服务端确实注册了它，但它的请求与响应形状还没有写下来。

下面这段是 handler 自己的文档注释（crates/lanrurugi-api/src/archives.rs:3688）的译文；原文以源码为准。

GET /archives/{id}/page-dimensions?count=N——只返回前 N 页的自然像素宽高，顺序与 /files 自己的 pages 数组一致（这样前端可以按下标直接配对，不必再做一次名称匹配）。它是对 /files 的新增端点，而不是折进 /files：/files 的既有调用方（第三方兼容的文件列表契约）不该被迫为一次需要逐条解析图片头的档案遍历买单；实际调用这个端点的只有无限滚动阅读视图（唯一真正需要它的调用方——用于在跳到恢复位置之前准确摆好尚未加载的 <img> 尺寸；为什么它只限定在跳转前的那些页而不是整个档案，见 read_page_dimensions 自身的文档）。

权限差异

• 对不在访客可见范围内的档案，这里返回 404 而不是 403——刻意与「档案不存在」不可区分，因此这个响应无法被用来探测访客范围之外的档案是否存在。

响应

200该端点已响应；其确切结构尚未记录，见 crates/lanrurugi-api/src/archives.rs:228 处的 handler。

该响应没有示例数据。

服务器地址API 令牌

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

删除补丁（DELETE /archives/{id}/patch，删除 .patch.zip 旁挂文件并清理相关状态）

DELETEhttp://localhost:3000/api/archives/{id}/patch

尚未在此参考中描述。这个端点会被列出，是因为服务端确实注册了它，但它的请求与响应形状还没有写下来。

下面这段是 handler 自己的文档注释（crates/lanrurugi-api/src/archives.rs:1160）的译文；原文以源码为准。

DELETE /archives/{id}/patch——删除旁挂的 .patch.zip（如果有），并清除该档案的 has_patch 标记。让用户可以撤销一个补丁——比如在重跑对比流程后换用另一个来源的页面——而不必改动档案本身。

响应

200该端点已响应；其确切结构尚未记录，见 crates/lanrurugi-api/src/archives.rs:248 处的 handler。

该响应没有示例数据。

服务器地址API 令牌

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

更新阅读进度

PUThttp://localhost:3000/api/archives/{id}/progress/{page}

告诉服务端你当前正在展示/阅读这个档案的第几页，以便它相应地更新内部的阅读进度。
这个端点还会用服务端当前时间戳更新该档案的最后阅读时间。

只有在你确认用户确实正在阅读你展示的那一页时才应调用它。
不要在为了预加载图片而请求服务端时使用它。

阅读进度是否允许回退由客户端决定。（网页端在用户开始重读前面的页面时会减小进度值）
不过建议在开始更新进度时顺手清掉档案上的「新！」标记——只要新标记还在，网页端就不会显示任何阅读进度。

⚠ 如果服务端配置为使用客户端进度跟踪，这个 API 调用会返回错误！
调用前请务必先用 /api/info 确认服务端是否跟踪阅读进度。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

pageinteger必填

要更新到的当前阅读页码。 必须是正整数，且不超过该档案的总页数。

响应

200成功响应

{
  "id": "75d18ce470dc99f83dc355bdad66319d1f33c82b",
  "lastreadtime": 123943543,
  "operation": "update_progress",
  "page": 34,
  "success": 1
}

400通用错误响应

{
  "error": "Server-side Progress Tracking is disabled on this instance.",
  "operation": "update_progress",
  "success": 0
}

401开启 authprogress 时需要认证

{
  "error": "This operation requires authentication.",
  "operation": "update_progress",
  "success": 0
}

423资源被锁定的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpathpagepath

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

重命名档案（PUT /archives/{id}/rename，新增端点，legacy 没有对应功能）

PUThttp://localhost:3000/api/archives/{id}/rename

尚未在此参考中描述。这个端点会被列出，是因为服务端确实注册了它，但它的请求与响应形状还没有写下来。

下面这段是 handler 自己的文档注释（crates/lanrurugi-api/src/archives.rs:1277）的译文；原文以源码为准。

PUT /archives/{id}/rename——新增端点，legacy 没有对应功能（legacy 根本没有档案重命名功能；已核对 ~/LANraragi/lib/LANraragi/Controller/*.pm 与 public/js/edit.js，任何地方都没有 rename 相关引用）。它重命名的是档案在磁盘上的文件（不只是存储的 title/name），并保持 Archive::file 与 LRR_FILEMAP 同步——参照 download_manager::ingest 自己那套「暂存文件改名进 archive_dir」的修正逻辑，那是「档案文件路径变了，要同步更新跟踪它的两处」最接近的既有先例。

旁挂的 .patch.zip（它如何被关联见 delete_patch 自身的文档——同目录、同主文件名，纯靠文件名约定）会随档案一起改名：把它留在旧主文件名下会静默破坏 patch::patch_path_for 之后每一次查找，使一个已存在的补丁变得不可见，既不报错也不删除任何东西——这类「静默接近数据丢失」的 bug，远比让本函数直接拒绝这次改名要糟糕。

响应

200该端点已响应；其确切结构尚未记录，见 crates/lanrurugi-api/src/archives.rs:249 处的 handler。

该响应没有示例数据。

服务器地址API 令牌

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

获取档案所属的 Tankoubon

GEThttp://localhost:3000/api/archives/{id}/tankoubons

获取当前引用了该档案 ID 的全部 Tankoubon。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

响应

200档案所属的 Tankoubon

{
  "operation": "find_arc_tankoubons",
  "success": 1,
  "tankoubons": [
    "TANK_1688616437",
    "TANK_1688693913"
  ]
}

400没有档案 ID 的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpath

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

获取档案缩略图

GEThttp://localhost:3000/api/archives/{id}/thumbnail

获取指定档案的缩略图。如果缩略图尚不存在，这个端点会返回一张占位图。若想把缩略图生成排入后台，可以使用 no_fallback 查询参数——这样你会拿到一个后台任务 ID，而不是占位图。

权限差异

• 对不在访客可见范围内的档案，这里返回 404 而不是 403——刻意与「档案不存在」不可区分，因此这个响应无法被用来探测访客范围之外的档案是否存在。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID

查询参数

no_fallbackstring · enum: true | false可选

关闭占位图，把缩略图排入提取队列，并返回 code 202 的 JSON。图片已存在时该参数不起作用。（无论哪种情况，只要图片已存在就会以 code 200 返回它）

pageinteger · min: 0可选

指定要取哪一页的缩略图，默认为封面，也就是第 1 页。

响应

200如果缩略图已经提取过，会直接返回它。

该响应没有示例数据。

202缩略图已排入提取队列。用 `/api/minion/:jobid` 跟踪它何时就绪。

{
  "job": 0,
  "operation": "",
  "success": 1
}

400没有档案 ID 的响应

{
  "error": "No archive ID specified.",
  "operation": "serve_thumbnail",
  "success": 0
}

服务器地址API 令牌

idpathno_fallbackquerypagequery

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

更新档案缩略图

PUThttp://localhost:3000/api/archives/{id}/thumbnail

更新指定档案的封面缩略图。你可以指定用哪一页作为缩略图，也可以使用默认缩略图。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

查询参数

pageinteger可选

用哪一页生成缩略图，默认第 1 页。

响应

200档案缩略图已更新

{
  "new_thumbnail": "",
  "operation": "update_thumbnail",
  "success": 0
}

400没有档案 ID 的响应

{
  "error": "No archive ID specified.",
  "operation": "update_thumbnail",
  "success": 0
}

服务器地址API 令牌

idpathpagequery

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

获取页面缩略图

GEThttp://localhost:3000/api/archives/{id}/thumbnails

尚未在此参考中描述。这个端点会被列出，是因为服务端确实注册了它，但它的请求与响应形状还没有写下来。

权限差异

• 对不在访客可见范围内的档案，这里返回 404 而不是 403——刻意与「档案不存在」不可区分，因此这个响应无法被用来探测访客范围之外的档案是否存在。

响应

200该端点已响应；其确切结构尚未记录，见 crates/lanrurugi-api/src/archives.rs:233 处的 handler。

该响应没有示例数据。

服务器地址API 令牌

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

从档案目录中移除条目

DELETEhttp://localhost:3000/api/archives/{id}/toc

从指定档案的目录中删除一个条目。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

查询参数

pageinteger必填

要删除的章节页码。

响应

200档案目录已更新

{
  "operation": "remove_toc",
  "success": 1,
  "successMessage": "Removed ToC entry for page 143."
}

400没有档案 ID 的响应，或其他错误

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

423资源被锁定的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpathpagequery

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

向档案目录添加条目

PUThttp://localhost:3000/api/archives/{id}/toc

向指定档案的目录添加一个条目。 目录以 JSON 编码的键值数组存储，把页码映射到从该页开始的章节标题。

路径参数

idstring · min: 40 · max: 40 · pattern必填

要处理的档案 ID。

查询参数

pageinteger必填

章节的起始页码。

titlestring必填

章节标题。

响应

200档案目录已更新

{
  "operation": "update_toc",
  "success": 1,
  "successMessage": "Added ToC entry for page 143."
}

400没有档案 ID 的响应，或其他错误

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

423资源被锁定的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpathpagequerytitlequery

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

获取全部未打标签的档案

GEThttp://localhost:3000/api/archives/untagged

获取没有任何标签记录的档案。 规则与批量打标签的筛选一致，因此 parody:、date_added:、series: 或 artist: 这类标签的存在不影响判定。

响应

200档案 ID 数组

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

服务器地址API 令牌

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

上传档案

PUThttp://localhost:3000/api/archives/upload

把档案上传到服务端。
如果附带该档案的 SHA1 校验和，服务端会做一次可选的传输中文件完整性校验，并在服务端算出的校验和不匹配时拒绝这次上传。

请求体

multipart/form-data

响应

200档案上传成功

{
  "id": "d07ff399dddb25a0408385bc75b9ba52709fe2c1",
  "operation": "upload",
  "success": 1
}

400请求有误

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

409重复的档案

{
  "error": "This file already exists in the Library. Enable replace duplicated archive in config to replace old ones.",
  "id": "0b91b546850e881034833c73375558928ddcec7c",
  "operation": "upload",
  "success": 0
}

415不支持的文件

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

417校验和不匹配

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

422无法处理的实体

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

423资源被锁定的响应

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

500服务端内部错误

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

Start or re-attach to a resumable upload

POSThttp://localhost:3000/api/archives/upload/session

Creates a session (an empty staged file plus a sidecar describing it) and returns the id. If client_key matches a session that is still alive, that session is returned instead, with the offset its bytes are already at — which is what makes a page refresh resumable rather than restarting the transfer.

The returned offset is always read from the staged file’s real length, never from the sidecar, so a truncated or edited sidecar cannot make the server believe it holds bytes it does not.

Sessions that have not been touched for 24 hours are swept by the operations here; the staged bytes also live in temp_dir, so DELETE /api/tempfolder reclaims them too.

请求体

application/json

响应

200A session to upload into.

{
  "created_at": 0,
  "file_name": "",
  "file_size": 0,
  "offset": 0,
  "operation": "upload",
  "resumed": false,
  "success": 1,
  "updated_at": 0,
  "upload_id": ""
}

服务器地址API 令牌

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

Abandon a session

DELETEhttp://localhost:3000/api/archives/upload/session/{id}

Drops the staged bytes and the sidecar. Safe to call on an unknown id.

路径参数

idstring必填

响应

200The session's bytes are gone (whether or not it existed).

该响应没有示例数据。

服务器地址API 令牌

idpath

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

Upload session status

GEThttp://localhost:3000/api/archives/upload/session/{id}

The handshake a resuming client starts from: how many bytes the server actually holds for this session. 404 means unknown, expired, or already completed — in every case the client’s correct move is to start a new session.

路径参数

idstring必填

响应

200The session, with its current offset.

{
  "created_at": 0,
  "file_name": "",
  "file_size": 0,
  "offset": 0,
  "operation": "upload",
  "resumed": false,
  "success": 1,
  "updated_at": 0,
  "upload_id": ""
}

404Unknown or expired session.

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpath

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

Append one chunk

PUThttp://localhost:3000/api/archives/upload/session/{id}

Appends the request body to the staged file, but only at the position the client claims. Upload-Offset is required and must equal the staged file’s real length; the response always reports the authoritative offset, including on failure:

• 204 — the chunk was appended; Upload-Offset is the new length.
• 409 — the client’s offset disagrees with the disk (a lost response, a retried chunk, two tabs); Upload-Offset says where to resume from.
• 400 — missing or malformed Upload-Offset.

A connection that dies mid-chunk keeps whatever bytes reached the disk and reports the offset, so a partial chunk is just fewer bytes rather than a corrupt one. The body is bounded at 64 MiB (the one-shot route is deliberately unbounded; a chunk is supposed to be small).

路径参数

idstring必填

请求头

Upload-Offsetinteger必填

Byte position this chunk starts at; must equal the server's own length.

请求体

application/octet-stream

响应

204Chunk appended.

该响应没有示例数据。

404Unknown or expired session.

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

409Offset mismatch; resync from the returned `Upload-Offset`.

该响应没有示例数据。

服务器地址API 令牌

idpath

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。

Finish a session and ingest it

POSThttp://localhost:3000/api/archives/upload/session/{id}/complete

Verifies what landed, hashes it, and hands it to the same ingest the one-shot route uses — including the persistent download-queue row, so a completed upload shows up (and can be removed) exactly like any other queue item.

Verification: a file_size announced at session creation must equal the staged length (417 otherwise, and the staged bytes are dropped), and an optional file_checksum is compared against the SHA-1 of the finished file (417 on mismatch). That SHA-1 is computed by reading the staged file once at this point rather than persisting incremental hasher state: a resumed upload’s early chunks were hashed by processes that are long gone, and state that can silently desync from the bytes on disk is a worse trade than one sequential read of an already-local file.

After this call the session no longer exists.

路径参数

idstring必填

请求体

application/json

响应

200Ingested; the same body the one-shot upload returns.

该响应没有示例数据。

400The session holds no bytes.

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

404Unknown or expired session.

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

417The announced size or the supplied checksum did not match what arrived.

{
  "error": "",
  "operation": "",
  "success": 0,
  "successMessage": ""
}

服务器地址API 令牌

idpath

该端点需要管理员令牌：访客（只读）令牌会被服务端拒绝。

发送复制为 cURL

填写你自己的实例地址，请求由浏览器直接发往该地址。