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:
You define the authentication logic on your side. Dify only passes the key—it does not validate it.
Request#
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#
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#
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 |