Tài liệu tham chiếu HTTP API

Các điểm kết nối để tìm kiếm, đặt câu hỏi, quản lý nguồn dữ liệu, tải tài liệu lên và đọc thông tin bản triển khai. Cùng một API phục vụ Proxyma Desktop, Home Server và Proxyma Enterprise Server. Khâu xác thực khác nhau, các điểm kết nối cho token chỉ có trên Proxyma Enterprise Server, và các điểm kết nối tải lên chỉ có trên Home Server và Proxyma Enterprise Server.

Trước khi bắt đầu

Xác thực

Proxyma Desktop và Home Server không có tài khoản. Mọi điểm kết nối bên dưới đều trả lời lệnh gọi không xác thực, vì vậy chỉ để chúng truy cập được từ máy hoặc mạng do bạn kiểm soát - xem tài liệu Home Server.

Proxyma Enterprise Server có tài khoản. Khi không có token, tìm kiếm và trò chuyện (nơi cho phép khách trò chuyện) chỉ thấy các nguồn dữ liệu dùng chung, còn các điểm kết nối cho nguồn dữ liệu, tải lên và token trả về 401. Hãy gửi kèm token để thấy cả nguồn dữ liệu của riêng bạn:

-H "Authorization: Bearer <token-cua-ban>"

Một token mang đúng quyền hạn của tài khoản đã tạo ra nó, không hơn.

Lấy một token

Trên Proxyma Enterprise Server, hãy tạo trong Cài đặt → Token API, hoặc qua API bằng token phiên của một trình duyệt đã đăng nhập (cookie PROXYMA-TOKEN của nó). Token MCP không tạo được token.

curl -X POST https://your-proxyma-host/api/v1/settings/mcp-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token-phien-cua-ban>" \
  -d '{"label": "ci-pipeline"}'

Token thô có dạng pxm_ theo sau là 64 ký tự hex và chỉ được trả về một lần, lúc tạo, trong trường token. Thêm "expiresInDays" bằng 30, 60, 90 hoặc 180 để token hết hạn. Token bị mất không thể lấy lại - hãy thu hồi nó và tạo token khác. Gọi GET cùng đường dẫn để liệt kê các token (chỉ hiện vài ký tự đầu), và DELETE /api/v1/settings/mcp-tokens/{id} để thu hồi một token.

Lỗi

400 khi phần thân yêu cầu sai định dạng hoặc có giá trị bị máy chủ từ chối, 401 khi lệnh gọi cần một phiên mà nó không có, 403 khi vai trò hoặc gói bản quyền của bạn không cho phép lệnh gọi đó, 404 với id không tồn tại, 429 khi chạm giới hạn tần suất hoặc hạn mức. Nguồn dữ liệu của người dùng khác trả về 400, không phải 403. Phần thân của một lỗi thường là JSON có trường detail hoặc error, và đôi khi để trống.

Những trường lạ trong phần thân yêu cầu bị bỏ qua chứ không bị từ chối. Một tham số viết sai chính tả vẫn trả về 200 và giá trị mặc định được dùng.

Tìm kiếm

Trả về các đoạn nội dung khớp cùng nguồn của chúng, bằng cùng cơ chế tìm theo từ khóa và vector như khung trò chuyện. Nó gửi truy vấn tới nhà cung cấp mô hình nhúng của bạn, và cả tới một mô hình khi bật mở rộng truy vấn hoặc xếp hạng lại, nhưng không viết câu trả lời - nên tốn ít hơn nhiều so với đặt câu hỏi.

POST /api/v1/search

Ví dụ

curl -X POST https://your-proxyma-host/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication flow", "topK": 5, "minScore": 0.4}'

Kết quả trả về

{
  "query": "authentication flow",
  "totalResults": 2,
  "results": [
    {
      "id": "a3f1c2e4-...",
      "title": "Authentication design",
      "snippet": "The auth module handles JWT...",
      "sourceUrl": "https://confluence.example.com/display/PROJ/auth-design",
      "connectorType": "confluence",
      "score": 0.87
    }
  ]
}

Đặt một câu hỏi

Trả về một câu trả lời do tác nhân (agent) tạo ra. Chi phí tính ở nhà cung cấp AI của bản triển khai, và thời gian tùy vào mô hình.

POST /api/v1/chat

curl -X POST https://your-proxyma-host/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Which open bugs mention the trap handler?"}'

{"conversationId": "7c9e6679-..."}

GET /api/v1/chat/events/{conversationId}

Một luồng text/event-stream mang lượt trao đổi về trong lúc nó đang chạy. Hãy mở luồng sau khi gửi tin nhắn: luồng phát lại lượt đó từ sự kiện đầu tiên, còn một luồng mở trước khi gửi sẽ không nhận được gì từ lượt đó. Một chú thích keepalive được gửi đi mỗi 15 giây.

Mọi sự kiện đều có tên chat, và dữ liệu của nó là JSON gồm type, callId, toolName, data và parentCallId. type là một trong các giá trị:

curl -N https://your-proxyma-host/api/v1/chat/events/7c9e6679-...

Nguồn dữ liệu

Một nguồn dữ liệu là một mục được lập chỉ mục - một thư mục, một dự án Jira, một trang web, một không gian Confluence. Các điểm kết nối cho nguồn dữ liệu nằm dưới /api/v1/indexing.

GET /api/v1/indexing/summary

Các con số tổng cộng kèm phần xem trước có giới hạn cho từng loại. Trên Proxyma Enterprise Server, thêm ?includeShared=true để đếm cả các nguồn dùng chung bên cạnh nguồn của riêng bạn.

curl https://your-proxyma-host/api/v1/indexing/summary

{
  "totalSources": 12,
  "totalDocs": 3480,
  "activeIndexingCount": 0,
  "byType": {
    "confluence": { "total": 3, "preview": [ ... ] }
  }
}

activeIndexingCount đếm số tài liệu đang được tải xuống, chuyển đổi hoặc nhúng ngay lúc này.

GET /api/v1/indexing/by-type/{type}

Các nguồn dữ liệu thuộc một loại - files, webpage, jira, confluence, bitbucket, svn, networkshare, sharepoint, teams, teamschat, outlook, hoặc all. Thêm ?q= để lọc theo tên. Kết quả trả về theo từng trang: truyền page và size (tối đa 100).

POST /api/v1/indexing/{id}/sync

Bắt đầu đồng bộ ngay. Trả về {"started": true}, hoặc false nếu đã có một lượt đang chạy; lượt thứ hai không được xếp hàng. Đồng bộ thủ công luôn là đồng bộ toàn bộ, nên nó nhận ra cả những mục đã bị xóa ở phía nguồn - trừ khi nó thấy ít hơn một nửa số mục nguồn đó từng có, khi đó không có gì bị gỡ bỏ.

POST /api/v1/indexing/{id}/reindex

Dựng lại nguồn dữ liệu từ đầu. Hãy dùng sau khi đổi mô hình nhúng; một lượt đồng bộ thường giữ nguyên các vector đã có. Nguồn dữ liệu vẫn tìm kiếm được trong lúc dựng lại. Sau khi đổi mô hình trên Proxyma Desktop hoặc Home Server, chỉ mục cũ được giữ cho tới khi chỉ mục mới hoàn tất.

GET /api/v1/indexing/{id}/items

Các tài liệu trong một nguồn dữ liệu hiện không được xử lý, kèm trạng thái lập chỉ mục, mỗi lần tối đa size tài liệu (không quá 200). Tài liệu lỗi được trả về trước, sau đó tới các tài liệu cập nhật gần nhất; truyền nextCursorFailed, nextCursorTouched và nextCursorId nhận được vào cursorFailed, cursorTouched và cursorId để lấy trang kế tiếp. /items/active trả về những tài liệu đang được xử lý. /items/{documentId}/reindex lập chỉ mục lại một tài liệu, trả về 409 nếu tài liệu đang được xử lý. Chỉ chủ sở hữu nguồn dữ liệu mới gọi được. /items/{documentId}/preview trả về {"chunks": [...]}, phần văn bản đã lập chỉ mục mà tìm kiếm nhìn thấy.

Thay đổi và gỡ bỏ

Tải tài liệu lên

Thêm tài liệu vào Home Server và Proxyma Enterprise Server bằng cách tải lên. Sau đó đăng ký một thư mục đã tải lên thành một nguồn dữ liệu bằng POST /api/v1/files/folders/register với phần thân {"folder": "policies"}.

POST /api/v1/files

multipart/form-data. 200 MB cho mỗi tệp.

curl -X POST https://your-proxyma-host/api/v1/files \
  -F "file=@handbook.pdf" \
  -F "folder=policies"

{
  "id": "b12f...",
  "originalName": "handbook.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 481923,
  "uploadedAt": "2026-09-13T10:04:11Z"
}

Liệt kê, hạn mức và xóa

Thông tin về bản triển khai

GET /api/v1/health

Bản triển khai có đang chạy hay không, và nó là gì. Không cần xác thực, không trả về gì nhạy cảm, và đây là điểm cuối nên dùng cho công cụ giám sát.

curl https://your-proxyma-host/api/v1/health

{
  "status": "ok",
  "edition": "Desktop",
  "version": "0.33.0",
  "platform": "windows",
  "uptimeSeconds": 92,
  "uptime": "1m 32s"
}

Sáu trường này là toàn bộ phản hồi và sẽ được giữ nguyên như vậy, để một phép kiểm tra viết dựa trên nó vẫn tiếp tục hoạt động.

GET /api/v1/config

Giao diện web được cấu hình ra sao: thương hiệu, những tính năng bản triển khai này cung cấp, và cách tài liệu được đưa vào. Không cần xác thực và không trả về gì nhạy cảm.

Đây không phải là điểm kiểm tra sức khỏe - hãy dùng GET /api/v1/health cho việc đó. Điểm cuối này mang những gì giao diện cần và thay đổi theo giao diện.

curl https://your-proxyma-host/api/v1/config

{
  "version": "0.33.0",
  "serverPort": 4246,
  "platform": "linux",
  "orgMode": false,
  "orgCredentialConfigured": false,
  "branding": { "productName": "Proxyma", "faviconUrl": "/favicon.svg" },
  "fileUpload": true,
  "homeServer": false
}

orgMode và orgCredentialConfigured hiện không được dùng, và orgMode không cho biết một bản triển khai có tài khoản hay không.

MCP

Để một trợ lý AI tự tìm trong các nguồn dữ liệu của bạn, hãy dùng máy chủ Model Context Protocol. Xem Thiết lập MCP cho Claude Code, GitHub Copilot và các máy khách khác.