Các REST endpoint thật được MasterOS API expose, tổ chức theo resource, dưới prefix /v1.
Đây là các endpoint thật, hôm nay
Tài liệu tham chiếu này mô tả API đúng như nó đang được triển khai ngay bây giờ. Nó được viết tay, không sinh ra
từ spec OpenAPI thật của API (xem Versioning để biết spec đó thực sự nằm ở đâu) — hãy
theo dõi Changelog để biết độ lệch giữa hai bên.
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/verify-login-code — 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/request-login-code | — | { email }. Gửi mã 6 chữ số qua email, tạo tài khoản ở lần dùng đầu tiên; luôn trả về cùng một thông báo. Bị giới hạn tần suất theo IP và theo email độc lập với nhau. |
| POST | /v1/auth/verify-login-code | — | { email, code }. 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).
