> For the complete documentation index, see [llms.txt](https://docs.clickai.vn/clickai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clickai.vn/clickai-docs/clickai-docs-en/database/external-knowledge-api.md). # External Knowledge API ## 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 , ClickAI will send requests to . ### 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)*