文档（列表 / 读写 / 文件 URL）

通用鉴权与 Base URL 见 HTTP API 总览。
上传见上传文件，删除见删除文档 / 空间。

列出文档

GET /v1/knowledge-bases/{kb_id}/documents
Authorization: Bearer <token>

查询参数	说明
`path`	可选。按目录精确匹配，如 `path=/` 或 `path=/wiki/`。省略则返回该空间未归档文档。
`include_scaffold`	可选，默认 `false`。为 `true` 时包含建库脚手架：`overview.md` / `log.md` / `index.json` / `.keep`。

成功：200，文档对象数组。默认不含 archived=true，也不含上述脚手架文件（与空间「文件数」一致）。元素字段见下方「文档对象」。

文档对象

列表与 GET /v1/documents/{doc_id} 共用同一结构（节选）：

字段	说明
`id`	文档 UUID
`knowledge_base_id`	所属空间 UUID
`filename` / `path` / `title`	文件名、目录、标题
`file_type`	见下方「file_type 取值」
`file_size`	字节数（笔记等可能为 `0`）
`status`	如 `pending`（解析中）、`ready`（可检索）、失败时见 `error_message`
`page_count`	页数（若有）
`tags`	字符串数组（知识库科目等）
`document_number`	空间内编号（若有）
`version`	内容版本号
`archived`	是否已归档
`created_at` / `updated_at`	时间

file_type 取值

来源	`file_type`
二进制上传（TUS / multipart）	`pdf` · `pptx` · `ppt` · `docx` · `doc` · `png` · `jpg` · `jpeg` · `webp` · `gif` · `xlsx` · `xls` · `csv` · `html`（`.htm` 也存为 `html`）
Markdown 笔记 / 参考文献导入 / 脚手架	`md`

上传允许的扩展名见上传文件。

单篇元数据

GET /v1/documents/{doc_id}
Authorization: Bearer <token>

成功：200，单个文档对象。
失败：404（不存在或无权）。

单篇正文

GET /v1/documents/{doc_id}/content
Authorization: Bearer <token>

成功：200

{
  "id": "<doc-uuid>",
  "content": "# 标题\n…",
  "version": 1
}

content 在尚未解析完成时可能为 null。

获取文件地址（单篇）

一次取出可打开的地址。请同时要 source,preview（或再加上 converted），缺的项是 null，整请求仍返回 200。

GET /v1/documents/{doc_id}/url?variant=source,preview,converted
Authorization: Bearer <token>

查询参数	说明
`variant`	可选，默认 `preview`。可逗号分隔：`preview`（阅读）、`source`（原件）、`converted`、`tagged`、`ocr`。

成功：200

{
  "url": "<第一个 variant 的地址，没有则为 null>",
  "variant": "source",
  "urls": { "source": "…", "preview": "…", "converted": null }
}

打开方式：

const BASE = "https://textira.com";
const headers = { Authorization: `Bearer ${token}` };

const loc = await fetch(
  `${BASE}/v1/documents/${docId}/url?variant=source,preview,converted`,
  { headers },
).then((r) => r.json());

if (loc.urls.preview) {
  // 可在浏览器中打开阅读
  window.open(loc.urls.preview, "_blank");
} else {
  // 没有阅读页时，把正文显示在页面里
  const { content } = await fetch(
    `${BASE}/v1/documents/${docId}/content`,
    { headers },
  ).then((r) => r.json());
}

只请求默认 /url（不带 variant）且没有阅读页时，会 404：No PDF preview; use document content。请改用上面的多 variant，或直接取正文。

未配置对象存储时可能 501。Markdown 笔记通常没有文件地址，用 GET /v1/documents/{doc_id}/content。

获取文件地址（批量）

按整个空间一次返回各文档的文件地址，供打开阅读。

GET /v1/knowledge-bases/{kb_id}/files
Authorization: Bearer <token>

查询参数	说明
`variants`	可选，默认 `source,preview`。逗号分隔，同「单篇」的 `variant` 取值。
`path`	可选。目录精确匹配，如 `path=/`。
`include_scaffold`	可选，默认 `false`。

按论文任务 ID（无需先查 kb_id）：

GET /v1/integrations/paper/task-libraries/by-external/{external_task_id}/files
Authorization: Bearer <token>

查询参数与上相同。详见论文相关接口 · 获取文件地址。

成功：200

{
  "knowledge_base_id": "...",
  "external_task_id": "lp_task_6",
  "count": 2,
  "variants": ["source", "preview"],
  "items": [
    {
      "document_id": "...",
      "filename": "paper.pdf",
      "file_type": "pdf",
      "title": "…",
      "path": "/",
      "status": "ready",
      "external_id": "ref_1",
      "doi": null,
      "has_content": true,
      "urls": {
        "source": "https://…",
        "preview": "https://…"
      }
    }
  ]
}

urls 里没有的项为 null。有 preview 即可在浏览器打开；没有且 has_content=true 时用 GET /v1/documents/{id}/content 展示正文。

更新正文

PUT /v1/documents/{doc_id}/content
Authorization: Bearer <token>
Content-Type: application/json

{ "content": "# 新正文\n…" }

成功：200，返回 { "id", "content", "version" }（version 递增）；服务端会重建检索分块。

更新元数据

PATCH /v1/documents/{doc_id}
Authorization: Bearer <token>
Content-Type: application/json

{ "title": "新标题", "tags": ["综述"], "path": "/wiki/" }

可更新字段包括：filename、path、title、tags 等。
成功：200，完整文档对象。

同步文档到知识库

对接方将任务文献库中的文档同步到 kind=knowledge 的目标库时调用。传目标库 id + 源文档 id 即可，无需自行下载再上传。完整字段与错误码见论文相关接口 · 同步文档到知识库。

POST /v1/knowledge-bases/{targetKbId}/documents/import
Authorization: Bearer <token>
Content-Type: application/json

{
  "sourceDocumentId": "<source-doc-uuid>",
  "directory": "/",
  "duplicateStrategy": "reuse"
}

字段	说明
路径 `{targetKbId}`	目标知识库 UUID（`kind=knowledge`）
`sourceDocumentId`	源文档 UUID
`directory`	可选目标目录；不可为 `/wiki/`
`tags`	省略=沿用源标签；`[]`=清空；非空=覆盖
`category`	可选，写入 `metadata.category`
`duplicateStrategy`	`reuse`（默认）或 `reject`

新建 201，幂等复用 200。批量：POST .../documents/import-batch。

整理到知识页（仅知识库）

把侧栏「资料」里已解析就绪的文件，整理成 /wiki/concepts/ 下的知识页，并更新 overview / log。
任务文献库不可用；已在 /wiki/ 下的页面也不能再整理。

POST /v1/knowledge-bases/{kb_id}/documents/{doc_id}/compile
Authorization: Bearer <token>

查询参数	说明
`force`	`true` 时已有知识页也强制重新生成

成功：200

{
  "status": "ready",
  "source_id": "<原资料 doc id>",
  "wiki_id": "<知识页 doc id>",
  "wiki_path": "/wiki/concepts/….md",
  "wiki_title": "标题",
  "reused": false
}

reused: true 表示沿用已有知识页（未传 force）。
需 API 侧配置 DASHSCOPE_API_KEY；未配置时 503。产品说明见知识库。