> ## 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. # 批量删除文档文件 > 一次调用请求删除最多 100 个文档文件，并返回每个文件的处理结果。与 [删除文档文件](/zh/api-reference/documents-and-chunks/delete-document-file) 一样，不要删除生效修订版本的文件。 此 `DELETE` 请求需携带 JSON 请求体。如果客户端默认不为 DELETE 请求发送请求体，需将其配置为显式发送。 文件先按 `documentId`、再按 `expectedRevision` 排序，并逐个独立处理。文件不存在、`expectedRevision` 已过时、已在删除中，或该密钥无权删除时，该文件会以 `rejected` 出现在 `results` 中，其他文件照常处理。遇到基础设施故障时，处理会中止，剩余文件保持 `pending`。 基础设施故障后，或整个调用失败后，如需继续，使用同一个 `Idempotency-Key` 再次发送相同的请求。它会返回原批次及其中已受理的作业，并且只重试 `pending` 的文件。 此调用不会创建批量任务。 删除流程详见 [删除文档和数据源](/zh/api-reference/guides/knowledge-base#delete-documents-and-sources)。 ## OpenAPI ````yaml /zh/api-reference/openapi_service.json delete /knowledge-fs/spaces/{knowledge_base_id}/documents/bulk 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/bulk: delete: tags: - Documents and Chunks summary: 批量删除文档文件 description: >- 一次调用请求删除最多 100 个文档文件，并返回每个文件的处理结果。与 [删除文档文件](/zh/api-reference/documents-and-chunks/delete-document-file) 一样，不要删除生效修订版本的文件。 此 `DELETE` 请求需携带 JSON 请求体。如果客户端默认不为 DELETE 请求发送请求体，需将其配置为显式发送。 文件先按 `documentId`、再按 `expectedRevision` 排序，并逐个独立处理。文件不存在、`expectedRevision` 已过时、已在删除中，或该密钥无权删除时，该文件会以 `rejected` 出现在 `results` 中，其他文件照常处理。遇到基础设施故障时，处理会中止，剩余文件保持 `pending`。 基础设施故障后，或整个调用失败后，如需继续，使用同一个 `Idempotency-Key` 再次发送相同的请求。它会返回原批次及其中已受理的作业，并且只重试 `pending` 的文件。 此调用不会创建批量任务。 删除流程详见 [删除文档和数据源](/zh/api-reference/guides/knowledge-base#delete-documents-and-sources)。 operationId: deleteDocumentFilesInBatch parameters: - description: >- 知识库 ID：即知识库 **API 访问** 对话框中所示服务 API 端点的最后一段（`…/knowledge-fs/spaces/`），也是地址栏中 `/datasets/new/` 之后的那一段。 in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- 本次删除请求的标识，必填。用同一个 API 密钥重复发送相同的键和请求，会返回原批次，并重试其中 `pending` 的文件。将该键用于其他请求，或通过其他 API 密钥使用，会返回 `409`。使用可打印 ASCII 字符，首尾不得有空白。 in: header name: Idempotency-Key required: true schema: maxLength: 255 minLength: 8 type: string requestBody: content: application/json: examples: request: summary: 请求示例 value: documents: - documentId: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b expectedRevision: 1 - documentId: 2c1e7a44-5b6d-4e8f-9a0b-1c2d3e4f5a6b expectedRevision: 1 - documentId: 9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a expectedRevision: 1 schema: additionalProperties: false properties: documents: description: 要删除的文件。每个 `documentId` 只能出现一次。超出上限的批次返回 `400`，部署也可能设置更低的上限。 items: additionalProperties: false properties: documentId: description: >- 文档文件 ID。从 [获取文档文件列表](/zh/api-reference/documents-and-chunks/list-document-files) 获取。 minLength: 1 type: string expectedRevision: description: >- 文档文件当前的 `version`，从 [获取文档文件列表](/zh/api-reference/documents-and-chunks/list-document-files) 或 [获取文档文件](/zh/api-reference/documents-and-chunks/get-document-file) 获取。文档文件的 `version` 始终为 `1`。不是 [获取文档修订版本列表](/zh/api-reference/documents-and-chunks/list-document-revisions) 返回的修订版本号。 minimum: 1 type: integer required: - documentId - expectedRevision type: object maxItems: 100 minItems: 1 type: array required: - documents type: object description: >- 规范化后的请求不得超过 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: batch_id: 3e5a7c9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d items: - document_id: 2c1e7a44-5b6d-4e8f-9a0b-1c2d3e4f5a6b document_title: null job: checkpoint: requested completed_at: null created_at: '2026-09-06T02:15:30Z' error: null id: b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b mode: cascade progress: null retry_at: null run_state: dispatch_pending target_id: 2c1e7a44-5b6d-4e8f-9a0b-1c2d3e4f5a6b target_type: document updated_at: '2026-09-06T02:15:30Z' status_url: >- https://api.example.com/v1/knowledge-fs/spaces/8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f/deletion-jobs/b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e - document_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b document_title: null job: checkpoint: requested completed_at: null created_at: '2026-09-06T02:15:30Z' error: null id: 0c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b mode: cascade progress: null retry_at: null run_state: dispatch_pending target_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b target_type: document updated_at: '2026-09-06T02:15:30Z' status_url: >- https://api.example.com/v1/knowledge-fs/spaces/8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f/deletion-jobs/0c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f results: - document_id: 2c1e7a44-5b6d-4e8f-9a0b-1c2d3e4f5a6b error: null job: checkpoint: requested completed_at: null created_at: '2026-09-06T02:15:30Z' error: null id: b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b mode: cascade progress: null retry_at: null run_state: dispatch_pending target_id: 2c1e7a44-5b6d-4e8f-9a0b-1c2d3e4f5a6b target_type: document updated_at: '2026-09-06T02:15:30Z' status: accepted status_url: >- https://api.example.com/v1/knowledge-fs/spaces/8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f/deletion-jobs/b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e - document_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b error: null job: checkpoint: requested completed_at: null created_at: '2026-09-06T02:15:30Z' error: null id: 0c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f knowledge_space_id: 9b2e5b7a-3c1d-4e2f-8a9b-1c2d3e4f5a6b mode: cascade progress: null retry_at: null run_state: dispatch_pending target_id: 6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b target_type: document updated_at: '2026-09-06T02:15:30Z' status: accepted status_url: >- https://api.example.com/v1/knowledge-fs/spaces/8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f/deletion-jobs/0c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f - document_id: 9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a error: code: DURABLE_DELETION_NOT_FOUND message: Deletion request was rejected retryable: false job: null status: rejected status_url: null status_url: >- https://api.example.com/v1/knowledge-fs/spaces/8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f/deletion-batches/3e5a7c9b-1d2f-4a6b-8c0d-2e4f6a8b0c1d total: 3 schema: $ref: '#/components/schemas/KnowledgeBaseDeletionBatch' description: >- 批次已记录。`results` 给出每个文件的处理结果，`items` 列出已受理的文件。删除在后台进行。从文件的删除请求被受理起，[获取文档文件](/zh/api-reference/documents-and-chunks/get-document-file) 即返回 `404`。如需跟踪每个文件直到处理结束，轮询 [获取删除批次](/zh/api-reference/deletion-jobs/get-deletion-batch)（即批次的 `status_url`）。 轮询返回的作业 ID。如需重试仍为 `pending` 的文件，使用同一个 `Idempotency-Key` 再次发送相同的请求。 headers: Location: description: 与批次的 `status_url` 相同的 URL。 schema: type: string '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: - documents 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` 列出每个出错的字段。 - `knowledge_fs_invalid_request`：两个条目的 `documentId` 相同，批次超出部署设定的单次调用上限，或某个 `documentId` 不是 UUID。 '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。文件不存在或该密钥无权读取时，不再导致整个调用失败，而是以 `rejected` 出现在 `results` 中。 - `not_found`：当前部署已关闭 Agent 知识库功能。 '409': content: application/json: examples: durable_deletion_idempotency_conflict: summary: knowledge_fs_conflict (key reused) value: code: knowledge_fs_conflict failure: category: conflict code: DURABLE_DELETION_IDEMPOTENCY_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: never traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 description: >- - `knowledge_fs_conflict`：该 `Idempotency-Key` 已用于其他请求，或已被其他 API 密钥使用。`failure.code` 为 `DURABLE_DELETION_IDEMPOTENCY_CONFLICT`，`retryPolicy` 为 `never`。 `expectedRevision` 已过时、文件已在删除中或已删除，或文件所属的数据源正在删除时，不再导致整个调用失败，该文件会以 `rejected` 出现在 `results` 中。 '413': content: application/json: examples: knowledge_fs_request_too_large: 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`：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`：未能及时收到响应，或无法读取响应。 部分文件可能已被受理。使用同一个 `Idempotency-Key` 再次发送相同的请求：它会返回原批次，并重试仍为 `pending` 的文件。 '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` 处理。 components: schemas: KnowledgeBaseDeletionBatch: properties: batch_id: description: 记录本次请求的批次 ID。 nullable: true type: string items: description: 每个已受理的文件对应一项。 items: properties: document_id: description: 文档文件 ID。 type: string document_title: description: 删除文档文件时始终为 `null`。 nullable: true type: string job: $ref: '#/components/schemas/KnowledgeBaseDeletionJob' status_url: description: >- 该文件对应作业的 [获取删除作业](/zh/api-reference/deletion-jobs/get-deletion-job) URL。 type: string type: object type: array results: description: 请求中的每个文件对应一项，包含其处理结果。 items: properties: document_id: description: 文档文件 ID。 type: string error: description: 拒绝该文件的原因。其他情况下为 `null`。 nullable: true properties: code: description: >- 错误码：`DURABLE_DELETION_NOT_FOUND`、`DURABLE_DELETION_REVISION_CONFLICT`、`DURABLE_DELETION_STATE_CONFLICT` 或 `DURABLE_DELETION_FORBIDDEN`。 type: string message: description: 始终为 `Deletion request was rejected`。 type: string retryable: description: 始终为 `false`。 type: boolean type: object job: allOf: - $ref: '#/components/schemas/KnowledgeBaseDeletionJob' description: '`status` 为 `accepted` 时的删除作业，否则为 `null`。' nullable: true status: description: |- - `accepted`：删除请求已受理，`job` 和 `status_url` 有值。 - `rejected`：未删除该文件，原因见 `error`。 - `pending`：尚未受理该文件。如需重试，使用同一个 `Idempotency-Key` 再次发送原请求。 type: string status_url: description: >- 该文件对应作业的 [获取删除作业](/zh/api-reference/deletion-jobs/get-deletion-job) URL。仅当 `status` 为 `accepted` 时有值，否则为 `null`。 nullable: true type: string type: object type: array status_url: description: >- 此批次的 [获取删除批次](/zh/api-reference/deletion-jobs/get-deletion-batch) URL：部署设置了 `SERVICE_API_URL` 时为绝对 URL，否则为以 `/v1/` 开头的路径。[批量删除文档文件](/zh/api-reference/documents-and-chunks/delete-document-files-in-batch) 也会在 `Location` 响应头中返回该值。 nullable: true type: string total: description: 原请求中的文件数。 type: integer type: object KnowledgeBaseDeletionJob: properties: checkpoint: description: >- 删除进行到哪一步：从 `requested`（刚受理）开始，依次经过 `quiescing`、`deleting_objects`、`deleting_derived_data`、`deleting_primary_data`，直到 `completed`。 type: string completed_at: description: 作业完成时间，ISO 8601 格式。完成前以及作业为 `failed` 时为 `null`。 nullable: true type: string created_at: description: 作业的受理时间，ISO 8601 格式。 type: string error: description: >- 最近一次错误，没有错误时为 `null`。`run_state` 为 `retry_wait` 时也会设置此字段，因此判断作业是否失败应看 `run_state`，而不是 `error`。 nullable: true properties: code: description: 最近一次错误的错误码。 type: string message: description: 最近一次错误的公开消息，不含内部错误详情。 type: string retryable: description: '`run_state` 为 `failed` 时为 `true`。此 API 无法重试失败的删除。' type: boolean type: object id: description: 删除作业 ID。 type: string knowledge_space_id: description: 知识库的内部 ID，并非路径中的知识库 ID。 type: string mode: description: 删除数据源时如何处理其文档：`cascade` 一并删除，`keep` 保留。删除文档文件时，该值不表示删除会移除哪些内容。 nullable: true type: string progress: description: 多项删除的项数统计。此 API 不填充该字段，始终为 `null`。 nullable: true properties: completed_items: description: 已删除的项数。 type: integer current_item_kind: description: 正在删除的项的类型。 nullable: true type: string total_items: description: 待删除的项数。 nullable: true type: integer type: object retry_at: description: 下次自动重试的时间，ISO 8601 格式。未安排重试时为 `null`。 nullable: true type: string run_state: description: |- 调度状态： - `dispatch_pending`（刚受理）、`queued`、`running`：进行中。 - `retry_wait`：已安排在 `retry_at` 自动重试。 - `completed`：已全部移除。 - `failed`：清理已停止，删除目标仍保持隐藏，且无法重试。 type: string target_id: description: 删除目标的 ID：`document` 时为文档文件 ID，`source` 时为数据源 ID。 type: string target_type: description: 作业删除的对象：`document` 表示文档文件，`source` 表示数据源。 type: string updated_at: description: 作业最后变更时间，ISO 8601 格式。 type: string 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.