External Knowledge API

API specification that your external knowledge service must implement to integrate with ClickAI.

Table of Contents

· [Authentication](#authentication)

· [Request](#request)

· [Response](#response)

· [Error Handling](#error-handling)

Authentication

ClickAI authenticates with your external knowledge service using a Bearer token in the Authorization header:

Authorization: Bearer {API_KEY}

The API Key is the credential you provide when registering the External Knowledge API in ClickAI.

Request

Endpoint

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

ClickAI automatically appends /retrieval to the registered API Endpoint. For example, if you configure the endpoint as https://your-service.com, ClickAI will send requests to https://your-service.com/retrieval.

Body

Field	Type	Required	Description
knowledge_id	string	✅	ID of the knowledge source in your external system
query	string	✅	Search query from the user
retrieval_setting	object	✅	Retrieval configuration (see below)
metadata_condition	object	❌	Metadata filter conditions (see below)

retrieval_setting

Field	Type	Description
top_k	integer	Maximum number of chunks to return
score_threshold	float	Minimum similarity score (0.0 - 1.0). Default 0.0 (no filtering)

metadata_condition

Field	Type	Description
logical_operator	string	Logic operator: and or or. Default and
conditions	array	List of filter conditions

Each condition contains:

Field	Type	Description
name	string	Metadata field name
comparison_operator	string	Comparison operator
value	any	Comparison value (not required for empty, not empty)

Supported Comparison Operators:

Data type	Operators
String	contains, not contains, start with, end with, is, is not, in, not in, empty, not empty
Number	=, ≠, >, <, ≥, ≤, empty, not empty
Date	before, after, is, empty, not empty

Example Request

{ "knowledge_id": "your-knowledge-id", "query": "What is ClickAI?", "retrieval_setting": { "top_k": 3, "score_threshold": 0.5 } }

Response

Response must contain a records field as an array. If no results, return an empty array:

{"records": []}

records

Each record in the records array contains:

Field	Type	Required	Description
content	string	✅	Text content of the chunk
score	float	✅	Relevance/similarity score (0.0 - 1.0)
title	string	❌	Source document title
metadata	object	✅	Additional metadata. Must be an object {}, NOT null

Example Response

{ "records": [ { "content": "ClickAI is a comprehensive AI platform for businesses.", "score": 0.98, "title": "introduction.txt", "metadata": { "path": "s3://clickai/introduction.txt", "description": "ClickAI introduction document" } }, { "content": "ClickAI allows building AI applications without code.", "score": 0.85, "title": "features.txt", "metadata": {} } ] }

Error Handling

When errors occur, the API should return an object containing error_code and error_msg:

Field	Type	Description
error_code	integer	Error code
error_msg	string	Detailed error message

Example Error Response

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

📖 Previous: [External Knowledge](./06-external-knowledge.md) · Next: [Manage Documents & Chunks](./08-manage-documents-chunks.md)