Référence / Agent Sandboxes

Créer un bac à sable

Crée un bac à sable et demande son premier démarrage.

POST/v1/customer/tenants/{tenantId}/sandboxes

URL de base : https://api.runzivo.dev

Authentification

Envoyez Authorization: Bearer <token> avec un jeton d’accès client ou une clé d’API de l’espace de travail.

Permission de clé d’API : sandboxes:write. Ce sont des permissions, et non des portées héritées. Une clé dotée de la portée all:all fonctionne aussi, dans les limites des permissions actuelles de son créateur dans l’espace de travail.

Paramètres

Paramètres de chemin et de requête
Champ	Description
`tenantId`string · pathObligatoire	L'ID de locataire (tenant) de votre espace de travail. Remplacez l'espace réservé par un ID auquel votre jeton a accès.

Corps de la requête

Envoyez Content-Type: application/json.

Champs JSON de la requête
Champ	Description
`name`stringObligatoire	De 1 à 80 caractères après suppression des espaces en début et en fin. Le nom d'un bac à sable actif doit être unique dans l'espace de travail.
`size`stringObligatoire	2vcpu-8gb, 4vcpu-16gb, 8vcpu-32gb ou 16vcpu-64gb. Choisissez une taille dans le champ sizes de la réponse de la liste.
`disk_gib`integerFacultatif	De 5 à 64 GiB ; 20 par défaut.
`client_operation_id`stringFacultatif	De 8 à 200 caractères. Réutiliser cette valeur renvoie le bac à sable créé en premier pour elle.

Comportement et limites

Envoyez application/json. Limite de taille du corps de la requête : 4 KiB. Les champs JSON inconnus sont rejetés.
Une requête réussie renvoie 201 et un objet Sandbox seul. Interrogez régulièrement son état (status) ; une réponse ne prouve pas que la VM est prête.
Les conflits incluent sandbox_limit_reached, credit_exhausted, sandbox_name_taken, size_unavailable et workspace_blocked. La durée de vie de huit heures court à partir du premier démarrage, et non de l'ouverture dans le navigateur ou la CLI.

Réponses

Codes de réponse HTTP
État	Signification
201 Créé	application/json
400 Requête invalide	JSON mal formé, champs inconnus ou valeurs invalides. Les mises à niveau de terminal rejettent aussi les négociations (handshakes) mal formées.
401 Non autorisé	Jeton porteur (bearer) manquant ou invalide. Une requête de terminal avec ticket peut plutôt renvoyer ticket_invalid.
403 Interdit	L'appelant n'a pas l'appartenance à l'espace de travail ni la permission requise, ou la clé d'API n'est pas autorisée. Les codes incluent tenant_membership_required, permission_required et api_key_scope_required.
409 Conflit	La création a été refusée par la limite de l'espace de travail, les crédits, le nom, la taille ou les contrôles de l'espace de travail. Les codes incluent sandbox_limit_reached, credit_exhausted, sandbox_name_taken, size_unavailable et workspace_blocked.
500 Erreur interne	Le serveur n'a pas pu traiter la requête.
503 Indisponible	Le service de bacs à sable est indisponible. Les opérations d'exécution de commande et de terminal peuvent aussi renvoyer sandbox_exec_unavailable.

Les exemples utilisent des identifiants, des dates et des valeurs fictifs. Consultez la réponse et l’état réels dans votre espace de travail.

Champs de la réponse d’un bac à sable

En cas de succès, la réponse est directement un objet Sandbox, avec ces champs.

Objet Sandbox
Champ	Description
`id`stringObligatoire	ID du bac à sable : sbx_ suivi de 24 caractères hexadécimaux en minuscules.
`name`stringObligatoire	Nom du bac à sable de l'espace de travail.
`size`stringObligatoire	L'identifiant de la taille choisie.
`disk_gib`integerObligatoire	Taille du disque de l'espace de travail en GiB.
`status`stringObligatoire	pending, starting, running, stopping, stopped, deleting, deleted, expired ou failed.
`error`object \| nullObligatoire	null, ou {code, message} expliquant l'échec d'un bac à sable en état failed.
`created_at`date-timeObligatoire	Moment de création du bac à sable.
`started_at`date-time \| nullObligatoire	Premier démarrage ; null tant qu'il n'a pas démarré.
`expires_at`date-time \| nullObligatoire	Premier démarrage plus huit heures. L'arrêt ne met pas la durée de vie en pause.
`remaining_seconds`integerObligatoire	Durée de vie restante ; 28800 avant le premier démarrage, 0 une fois le bac à sable expiré ou supprimé.
`runtime_seconds`integerObligatoire	Secondes pendant lesquelles la VM a été active ; exclut le temps d'arrêt.
`credits_used`numberObligatoire	Unités-minutes facturées selon le multiplicateur de la taille.

Limites et facturation des bacs à sable →

Outils de la page

Voir en Markdown (anglais)

Poser une question à une IA sur cette page

Ouvrir dans ChatGPT Ouvrir dans Claude Ouvrir dans Cursor

Claude affiche une bannière de mise en garde sur toute invite préremplie. C’est normal : examinez l’invite, puis envoyez-la.

Exemple de requête

Requête à titre d’illustration. Définissez RUNZIVO_TOKEN et TENANT_ID dans votre interpréteur de commandes. Remplacez les valeurs fictives par les vôtres. Cette page n’envoie aucune requête.

cURL

curl --request POST \
  "https://api.runzivo.dev/v1/customer/tenants/${TENANT_ID}/sandboxes" \
  --header "Authorization: Bearer ${RUNZIVO_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "docs-example",
  "size": "2vcpu-8gb",
  "disk_gib": 20,
  "client_operation_id": "docs-create-example-01"
}'

Exemple de réponse

application/json · Réponse illustrative ; les valeurs et les délais varient dans votre espace de travail.

201 · application/json

{
  "id": "sbx_000000000000000000000001",
  "name": "docs-example",
  "size": "2vcpu-8gb",
  "disk_gib": 20,
  "status": "pending",
  "error": null,
  "created_at": "2026-10-31T12:00:00Z",
  "started_at": null,
  "expires_at": null,
  "remaining_seconds": 28800,
  "runtime_seconds": 0,
  "credits_used": 0
}

Tous les exemples de réponse (aussi accessibles sans JavaScript)

201 Créé

Réponse illustrative ; les valeurs et les délais varient dans votre espace de travail.

application/json

{
  "id": "sbx_000000000000000000000001",
  "name": "docs-example",
  "size": "2vcpu-8gb",
  "disk_gib": 20,
  "status": "pending",
  "error": null,
  "created_at": "2026-10-31T12:00:00Z",
  "started_at": null,
  "expires_at": null,
  "remaining_seconds": 28800,
  "runtime_seconds": 0,
  "credits_used": 0
}

400 Requête invalide

JSON mal formé, champs inconnus ou valeurs invalides. Les mises à niveau de terminal rejettent aussi les négociations (handshakes) mal formées.

application/json

{
  "error": {
    "code": "invalid_request"
  }
}

401 Non autorisé

Jeton porteur (bearer) manquant ou invalide. Une requête de terminal avec ticket peut plutôt renvoyer ticket_invalid.

application/json

{
  "error": {
    "code": "unauthorized"
  }
}

403 Interdit

L'appelant n'a pas l'appartenance à l'espace de travail ni la permission requise, ou la clé d'API n'est pas autorisée. Les codes incluent tenant_membership_required, permission_required et api_key_scope_required.

application/json

{
  "error": {
    "code": "permission_required"
  }
}

409 Conflit

La création a été refusée par la limite de l'espace de travail, les crédits, le nom, la taille ou les contrôles de l'espace de travail. Les codes incluent sandbox_limit_reached, credit_exhausted, sandbox_name_taken, size_unavailable et workspace_blocked.

application/json

{
  "error": {
    "code": "sandbox_limit_reached"
  }
}

500 Erreur interne

Le serveur n'a pas pu traiter la requête.

application/json

{
  "error": {
    "code": "internal_error"
  }
}

503 Indisponible

Le service de bacs à sable est indisponible. Les opérations d'exécution de commande et de terminal peuvent aussi renvoyer sandbox_exec_unavailable.

application/json

{
  "error": {
    "code": "sandboxes_unavailable"
  }
}