Retrieve Chunks from a Knowledge Base / 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>",
"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>",
"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>',
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>',
'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 \"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 \"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 \"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
}
]
}Knowledge Bases
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.
POST
/
datasets
/
{dataset_id}
/
retrieve
Retrieve Chunks from a Knowledge Base / 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>",
"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>",
"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>',
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>',
'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 \"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 \"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 \"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
}
]
}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
application/json
Search query text.
Maximum string length:
250Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base.
Show child attributes
Show child attributes
Retrieval settings for external knowledge bases.
Show child attributes
Show child attributes
⌘I