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, 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.

DELETE /knowledge-fs/spaces/{knowledge_base_id}/documents/bulk

Delete Document Files in Batch

cURL

curl --request DELETE \
  --url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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
    }
  ]
}
'

202

success

{
  "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
}

Authorizations

Authorization · string · header · required

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).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Headers

Idempotency-Key · string · required

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.

Required string length: 8 - 255

Path Parameters

knowledge_base_id · string<uuid> · required

Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.

Body

application/json

The normalized request must fit within 1,048,576 UTF-8 bytes. See Request Size Limits.

documents · object[] · required

Files to delete. Each documentId must appear once. A larger batch answers 400. The deployment may set a lower cap.

Required array length: 1 - 100 elements

Show child attributes

Response

202

application/json

The batch was recorded. results gives each file's outcome, and items lists the accepted files. Deletion runs in the background. 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 (the batch status_url).

Poll the returned job IDs. To retry files left pending, send the same request again with the same Idempotency-Key.

batch_id · string | null

ID of the batch that records this request.

items · object[]

One entry per accepted file.

Show child attributes

results · object[]

One entry per requested file, with its outcome.

Show child attributes

status_url · string | null

URL of 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 also sends it in the Location response header.

total · integer

Number of files in the original request.