> 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/co-so-du-lieu/dac-ta-api-kien-thuc-ben-ngoai.md). # Đặc tả API Kiến thức Bên ngoài ## Mục lục · \[Authentication]\(#authentication) · \[Request]\(#request) · \[Response]\(#response) · \[Error Handling]\(#error-handling) ## Authentication ClickAI xác thực với external knowledge service bằng Bearer token trong Authorization header: Authorization: Bearer {API\_KEY} API Key là credential bạn cung cấp khi đăng ký External Knowledge API trong ClickAI. ## Request ### Endpoint POST {your-endpoint}/retrieval\ Content-Type: application/json\ Authorization: Bearer {API\_KEY} ClickAI tự động thêm /retrieval vào API Endpoint đã đăng ký. Ví dụ nếu bạn cấu hình endpoint là , ClickAI sẽ gửi request đến . ### Body


Trường	Kiểu	Bắt buộc	Mô tả
knowledge_id	string	✅	ID của knowledge source trong hệ thống bên ngoài
query	string	✅	Câu hỏi tìm kiếm từ người dùng
retrieval_setting	object	✅	Cấu hình retrieval (xem chi tiết bên dưới)
metadata_condition	object	❌	Điều kiện lọc metadata (xem chi tiết bên dưới)

### retrieval\_setting


Trường	Kiểu	Mô tả
top_k	integer	Số chunks tối đa trả về
score_threshold	float	Điểm similarity tối thiểu (0.0 - 1.0). Mặc định 0.0 (không lọc)

### metadata\_condition


Trường	Kiểu	Mô tả
logical_operator	string	Toán tử logic: and hoặc or. Mặc định and
conditions	array	Danh sách điều kiện lọc

Mỗi condition gồm:


Trường	Kiểu	Mô tả
name	string	Tên trường metadata
comparison_operator	string	Toán tử so sánh
value	any	Giá trị so sánh (không bắt buộc cho empty, not empty)

Supported Comparison Operators:


Loại dữ liệu	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": "ClickAI là gì?",\ "retrieval\_setting": {\ "top\_k": 3,\ "score\_threshold": 0.5\ }\ } Example Request với Metadata Filtering: {\ "knowledge\_id": "your-knowledge-id",\ "query": "Chính sách bảo hành",\ "retrieval\_setting": {\ "top\_k": 5,\ "score\_threshold": 0.4\ },\ "metadata\_condition": {\ "logical\_operator": "and",\ "conditions": \[\ {\ "name": "category",\ "comparison\_operator": "is",\ "value": "policy"\ },\ {\ "name": "language",\ "comparison\_operator": "is",\ "value": "vi"\ }\ ]\ }\ } ## Response Response phải chứa trường records dạng array. Nếu không có kết quả, trả về array rỗng: {"records": \[]} ### records Mỗi record trong array records gồm:


Trường	Kiểu	Bắt buộc	Mô tả
content	string	✅	Nội dung text của chunk
score	float	✅	Điểm relevance/similarity (0.0 - 1.0)
title	string	❌	Tiêu đề tài liệu nguồn
metadata	object	✅	Metadata bổ sung. Phải là object {}, KHÔNG được là null

### Example Response {\ "records": \[\ {\ "content": "ClickAI là nền tảng AI toàn diện cho doanh nghiệp.",\ "score": 0.98,\ "title": "gioi-thieu.txt",\ "metadata": {\ "path": "s3://clickai/gioi-thieu.txt",\ "description": "Tài liệu giới thiệu ClickAI"\ }\ },\ {\ "content": "ClickAI cho phép xây dựng ứng dụng AI không cần code.",\ "score": 0.85,\ "title": "features.txt",\ "metadata": {}\ }\ ]\ } ## Error Handling Khi xảy ra lỗi, API nên trả về object chứa error\_code và error\_msg:


Trường	Kiểu	Mô tả
error_code	integer	Mã lỗi
error_msg	string	Thông điệp lỗi chi tiết

Các mã lỗi phổ biến:


Mã lỗi	Mô tả
1001	Invalid request format
1002	Authorization failed
2001	Knowledge not found
2002	Retrieval service unavailable

### Example Error Response {\ "error\_code": 1002,\ "error\_msg": "Authorization failed. Please check your API key."\ } *📖 Trước: \[Kết nối External Knowledge]\(./06-external-knowledge.md) · Tiếp: \[Quản lý 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/co-so-du-lieu/dac-ta-api-kien-thuc-ben-ngoai.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.