Aperçu de l’API

Le plan de contrôle expose une API REST qui permet de gérer les exécuteurs ainsi que la politique associée à chacun d’eux. Cette page décrit les comportements transversaux (authentification, gestion des versions, format des erreurs et pagination) qui s’appliquent à tous les points de terminaison. Pour connaître le schéma de chaque champ d’une politique, consultez la Référence des politiques. Pour des guides pas à pas orientés tâches qui utilisent ces points de terminaison, consultez Configurer une politique de sandbox et Déployer et gérer un exécuteur.

URL de base et gestion des versions

https://api.coreweave.com/v1/sandbox

Il s’agit de l’URL de base du plan de contrôle. Elle héberge les points de terminaison des exécuteurs documentés sur cette page : déployer des exécuteurs, définir la politique associée à chacun d’eux et consulter leur état. Elle est distincte du plan de données des sandbox, que le client Python cwsandbox utilise pour démarrer des bacs à sable et diffuser en continu les commandes et la sortie (Sandbox.run(), sb.exec(), opérations sur les fichiers). Les opérations du plan de contrôle créent et configurent l’infrastructure qui produit les bacs à sable. Les opérations du plan de données interagissent avec les bacs à sable en cours d’exécution. L’API est versionnée v1. Les modifications additives et rétrocompatibles sont publiées dans v1. Les changements non rétrocompatibles sont publiés sous un nouveau préfixe de version, et CoreWeave les annonce avant leur publication. Une version antérieure de l’API, v1beta2, reste disponible : c’est là que se trouvent les modèles de profil et les liaisons de profil. Ceux-ci sont remplacés par la politique et ne seront pas ajoutés à v1. Les nouvelles intégrations doivent cibler v1.

Authentification

Toutes les requêtes utilisent une authentification par jeton de type Bearer via TLS. Remplacez [API-ACCESS-TOKEN] par un jeton d’accès à l’API CoreWeave :

Authorization: Bearer [API-ACCESS-TOKEN]

Générez un jeton d’accès API depuis la page Tokens de la Cloud Console. Les jetons héritent des autorisations de l’utilisateur auquel ils appartiennent, et le serveur applique ces autorisations à chaque requête. Deux actions IAM s’appliquent à CoreWeave Sandboxes :

SANDBOX_ADMIN : créer, lire, mettre à jour et supprimer des exécuteurs, et définir la politique qui leur est associée. Tous les points de terminaison documentés sur cette page l’exigent, y compris en lecture. Inclut SANDBOX_USER.
SANDBOX_USER : créer et utiliser des bacs à sable. Cette action ne donne accès à aucun point de terminaison de cette page.

Accordez l’une ou l’autre de ces actions sur la page Access Policies de la Cloud Console. Pour comprendre le fonctionnement des Access Policies et suivre la procédure d’attribution étape par étape, consultez Gestion des identités et des accès (IAM) et Gérer les Access Policies. Pour en savoir plus sur les jetons, consultez Gérer les jetons d’accès à l’API. Les requêtes non authentifiées renvoient 401 Unauthenticated avec un corps au format google.rpc.Status. La CoreWeave Intelligent CLI (cwic) encapsule ces points de terminaison REST. Les utilisateurs de la CLI s’authentifient une seule fois avec cwic auth login, puis cwic stocke le jeton dans sa configuration locale. Pour le flux de travail en CLI, consultez Configurer une politique de sandbox.

Type de contenu

Tous les corps de requête et de réponse sont au format JSON :

Content-Type: application/json

L’API fonctionne sur HTTP/2 via connectrpc, mais les clients standard de type curl ou fetch fonctionnent de manière transparente. Aucun client gRPC n’est nécessaire. Pour consulter les définitions Protobuf publiées sur lesquelles reposent ces points de terminaison, ainsi que les SDK générés à partir de celles-ci, voir Protobuf.

Familles de ressources

Le plan de contrôle expose les exécuteurs gérés comme ressource d’administration :

Famille	Chemin de base	Opérations
Exécuteurs gérés	`/v1/sandbox/managedRunners`	Créer, Obtenir, Lister, Mettre à jour, Supprimer, `:applyAvailableUpdate`

Une politique n’est pas adressable indépendamment. Comme il s’agit d’un champ de l’exécuteur, vous la lisez en récupérant l’exécuteur et vous l’écrivez au moyen d’une mise à jour de l’exécuteur dont le masque cible policy. Chaque écriture remplace l’intégralité du document. Pour la procédure, consultez Configurer une politique de sandbox. Les modèles de profil restent disponibles sur la surface v1beta2 à l’adresse /v1beta2/sandbox/profile-templates, de même que le champ profile_bindings d’un exécuteur. Ils sont remplacés par les politiques, ne font pas partie du modèle v1 et n’y seront pas ajoutés. Pour le modèle conceptuel et la manière dont la passerelle relaie les requêtes d’exécution, consultez Architecture des bacs à sable. Cette page décrit le contrat des points de terminaison.

Pagination

Les points de terminaison de liste prennent en charge la pagination par curseur :

pageSize : taille de la page. Par défaut 50, maximum 100.
pageToken : curseur renvoyé dans le champ nextPageToken de la page précédente. Une chaîne vide indique qu’il n’y a plus de pages.

Paginate managed runners

curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50'

# Suivre le curseur
curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50&pageToken=[NEXT-PAGE-TOKEN]'

La CoreWeave Intelligent CLI pagine automatiquement les résultats des commandes de liste, comme cwic sandbox runner get.

Masques de champs lors des mises à jour

Les points de terminaison de mise à jour acceptent un update_mask facultatif. S’il est fourni, seuls les champs listés dans le masque sont appliqués et l’API ignore tout le reste de l’objet de la requête. S’il est absent, tous les champs modifiables non vides de l’objet de la requête sont appliqués. Les chemins utilisent la notation pointée et des noms de champs en snake_case (convention standard de google.protobuf.FieldMask). Chemins modifiables les plus courants :

Chemin	S’applique à	Objectif
`spec.release_channel`	Exécuteur géré	Changer de canal de publication (`RELEASE_CHANNEL_STABLE` ou `RELEASE_CHANNEL_RAPID`).
`spec.maintenance_policy`	Exécuteur géré	Ajuster les fenêtres de maintenance des mises à jour automatiques.
`spec.overrides`	Exécuteur géré	Ajuster les tolérances, les sélecteurs de nœuds et la classe de runtime du pod de l’exécuteur.
`spec.enforce_resource_limits`	Exécuteur géré	Exiger que les bacs à sable de l’exécuteur déclarent des limites de CPU et de mémoire.
`policy`	Exécuteur géré	Remplacer l’intégralité du document de politique. Seul chemin de masque pris en charge pour la politique.
`profile_bindings`	Exécuteur géré	Remplacer la liste complète des liaisons de profils. Obsolète, `v1beta2` uniquement ; rejeté par les écritures `v1`.

Sur l’interface REST, fournissez le masque sous la forme d’un unique paramètre de requête updateMask dont les valeurs sont séparées par des virgules, en utilisant la forme JSON (camelCase) de chaque chemin, et envoyez directement la ressource comme corps de requête, sans encapsuleur :

curl -X PATCH "https://api.coreweave.com/v1/sandbox/managedRunners/[RUNNER-ID]?updateMask=spec.releaseChannel,spec.maintenancePolicy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "releaseChannel": "RELEASE_CHANNEL_RAPID" } }'

La référence de chaque point de terminaison indique les chemins modifiables de chaque ressource.

Erreurs

Les erreurs renvoient un code de statut HTTP approprié et un corps google.rpc.Status.

{
  "code":    3,
  "message": "runner.identity.zone is required",
  "details": []
}

Le tableau suivant répertorie les mappages courants :

HTTP	`code`	Signification
400	3 (`INVALID_ARGUMENT`)	Champ requis manquant, entrée mal formée, spécification non valide.
401	16 (`UNAUTHENTICATED`)	Jeton API manquant ou non valide.
403	7 (`PERMISSION_DENIED`)	Le jeton ne dispose pas de l’autorisation requise pour effectuer l’action.
404	5 (`NOT_FOUND`)	La ressource n’existe pas.
409	6 (`ALREADY_EXISTS`)	`displayName` ou `runnerId` en double, ou tentative de création d’un second exécuteur sur le même cluster.
503	14 (`UNAVAILABLE`)	Dépendance (par exemple, la validation du cluster) temporairement indisponible. Vous pouvez réessayer sans risque.
500	13 (`INTERNAL`)	Erreur inattendue du serveur. Réessayez avec un backoff exponentiel.

Les messages de validation font partie de la surface stable de l’API. Vous pouvez les afficher tels quels aux utilisateurs finaux.

Idempotence

L’API du plan de contrôle offre les garanties d’idempotence suivantes :

Les points de terminaison Delete* sont idempotents. Un appel DELETE sur une ressource déjà supprimée renvoie 404 sans effet de bord.
Les points de terminaison Create* ne sont pas idempotents. Si vous fournissez deux fois le même runnerId ou le même displayName, l’API renvoie 409 Conflict. Pour effectuer une nouvelle tentative sans risque, vérifiez d’abord avec GET si la ressource existe déjà.
Les points de terminaison Update* peuvent faire l’objet de nouvelles tentatives sans risque si vous utilisez un masque de champs et ne définissez que les champs à modifier.

Signaux de pulsation

Les signaux de pulsation (heartbeats) permettent de vérifier que les exécuteurs sont actifs. Si le plan de contrôle ne reçoit aucun signal de pulsation pendant la fenêtre d’activité, le connectionStatus de l’exécuteur passe à DISCONNECTED. Comptez jusqu’à 30 secondes de décalage entre le moment où l’exécuteur devient injoignable et celui où le plan de contrôle en tient compte. Vous pouvez lire connectionStatus ainsi que le champ associé installStatus dans la réponse d’une requête Get sur un exécuteur.

Voir aussi

Architecture des bacs à sable : la taxonomie à quatre ressources et la façon dont la passerelle relaie les requêtes d’exécution.
Aperçu des politiques : comment un sandbox est résolu par rapport à une politique.
Configurer une politique de sandbox : flux de travail avec CoreWeave Intelligent CLI et guide pas à pas, champ par champ, de la spécification du profil.
Déployer et gérer un exécuteur : guide pas à pas du cycle de vie de l’exécuteur avec CoreWeave Intelligent CLI et l’API REST.
Référence des politiques : tous les champs que vous pouvez définir dans un profil.
Protobuf : où trouver le module Protobuf publié, quel hôte expose chaque service et comment installer un SDK généré.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

URL de base et gestion des versions

Authentification

Type de contenu

Familles de ressources

Masques de champs lors des mises à jour

Erreurs

Idempotence

Signaux de pulsation

Voir aussi

​URL de base et gestion des versions

​Authentification

​Type de contenu

​Familles de ressources

​Pagination

​Masques de champs lors des mises à jour

​Erreurs

​Idempotence

​Signaux de pulsation

​Voir aussi

URL de base et gestion des versions

Authentification

Type de contenu

Familles de ressources

Pagination

Masques de champs lors des mises à jour

Erreurs

Idempotence

Signaux de pulsation

Voir aussi