API Reference

DXA KnowledgeBase API

Curated knowledge & semantic search (RAG) for AI

DXA KnowledgeBase collects, validates (Maker–Checker) and vector-indexes enterprise knowledge so AI assistants always answer from verified data. The API covers: document sync from the desktop client, review decisions, semantic search, and an MCP server for AI agents to query approved knowledge.

Base URL

https://kb.dxa.io.vn

Authentication

Two mechanisms: (1) an SSO `xv_session` session for web reviewers; (2) a Personal Access Token (PAT, `xkb_` prefix, Bearer header) for the desktop client and AI agents, scoped `sync` or `ai:read`. The MCP server at `/mcp` requires a PAT with scope `ai:read`.

Semantic search (RAG)

POST /api/ai/search

Semantic search over approved documents (bge-m3 vectors)

Auth: PAT (scope `ai:read`) or SSO session

Body parameters

Field	Type	Description
`query`*	`string`	Search query
`topK`	`number`	Number of hits (default 5)

Example request

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 }'

Example response

{
  "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
    }
  ]
}

Document sync & review

POST /api/sync/push

Push a Markdown document to staging (draft)

Auth: PAT (scope `sync`)

Body parameters

Field	Type	Description
`path`*	`string`	Document path in the vault
`content`*	`string`	Markdown content
`hash`*	`string`	Content hash (dedupe)
`title`	`string`	Document title

Example response

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

POST /api/sync/submit

Submit a draft for review (draft → under_review)

Auth: PAT (scope `sync`)

Body parameters

Field	Type	Description
`docId`*	`string`	Document ID

Example response

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

POST /api/review/decide

Approve or reject a document (Checker)

Auth: SSO session · `review:decide` permission

Body parameters

Field	Type	Description
`docId`*	`string`	Document ID
`decision`*	`'approve' \| 'reject'`	Review decision
`note`	`string`	Note

Example response

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

MCP server (for AI agents)

POST /mcp

Streamable HTTP MCP — query approved knowledge

Auth: PAT scope `ai:read` (Bearer)

Example request

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

Example response

// 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