External Knowledge API

This page defines the API contract your external knowledge service must implement for Intellos to retrieve content from it. Once your API is ready, see Connect to External Knowledge Base to register it in Intellos.

Authentication

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

Authorization: Bearer {API_KEY}

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

Request

POST {your-endpoint}/retrieval
Content-Type: application/json
Authorization: Bearer {API_KEY}

Intellos appends /retrieval to the endpoint URL you configured. If you registered https://your-service.com, Intellos 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 Intellos, this value is `0.0`.

`metadata_condition`

Intellos 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

{
    "knowledge_id": "your-knowledge-id",
    "query": "What is Intellos?",
    "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. Intellos 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 Intellos.

Intellos 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 Intellos’s retrieval pipeline.

Example Response

{
    "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

Intellos 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 Intellos:

Code	Suggested Usage
1001	Invalid Authorization header format
1002	Authorization failed
2001	Knowledge base not found

Example Error Response

{
    "error_code": 1002,
    "error_msg": "Authorization failed. Please check your API key."
}

Get Started

Build

Publish

Monitor

Knowledge

Workspace

Tutorials

Authentication

Request

Body

`retrieval_setting`

`metadata_condition`

Example Request

Response

`records`

Example Response

Error Handling

Example Error Response

​Authentication

​Request

​Body

​retrieval_setting

​metadata_condition

​Example Request

​Response

​records

​Example Response

​Error Handling

​Example Error Response

Authentication

Request

Body

`retrieval_setting`

`metadata_condition`

Example Request

Response

`records`

Example Response

Error Handling

Example Error Response