Virtana / Documentation / API

Pilotez vos conteneurs depuis vos scripts.

Une API JSON authentifiée par jetons d’accès personnels : liste et état des conteneurs, démarrage, arrêt, sauvegardes, opérations et mesures.

01Créer un jeton d’accès

Un jeton d’accès personnel permet à un script, à une intégration continue ou à un outil de supervision de consulter vos conteneurs et, si vous l’autorisez, de les démarrer, les arrêter, les redémarrer, les sauvegarder ou d’en prendre un instantané.

  1. Ouvrez votre compte, section « Jetons d’accès à l’API ».

  2. Donnez un nom au jeton, puis choisissez ses droits (lecture seule, ou lecture et actions), sa durée (30, 90 ou 365 jours, ou sans expiration) et, si vous le souhaitez, les conteneurs auxquels il est limité.

  3. Copiez le jeton affiché : il commence par vtn_ et n’est montré qu’une fois. Virtana n’en garde qu’une empreinte (SHA-256) : un jeton perdu se remplace par un nouveau.

  • Le jeton agit avec vos droits : sur vos conteneurs et sur ceux partagés avec vous, dans la limite des permissions que leur propriétaire vous a données.
  • Révoquez-le depuis la même page dès qu’il ne sert plus ou s’il a pu fuiter : il est refusé dès la requête suivante.
  • Un compte suspendu ne peut plus utiliser ses jetons.
  • La page indique, pour chaque jeton, sa dernière utilisation et le nombre d’actions demandées.

Gardez le jeton comme un mot de passe : dans un gestionnaire de secrets ou une variable d’environnement, jamais dans un dépôt Git.

Retour au sommaire

02Authentification et erreurs

Toutes les adresses commencent par https://virtana.fr/api/v1. Le jeton passe dans l’en-tête Authorization, sans session ni cookie.

Vérifiez votre jeton : la réponse donne son nom, ses droits, ses conteneurs et son expiration.

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

Les réponses sont en JSON. Une ressource se trouve dans data. Une erreur a toujours la même forme :

{"error": {"code": "token_expired", "message": "Ce jeton d’accès a expiré : créez-en un nouveau depuis votre compte."}}

Le champ code est stable et destiné à vos programmes. Le champ message suit l’en-tête Accept-Language : français par défaut, ou anglais. Un refus de validation ajoute details, champ par champ.

  • 401 : jeton absent (unauthenticated), inconnu (invalid_token), expiré (token_expired) ou révoqué (token_revoked).
  • 403 : jeton en lecture seule (insufficient_scope), permission manquante sur le conteneur (forbidden) ou compte suspendu (account_suspended).
  • 404 : conteneur ou opération inexistants, ou hors de portée du jeton (container_not_found, operation_not_found).
  • 409 : Idempotency-Key déjà utilisée pour une autre action (idempotency_key_reused).
  • 422 : action refusée par l’état du conteneur, la période payée ou l’offre (action_refused), action absente de l’API (action_not_supported) ou données invalides (validation_failed).
  • 429 : limite de débit atteinte (rate_limited).
Retour au sommaire

03Lister et consulter vos conteneurs

La liste comprend vos conteneurs et ceux partagés avec vous, ou seulement ceux du jeton s’il est limité. Chaque conteneur a un identifiant id, le même que dans l’adresse de sa fiche.

Lister les conteneurs, 25 par page, jusqu’à 100 avec per_page, et filtrer par état avec state :

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

Afficher un conteneur :

curl -s https://virtana.fr/api/v1/containers/ID -H "Authorization: Bearer $VIRTANA_TOKEN"
  • state : état du conteneur (running, stopped, archived, suspended…). resources : processeurs (vcpu), mémoire en Mio (ram_mb) et disque en Go (disk_gb).
  • access : la commande SSH et l’adresse HTTPS, une fois le conteneur publié, si vous avez la permission « Console ».
  • billing.term : échéance, c’est-à-dire la fin de la période payée, ou la date d’arrêt d’un abonnement résilié.
  • role et permissions : propriétaire ou collaborateur, et ce que vous pouvez y faire.
  • meta.total et links.next : nombre de conteneurs et page suivante.
Retour au sommaire

04Démarrer, arrêter, sauvegarder

Un jeton « lecture et actions » peut démarrer, arrêter ou redémarrer un conteneur, lancer une sauvegarde ou prendre un instantané. Les contrôles de l’espace client s’appliquent : état du conteneur, période payée, sauvegardes prévues par l’offre, permissions d’un collaborateur.

Chaque action porte un en-tête Idempotency-Key : un UUID que vous générez une fois par 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"}'
  • Valeurs de action : start, stop, restart, backup et snapshot. Commande, paiement, résiliation, réinstallation et restauration restent dans l’espace client.
  • La réponse 202 renvoie l’opération créée, avec son id et le statut pending, et donne son adresse dans l’en-tête Location.
  • La même requête renvoyée avec la même clé, par exemple après une coupure réseau, ne crée pas de seconde opération : vous recevez la première, avec l’en-tête Idempotent-Replayed: true. Une clé réutilisée pour une autre action est refusée.
  • Une seule opération à la fois par conteneur : tant qu’une action est en cours, la suivante est refusée.
  • Chaque action figure dans le journal du conteneur avec le nom du jeton qui l’a demandée.
Retour au sommaire

05Suivre une opération

Une action se déroule en arrière-plan. Consultez l’opération jusqu’à ce que son status vaille succeeded, failed ou uncertain.

Consulter une opération :

curl -s https://virtana.fr/api/v1/operations/OPERATION_ID -H "Authorization: Bearer $VIRTANA_TOKEN"
  • pending : en file d’attente ; running : en cours ; succeeded : terminée ; failed : échouée, avec error_code ; uncertain : résultat à vérifier par un opérateur.
  • Pour une sauvegarde ou un instantané, backup donne l’identifiant de la copie une fois créée.

Attendre la fin d’une opération dans un 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
Retour au sommaire

06Sauvegardes et mesures

Deux lectures complètent la fiche d’un conteneur : ses copies conservées et son dernier relevé.

Lister les sauvegardes et les instantanés conservés, du plus récent au plus ancien. Un collaborateur a besoin de la permission de lecture des sauvegardes.

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

Lire les dernières mesures : processeur, mémoire, disque et réseau. fresh indique un relevé de moins de cinq minutes.

curl -s https://virtana.fr/api/v1/containers/ID/metrics -H "Authorization: Bearer $VIRTANA_TOKEN"
Retour au sommaire

07Limites de débit

Chaque jeton a droit à 60 requêtes par minute, dont 10 actions.

  • Les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining de chaque réponse indiquent votre marge.
  • Au-delà, la réponse est 429 (rate_limited), avec l’en-tête Retry-After en secondes.
  • Trop de jetons invalides envoyés depuis la même adresse la bloquent une minute.
Retour au sommaire

08Spécification OpenAPI

La description complète de l’API, au format OpenAPI 3.1, est publique : openapi.json. Importez-la dans Postman ou Insomnia, ou générez un client dans votre langage.

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

Les champs de la version 1 ne changeront pas de sens ; de nouveaux champs peuvent s’ajouter. Une évolution incompatible prendra la forme d’une version 2, à une autre adresse.

Retour au sommaire