---
title: External Knowledge API
---

## Endpoint

```
POST <your-endpoint>/retrieval
```

## Header

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](https://docs.dify.ai/guides/knowledge-base/connect-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.

| Property | Required | Type | Description | Example value |
|----------|----------|------|-------------|---------------|
| knowledge_id | TRUE | string | Your knowledge's unique ID | AAA-BBB-CCC |
| query | TRUE | string | User's query | What is Dify? |
| retrieval_setting | TRUE | object | Knowledge's retrieval parameters | See below |
| metadata_condition | FALSE | Object | Original array filtering | See below |

The `retrieval_setting` property is an object containing the following keys:

| Property | Required | Type | Description | Example value |
|----------|----------|------|-------------|---------------|
| top_k | TRUE | int | Maximum number of retrieved results | 5 |
| score_threshold | TRUE | float | The score limit of relevance of the result to the query, scope: 0~1 | 0.5 |

The `metadata_condition` property is an object containing the following keys:

| Attribute | Required | Type | Description | Example Value |
|-----------|----------|------|-------------|--------------|
| logical_operator | No | String | Logical operator, values can be `and` or `or`, default is `and` | and |
| conditions | Yes | Array (Object) | List of conditions | See below |

Each object in the `conditions` array contains the following keys:

| Attribute | Required | Type | Description | Example Value |
|-----------|----------|------|-------------|--------------|
| name | Yes | Array (String) | Names of the metadata to filter | `["category", "tag"]` |
| comparison_operator | Yes | String | Comparison operator | `contains` |
| value | No | String | Comparison 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

```json
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.

| Property | Required | Type | Description | Example value |
|----------|----------|------|-------------|---------------|
| records | TRUE | List[Object] | A list of records from querying the knowledge base. | See below |

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

| Property | Required | Type | Description | Example value |
|----------|----------|------|-------------|---------------|
| content | TRUE | string | Contains a chunk of text from a data source in the knowledge base. | Dify:The Innovation Engine for GenAI Applications |
| score | TRUE | float | The score of relevance of the result to the query, scope: 0~1 | 0.5 |
| title | TRUE | string | Document title | Dify Introduction |
| metadata | FALSE | json | Contains metadata attributes and their values for the document in the data source. | See example |

## Response Syntax

```json
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:

| Property | Required | Type | Description | Example value |
|----------|----------|------|-------------|---------------|
| error_code | TRUE | int | Error code | 1001 |
| error_msg | TRUE | string | The description of API exception | Invalid Authorization header format. Expected 'Bearer `<api-key>`' format. |

The `error_code` property has the following types:

| Code | Description |
|------|-------------|
| 1001 | Invalid Authorization header format. |
| 1002 | Authorization failed |
| 2001 | The 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

## Development Example

You can learn how to develop external knowledge base plugins through the following video tutorial using LlamaCloud as an example:


For more information about how it works, please refer to the plugin's [GitHub repository](https://github.com/langgenius/dify-official-plugins/tree/main/extensions/llamacloud).

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/guides/knowledge-base/external-knowledge-api.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)

