> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # 重新索引文档 > 为每个选中的文档排入一个索引任务，根据其当前文件重建索引。返回一个批量任务 ID，用于统一跟踪这些任务。 `all: true` 和 `documentIds` 必须且只能提供其中一个。 不会重新上传任何文件。用 `compilation_job.id` 通过 [获取索引任务](/zh/api-reference/indexing-tasks/get-indexing-task) 跟踪单个任务，通过 [获取批量任务](/zh/api-reference/indexing-tasks/get-bulk-task) 跟踪整个请求。 重新索引流程详见 [重新索引并跟踪索引进度](/zh/api-reference/guides/knowledge-base#track-indexing)。 ## OpenAPI ````yaml /zh/api-reference/openapi_service.json post /knowledge-fs/spaces/{knowledge_base_id}/documents/reindex openapi: 3.0.1 info: description: 用于 Dify 应用与知识库的 REST API。应用类接口使用应用 API 密钥认证，知识库类接口使用知识库 API 密钥认证。 title: Dify 服务 API version: 1.0.0 servers: - description: Dify 服务 API 的基础 URL。自部署时，替换为你的 API 基础 URL。 url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: API 基础 URL 的主机与路径，不含 `https://` 前缀。 security: - ApiKeyAuth: [] tags: - description: 与聊天消息和交互相关的操作。 name: 对话消息 - description: 文件上传和预览操作。 name: 文件操作 - description: 终端用户信息相关操作。 name: 终端用户 - description: 用户反馈操作。 name: 消息反馈 - description: 与管理会话相关的操作。 name: 会话管理 - description: 文字转语音和语音转文字操作。 name: 语音与文字转换 - description: 获取应用设置和信息的操作。 name: 应用配置 - description: 与管理标注直接回复相关的操作。 name: 标注管理 - description: 暂停等待人工输入的工作流恢复操作。 name: 人工介入 - description: 用于执行和管理工作流的操作。 name: 工作流运行 - description: 文本生成相关操作。 name: 文本生成消息 - description: 用于管理知识库的操作，包括创建、配置和检索。 name: 知识库 - description: 用于在知识库中创建、更新和管理文档的操作。 name: 文档 - description: 用于管理分段和子分段的操作。 name: 分段 - description: 用于管理知识库元数据字段和文档元数据值的操作。 name: 元数据 - description: 用于管理知识库标签和标签绑定的操作。 name: 标签 - description: 用于获取可用模型的操作。 name: 模型 - description: 用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。 name: 知识流水线 - description: 向知识库提问，并流式返回回答。 name: 查询 - description: 查看一次查询检索到了什么，以及原因。 name: 查询记录 - description: 在后台运行研究问题，并获取其结果。 name: 研究任务 - description: 读取知识库中的文档及其文件、修订版本和分段，并用元数据标注文档。 name: 文档与分段 - description: 跟踪、取消或重试索引，并列出知识库的后台任务。 name: 索引任务 - description: 跟踪文档文件、一批文件或数据源的删除，直到完成。 name: 删除作业 - description: 管理为知识库提供内容的数据源，以及它们的定时同步设置和连接。 name: 数据源 - description: 立即同步数据源，导入网站页面或提供商条目，并跟踪、取消或重试运行。 name: 数据源同步与导入 - description: 读取和更改知识库的模型与检索设置，并跟踪更改触发的迁移。 name: 设置 paths: /knowledge-fs/spaces/{knowledge_base_id}/documents/reindex: post: tags: - Documents and Chunks summary: 重新索引文档 description: >- 为每个选中的文档排入一个索引任务，根据其当前文件重建索引。返回一个批量任务 ID，用于统一跟踪这些任务。 `all: true` 和 `documentIds` 必须且只能提供其中一个。 不会重新上传任何文件。用 `compilation_job.id` 通过 [获取索引任务](/zh/api-reference/indexing-tasks/get-indexing-task) 跟踪单个任务，通过 [获取批量任务](/zh/api-reference/indexing-tasks/get-bulk-task) 跟踪整个请求。 重新索引流程详见 [重新索引并跟踪索引进度](/zh/api-reference/guides/knowledge-base#track-indexing)。 operationId: reindexDocuments parameters: - description: >- 知识库 ID：即知识库 **API 访问** 对话框中所示服务 API 端点的最后一段（`…/knowledge-fs/spaces/`），也是地址栏中 `/datasets/new/` 之后的那一段。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- 每次调用都应发送幂等键，这样重试才安全。使用 8～255 个可打印 ASCII 字符，首尾不得有空白；格式不正确的键返回 `400`。 重复发送相同的键和请求体，会返回原批量任务，不会启动新的索引任务。以不同的请求体、通过其他 API 密钥、在其他知识库中或为其他操作复用该键，会返回 `409`。 in: header name: Idempotency-Key required: false schema: maxLength: 255 minLength: 8 type: string requestBody: content: application/json: examples: all: summary: 请求示例 - 全部文档文件 value: all: true by_id: summary: 请求示例 - 指定文档 value: documentIds: - 3d2f1c0b-9a8e-4d7c-b6a5-4f3e2d1c0b9a - 8f14e45f-ceea-467a-9575-62c9a2d3e6b1 schema: additionalProperties: false description: >- 发送 `all: true` 或非空的 `documentIds` 数组，二者不可同时发送。使用 `documentIds` 时，`all` 可省略，也可为 `false` 或 `null`。使用 `all: true` 时，`documentIds` 可省略或为 `null`；空数组会被拒绝。 oneOf: - properties: all: enum: - true nullable: false type: boolean documentIds: enum: - null nullable: true type: array required: - all title: 全部文档 - properties: all: enum: - false - null nullable: true type: boolean documentIds: minItems: 1 nullable: false type: array required: - documentIds title: 指定文档 properties: all: description: >- 设为 `true` 时，重新索引该密钥可读取的所有文档文件。文件数超过上限（默认 100）时，调用返回 `400`，且不会重新索引任何内容。 nullable: true type: boolean documentIds: description: >- 要重新索引的文档，可传文档 ID（从 [获取文档列表](/zh/api-reference/documents-and-chunks/list-documents) 获取）或文档文件 ID（从 [获取文档文件列表](/zh/api-reference/documents-and-chunks/list-document-files) 获取）。部署可能设置更低的上限。重复的 ID 会合并，因此 `total` 可能小于发送的数量。每个 ID 只发送一次，`items` 就会按顺序与请求逐项对应。 items: format: uuid type: string maxItems: 100 minItems: 1 nullable: true type: array type: object description: >- 标记为 nullable 的可选字段，传 `null` 等同于省略。 规范化后的请求不得超过 1,048,576 个 UTF-8 字节。参见 [请求大小限制](/zh/api-reference/guides/knowledge-base#request-size-limits)。 required: true responses: '202': content: application/json: examples: success: summary: 响应示例 value: bulk_job_id: 5a1c2e3d-7b8f-4a9c-8d1e-2f3a4b5c6d7e items: - asset: created_at: '2026-09-03T10:02:11Z' filename: handbook.pdf id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b metadata: {} mime_type: application/pdf object_key: >- 1a7c9e40-2b3d-4f56-8a90-b1c2d3e4f506/spaces/9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b/documents/6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b/handbook.pdf parser_status: parsed sha256: >- 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 size_bytes: 482113 source_id: null updated_at: null version: 1 code: null compilation_job: id: e4a1f0b2-7c3d-4e5f-9a1b-2c3d4e5f6a7b stage: queued document_id: null error: null status: queued status_url: >- /knowledge-spaces/9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b/documents/3d2f1c0b-9a8e-4d7c-b6a5-4f3e2d1c0b9a/processing-tasks/e4a1f0b2-7c3d-4e5f-9a1b-2c3d4e5f6a7b - asset: null code: null compilation_job: null document_id: 8f14e45f-ceea-467a-9575-62c9a2d3e6b1 error: null status: not_found status_url: null total: 2 schema: properties: bulk_job_id: description: >- 批量任务 ID。通过 [获取批量任务](/zh/api-reference/indexing-tasks/get-bulk-task) 轮询。 type: string items: description: >- 发送的每个不同 ID 对应一个条目，按请求顺序排列；`all` 为 `true` 时，其后是每个选中文件对应的条目。解析为同一文档文件的多个 ID 共用一个条目。 items: properties: asset: allOf: - $ref: '#/components/schemas/KnowledgeBaseDocumentFile' description: 正在重新索引的文档文件。仅当 `status` 为 `queued` 时有值，否则为 `null`。 nullable: true code: description: '`status` 为 `failed` 时的失败代码，否则为 `null`。' nullable: true type: string compilation_job: description: 索引任务。仅当 `status` 为 `queued` 时有值，否则为 `null`。 nullable: true properties: id: description: >- 索引任务 ID。通过 [获取索引任务](/zh/api-reference/indexing-tasks/get-indexing-task) 轮询。 type: string stage: description: 此时始终为 `queued`。 type: string type: object document_id: description: >- 请求中发送的 ID；对于通过 `all: true` 选中的条目，则为文档文件 ID。`status` 为 `disabled`、`not_found`、`failed` 或 `pending` 时有值。`queued` 条目为 `null`，其文档文件 ID 见 `asset.id`。 nullable: true type: string error: description: '`status` 为 `failed` 时的失败信息，否则为 `null`。' nullable: true type: string status: description: >- - `queued`：已启动索引任务，`asset`、`compilation_job` 和 `status_url` 均有值。 - `disabled`：文档已禁用，因此没有排入任务，批量任务将其计为已取消。此 API 中没有可启用文档的操作。 - `not_found`：没有与该 ID 匹配的可读文档文件。 - `failed`：未启动索引任务，原因见 `code` 和 `error`。 - `pending`：无法确认是否已启动索引任务。 type: string status_url: description: >- 任务的内部路径，仅供参考。跟踪任务应改用 [获取批量任务](/zh/api-reference/indexing-tasks/get-bulk-task)。仅当 `status` 为 `queued` 时有值，否则为 `null`。 nullable: true type: string type: object type: array total: description: '`items` 中的条目数。' type: integer type: object description: 索引任务已排入队列。 '400': content: application/json: examples: knowledge_fs_invalid_request_local: summary: knowledge_fs_invalid_request (request validation) value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - documentIds type: too_long knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (rejected) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`：请求未通过校验。`violations` 列出每个出错的字段。`all: true` 和 `documentIds` 都未提供或同时提供时，返回 `400`。 - `knowledge_fs_invalid_request`：`documentIds` 的条目数超出部署设定的上限，`all: true` 选中的文件数超出上限，或某个 ID 不是 UUID。 - `knowledge_fs_invalid_request`：`Idempotency-Key` 不是 8～255 个可打印 ASCII 字符，或首尾带有空白。 '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`：缺少 `Authorization` 请求头，或密钥无法识别、不是知识库 API 密钥。 - `knowledge_fs_invalid_credential`：密钥有效，但其所属工作空间中没有此 ID 的知识库，或该密钥未关联任何工作空间。 '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied_scope: summary: knowledge_fs_access_denied (key scope) value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 knowledge_fs_access_denied_upstream: summary: knowledge_fs_access_denied (rejected) value: code: knowledge_fs_access_denied failure: action: contact_admin category: authorization code: KNOWLEDGE_FS_ACCESS_DENIED message: >- You do not have permission to perform this Agent Knowledge Base operation. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- You do not have permission to perform this Agent Knowledge Base operation. status: 403 description: >- - `knowledge_fs_access_denied`：该密钥的访问范围限定为其他知识库、此知识库已关闭 **API 访问**，或知识库未处于活动状态。 - `knowledge_fs_access_denied`：该密钥无权访问此知识库的内容。 - `forbidden`：在 Dify Cloud 上，工作空间已达到其订阅套餐的知识库请求频率限制。所有调用都计入，读取操作也不例外。 '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: >- - `knowledge_fs_resource_not_found`：无法识别该知识库 ID。 - `knowledge_fs_resource_not_found`：某个选中的文档文件已无法用该密钥读取，例如密钥的访问权限变更后，又用同一个 `Idempotency-Key` 重复请求。 - `not_found`：当前部署已关闭 Agent 知识库功能。 '409': content: application/json: examples: knowledge_fs_conflict: summary: knowledge_fs_conflict value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_FS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: manual traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`：该知识库仍在从经典知识库格式迁移，稍后重试。 - `knowledge_fs_conflict`：某个文档没有生效的修订版本，且其最新修订版本的索引任务无法重试。 - `knowledge_fs_conflict`：`Idempotency-Key` 已以不同的请求体、通过其他 API 密钥、在其他知识库中或为其他操作使用过。 '413': content: application/json: examples: knowledge_fs_request_too_large: summary: knowledge_fs_request_too_large value: code: knowledge_fs_request_too_large failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 7f3c1a90-2e64-4b7d-8a51-6c0d9e2f4b83 message: The Agent Knowledge Base request is invalid. status: 413 knowledge_fs_request_too_large_budget: summary: knowledge_fs_request_too_large (request budget) value: code: knowledge_fs_request_too_large message: Agent Knowledge Base request is too large. status: 413 description: >- - `knowledge_fs_request_too_large`：知识库超出了配置的资源配额，或服务无法完成配额检查。响应体中的 `failure.code` 为 `KNOWLEDGE_FS_INVALID_REQUEST`。 - `knowledge_fs_request_too_large`：Dify 补上默认值后，请求超过 1,048,576 个 UTF-8 字节。参见 [请求大小限制](/zh/api-reference/guides/knowledge-base#request-size-limits)。 '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable (service error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 knowledge_fs_upstream_unavailable_transport: summary: knowledge_fs_upstream_unavailable (no response) value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 description: >- - `knowledge_fs_upstream_unavailable`：未能及时收到响应，或无法读取响应。 响应丢失前，索引可能已经开始。如果收到了任务 ID，轮询这些任务。如果发送了 `Idempotency-Key`，用同一个键再次发送相同的请求：它会返回原批量任务。 '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`：此工作空间尚未配置 Agent 知识库功能、当前部署不提供此操作，或在请求鉴权期间该密钥对此知识库的访问权限发生了变化。 - `knowledge_fs_operation_unavailable`：暂时无法处理该请求。按 `failure.retryPolicy` 处理。 - `knowledge_fs_operation_unavailable`：使用 `all: true` 时，请求在列出该密钥可读取的文件之前就已放弃，大部分文件对该密钥不可见时会出现这种情况。 components: schemas: KnowledgeBaseDocumentFile: properties: created_at: description: 文件存储时间，ISO 8601 格式。 type: string filename: description: 原始文件名。 type: string id: description: 文档文件 ID。与在 Dify 中打开文档时地址栏里的文档 ID 不同。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string metadata: additionalProperties: true description: 上传或导入文件时随文件记录的元数据。 type: object mime_type: description: 文件的 MIME 类型。 type: string object_key: description: 文件在对象存储中的键。此 API 中没有返回文件内容的操作。 type: string parser_status: description: >- 该版本文件的解析状态：`pending`、`parsed` 或 `failed`。解析是索引的一个步骤。`parsed` 的文件也可能没有大纲和分段。 type: string sha256: description: 文件内容的 SHA-256 哈希值，十六进制编码。 type: string size_bytes: description: 文件大小，单位为字节。 type: integer source_id: description: 文件导入来源的数据源 ID。上传的文件为 `null`。 nullable: true type: string updated_at: description: 文件记录最后变更时间，ISO 8601 格式。创建后未变更时为 `null`。 nullable: true type: string version: description: >- 对此文件 ID 始终为 `1`。内容更新（包括数据源同步）会生成新的文件 ID，而不会递增此值。此值与文档内容的修订版本相互独立。调用 [删除文档文件](/zh/api-reference/documents-and-chunks/delete-document-file) 时将其作为 `expectedRevision` 传入。 type: integer type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- 每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/api-reference/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.