curl --request POST \
--url https://{api_base_url}/datasets/{dataset_id}/retrieve \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"attachment_ids": [
"<string>"
],
"external_retrieval_model": {
"top_k": 123,
"score_threshold": 123,
"score_threshold_enabled": true
}
}
'import requests
url = "https://{api_base_url}/datasets/{dataset_id}/retrieve"
payload = {
"query": "<string>",
"attachment_ids": ["<string>"],
"external_retrieval_model": {
"top_k": 123,
"score_threshold": 123,
"score_threshold_enabled": True
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
attachment_ids: ['<string>'],
external_retrieval_model: {top_k: 123, score_threshold: 123, score_threshold_enabled: true}
})
};
fetch('https://{api_base_url}/datasets/{dataset_id}/retrieve', 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}/datasets/{dataset_id}/retrieve",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '<string>',
'attachment_ids' => [
'<string>'
],
'external_retrieval_model' => [
'top_k' => 123,
'score_threshold' => 123,
'score_threshold_enabled' => true
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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}/datasets/{dataset_id}/retrieve"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"attachment_ids\": [\n \"<string>\"\n ],\n \"external_retrieval_model\": {\n \"top_k\": 123,\n \"score_threshold\": 123,\n \"score_threshold_enabled\": true\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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.post("https://{api_base_url}/datasets/{dataset_id}/retrieve")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"attachment_ids\": [\n \"<string>\"\n ],\n \"external_retrieval_model\": {\n \"top_k\": 123,\n \"score_threshold\": 123,\n \"score_threshold_enabled\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/datasets/{dataset_id}/retrieve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"attachment_ids\": [\n \"<string>\"\n ],\n \"external_retrieval_model\": {\n \"top_k\": 123,\n \"score_threshold\": 123,\n \"score_threshold_enabled\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"query": {
"content": "What is Dify?"
},
"records": [
{
"segment": {
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 1,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"data_source_type": "upload_file",
"name": "guide.txt",
"doc_type": null,
"doc_metadata": null
}
},
"child_chunks": [],
"score": 0.92,
"tsne_position": null,
"files": [],
"summary": null
}
]
}Retrieve Chunks from a Knowledge Base / Test Retrieval
Searches a knowledge base and returns the chunks most relevant to the query, for both production retrieval and test retrieval.
curl --request POST \
--url https://{api_base_url}/datasets/{dataset_id}/retrieve \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"attachment_ids": [
"<string>"
],
"external_retrieval_model": {
"top_k": 123,
"score_threshold": 123,
"score_threshold_enabled": true
}
}
'import requests
url = "https://{api_base_url}/datasets/{dataset_id}/retrieve"
payload = {
"query": "<string>",
"attachment_ids": ["<string>"],
"external_retrieval_model": {
"top_k": 123,
"score_threshold": 123,
"score_threshold_enabled": True
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
attachment_ids: ['<string>'],
external_retrieval_model: {top_k: 123, score_threshold: 123, score_threshold_enabled: true}
})
};
fetch('https://{api_base_url}/datasets/{dataset_id}/retrieve', 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}/datasets/{dataset_id}/retrieve",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '<string>',
'attachment_ids' => [
'<string>'
],
'external_retrieval_model' => [
'top_k' => 123,
'score_threshold' => 123,
'score_threshold_enabled' => true
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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}/datasets/{dataset_id}/retrieve"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"attachment_ids\": [\n \"<string>\"\n ],\n \"external_retrieval_model\": {\n \"top_k\": 123,\n \"score_threshold\": 123,\n \"score_threshold_enabled\": true\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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.post("https://{api_base_url}/datasets/{dataset_id}/retrieve")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"attachment_ids\": [\n \"<string>\"\n ],\n \"external_retrieval_model\": {\n \"top_k\": 123,\n \"score_threshold\": 123,\n \"score_threshold_enabled\": true\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/datasets/{dataset_id}/retrieve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"attachment_ids\": [\n \"<string>\"\n ],\n \"external_retrieval_model\": {\n \"top_k\": 123,\n \"score_threshold\": 123,\n \"score_threshold_enabled\": true\n }\n}"
response = http.request(request)
puts response.read_body{
"query": {
"content": "What is Dify?"
},
"records": [
{
"segment": {
"id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
"position": 1,
"document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"content": "Dify is an open-source LLM app development platform.",
"sign_content": "",
"answer": "",
"word_count": 9,
"tokens": 12,
"keywords": [
"dify",
"platform",
"llm"
],
"index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
"index_node_hash": "abc123def456",
"hit_count": 1,
"enabled": true,
"disabled_at": null,
"disabled_by": null,
"status": "completed",
"created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
"created_at": 1741267200,
"indexing_at": 1741267200,
"completed_at": 1741267200,
"error": null,
"stopped_at": null,
"document": {
"id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
"data_source_type": "upload_file",
"name": "guide.txt",
"doc_type": null,
"doc_metadata": null
}
},
"child_chunks": [],
"score": 0.92,
"tsne_position": null,
"files": [],
"summary": null
}
]
}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).
Path Parameters
Knowledge base ID, from List Knowledge Bases.
Body
Search query text.
250Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base.
Show child attributes
Show child attributes
List of attachment IDs to include in the retrieval context.
Retrieval settings for external knowledge bases.
Show child attributes
Show child attributes