> 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)*