> ## 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. # Delete Document Files in Batch > Requests the deletion of up to 100 document files in one call and reports an outcome for each file. As with [Delete Document File](/en/api-reference/documents-and-chunks/delete-document-file), avoid files of active revisions. Send the JSON body with this `DELETE`. If your client omits bodies on DELETE requests, configure it to send the body explicitly. Files are sorted by `documentId`, then `expectedRevision`, and each is handled on its own. A file that does not exist, has a stale `expectedRevision`, is already being deleted, or cannot be deleted with this key comes back in `results` as `rejected`, and the other files proceed. An infrastructure failure stops the run and leaves the remaining files `pending`. To continue after an infrastructure failure, or after the call fails as a whole, send the same request again with the same `Idempotency-Key`. It returns the original batch with the jobs already accepted and retries only the `pending` files. This call creates no bulk task. For the deletion flow, see [Delete Documents and Sources](/en/api-reference/guides/knowledge-base#delete-documents-and-sources). ## OpenAPI ````yaml /en/api-reference/openapi_service.json delete /knowledge-fs/spaces/{knowledge_base_id}/documents/bulk openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/documents/bulk: delete: tags: - Documents and Chunks summary: Delete Document Files in Batch description: >- Requests the deletion of up to 100 document files in one call and reports an outcome for each file. As with [Delete Document File](/en/api-reference/documents-and-chunks/delete-document-file), avoid files of active revisions. Send the JSON body with this `DELETE`. If your client omits bodies on DELETE requests, configure it to send the body explicitly. Files are sorted by `documentId`, then `expectedRevision`, and each is handled on its own. A file that does not exist, has a stale `expectedRevision`, is already being deleted, or cannot be deleted with this key comes back in `results` as `rejected`, and the other files proceed. An infrastructure failure stops the run and leaves the remaining files `pending`. To continue after an infrastructure failure, or after the call fails as a whole, send the same request again with the same `Idempotency-Key`. It returns the original batch with the jobs already accepted and retries only the `pending` files. This call creates no bulk task. For the deletion flow, see [Delete Documents and Sources](/en/api-reference/guides/knowledge-base#delete-documents-and-sources). operationId: deleteDocumentFilesInBatch parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string - description: >- Required identifier for this deletion request. Repeating the same key and request with the same API key returns the original batch and retries its `pending` files. Reusing the key for a different request, or from another API key, answers `409`. Use printable ASCII characters without leading or trailing whitespace. in: header name: Idempotency-Key required: true schema: maxLength: 255 minLength: 8 type: string requestBody: content: application/json: examples: request: summary: Request Example 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: >- Files to delete. Each `documentId` must appear once. A larger batch answers `400`. The deployment may set a lower cap. items: additionalProperties: false properties: documentId: description: >- Document file ID. From [List Document Files](/en/api-reference/documents-and-chunks/list-document-files). minLength: 1 type: string expectedRevision: description: >- The document file's current `version`, from [List Document Files](/en/api-reference/documents-and-chunks/list-document-files) or [Get Document File](/en/api-reference/documents-and-chunks/get-document-file). A document file's `version` is always `1`. Not the revision number from [List Document Revisions](/en/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: >- The normalized request must fit within 1,048,576 UTF-8 bytes. See [Request Size Limits](/en/api-reference/guides/knowledge-base#request-size-limits). required: true responses: '202': content: application/json: examples: success: summary: Response Example 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: >- The batch was recorded. `results` gives each file's outcome, and `items` lists the accepted files. Deletion runs in the background. [Get Document File](/en/api-reference/documents-and-chunks/get-document-file) answers `404` from the moment a file's deletion is accepted. To follow every file to the end, poll [Get Deletion Batch](/en/api-reference/deletion-jobs/get-deletion-batch) (the batch `status_url`). Poll the returned job IDs. To retry files left `pending`, send the same request again with the same `Idempotency-Key`. headers: Location: description: The same URL as the batch `status_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`: the request failed validation. `violations` names each failing field. - `knowledge_fs_invalid_request`: two entries share a `documentId`, the batch exceeds the deployment's per-call cap, or a `documentId` is not a 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`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '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`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `knowledge_fs_access_denied`: the key's write access was revoked while the batch was being admitted. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '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`: the knowledge base ID isn't recognized. A file that does not exist or that the key cannot read no longer fails the call; it comes back in `results` as `rejected`. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '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`: the `Idempotency-Key` was already used for a different request or from another API key. `failure.code` is `DURABLE_DELETION_IDEMPOTENCY_CONFLICT`, with `retryPolicy` `never`. A stale `expectedRevision`, a file that is already deleting or deleted, or a file whose source is being deleted no longer fails the call; that file comes back in `results` as `rejected`. '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`: the request, once Dify adds its defaults, exceeds 1,048,576 UTF-8 bytes. See [Request Size Limits](/en/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`: no answer came back in time, or the answer couldn't be read. Some files may have been accepted. Send the same request again with the same `Idempotency-Key`: it returns the original batch and retries the files still `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`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. components: schemas: KnowledgeBaseDeletionBatch: properties: batch_id: description: ID of the batch that records this request. nullable: true type: string items: description: One entry per accepted file. items: properties: document_id: description: The document file ID. type: string document_title: description: Always `null` for document file deletions. nullable: true type: string job: $ref: '#/components/schemas/KnowledgeBaseDeletionJob' status_url: description: >- URL of the file's job in [Get Deletion Job](/en/api-reference/deletion-jobs/get-deletion-job). type: string type: object type: array results: description: One entry per requested file, with its outcome. items: properties: document_id: description: The document file ID. type: string error: description: Why the file was rejected. `null` otherwise. nullable: true properties: code: description: >- Error code: `DURABLE_DELETION_NOT_FOUND`, `DURABLE_DELETION_REVISION_CONFLICT`, `DURABLE_DELETION_STATE_CONFLICT`, or `DURABLE_DELETION_FORBIDDEN`. type: string message: description: Always `Deletion request was rejected`. type: string retryable: description: Always `false`. type: boolean type: object job: allOf: - $ref: '#/components/schemas/KnowledgeBaseDeletionJob' description: >- The deletion job when `status` is `accepted`. `null` otherwise. nullable: true status: description: >- - `accepted`: deletion was accepted, and `job` and `status_url` are set. - `rejected`: the file was not deleted. `error` says why. - `pending`: the file was not accepted yet. To retry it, send the original request again with the same `Idempotency-Key`. type: string status_url: description: >- URL of [Get Deletion Job](/en/api-reference/deletion-jobs/get-deletion-job) for the file's job. `null` unless `status` is `accepted`. nullable: true type: string type: object type: array status_url: description: >- URL of [Get Deletion Batch](/en/api-reference/deletion-jobs/get-deletion-batch) for this batch: absolute when the deployment sets `SERVICE_API_URL`, otherwise a path that starts with `/v1/`. [Delete Document Files in Batch](/en/api-reference/documents-and-chunks/delete-document-files-in-batch) also sends it in the `Location` response header. nullable: true type: string total: description: Number of files in the original request. type: integer type: object KnowledgeBaseDeletionJob: properties: checkpoint: description: >- How far the deletion has progressed: `requested` (newly accepted), then `quiescing`, `deleting_objects`, `deleting_derived_data`, `deleting_primary_data`, and `completed`. type: string completed_at: description: >- When the job completed, ISO 8601. `null` until then, and on a `failed` job. nullable: true type: string created_at: description: When the job was accepted, ISO 8601. type: string error: description: >- The last error, or `null` when there is none. It is also set while `run_state` is `retry_wait`, so read `run_state`, not `error`, to tell whether the job failed. nullable: true properties: code: description: Code of the last error. type: string message: description: >- Public message for the last error. Internal error details are omitted. type: string retryable: description: >- `true` when `run_state` is `failed`. This API can't retry a failed deletion. type: boolean type: object id: description: Deletion job ID. type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string mode: description: >- How a source deletion treats the source's documents: `cascade` deletes them, `keep` keeps them. On a document file deletion it says nothing about what the deletion removes. nullable: true type: string progress: description: >- Item counts of a multi-item deletion. Not populated by this API. Always `null`. nullable: true properties: completed_items: description: Items deleted so far. type: integer current_item_kind: description: Kind of the item being deleted. nullable: true type: string total_items: description: Items to delete. nullable: true type: integer type: object retry_at: description: >- When the next automatic retry runs, ISO 8601. `null` when none is scheduled. nullable: true type: string run_state: description: >- Scheduler state: - `dispatch_pending` (newly accepted), `queued`, `running`: in progress. - `retry_wait`: an automatic retry is scheduled at `retry_at`. - `completed`: everything was removed. - `failed`: cleanup stopped, and the target stays hidden. It can't be retried. type: string target_id: description: >- ID of the target: the document file ID for `document`, the source ID for `source`. type: string target_type: description: >- What the job deletes: `document` for a document file, `source` for a source. type: string updated_at: description: When the job last changed, ISO 8601. type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.