Delete Document File
Requests the deletion of a document file and returns the deletion job. Every revision built on the file stops returning chunks through List Chunks.
To remove a whole document, use Delete Document. Avoid deleting the file of a document’s active revision. The document is left failed with no active revision and drops out of List Documents and Dify’s document list. It still counts toward the document quota.
Send the JSON body with this DELETE. If your client omits bodies on DELETE requests, configure it to send the body explicitly.
For the deletion flow, see Delete Documents and Sources.
curl --request DELETE \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"expectedRevision": 1
}
'import requests
url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}"
payload = { "expectedRevision": 1 }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.delete(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'DELETE',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({expectedRevision: 1})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => json_encode([
'expectedRevision' => 1
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}"
payload := strings.NewReader("{\n \"expectedRevision\": 1\n}")
req, _ := http.NewRequest("DELETE", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expectedRevision\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expectedRevision\": 1\n}"
response = http.request(request)
puts response.read_body{
"document_title": null,
"job": {
"checkpoint": "requested",
"completed_at": null,
"created_at": "2026-09-06T02:25:00Z",
"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": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
"target_type": "document",
"updated_at": "2026-09-06T02:25:00Z"
},
"status_url": "https://api.example.com/v1/knowledge-fs/spaces/8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f/deletion-jobs/b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e"
}Authorizations
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
Repeating the same key and request with the same API key returns the original job with 202. Reusing the key for a different request, or from another API key, answers 409. Use printable ASCII characters without leading or trailing whitespace.
8 - 255Path Parameters
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.
Document file ID. From List Document Files.
Body
The document file's current version, from List Document Files or Get Document File. A document file's version is always 1. Not the revision number from List Document Revisions. A stale value answers 409 and nothing is deleted.
x >= 1Response
The deletion request was accepted and runs in the background. Get Document File answers 404 from the moment it is accepted. To confirm that it finished, poll Get Deletion Job (the status_url) until run_state is completed or failed.
The document's title, for a Delete Document request. It's null when you resend the request with the same Idempotency-Key, and always null for document file deletions.
Show child attributes
Show child attributes
URL of Get Deletion Job for this job: absolute when the deployment sets SERVICE_API_URL, otherwise a path that starts with /v1/. The same value is sent in the Location response header.
Was this page helpful?
curl --request DELETE \
--url https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"expectedRevision": 1
}
'import requests
url = "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}"
payload = { "expectedRevision": 1 }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.delete(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'DELETE',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({expectedRevision: 1})
};
fetch('https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => json_encode([
'expectedRevision' => 1
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}"
payload := strings.NewReader("{\n \"expectedRevision\": 1\n}")
req, _ := http.NewRequest("DELETE", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"expectedRevision\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/knowledge-fs/spaces/{knowledge_base_id}/documents/{document_file_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"expectedRevision\": 1\n}"
response = http.request(request)
puts response.read_body{
"document_title": null,
"job": {
"checkpoint": "requested",
"completed_at": null,
"created_at": "2026-09-06T02:25:00Z",
"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": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b",
"target_type": "document",
"updated_at": "2026-09-06T02:25:00Z"
},
"status_url": "https://api.example.com/v1/knowledge-fs/spaces/8d2c6a1e-5b3f-4c7d-9e01-2a3b4c5d6e7f/deletion-jobs/b7e1c2d3-4f5a-4b6c-8d9e-0f1a2b3c4d5e"
}