Tài liệu API

Xác thực

Gắn khoá vào header của mỗi request. Không có khoá hoặc khoá sai thì nhận 401.

curl -H "Authorization: Bearer vk_xxxxxxxx" \
     https://onie.net/v1/vm

Phạm vi quyền

Mỗi khoá chỉ gọi được những endpoint thuộc phạm vi quyền đã chọn lúc tạo. Thiếu quyền thì nhận 403 kèm mã `scope_required`.

Danh sách endpoint

62 endpoint. Cột “Cần quyền” là phạm vi quyền khoá phải có.

Hạn mức gọi

Mỗi khoá 120/phút, mỗi tài khoản 300/phút. Mọi phản hồi đều kèm X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; vượt hạn mức thì nhận 429 kèm Retry-After (số giây nên chờ).

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1758658800
Retry-After: 37          ← chỉ có khi 429
X-Request-Id: r7f2a9c1b4e8d0a63

Lệnh tốn tiền

Tạo máy, đổi gói và xoá máy bắt buộc kèm header Idempotency-Key. Gọi lại đúng chuỗi đó sẽ trả lại kết quả cũ thay vì làm lần nữa — mạng chập chờn cũng không bị trừ tiền hai lần.

curl -X POST https://onie.net/v1/vm \
     -H "Authorization: Bearer vk_xxxxxxxx" \
     -H "Idempotency-Key: don-hang-2026-09-23-001" \
     -H "Content-Type: application/json" \
     -d '{"plan":"vm-1-2","template":"ubuntu-24.04","hostname":"web-01"}'

Khuôn lỗi

Mọi lỗi đều cùng một khuôn, kèm X-Request-Id để đối chiếu khi cần hỗ trợ.

{
  "error": {
    "code": "scope_required",
    "message": "Khoá thiếu phạm vi quyền 'vm:write' cho POST /v1/vm/:id/start"
  }
}

Gọi từ đâu

API dành cho máy chủ của bạn, không mở CORS nên không gọi được thẳng từ trình duyệt. Đừng nhúng khoá vào mã chạy trên máy khách.