​
Endpoint

POST <your-endpoint>/retrieval

This API is used to connect to a knowledge base that is independent of the Dify and maintained by developers. For more details, please refer to Connecting to an External Knowledge Base. You can use API-Key in the Authorization HTTP Header to verify permissions. The authentication logic is defined by you in the retrieval API, as shown below:

Authorization: Bearer {API_KEY}

​
Request Body Elements

The request accepts the following data in JSON format.

PropertyRequiredTypeDescriptionExample value
knowledge_idTRUEstringYour knowledge’s unique IDAAA-BBB-CCC
queryTRUEstringUser’s queryWhat is Dify?
retrieval_settingTRUEobjectKnowledge’s retrieval parametersSee below
metadata_conditionYesObjectOriginal array filteringSee below

The retrieval_setting property is an object containing the following keys:

PropertyRequiredTypeDescriptionExample value
top_kTRUEintMaximum number of retrieved results5
score_thresholdTRUEfloatThe score limit of relevance of the result to the query, scope: 0~10.5

The metadata_condition property is an object containing the following keys:

AttributeRequiredTypeDescriptionExample Value
logical_operatorNoStringLogical operator, values can be and or or, default is andand
conditionsYesArray (Object)List of conditionsSee below

Each object in the conditions array contains the following keys:

AttributeRequiredTypeDescriptionExample Value
nameYesArray (String)Names of the metadata to filter["category", "tag"]
comparison_operatorYesStringComparison operatorcontains
valueNoStringComparison value, can be omitted when the operator is empty, not empty, null, or not null"AI"

Supported comparison_operator Operators

  • contains: Contains a certain value
  • not contains: Does not contain a certain value
  • start with: Starts with a certain value
  • end with: Ends with a certain value
  • is: Equals a certain value
  • is not: Does not equal a certain value
  • empty: Is empty
  • not empty: Is not empty
  • =: Equals
  • ≠: Not equal
  • >: Greater than
  • <: Less than
  • ≥: Greater than or equal to
  • ≤: Less than or equal to
  • before: Before a certain date
  • after: After a certain date

​
Request Syntax

POST <your-endpoint>/retrieval HTTP/1.1
-- header
Content-Type: application/json
Authorization: Bearer your-api-key
-- data
{
    "knowledge_id": "your-knowledge-id",
    "query": "your question",
    "retrieval_setting":{
        "top_k": 2,
        "score_threshold": 0.5
    }
}

​
Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

PropertyRequiredTypeDescriptionExample value
recordsTRUEList[Object]A list of records from querying the knowledge base.See below

The records property is a list object containing the following keys:

PropertyRequiredTypeDescriptionExample value
contentTRUEstringContains a chunk of text from a data source in the knowledge base.Dify:The Innovation Engine for GenAI Applications
scoreTRUEfloatThe score of relevance of the result to the query, scope: 0~10.5
titleTRUEstringDocument titleDify Introduction
metadataFALSEjsonContains metadata attributes and their values for the document in the data source.See example

​
Response Syntax

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

​
Errors

If the action fails, the service sends back the following error information in JSON format:

PropertyRequiredTypeDescriptionExample value
error_codeTRUEintError code1001
error_msgTRUEstringThe description of API exceptionInvalid Authorization header format. Expected ‘Bearer <api-key>’ format.

The error_code property has the following types:

CodeDescription
1001Invalid Authorization header format.
1002Authorization failed
2001The knowledge does not exist

​
HTTP Status Codes

AccessDeniedException The request is denied because of missing access permissions. Check your permissions and retry your request. HTTP Status Code: 403

InternalServerException An internal server error occurred. Retry your request. HTTP Status Code: 500

Was this page helpful?