API documentation

Authentication

Attach the key to every request header. No key or a bad key returns 401.

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

Scopes

A key can only call endpoints within the scopes you picked when creating it. Missing scope returns 403 with code `scope_required`.

Endpoints

62 endpoints. “Scope” is what the key must have.

Rate limits

120 per key per minute, 300 per account per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit you get 429 with Retry-After (seconds to wait).

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

Money-spending calls

Creating a VM, changing plan and deleting a VM require an Idempotency-Key header. Repeating the same value returns the earlier result instead of doing it again — a flaky network will not charge you twice.

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"}'

Error shape

Every error uses the same shape, with X-Request-Id so support can trace it.

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

Where to call from

This API is for your servers. CORS is not enabled, so it cannot be called from a browser. Never embed a key in client-side code.