External Knowledge API

API specification that your external knowledge service must implement to integrate with Dify

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

Property	Required	Type	Description
knowledge_id	Yes	string	The 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.
query	Yes	string	The user’s search query.
retrieval_setting	Yes	object	Retrieval parameters. See below.
metadata_condition	No	object	Metadata filtering conditions. See below.

retrieval_setting

Property	Required	Type	Description
top_k	Yes	int	Maximum number of results to return.
score_threshold	Yes	float	Minimum 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.

Property	Required	Type	Description
logical_operator	No	string	and or or. Default: and.
conditions	Yes	array[object]	List of filter conditions.

Each object in conditions:

Property	Required	Type	Description
name	Yes	string	Metadata field name to filter on.
comparison_operator	Yes	string	Comparison operator. See supported values below.
value	No	string, number, or array[string]	Comparison value. Omit when using empty or not empty.

Supported Comparison Operators

Operator	Description
contains	Contains a value
not contains	Does not contain a value
start with	Starts with a value
end with	Ends with a value
is	Equals a value
is not	Does not equal a value
in	Matches any value in a list
not in	Does not match any value in a list
empty	Is empty
not empty	Is not empty
=	Equals (numeric)
≠	Not equal (numeric)
>	Greater than
<	Less than
≥	Greater than or equal to
≤	Less than or equal to
before	Before a date
after	After 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

Property	Type	Description
content	string	The retrieved text chunk. Dify uses this as the context passed to the LLM.
score	float	Similarity score (0–1). Used for score threshold filtering and result ranking.
title	string	Source document title.
metadata	object	Arbitrary 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:

Property	Type	Description
error_code	int	An application-level error code you define.
error_msg	string	A human-readable error description.

The following are suggested error codes. These are conventions, not enforced by Dify:

Code	Suggested Usage
1001	Invalid Authorization header format
1002	Authorization failed
2001	Knowledge base not found

Example Error Response

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