> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt > Use this file to discover all available pages before exploring further. # Aperçu de l’API > URL de base, authentification, gestion des versions, pagination et gestion des erreurs pour l’API du plan de contrôle de CoreWeave Sandboxes. 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](/fr/products/sandboxes/reference/profile). Pour des guides pas à pas orientés tâches qui utilisent ces points de terminaison, consultez [Configurer une politique de sandbox](/fr/products/sandboxes/profiles/configure) et [Déployer et gérer un exécuteur](/fr/products/sandboxes/operations/managed-runners).

URL de base et gestion des versions

```text theme={"system"} 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](/fr/products/sandboxes/client) 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 : ```text theme={"system"} Authorization: Bearer [API-ACCESS-TOKEN] ``` Générez un jeton d’accès API depuis la page [Tokens](https://console.coreweave.com/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](https://console.coreweave.com/organization/iam/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)](/security/iam) et [Gérer les Access Policies](/security/iam/access-policies/manage). Pour en savoir plus sur les jetons, consultez [Gérer les jetons d’accès à l’API](/security/authn-authz/manage-api-access-tokens). Les requêtes non authentifiées renvoient `401 Unauthenticated` avec un corps au format `google.rpc.Status`. La [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`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](/fr/products/sandboxes/profiles/configure#before-you-begin).

Type de contenu

Tous les corps de requête et de réponse sont au format JSON : ```text theme={"system"} Content-Type: application/json ``` L'API fonctionne sur HTTP/2 via [connectrpc](https://connectrpc.com/), 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](/fr/products/sandboxes/reference/protos).

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](/fr/products/sandboxes/profiles/configure). 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](/fr/products/sandboxes/architecture). 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. ```bash title="Paginate managed runners" theme={"system"} 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 : ```bash theme={"system"} 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`. ```json theme={"system"} { "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](/fr/products/sandboxes/architecture) : la taxonomie à quatre ressources et la façon dont la passerelle relaie les requêtes d’exécution. * [Aperçu des politiques](/fr/products/sandboxes/profiles/profiles) : comment un sandbox est résolu par rapport à une politique. * [Configurer une politique de sandbox](/fr/products/sandboxes/profiles/configure) : 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](/fr/products/sandboxes/operations/managed-runners) : guide pas à pas du cycle de vie de l’exécuteur avec CoreWeave Intelligent CLI et l’API REST. * [Référence des politiques](/fr/products/sandboxes/reference/profile) : tous les champs que vous pouvez définir dans un profil. * [Protobuf](/fr/products/sandboxes/reference/protos) : où trouver le module Protobuf publié, quel hôte expose chaque service et comment installer un SDK généré.