Automation & API

Everything the web console does, it does by calling a REST API — so anything you can do by clicking, you can do from a script, a pipeline or another system. There's no separate "automation edition": the same API runs the product. This guide covers how to authenticate, the conventions every endpoint follows, and how to drive operations that take a while.

Authenticate with an API key

Automation should use its own credentials, never a person's password. An administrator issues an API key — a token scoped to exactly what the integration needs and revocable on its own, without disturbing anything else.

A key is shown once, at creation. Store it in your secrets manager; the platform keeps only a hash and a short prefix so you can recognise it later.
Send it on every request as a bearer token: Authorization: Bearer sk-…
Keys can carry an expiry and are revoked instantly when you delete them.

Scopes — least privilege

Scopes decide what a key may do. They range from coarse to per-resource:

Scope	Grants
(none) or `viewer`	Read-only, every resource.
`operator`	Read and write, every resource.
`admin`	Everything.
`read:<resource>`	Read that one resource type (e.g. `read:vms`).
`write:<resource>`	Read and write that resource type (e.g. `write:volumes`).
`read:` / `write:`	All-resource forms of the above.

A write scope always implies the matching read. Give a backup script read:vms plus write:backup-targets and it can do its job and nothing else.

Making a request

The API lives under /api/v1 on the cluster's management address, over HTTPS. Requests and responses are JSON. Any HTTP client works — curl, Python, Go, your CI runner.

# List virtual machines
curl -H "Authorization: Bearer $SKYVIRT_KEY" \
     https://cluster.example:8443/api/v1/vms

Conventions every endpoint shares

Lists are paginated

Collection endpoints accept page, per_page, sort_by and sort_order, and return the rows plus a pagination block:

GET /api/v1/vms?page=2&per_page=100&sort_by=name&sort_order=asc

{ "data": [ … ],
  "pagination": { "page": 2, "per_page": 100, "total": 237, "total_pages": 3 } }

Errors are structured

Failures return a consistent envelope — a human message, a stable machine code you can branch on, and a request id to quote in support tickets:

{ "error": "resource pool \"team-red\" CPU limit exceeded: 6 in use + 4 requested > 8 cores",
  "error_code": "conflict",
  "request_id": "…" }

Codes include invalid_request, unauthorized, forbidden, not_found, conflict, precondition_failed and rate_limited.

Safe concurrent edits (optimistic concurrency)

Reads return an ETag. To change something safely, send it back as If-Match on the update: if someone else changed the resource since you read it, you get 412 Precondition Failed instead of silently overwriting their work.

Safe retries (idempotency)

Network blip mid-request? Retrying a create could make two of something. Send an Idempotency-Key header (any unique string) on a mutating request and the platform guarantees it runs at most once — a replay returns the original result with X-Idempotency-Replay: true.

Long-running operations

Some actions — cloning a VM, taking a backup, a live migration, bulk operations — take longer than a request should wait. These return promptly with a task to follow. Poll the task for progress and outcome, or watch every in-flight operation at once:

GET /api/v1/tasks/{id}        # one operation: state, progress, result
GET /api/v1/tasks/active      # everything currently running

Rate limits

The API is rate-limited per client, and a few expensive operations (file browsing, bulk creates) have tighter caps. Over the limit returns 429 — back off and retry.

A worked example: create a VM

curl -X POST https://cluster.example:8443/api/v1/vms \
  -H "Authorization: Bearer $SKYVIRT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
        "name": "web-01",
        "vcpus": 2,
        "memory_bytes": 4294967296,
        "image_id": "…",
        "network_name": "default-network"
      }'

The network can be given by name or id; quotas and resource-pool limits are checked before anything is created, so an over-budget request fails fast with a clear reason rather than half-building a VM.

The full endpoint reference

This guide covers the patterns; the complete, always-current list of endpoints — every resource, method and field — lives in the console's built-in API reference, generated from the running platform so it never drifts from what you actually have.