> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/en/use-dify/knowledge/connect-external-knowledge-base) to register it in Dify.

## Authentication

Dify sends the API Key you configured as a Bearer token in every request:

```text theme={null}
Authorization: Bearer {API_KEY}
```

You define the authentication logic on your side. Dify only passes the key—it does not validate it.

## Request

```text theme={null}
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](#retrieval_setting).                                                                                                                                                         |
| `metadata_condition` | No       | object | Metadata filtering conditions. See [below](#metadata_condition).                                                                                                                                               |

#### `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`

<Info>
  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.
</Info>

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

<Accordion title="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                       |
</Accordion>

### Example Request

```json theme={null}
{
    "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.

<Warning>
  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.
</Warning>

### Example Response

```json theme={null}
{
    "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

```json theme={null}
{
    "error_code": 1002,
    "error_msg": "Authorization failed. Please check your API key."
}
```