> 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)* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.clickai.vn/clickai-docs/clickai-docs-en/database/external-knowledge-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.