API & SDK
Tổng quan API
REST API IDEAS AI mở ra cánh cửa để bạn đưa toàn bộ sức mạnh của nền tảng vào chính ứng dụng của mình. Từ việc quản lý workspace, gửi tin nhắn đến AI Agents cho tới truy xuất dữ liệu cơ sở kiến thức — mọi thứ đều thực hiện được bằng lập trình, thông qua các yêu cầu HTTP tiêu chuẩn mà bạn đã quen thuộc.
URL gốc
https://api.ideas-ai.edu.vn/v1Tất cả endpoint đều được đánh phiên bản dưới /v1, giúp tích hợp của bạn luôn ổn định theo thời gian. Khi có thay đổi phá vỡ tương thích, một phiên bản mới (ví dụ: /v2) sẽ được phát hành song song với phiên bản hiện có — nên bạn có đủ thời gian để chuyển đổi mà không gián đoạn.
Định dạng yêu cầu
- Tất cả yêu cầu phải sử dụng HTTPS.
- Phần thân yêu cầu phải được mã hóa dưới dạng JSON với header:
Content-Type: application/json- Xác thực được thực hiện qua Bearer token trong header
Authorization. Xem Xác thực để biết chi tiết.
Định dạng phản hồi
Mọi phản hồi đều trả về JSON theo cùng một cấu trúc envelope nhất quán, nên bạn chỉ cần viết logic xử lý một lần và dùng lại ở khắp nơi:
{
"success": true,
"data": { ... },
"error": null
}| Trường | Kiểu | Mô tả |
|---|---|---|
success | boolean | true nếu yêu cầu thành công |
data | object | array | Payload phản hồi |
error | string | null | Thông báo lỗi khi success là false |
Giới hạn tốc độ
| Gói | Yêu cầu / phút | Token / ngày |
|---|---|---|
| Miễn phí | 20 | 50.000 |
| Pro | 100 | 500.000 |
| Enterprise | Không giới hạn | Không giới hạn |
Nếu ứng dụng của bạn gửi yêu cầu vượt quá giới hạn, API sẽ trả về HTTP 429 Too Many Requests. Đừng lo — chỉ cần thử lại sau khoảng thời gian được chỉ định trong header phản hồi Retry-After là mọi thứ sẽ tiếp tục bình thường.
Mã trạng thái HTTP
| Mã | Ý nghĩa |
|---|---|
200 | Thành công |
201 | Tài nguyên đã được tạo |
400 | Yêu cầu không hợp lệ — kiểm tra tham số |
401 | Chưa được ủy quyền — API key không hợp lệ hoặc thiếu |
403 | Bị cấm — không đủ quyền |
404 | Không tìm thấy tài nguyên |
429 | Vượt quá giới hạn tốc độ |
500 | Lỗi máy chủ nội bộ |
Các endpoint khả dụng
| Danh mục | Tiền tố endpoint | Mô tả |
|---|---|---|
| Agents | /agents | Liệt kê, tạo và gọi AI Agents |
| Knowledge | /knowledge | Tải lên và truy vấn tài liệu cơ sở kiến thức |
| Chat | /chat | Gửi tin nhắn và lấy lịch sử hội thoại |
| Workspaces | /workspaces | Quản lý workspace và thành viên |
Tài liệu tham khảo endpoint đầy đủ với schema yêu cầu/phản hồi có trong phần SDK.
