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.
-
Open your account, section “API access tokens”.
-
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.
-
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 contents02Authentication 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-Keyalready 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).
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.roleandpermissions: owner or collaborator, and what you may do with it.meta.totalandlinks.next: number of containers and next page.
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,backupandsnapshot. Ordering, payment, cancellation, reinstallation and restoration stay in the customer area. - The
202answer gives back the operation created, with itsidand thependingstatus, and its address in theLocationheader. - 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: trueheader. 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.
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, witherror_code;uncertain: result to be checked by an operator.- For a backup or a snapshot,
backupgives 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; done06Backups 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"07Rate limits
Each token may send 60 requests per minute, 10 of them actions.
- The
X-RateLimit-LimitandX-RateLimit-Remainingheaders of each answer give your margin. - Beyond it, the answer is
429(rate_limited), with theRetry-Afterheader in seconds. - Too many invalid tokens sent from one address block it for a minute.
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.jsonThe 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