API Reference

DXA KnowledgeBase API

Tri thức đã kiểm duyệt & tìm kiếm ngữ nghĩa (RAG) cho AI

DXA KnowledgeBase tập hợp, kiểm duyệt (Maker–Checker) và lập chỉ mục vector tri thức doanh nghiệp để trợ lý AI luôn trả lời dựa trên dữ liệu đã được xác thực. API gồm: luồng đồng bộ tài liệu từ máy trạm, duyệt nội dung, tìm kiếm ngữ nghĩa, và một máy chủ MCP để AI agent truy vấn tri thức đã duyệt.

Base URL

https://kb.dxa.io.vn

Xác thực

Hai cơ chế: (1) phiên SSO `xv_session` cho người duyệt trên web; (2) Personal Access Token (PAT, tiền tố `xkb_`, header Bearer) cho máy trạm và AI agent, với scope `sync` hoặc `ai:read`. Máy chủ MCP ở `/mcp` yêu cầu PAT scope `ai:read`.

Tìm kiếm ngữ nghĩa (RAG)

POST /api/ai/search

Tìm kiếm ngữ nghĩa trên tài liệu đã duyệt (vector bge-m3)

Xác thực: PAT (scope `ai:read`) hoặc phiên SSO

Tham số (body)

Trường	Kiểu	Mô tả
`query`*	`string`	Truy vấn tìm kiếm
`topK`	`number`	Số kết quả (mặc định 5)

Ví dụ yêu cầu

curl -X POST 'https://kb.dxa.io.vn/api/ai/search' \
  -H 'Authorization: Bearer xkb_<token>' \
  -H 'Content-Type: application/json' \
  -d '{ "query": "điều kiện hoàn tiền", "topK": 5 }'

Phản hồi mẫu

{
  "hits": [
    {
      "docId": "doc_8a1…",
      "title": "Chính sách hoàn tiền",
      "headingPath": "Hoàn tiền › Điều kiện",
      "text": "Khách hàng được hoàn tiền trong vòng 7 ngày…",
      "score": 0.856
    }
  ]
}

Đồng bộ & duyệt tài liệu

POST /api/sync/push

Đẩy tài liệu Markdown lên khu nháp (draft)

Xác thực: PAT (scope `sync`)

Tham số (body)

Trường	Kiểu	Mô tả
`path`*	`string`	Đường dẫn tài liệu trong vault
`content`*	`string`	Nội dung Markdown
`hash`*	`string`	Hash nội dung (chống đẩy trùng)
`title`	`string`	Tiêu đề tài liệu

Phản hồi mẫu

{ "docId": "doc_8a1…", "state": "draft", "unchanged": false }

POST /api/sync/submit

Gửi tài liệu nháp để duyệt (draft → under_review)

Xác thực: PAT (scope `sync`)

Tham số (body)

Trường	Kiểu	Mô tả
`docId`*	`string`	ID tài liệu

Phản hồi mẫu

{ "ok": true, "state": "under_review" }

POST /api/review/decide

Duyệt hoặc từ chối tài liệu (Checker)

Xác thực: Phiên SSO · quyền `review:decide`

Tham số (body)

Trường	Kiểu	Mô tả
`docId`*	`string`	ID tài liệu
`decision`*	`'approve' \| 'reject'`	Quyết định duyệt
`note`	`string`	Ghi chú

Phản hồi mẫu

{ "ok": true, "state": "approved" }

Máy chủ MCP (cho AI agent)

POST /mcp

Streamable HTTP MCP — tra cứu tri thức đã duyệt

Xác thực: PAT scope `ai:read` (Bearer)

Ví dụ yêu cầu

{
  "mcpServers": {
    "dxa-knowledgebase": {
      "url": "https://kb.dxa.io.vn/mcp",
      "headers": { "Authorization": "Bearer xkb_<token>" }
    }
  }
}

Phản hồi mẫu

// Các tool MCP khả dụng:
// • search_knowledge  → tìm ngữ nghĩa trên tài liệu đã duyệt { query, topK }
// • list_documents    → liệt kê tài liệu đã duyệt