> ## 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.

# API の概要

> CoreWeave Sandboxes コントロールプレーン API のベース URL、認証、バージョニング、ページネーション、エラー処理について説明します。

コントロールプレーンは、ランナーと各ランナーが保持するポリシーを管理するための REST API を提供します。このページでは、すべてのエンドポイントに共通する横断的な挙動 (認証、バージョニング、エラー形式、ページネーション) について説明します。

ポリシー内の各フィールドのスキーマについては、[ポリシーリファレンス](/ja/products/sandboxes/reference/profile)を参照してください。これらのエンドポイントを使用する実践的な手順については、[サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure)および[ランナーのデプロイと管理](/ja/products/sandboxes/operations/managed-runners)を参照してください。

<h2 id="base-url-and-versioning">
  ベース URL とバージョニング
</h2>

```text theme={"system"}
https://api.coreweave.com/v1/sandbox
```

これはコントロールプレーンのベース URL です。このページで説明するランナーエンドポイント (ランナーのデプロイ、各ランナーが持つポリシーの設定、状態の照会) を提供します。[cwsandbox Python client](/ja/products/sandboxes/client) がサンドボックスの起動やコマンドと出力のストリーミング (`Sandbox.run()`、`sb.exec()`、ファイル操作) に使用するサンドボックスのデータプレーンとは異なります。コントロールプレーンの操作では、サンドボックスを生成するインフラストラクチャを作成・設定します。データプレーンの操作では、実行中のサンドボックスと対話します。

API は `v1` でバージョニングされています。追加的で後方互換性のある変更は `v1` 内で提供されます。互換性を損なう変更は新しいバージョンプレフィックスで提供され、CoreWeave はリリース前に告知します。

以前の `v1beta2` サーフェスも引き続き利用でき、プロファイルテンプレートとプロファイルバインディングはそこにあります。これらはポリシーに置き換えられており、`v1` には追加されません。新しい統合では `v1` を対象にしてください。

<h2 id="authentication">
  認証
</h2>

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

```text theme={"system"}
Authorization: Bearer [API-ACCESS-TOKEN]
```

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

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

Cloud Console の [Access Policies](https://console.coreweave.com/organization/iam/access-policies) ページで、いずれかの action を付与します。アクセスポリシーの仕組みと権限付与の手順については、[アイデンティティとアクセス管理 (IAM)](/security/iam) および [アクセスポリシーを管理する](/security/iam/access-policies/manage) を参照してください。トークンの詳細については、[API アクセストークンを管理する](/security/authn-authz/manage-api-access-tokens) を参照してください。

認証されていないリクエストは、`google.rpc.Status` 形式の本文とともに `401 Unauthenticated` を返します。

[CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`cwic`) は、これらの REST エンドポイントをラップします。CLI ユーザーは `cwic auth login` で一度認証すると、`cwic` がローカルの `cwic` 設定にトークンを保存します。CLI のワークフローについては、[サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure#before-you-begin) を参照してください。

<h2 id="content-type">
  コンテンツタイプ
</h2>

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

```text theme={"system"}
Content-Type: application/json
```

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

<h2 id="resource-families">
  リソースファミリー
</h2>

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

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

ポリシーを個別に指定してアクセスすることはできません。ポリシーはランナーのフィールドであるため、ランナーを取得して読み取り、更新対象を `policy` に限定したランナーの更新で書き込みます。書き込みのたびにドキュメント全体が置き換えられます。手順については、[サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure)を参照してください。

プロフィールテンプレートは、ランナーの `profile_bindings` フィールドとともに、引き続き `v1beta2` の `/v1beta2/sandbox/profile-templates` で利用できます。これらはポリシーに置き換えられており、`v1` モデルには含まれず、今後も追加されません。

概念モデルと、ゲートウェイが実行時のリクエストを仲介する仕組みについては、[サンドボックスのアーキテクチャ](/ja/products/sandboxes/architecture)を参照してください。このページでは、エンドポイントの仕様を説明します。

<h2 id="pagination">
  ページネーション
</h2>

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

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

```bash title="Paginate managed runners" theme={"system"}
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` などの一覧表示コマンドの出力を自動的にページ分割します。

<h2 id="field-masks-on-updates">
  更新時のフィールドマスク
</h2>

更新用のエンドポイントは、オプションの `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` クエリパラメーターとして指定し、リソース自体はラッパーなしでリクエストボディとして送信します。

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

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

<h2 id="errors">
  エラー
</h2>

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

```json theme={"system"}
{
  "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`) | 予期しないサーバーエラー。指数バックオフで再試行してください。 |

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

<h2 id="idempotency">
  冪等性
</h2>

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

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

<h2 id="heartbeats">
  ハートビート
</h2>

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

<h2 id="see-also">
  関連情報
</h2>

* [サンドボックスのアーキテクチャ](/ja/products/sandboxes/architecture): 4 種類のリソースの分類と、ゲートウェイが実行時リクエストを仲介する仕組みを説明します。
* [ポリシーの概要](/ja/products/sandboxes/profiles/profiles): サンドボックスにポリシーが適用される仕組みを説明します。
* [サンドボックスポリシーを設定する](/ja/products/sandboxes/profiles/configure): CoreWeave Intelligent CLI のワークフローと、プロフィールの spec の各フィールドを順に説明します。
* [ランナーのデプロイと管理](/ja/products/sandboxes/operations/managed-runners): CoreWeave Intelligent CLI と REST を使用したランナーのライフサイクル管理を順に説明します。
* [ポリシーリファレンス](/ja/products/sandboxes/reference/profile): プロフィールで設定できるすべてのフィールドを説明します。
* [Protobuf](/ja/products/sandboxes/reference/protos): 公開されている Protobuf モジュールの入手先、各サービスを提供するホスト、生成された SDK のインストール方法を説明します。