SurfSense/_bmad-output/api-contracts-backend.md

Hợp Đồng API (Backend)

Tài liệu này tóm tắt các REST API endpoints chính được phơi bày bởi Backend FastAPI.

Lưu ý: Tất cả các protected endpoints đều yêu cầu Header Authorization: Bearer <token>.

Quản Lý Tài Liệu (Documents)

Method	Endpoint	Mô tả	Quyền Truy Cập
POST	/api/v1/documents/	Tạo hoặc upload tài liệu mới.	User
GET	/api/v1/documents/	Liệt kê tài liệu (có phân trang & lọc).	User
GET	/api/v1/documents/{doc_id}	Lấy chi tiết một tài liệu.	User (Owner)
PATCH	/api/v1/documents/{doc_id}	Cập nhật metadata tài liệu.	User (Owner)
DELETE	/api/v1/documents/{doc_id}	Xóa tài liệu (Soft or Hard delete).	User (Owner)
POST	/api/v1/documents/search	Tìm kiếm ngữ nghĩa (Semantic search) trên tài liệu.	User

Chat & AI

Method	Endpoint	Mô tả
POST	/api/v1/chat/threads	Tạo phiên chat mới.
GET	/api/v1/chat/threads	Lấy lịch sử các phiên chat.
POST	/api/v1/chat/message	Gửi tin nhắn tới Agent (Streaming response).
GET	/api/v1/chat/{thread_id}/history	Lấy lịch sử tin nhắn của một thread.

Connectors (Tích Hợp)

Method	Endpoint	Mô tả
GET	/api/v1/connectors/available	Danh sách các connectors được hỗ trợ.
POST	/api/v1/connectors/{type}/auth	Bắt đầu quy trình OAuth cho connector.
POST	/api/v1/connectors/{type}/sync	Kích hoạt đồng bộ dữ liệu thủ công.

Tiện Ích Trình Duyệt (Extension)

Method	Endpoint	Mô tả
POST	/api/v1/extension/ingest	Nhận dữ liệu trang web từ extension.
POST	/api/v1/extension/context	Kiểm tra ngữ cảnh hiện tại (User có đang track trang này không?).