Référence / Agent Sandboxes

Créer un ticket de terminal

Émet un ticket à usage unique permettant à un navigateur d'ouvrir le terminal sans en-tête Authorization.

POST/v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/terminal-ticket

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

Nécessite un bac à sable en cours d'exécution. Un ticket dure environ 30 secondes et est lié à un seul bac à sable et à un seul espace de travail.
Ajoutez le ticket encodé pour URL sous la forme ?ticket= à l'URL de terminal renvoyée. Ne consignez pas la chaîne de requête. Un bac à sable peut avoir au plus dix tickets inutilisés (429 ticket_limit_reached).
Les connexions WebSocket des navigateurs ne peuvent pas fournir Authorization. Utilisez le ticket sans en-tête Authorization ; les clients d'API et de CLI peuvent plutôt authentifier directement le terminal.

Réponses

Codes de réponse HTTP
État	Signification
201 Créé	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.
429 Trop de tickets	Dix tickets inutilisés existent déjà pour ce bac à sable.
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 du billet

Billet de terminal
Champ	Description
`url`stringObligatoire	URL wss absolue du terminal de ce bac à sable.
`ticket`stringObligatoire	Billet à usage unique, valide environ 30 secondes. Ajoutez-le comme paramètre de requête encodé en URL.
`expires_at`date-timeObligatoire	Moment où le billet expire.

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}/terminal-ticket" \
  --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.

201 · application/json

{
  "url": "wss://api.runzivo.dev/v1/customer/tenants/<tenant-id>/sandboxes/sbx_000000000000000000000001/terminal",
  "ticket": "<single-use-ticket>",
  "expires_at": "2026-10-31T12:00:30Z"
}

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

{
  "url": "wss://api.runzivo.dev/v1/customer/tenants/<tenant-id>/sandboxes/sbx_000000000000000000000001/terminal",
  "ticket": "<single-use-ticket>",
  "expires_at": "2026-10-31T12:00:30Z"
}

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

429 Trop de tickets

Dix tickets inutilisés existent déjà pour ce bac à sable.

application/json

{
  "error": {
    "code": "ticket_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"
  }
}