Retrieve Chunks from a Knowledge Base / Test Retrieval

post/datasets/{dataset_id}/retrieve

Request example

curl --request POST \
  --url https://api.dify.ai/v1/datasets/{dataset_id}/retrieve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "attachment_ids": [
    "<string>"
  ],
  "external_retrieval_model": {
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "top_k": 1
  },
  "query": "<string>",
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  }
}'

import requests

url = "https://api.dify.ai/v1/datasets/{dataset_id}/retrieve"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "attachment_ids": [
        "<string>"
    ],
    "external_retrieval_model": {
        "score_threshold": 1,
        "score_threshold_enabled": True,
        "top_k": 1
    },
    "query": "<string>",
    "retrieval_model": {
        "metadata_filtering_conditions": {
            "conditions": [
                {
                    "comparison_operator": "contains",
                    "name": "<string>",
                    "value": "<string>"
                }
            ],
            "logical_operator": "and"
        },
        "reranking_enable": True,
        "reranking_mode": "reranking_model",
        "reranking_model": {
            "reranking_model_name": "<string>",
            "reranking_provider_name": "<string>"
        },
        "score_threshold": 1,
        "score_threshold_enabled": True,
        "search_method": "keyword_search",
        "top_k": 1,
        "weights": {
            "keyword_setting": {
                "keyword_weight": 1
            },
            "vector_setting": {
                "embedding_model_name": "<string>",
                "embedding_provider_name": "<string>",
                "vector_weight": 1
            },
            "weight_type": "semantic_first"
        }
    }
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/datasets/{dataset_id}/retrieve', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "attachment_ids": [
      "<string>"
    ],
    "external_retrieval_model": {
      "score_threshold": 1,
      "score_threshold_enabled": true,
      "top_k": 1
    },
    "query": "<string>",
    "retrieval_model": {
      "metadata_filtering_conditions": {
        "conditions": [
          {
            "comparison_operator": "contains",
            "name": "<string>",
            "value": "<string>"
          }
        ],
        "logical_operator": "and"
      },
      "reranking_enable": true,
      "reranking_mode": "reranking_model",
      "reranking_model": {
        "reranking_model_name": "<string>",
        "reranking_provider_name": "<string>"
      },
      "score_threshold": 1,
      "score_threshold_enabled": true,
      "search_method": "keyword_search",
      "top_k": 1,
      "weights": {
        "keyword_setting": {
          "keyword_weight": 1
        },
        "vector_setting": {
          "embedding_model_name": "<string>",
          "embedding_provider_name": "<string>",
          "vector_weight": 1
        },
        "weight_type": "semantic_first"
      }
    }
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/datasets/{dataset_id}/retrieve',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "attachment_ids": [
    "<string>"
  ],
  "external_retrieval_model": {
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "top_k": 1
  },
  "query": "<string>",
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  }
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/datasets/{dataset_id}/retrieve"
	payload := strings.NewReader("{\n  \"attachment_ids\": [\n    \"<string>\"\n  ],\n  \"external_retrieval_model\": {\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"top_k\": 1\n  },\n  \"query\": \"<string>\",\n  \"retrieval_model\": {\n    \"metadata_filtering_conditions\": {\n      \"conditions\": [\n        {\n          \"comparison_operator\": \"contains\",\n          \"name\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"logical_operator\": \"and\"\n    },\n    \"reranking_enable\": true,\n    \"reranking_mode\": \"reranking_model\",\n    \"reranking_model\": {\n      \"reranking_model_name\": \"<string>\",\n      \"reranking_provider_name\": \"<string>\"\n    },\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"search_method\": \"keyword_search\",\n    \"top_k\": 1,\n    \"weights\": {\n      \"keyword_setting\": {\n        \"keyword_weight\": 1\n      },\n      \"vector_setting\": {\n        \"embedding_model_name\": \"<string>\",\n        \"embedding_provider_name\": \"<string>\",\n        \"vector_weight\": 1\n      },\n      \"weight_type\": \"semantic_first\"\n    }\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))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/datasets/{dataset_id}/retrieve"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"attachment_ids\": [\n    \"<string>\"\n  ],\n  \"external_retrieval_model\": {\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"top_k\": 1\n  },\n  \"query\": \"<string>\",\n  \"retrieval_model\": {\n    \"metadata_filtering_conditions\": {\n      \"conditions\": [\n        {\n          \"comparison_operator\": \"contains\",\n          \"name\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"logical_operator\": \"and\"\n    },\n    \"reranking_enable\": true,\n    \"reranking_mode\": \"reranking_model\",\n    \"reranking_model\": {\n      \"reranking_model_name\": \"<string>\",\n      \"reranking_provider_name\": \"<string>\"\n    },\n    \"score_threshold\": 1,\n    \"score_threshold_enabled\": true,\n    \"search_method\": \"keyword_search\",\n    \"top_k\": 1,\n    \"weights\": {\n      \"keyword_setting\": {\n        \"keyword_weight\": 1\n      },\n      \"vector_setting\": {\n        \"embedding_model_name\": \"<string>\",\n        \"embedding_provider_name\": \"<string>\",\n        \"vector_weight\": 1\n      },\n      \"weight_type\": \"semantic_first\"\n    }\n  }\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/datasets/{dataset_id}/retrieve')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "attachment_ids": [
    "<string>"
  ],
  "external_retrieval_model": {
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "top_k": 1
  },
  "query": "<string>",
  "retrieval_model": {
    "metadata_filtering_conditions": {
      "conditions": [
        {
          "comparison_operator": "contains",
          "name": "<string>",
          "value": "<string>"
        }
      ],
      "logical_operator": "and"
    },
    "reranking_enable": true,
    "reranking_mode": "reranking_model",
    "reranking_model": {
      "reranking_model_name": "<string>",
      "reranking_provider_name": "<string>"
    },
    "score_threshold": 1,
    "score_threshold_enabled": true,
    "search_method": "keyword_search",
    "top_k": 1,
    "weights": {
      "keyword_setting": {
        "keyword_weight": 1
      },
      "vector_setting": {
        "embedding_model_name": "<string>",
        "embedding_provider_name": "<string>",
        "vector_weight": 1
      },
      "weight_type": "semantic_first"
    }
  }
}'

response = http.request(request)
puts response.read_body

Response

{
  "query": {
    "content": "What is Dify?"
  },
  "records": [
    {
      "child_chunks": [],
      "files": [],
      "score": 0.92,
      "segment": {
        "answer": "",
        "completed_at": 1741267200,
        "content": "Dify is an open-source LLM app development platform.",
        "created_at": 1741267200,
        "created_by": "ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4",
        "disabled_at": null,
        "disabled_by": null,
        "document": {
          "data_source_type": "upload_file",
          "doc_metadata": null,
          "doc_type": null,
          "id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
          "name": "guide.txt"
        },
        "document_id": "a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac",
        "enabled": true,
        "error": null,
        "hit_count": 1,
        "id": "f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1",
        "index_node_hash": "abc123def456",
        "index_node_id": "a1b2c3d4-e5f6-7890-abcd-000000000001",
        "indexing_at": 1741267200,
        "keywords": [
          "dify",
          "platform",
          "llm"
        ],
        "position": 1,
        "sign_content": "",
        "status": "completed",
        "stopped_at": null,
        "tokens": 12,
        "word_count": 9
      },
      "summary": null,
      "tsne_position": null
    }
  ]
}

{
  "code": "completion_request_error",
  "message": "Completion request failed.",
  "status": 400
}

{
  "code": "dataset_not_initialized",
  "message": "The dataset is still being initialized or indexing. Please wait a moment.",
  "status": 400
}

{
  "code": "invalid_param",
  "message": "Invalid parameter value.",
  "status": 400
}

{
  "code": "model_currently_not_support",
  "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.",
  "status": 400
}

{
  "code": "provider_not_initialize",
  "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.",
  "status": 400
}

{
  "code": "provider_quota_exceeded",
  "message": "Your quota for Dify Hosted Model Provider has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.",
  "status": 400
}

{
  "code": "forbidden",
  "message": "Dataset api access is not enabled.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
  "status": 403
}

{
  "code": "forbidden",
  "message": "The API key is not authorized to access this knowledge base.",
  "status": 403
}

{
  "code": "not_found",
  "message": "Dataset not found.",
  "status": 404
}

{
  "code": "internal_server_error",
  "message": "An internal error occurred.",
  "status": 500
}

post/datasets/{dataset_id}/retrieve

Authorization

Authorizationstringheaderrequired#

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

dataset_idstringrequired#

Knowledge base ID, from List Knowledge Bases. For a scoped key, copy the ID from the Dify URL.

Body

application/json

attachment_idsstring[]#

List of attachment IDs to include in the retrieval context.

external_retrieval_modelobject#

Retrieval settings for external knowledge bases.

Show child attributes

score_thresholdnumber#

Minimum similarity score threshold for filtering results.

score_threshold_enabledboolean#

Whether score threshold filtering is enabled.

top_kinteger#

Maximum number of results to return.

querystringrequired#

Search query text.

Length: max 250

retrieval_modelobject#

Show child attributes

metadata_filtering_conditionsobject#

Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields.

Show child attributes

conditionsobject[]#

List of metadata conditions to evaluate.

Show child attributes

comparison_operatorenum<string>required#

Comparison to apply, by metadata type:

String or array metadata: contains, not contains, start with, end with, is, is not, empty, not empty, in, not in
Numeric metadata: =, ≠, >, <, ≥, ≤
Time metadata: before, after

Options:containsnot containsstart withend withisis notemptynot emptyinnot in=≠><≥≤beforeafter

namestringrequired#

Metadata field name to compare against.

valuestring · string[] · number#

Value to compare against. Type depends on comparison_operator: string for most string operators, array of strings for in and not in, number for numeric operators, and omitted for empty and not empty.

logical_operatorenum<string>#

How to combine multiple conditions.

Default: "and"

Options:andor

reranking_enablebooleanrequired#

Whether reranking is enabled.

reranking_modeenum<string>#

Reranking mode. Required when reranking_enable is true.

Options:reranking_modelweighted_score

reranking_modelobject#

Reranking model configuration.

Show child attributes

reranking_model_namestring#

Name of the reranking model.

reranking_provider_namestring#

Reranking model provider identifier, formatted as organization/plugin_name/provider_name (e.g. langgenius/cohere/cohere). A bare name like cohere expands to langgenius/<name>/<name> and works only for langgenius-published plugins.

Get valid values from the provider field of Get Available Models with model_type=rerank.

score_thresholdnumber#

Minimum similarity score for results. Only effective when score_threshold_enabled is true.

score_threshold_enabledbooleanrequired#

Whether score threshold filtering is enabled.

search_methodenum<string>required#

Search method used for retrieval.

Options:keyword_searchsemantic_searchfull_text_searchhybrid_search

top_kintegerrequired#

Maximum number of results to return.

weightsobject#

Weight configuration for hybrid search.

Show child attributes

keyword_settingobject#

Keyword search weight settings.

Show child attributes

keyword_weightnumber#

Weight assigned to keyword search results.

vector_settingobject#

Semantic search weight settings.

Show child attributes

embedding_model_namestring#

Name of the embedding model used for vector search.

embedding_provider_namestring#

Provider of the embedding model used for vector search.

vector_weightnumber#

Weight assigned to semantic (vector) search results.

weight_typeenum<string>#

Strategy for balancing semantic and keyword search weights.

Options:semantic_firstkeyword_firstcustomized

Responses

application/json

Retrieval results.

queryobject#

The original query object.

Show child attributes

contentstring#

The query text.

recordsobject[]#

List of matched retrieval records.

Show child attributes

child_chunksobject[]#

Matched child chunks within the chunk, if using hierarchical indexing.

Show child attributes

contentstring#

Text content of the child chunk.

idstring#

Unique identifier of the child chunk.

positioninteger#

Position of the child chunk within the parent chunk.

scorenumber#

Similarity score of the child chunk.

filesobject[]#

Files attached to this chunk.

Show child attributes

extensionstring#

File extension.

idstring#

Attachment file identifier.

mime_typestring#

MIME type of the file.

namestring#

Original file name.

sizeinteger#

File size in bytes.

source_urlstring#

URL to access the attachment.

scorenumber#

Similarity score.

segmentobject#

Matched chunk from the knowledge base.

Show child attributes

answerstring#

Answer content, used in Q&A mode documents.

completed_atnumber#

Timestamp when indexing completed. null if not yet completed.

contentstring#

Text content of the chunk.

created_atnumber#

Creation timestamp (Unix epoch in seconds).

created_bystring#

ID of the user who created the chunk.

disabled_atnumber#

Timestamp when the chunk was disabled. null if enabled.

disabled_bystring#

ID of the user who disabled the chunk. null if enabled.

documentobject#

Parent document information for the matched chunk.

Show child attributes

data_source_typestring#

How the document was created.

doc_metadataobject#

Metadata values for the document. null if no metadata is configured.

doc_typestring#

Document type classification. null if not set.

idstring#

Unique identifier of the document.

namestring#

Document name.

document_idstring#

ID of the document this chunk belongs to.

enabledboolean#

Whether the chunk is enabled for retrieval.

errorstring#

Error message if indexing failed. null when no error.

hit_countinteger#

Number of times this chunk has been matched in retrieval queries.

idstring#

Unique identifier of the chunk.

index_node_hashstring#

Hash of the indexed content, used to detect changes.

index_node_idstring#

ID of the index node in the vector store.

indexing_atnumber#

Timestamp when indexing started. null if not yet started.

keywordsstring[]#

Keywords associated with this chunk for keyword-based retrieval.

positioninteger#

Position of the chunk within the document.

sign_contentstring#

Signed content hash for integrity verification.

statusstring#

Indexing status of the chunk.

stopped_atnumber#

Timestamp when indexing was stopped. null if not stopped.

tokensinteger#

Token count of the chunk content.

word_countinteger#

Word count of the chunk content.

summarystring#

Summary content if retrieved via summary index.

tsne_positionobject#

t-SNE visualization position.

Delete Knowledge Base Create Document by Text