> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-add-new-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/en/use-dify/knowledge/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 theme={null}
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 theme={null}
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).