Référence / Agent Sandboxes

Arrêter un bac à sable

Arrête un bac à sable en cours d'exécution en conservant ses fichiers.

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

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.
`sandboxId`string · pathObligatoire	L'id renvoyé à la création du bac à sable : sbx_ suivi de 24 caractères hexadécimaux en minuscules.

Corps de la requête

Aucun corps de requête n’est requis.

Comportement et limites

Le calcul cesse d'être facturé à l'arrêt de la VM. Sa durée de vie de huit heures, mesurée à l'horloge murale, continue de s'écouler pendant l'arrêt.

Réponses

Codes de réponse HTTP
État	Signification
200 OK	application/json
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.
404 Introuvable	Aucun bac à sable avec cet ID n'existe dans l'espace de travail autorisé.
409 Conflit	L'opération n'est pas permise dans l'état actuel du bac à sable. Consultez les notes de l'opération pour d'autres codes de conflit possibles.
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 et SANDBOX_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/${SANDBOX_ID}/stop" \
  --header "Authorization: Bearer ${RUNZIVO_TOKEN}"

Exemple de réponse

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

200 · application/json

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

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

200 OK

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": "stopping",
  "error": null,
  "created_at": "2026-10-31T12:00:00Z",
  "started_at": "2026-10-31T12:00:00Z",
  "expires_at": "2026-10-31T20:00:00Z",
  "remaining_seconds": 28740,
  "runtime_seconds": 60,
  "credits_used": 1
}

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"
  }
}

404 Introuvable

Aucun bac à sable avec cet ID n'existe dans l'espace de travail autorisé.

application/json

{
  "error": {
    "code": "sandbox_not_found"
  }
}

409 Conflit

L'opération n'est pas permise dans l'état actuel du bac à sable. Consultez les notes de l'opération pour d'autres codes de conflit possibles.

application/json

{
  "error": {
    "code": "sandbox_wrong_state"
  }
}

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"
  }
}