Documentation
Référence de l’API des bacs à sable
Créez, listez, lisez, démarrez, arrêtez et supprimez des bacs à sable par l’API client.
Authentification
Appelez https://api.runzivo.dev avec le jeton d’accès d’une personne ou une clé d’API d’espace de travail comme jeton porteur. Une clé d’API lit les bacs à sable avec la permission sandboxes:read ou sandboxes:write, et crée, démarre, arrête, supprime, exécute des commandes et ouvre des terminaux avec sandboxes:write. Ce sont des permissions de clé, pas des portées : accordez-les sous « Settings », « API Keys » dans le portail, ou avec rzv api-keys create --permissions sandboxes:write. Une clé avec la portée all:all peut aussi tout faire cela. Une clé ne peut jamais faire plus que ce que permet le rôle actuel de son créateur dans l’espace de travail. Tant qu’Agent Sandboxes est désactivé, chaque route répond 503 sandboxes_unavailable.
Routes
- GET /v1/customer/tenants/{tenantId}/sandboxes liste les bacs à sable, du plus récent au plus ancien, avec sizes (les tailles offertes) et max_running.
- POST /v1/customer/tenants/{tenantId}/sandboxes crée un bac à sable et le démarre. Répond 201.
- GET /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId} lit un bac à sable.
- POST /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/start démarre un bac à sable arrêté ou en échec. Il conserve son expiration d’origine.
- POST /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/stop arrête un bac à sable en cours d’exécution. Ses fichiers restent.
- DELETE /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId} arrête la VM et supprime le disque d’espace de travail. Les fichiers ne peuvent pas être récupérés. Supprimer de nouveau ne change rien.
Requête de création
- name : de 1 à 80 caractères. Obligatoire.
- size : 2vcpu-8gb, 4vcpu-16gb, 8vcpu-32gb ou 16vcpu-64gb, facturé à 1x, 2x, 4x ou 8x. Obligatoire. Les tailles offertes dépendent de la capacité actuelle : utilisez une taille que nomme le champ sizes de la réponse de liste.
- disk_gib : de 5 à 64, 20 par défaut.
- client_operation_id : de 8 à 200 caractères. Le répéter retourne le bac à sable créé la première fois.
Objet bac à sable
- id (sbx_ et 24 caractères hexadécimaux), name, size, disk_gib, status, created_at.
- error : null, ou un code et un message. Codes : no_capacity, insufficient_disk, start_timeout, stop_timeout, boot_failed, host_lost, credit_exhausted, workspace_blocked.
- started_at : le premier démarrage, null jusque-là. expires_at : le premier démarrage plus huit heures.
- remaining_seconds : durée de vie restante, 28800 avant le premier démarrage et 0 une fois expiré. runtime_seconds : temps pendant lequel la VM a été active.
- credits_used : unités-minutes facturées jusqu’ici, au multiplicateur de la taille.
Refus
- 403 : le jeton ou le rôle de son créateur n’autorise pas la route. 404 sandbox_not_found : aucun bac à sable de ce nom dans cet espace de travail.
- 409 sandbox_limit_reached, credit_exhausted, sandbox_name_taken, size_unavailable, workspace_blocked, sandbox_expired ou sandbox_wrong_state.