Virtana / Documentation / API

Drive your containers from your scripts.

A JSON API authenticated by personal access tokens: list and state of the containers, start, stop, backups, operations and measurements.

01Create an access token

A personal access token lets a script, a continuous integration job or a monitoring tool read your containers and, if you allow it, start, stop, restart or back them up, or take a snapshot.

  1. Open your account, section “API access tokens”.

  2. Name the token, then choose its rights (read only, or read and actions), its lifetime (30, 90 or 365 days, or no expiry) and, if you wish, the containers it is limited to.

  3. Copy the token shown: it starts with vtn_ and is shown only once. Virtana keeps only a fingerprint of it (SHA-256): a lost token is replaced by a new one.

  • The token acts with your rights: on your containers and on those shared with you, within the permissions their owner gave you.
  • Revoke it from the same page as soon as it is no longer used or may have leaked: it is refused from the next request.
  • A suspended account can no longer use its tokens.
  • For each token, the page shows its last use and the number of actions it asked for.

Keep the token like a password: in a secrets manager or an environment variable, never in a Git repository.

Back to contents

02Authentication and errors

Every address starts with https://virtana.fr/api/v1. The token goes in the Authorization header, with no session or cookie.

Check your token: the answer gives its name, rights, containers and expiry.

export VIRTANA_TOKEN="vtn_…"
curl -s https://virtana.fr/api/v1/token -H "Authorization: Bearer $VIRTANA_TOKEN"

Answers are in JSON. A resource is found in data. An error always has the same shape:

{"error": {"code": "token_expired", "message": "This access token has expired: create a new one from your account."}}

The code field is stable and meant for your programs. The message field follows the Accept-Language header: French by default, or English. A validation refusal adds details, field by field.

  • 401: token missing (unauthenticated), unknown (invalid_token), expired (token_expired) or revoked (token_revoked).
  • 403: read-only token (insufficient_scope), missing permission on the container (forbidden) or suspended account (account_suspended).
  • 404: container or operation that does not exist or is out of the token’s reach (container_not_found, operation_not_found).
  • 409: Idempotency-Key already used for another action (idempotency_key_reused).
  • 422: action refused by the container’s state, the paid period or the offer (action_refused), action not in the API (action_not_supported) or invalid data (validation_failed).
  • 429: rate limit reached (rate_limited).
Back to contents

03List and read your containers

The list holds your containers and those shared with you, or only the token’s ones if it is limited. Each container has an id, the same as in the address of its page.

List the containers, 25 per page, up to 100 with per_page, and filter by state with state:

curl -s "https://virtana.fr/api/v1/containers?state=running" -H "Authorization: Bearer $VIRTANA_TOKEN"

Show a container:

curl -s https://virtana.fr/api/v1/containers/ID -H "Authorization: Bearer $VIRTANA_TOKEN"
  • state: state of the container (running, stopped, archived, suspended…). resources: processors (vcpu), memory in MiB (ram_mb) and disk in GB (disk_gb).
  • access: the SSH command and the HTTPS address, once the container is published, if you have the “Console” permission.
  • billing.term: the term, that is the end of the paid period, or the date a cancelled subscription stops.
  • role and permissions: owner or collaborator, and what you may do with it.
  • meta.total and links.next: number of containers and next page.
Back to contents

04Start, stop, back up

A “read and actions” token can start, stop or restart a container, run a backup or take a snapshot. The checks of the customer area apply: state of the container, paid period, backups included in the offer, permissions of a collaborator.

Each action carries an Idempotency-Key header: a UUID you generate once per action.

curl -s -X POST https://virtana.fr/api/v1/containers/ID/actions \
  -H "Authorization: Bearer $VIRTANA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"action": "restart"}'
  • Values of action: start, stop, restart, backup and snapshot. Ordering, payment, cancellation, reinstallation and restoration stay in the customer area.
  • The 202 answer gives back the operation created, with its id and the pending status, and its address in the Location header.
  • The same request sent again with the same key, for instance after a network failure, does not create a second operation: you receive the first one, with the Idempotent-Replayed: true header. A key reused for another action is refused.
  • One operation at a time per container: while an action runs, the next one is refused.
  • Each action appears in the container’s journal with the name of the token that asked for it.
Back to contents

05Follow an operation

An action runs in the background. Read the operation until its status is succeeded, failed or uncertain.

Read an operation:

curl -s https://virtana.fr/api/v1/operations/OPERATION_ID -H "Authorization: Bearer $VIRTANA_TOKEN"
  • pending: queued; running: in progress; succeeded: done; failed: failed, with error_code; uncertain: result to be checked by an operator.
  • For a backup or a snapshot, backup gives the identifier of the copy once created.

Wait for an operation to end in a script:

until curl -s https://virtana.fr/api/v1/operations/OPERATION_ID -H "Authorization: Bearer $VIRTANA_TOKEN" \
  | grep -Eq '"status": ?"(succeeded|failed|uncertain)"'; do sleep 5; done
Back to contents

06Backups and measurements

Two readings complete a container’s page: its kept copies and its latest sample.

List the backups and snapshots kept, newest first. A collaborator needs the permission to read backups.

curl -s https://virtana.fr/api/v1/containers/ID/backups -H "Authorization: Bearer $VIRTANA_TOKEN"

Read the latest measurements: processor, memory, disk and network. fresh marks a sample under five minutes old.

curl -s https://virtana.fr/api/v1/containers/ID/metrics -H "Authorization: Bearer $VIRTANA_TOKEN"
Back to contents

07Rate limits

Each token may send 60 requests per minute, 10 of them actions.

  • The X-RateLimit-Limit and X-RateLimit-Remaining headers of each answer give your margin.
  • Beyond it, the answer is 429 (rate_limited), with the Retry-After header in seconds.
  • Too many invalid tokens sent from one address block it for a minute.
Back to contents

08OpenAPI specification

The full description of the API, in the OpenAPI 3.1 format, is public: openapi.json. Import it into Postman or Insomnia, or generate a client in your language.

curl -s https://virtana.fr/api/v1/openapi.json -o virtana-openapi.json

The fields of version 1 will keep their meaning; new fields may be added. An incompatible change will take the form of a version 2, at another address.

Back to contents