API の概要

コントロールプレーンは、ランナーと各ランナーが保持するポリシーを管理するための REST API を提供します。このページでは、すべてのエンドポイントに共通する横断的な挙動 (認証、バージョニング、エラー形式、ページネーション) について説明します。ポリシー内の各フィールドのスキーマについては、ポリシーリファレンスを参照してください。これらのエンドポイントを使用する実践的な手順については、サンドボックスポリシーを設定するおよびランナーのデプロイと管理を参照してください。

ベース URL とバージョニング

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

これはコントロールプレーンのベース URL です。このページで説明するランナーエンドポイント (ランナーのデプロイ、各ランナーが持つポリシーの設定、状態の照会) を提供します。cwsandbox Python client がサンドボックスの起動やコマンドと出力のストリーミング (Sandbox.run()、sb.exec()、ファイル操作) に使用するサンドボックスのデータプレーンとは異なります。コントロールプレーンの操作では、サンドボックスを生成するインフラストラクチャを作成・設定します。データプレーンの操作では、実行中のサンドボックスと対話します。 API は v1 でバージョニングされています。追加的で後方互換性のある変更は v1 内で提供されます。互換性を損なう変更は新しいバージョンプレフィックスで提供され、CoreWeave はリリース前に告知します。以前の v1beta2 サーフェスも引き続き利用でき、プロファイルテンプレートとプロファイルバインディングはそこにあります。これらはポリシーに置き換えられており、v1 には追加されません。新しい統合では v1 を対象にしてください。

認証

すべてのリクエストは、TLS 経由で Bearer トークン認証を使用します。[API-ACCESS-TOKEN] を CoreWeave API アクセストークンに置き換えてください：

Authorization: Bearer [API-ACCESS-TOKEN]

Cloud Console の Tokens ページから API アクセストークンを生成します。トークンは所属するユーザーの権限を継承し、サーバーはすべてのリクエストでその権限を適用します。CoreWeave Sandboxes には、次の 2 つの IAM action が適用されます。

SANDBOX_ADMIN: ランナーの作成、読み取り、更新、削除、およびランナーに設定するポリシーの指定ができます。このページに記載されているエンドポイントは、読み取り系も含めてすべてこの action が必要です。SANDBOX_USER を含みます。
SANDBOX_USER: サンドボックスの作成と操作ができます。このページのエンドポイントへのアクセス権は付与されません。

Cloud Console の Access Policies ページで、いずれかの action を付与します。アクセスポリシーの仕組みと権限付与の手順については、アイデンティティとアクセス管理 (IAM) およびアクセスポリシーを管理するを参照してください。トークンの詳細については、API アクセストークンを管理するを参照してください。認証されていないリクエストは、google.rpc.Status 形式の本文とともに 401 Unauthenticated を返します。 CoreWeave Intelligent CLI (cwic) は、これらの REST エンドポイントをラップします。CLI ユーザーは cwic auth login で一度認証すると、cwic がローカルの cwic 設定にトークンを保存します。CLI のワークフローについては、サンドボックスポリシーを設定するを参照してください。

コンテンツタイプ

リクエストボディとレスポンスボディはすべて JSON 形式です。

Content-Type: application/json

この API は connectrpc を利用して HTTP/2 上で動作しますが、標準的な curl や fetch 形式のクライアントもそのまま利用できます。gRPC クライアントは不要です。これらのエンドポイントのベースとなっている公開 Protobuf 定義と、そこから生成された SDK については、Protobuf を参照してください。

リソースファミリー

コントロールプレーンは、管理用リソースとしてマネージドランナーを公開します。

ファミリー	ベースパス	オペレーション
マネージドランナー	`/v1/sandbox/managedRunners`	作成、取得、一覧取得、更新、削除、`:applyAvailableUpdate`

ポリシーを個別に指定してアクセスすることはできません。ポリシーはランナーのフィールドであるため、ランナーを取得して読み取り、更新対象を policy に限定したランナーの更新で書き込みます。書き込みのたびにドキュメント全体が置き換えられます。手順については、サンドボックスポリシーを設定するを参照してください。プロフィールテンプレートは、ランナーの profile_bindings フィールドとともに、引き続き v1beta2 の /v1beta2/sandbox/profile-templates で利用できます。これらはポリシーに置き換えられており、v1 モデルには含まれず、今後も追加されません。概念モデルと、ゲートウェイが実行時のリクエストを仲介する仕組みについては、サンドボックスのアーキテクチャを参照してください。このページでは、エンドポイントの仕様を説明します。

ページネーション

List エンドポイントは、カーソルベースのページネーションをサポートしています。

pageSize: ページサイズ。デフォルトは 50、最大は 100 です。
pageToken: 前のページで nextPageToken として返されたカーソル。空文字列の場合、それ以上のページはありません。

Paginate managed runners

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

# カーソルをたどります
curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1/sandbox/managedRunners?pageSize=50&pageToken=[NEXT-PAGE-TOKEN]'

CoreWeave Intelligent CLI は、cwic sandbox runner get などの一覧表示コマンドの出力を自動的にページ分割します。

更新時のフィールドマスク

更新用のエンドポイントは、オプションの update_mask を受け付けます。マスクが指定されている場合は、マスクに列挙されたフィールドのみが適用され、API はリクエストオブジェクト上のその他のフィールドをすべて無視します。マスクが指定されていない場合は、リクエストオブジェクト上の空でない変更可能なフィールドがすべて適用されます。パスはドット区切り表記と snake_case のフィールド名を使用します (標準の google.protobuf.FieldMask の規則) 。よく使用される変更可能なパスは次のとおりです。

パス	適用対象	目的
`spec.release_channel`	マネージドランナー	リリースチャンネル (`RELEASE_CHANNEL_STABLE` または `RELEASE_CHANNEL_RAPID`) を切り替えます。
`spec.maintenance_policy`	マネージドランナー	自動更新のメンテナンス期間を調整します。
`spec.overrides`	マネージドランナー	ランナー Pod のトレランス、ノードセレクター、ランタイムクラスを調整します。
`spec.enforce_resource_limits`	マネージドランナー	ランナー上のサンドボックスに CPU とメモリ制限の宣言を必須とします。
`policy`	マネージドランナー	ポリシードキュメント全体を置き換えます。ポリシーに対して実装されている唯一のマスクパスです。
`profile_bindings`	マネージドランナー	プロフィールバインディングのリスト全体を置き換えます。レガシーであり、`v1beta2` のみ対応です。`v1` での書き込みでは拒否されます。

REST インターフェースでは、各パスの JSON (camelCase) 形式を使用して、マスクをカンマ区切りの単一の updateMask クエリパラメーターとして指定し、リソース自体はラッパーなしでリクエストボディとして送信します。

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

各エンドポイントのリファレンスに、リソースごとの変更可能なパスが記載されています。

エラー

エラーは適切な HTTP ステータスと google.rpc.Status 本文を返します。

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

次の表は一般的な対応関係を示します:

HTTP	`code`	意味
400	3 (`INVALID_ARGUMENT`)	必須フィールドの欠落、不正な形式の入力、無効な spec。
401	16 (`UNAUTHENTICATED`)	API トークンの欠落または無効な API トークン。
403	7 (`PERMISSION_DENIED`)	トークンに action に必要な権限がありません。
404	5 (`NOT_FOUND`)	リソースが存在しません。
409	6 (`ALREADY_EXISTS`)	`displayName` または `runnerId` が重複しているか、同じクラスターに 2 つ目のランナーを作成しようとしました。
503	14 (`UNAVAILABLE`)	依存先 (クラスターの検証など) が一時的に利用できません。安全に再試行できます。
500	13 (`INTERNAL`)	予期しないサーバーエラー。指数バックオフで再試行してください。

検証メッセージは安定した公開仕様の一部です。エンドユーザーに直接表示できます。

冪等性

コントロールプレーンAPIは、次の冪等性を保証します。

Delete* エンドポイントは冪等です。すでに削除済みのリソースに対して DELETE を呼び出した場合、副作用なしに 404 が返されます。
Create* エンドポイントは冪等ではありません。同じ runnerId または displayName を2回指定すると 409 Conflict が返されます。安全に再試行するには、GET でリソースがすでに存在するかどうかを確認してください。
Update* エンドポイントは、フィールドマスクを使用し、変更したいフィールドのみを設定していれば、安全に再試行できます。

ハートビート

ランナーのハートビートは、ランナーの生存状態をトラッキングします。コントロールプレーンが生存確認期間内にハートビートを受信しないと、ランナーの connectionStatus は DISCONNECTED に切り替わります。ランナーに到達できなくなってからコントロールプレーンに反映されるまで、最大 30 秒の遅延が生じます。ランナーの Get 応答から、connectionStatus と関連する installStatus フィールドの両方を読み取れます。

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

ベース URL とバージョニング

認証

コンテンツタイプ

リソースファミリー

更新時のフィールドマスク

エラー

冪等性

ハートビート

関連情報

​ベース URL とバージョニング

​認証

​コンテンツタイプ

​リソースファミリー

​ページネーション

​更新時のフィールドマスク

​エラー

​冪等性

​ハートビート

​関連情報

ベース URL とバージョニング

認証

コンテンツタイプ

リソースファミリー

ページネーション

更新時のフィールドマスク

エラー

冪等性

ハートビート

関連情報