Skip to main content
This page defines the API contract your external knowledge service must implement for Dify to retrieve content from it. Once your API is ready, see Connect to External Knowledge Base to register it in Dify.

​
Authentication

Dify sends the API Key you configured as a Bearer token in every request: 
Authorization: Bearer {API_KEY}
You define the authentication logic on your side. Dify only passes the key—it does not validate it.

​
Request

POST {your-endpoint}/retrieval
Content-Type: application/json
Authorization: Bearer {API_KEY}
Dify appends /retrieval to the endpoint URL you configured. If you registered https://your-service.com, Dify sends requests to https://your-service.com/retrieval.

​
Body

PropertyRequiredTypeDescription
knowledge_idYesstringThe identifier of the knowledge source in your external system. This is the value you entered in the External Knowledge ID field when connecting. Use it to route queries to the correct knowledge source.
queryYesstringThe user’s search query.
retrieval_settingYesobjectRetrieval parameters. See below.
metadata_conditionNoobjectMetadata filtering conditions. See below.

​
retrieval_setting

PropertyRequiredTypeDescription
top_kYesintMaximum number of results to return.
score_thresholdYesfloatMinimum similarity score (0-1). When score threshold is disabled in Dify, this value is 0.0.

​
metadata_condition

Dify passes metadata conditions to your API but does not currently provide a UI for users to configure them. This parameter is available for programmatic use only.
PropertyRequiredTypeDescription
logical_operatorNostringand or or. Default: and.
conditionsYesarray[object]List of filter conditions.
Each object in conditions:
PropertyRequiredTypeDescription
nameYesstringMetadata field name to filter on.
comparison_operatorYesstringComparison operator. See supported values below.
valueNostring, number, or array[string]Comparison value. Omit when using empty or not empty.
OperatorDescription
containsContains a value
not containsDoes not contain a value
start withStarts with a value
end withEnds with a value
isEquals a value
is notDoes not equal a value
inMatches any value in a list
not inDoes not match any value in a list
emptyIs empty
not emptyIs not empty
=Equals (numeric)
≠Not equal (numeric)
>Greater than
<Less than
≥Greater than or equal to
≤Less than or equal to
beforeBefore a date
afterAfter a date

​
Example Request

{
    "knowledge_id": "your-knowledge-id",
    "query": "What is Dify?",
    "retrieval_setting": {
        "top_k": 3,
        "score_threshold": 0.5
    }
}

​
Response

Return HTTP 200 with a JSON body containing a records array. If no results match the query, return an empty array: {"records": []}.

​
records

PropertyTypeDescription
contentstringThe retrieved text chunk. Dify uses this as the context passed to the LLM.
scorefloatSimilarity score (0–1). Used for score threshold filtering and result ranking.
titlestringSource document title.
metadataobjectArbitrary key-value pairs preserved by Dify.
Dify does not reject records with missing fields, but omitting content or score will produce incomplete or unranked results.
If you include metadata in a record, it must be an object ({}), not null. A null metadata value causes errors in Dify’s retrieval pipeline.

​
Example Response

{
    "records": [
        {
            "content": "This is the document for external knowledge.",
            "score": 0.98,
            "title": "knowledge.txt",
            "metadata": {
                "path": "s3://dify/knowledge.txt",
                "description": "dify knowledge document"
            }
        },
        {
            "content": "The Innovation Engine for GenAI Applications",
            "score": 0.66,
            "title": "introduce.txt",
            "metadata": {}
        }
    ]
}

​
Error Handling

Dify checks the HTTP status code of your response. A non-200 status raises an error that surfaces to the user. You can optionally return structured error information in JSON:
PropertyTypeDescription
error_codeintAn application-level error code you define.
error_msgstringA human-readable error description.
The following are suggested error codes. These are conventions, not enforced by Dify:
CodeSuggested Usage
1001Invalid Authorization header format
1002Authorization failed
2001Knowledge base not found

​
Example Error Response

{
    "error_code": 1002,
    "error_msg": "Authorization failed. Please check your API key."
}