Skip to main content

Documentation Index

Fetch the complete documentation index at: https://vmarea.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The VMArea Public API supports Stripe-style idempotent retries on every write endpoint, so a network blip or client crash never leaves you wondering whether a POST actually went through.

​
How it works

Send an Idempotency-Key header on any POST, PUT, PATCH, or DELETE request to /api/public/v1/*. Replays of the same key by the same API token return the original response — same status, same body — without re-executing the endpoint.
AspectDetail
HeaderIdempotency-Key
Format1–255 ASCII printable characters (UUID4 ideal)
Applies toPOST / PUT / PATCH / DELETE write routes
Cache window24 hours from the original response
Replay markerResponse carries Idempotency-Replayed: true
Concurrent replay409 Conflict while the first request is still in flight
5xx responsesNOT cached — safe to retry with the same key
GET / HEADHeader ignored (these are already idempotent)

​
Picking a key

Generate a fresh value per logical operation — typically a UUID4 — and reuse it only when retrying that exact request. Use different keys for different operations; use the same key for retries of the same operation.

​
Example

KEY=$(uuidgen)

curl -X POST https://api.vmarea.com/api/public/v1/vms \
  -H "x-api-key: $VMAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"web-01","planId":"plan_xxx","regionId":"sin-1","osTemplateId":"tpl_ubuntu_24"}'

# Network glitch? Replay the same key — you'll get the original response
# back, with Idempotency-Replayed: true in the headers.
curl -X POST https://api.vmarea.com/api/public/v1/vms \
  -H "x-api-key: $VMAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"web-01","planId":"plan_xxx","regionId":"sin-1","osTemplateId":"tpl_ubuntu_24"}'

​
Caveats

The cache key is (API token user, Idempotency-Key). A different token from the same account is treated as a different caller.
  • Request bodies are not checksummed — sending a different body with a reused key still returns the original response. Keep one key per operation.
  • Binary downloads (PDF invoices, etc.) are out of scope: replays of those endpoints will re-execute.
  • Idempotency is best-effort. If the cache is briefly unavailable, requests are let through rather than failed; in that rare window a retry may produce a duplicate side effect. Pair this header with normal defensive patterns for true at-most-once semantics.