Tài liệu API

Mọi endpoint đều tương đối so với base URL của API, dưới prefix /v1 (xem Versioning). Mọi endpoint có xác thực đều dùng một session cookie httpOnly được thiết lập bởi POST /v1/auth/login — hiện chưa có cơ chế xác thực bằng API key riêng biệt (xem Authentication).

auth

Method	Path	Auth	Ghi chú
POST	/v1/auth/register	—	{ email, password }. Mật khẩu phải từ 12–128 ký tự.
POST	/v1/auth/login	—	{ email, password }. Thiết lập session cookie. Bị giới hạn tần suất theo IP và theo email độc lập với nhau.
POST	/v1/auth/logout	session	Xoá session cookie.
GET	/v1/auth/me	session	Trả về người dùng hiện tại.
GET	/v1/auth/google	—	Chuyển hướng tới Google OAuth.
GET	/v1/auth/google/callback	—	Callback OAuth; chuyển hướng vào ứng dụng khi thành công.
GET	/v1/auth/facebook	—	Chuyển hướng tới Facebook OAuth.
GET	/v1/auth/facebook/callback	—	Callback OAuth; chuyển hướng vào ứng dụng khi thành công.
POST	/v1/auth/forgot-password	—	{ email }. Luôn trả về cùng một thông điệp, bất kể email đó đã đăng ký hay chưa.
POST	/v1/auth/reset-password	—	{ token, password }. Token chỉ dùng được một lần và có hạn.

chat

Method	Path	Auth	Ghi chú
POST	/v1/chat	session	{ model, messages, conversationId?, idempotencyKey }. Stream về một response body dạng plain-text; header x-conversation-id của response mang conversation id. idempotencyKey là bắt buộc — một request được gửi lại với cùng key sẽ không bao giờ bị tính phí lại hoặc gọi lại provider.

skills

Method	Path	Auth	Ghi chú
POST	/v1/skills	session	{ name, instruction, input_schema?, output_schema? }. Tạo một Skill riêng tư cho tài khoản của bạn.
GET	/v1/skills	session	Liệt kê các Skill của chính bạn.
GET	/v1/skills/templates	session	Liệt kê các template khởi điểm bạn có thể nhân bản thành Skill của riêng bạn.
POST	/v1/skills/templates/:id/duplicate	session	Sao chép một template thành một Skill mới của riêng bạn.
POST	/v1/skills/import	session	{ name, instruction, input_schema?, output_schema?, version? } — đúng hình dạng mà GET /v1/skills/:id/export tạo ra, nên export → import round-trip được. Bất kỳ field nào khác (id, owner_id, organization_id, allowed_tools) đều bị từ chối thẳng; một Skill được import không bao giờ mang theo tool binding từ file.
GET	/v1/skills/:id	session	Một Skill bạn sở hữu, cùng tất cả các version của nó.
GET	/v1/skills/:id/export	session	Hình dạng dữ liệu di động { name, instruction, input_schema, output_schema, version }, khớp với input của endpoint import.
POST	/v1/skills/:id/versions	session	{ instruction, input_schema?, output_schema? }. Xuất bản một version mới, bất biến.
POST	/v1/skills/:id/run	session	{ model, input, conversationId?, idempotencyKey }. Đi lại vào cùng pipeline chat như POST /v1/chat, với input đóng vai trò tin nhắn người dùng duy nhất — cùng hành vi idempotency/quota/ledger.

conversations

Method	Path	Auth	Ghi chú
GET	/v1/conversations	session	Liệt kê các cuộc trò chuyện của chính bạn.
GET	/v1/conversations/:id	session	Một cuộc trò chuyện đơn lẻ cùng các tin nhắn của nó. Trả về 404 cho một cuộc trò chuyện bạn không sở hữu.

files

Method	Path	Auth	Ghi chú
GET	/v1/files	session	Liệt kê các file bạn đã tải lên.
POST	/v1/files	session	Upload dạng multipart, tên field là file. Chấp nhận văn bản thuần, Markdown, PDF, và .docx, tối đa 20 MB.
DELETE	/v1/files/:id	session	Xoá một file bạn sở hữu (đối tượng storage + bản ghi).

plans

Method	Path	Auth	Ghi chú
GET	/v1/plans	— (công khai)	Liệt kê các gói kèm giá và model được phép — cố ý công khai để giá cả được nhìn thấy trước khi đăng nhập.

billing

Method	Path	Auth	Ghi chú
POST	/v1/billing/checkout	session	{ planId, provider: "sepay" | "paddle" }. Số tiền bị tính phí luôn đến từ việc tra cứu gói ở phía server, không bao giờ từ client. Gói Free và Enterprise không thể checkout theo cách này.
GET	/v1/billing/quota	session	Giới hạn quota hằng ngày hiện tại và số dư còn lại của bạn.

Có thêm hai resource tồn tại trong API đang chạy nhưng không được tài liệu hoá như một bề mặt hướng tới khách hàng ở đây: /v1/webhooks/* (chỉ nhận vào, được gọi bởi SePay/Paddle — không phải thứ bạn tự gọi) và /v1/admin/* (nội bộ, chỉ dành cho admin).