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

> Base URL, authentication, versioning, pagination, and error handling for the CoreWeave Sandbox control plane API.

The control plane exposes a REST API for managing runners and profiles. This page covers the cross-cutting behavior (authentication, versioning, error shapes, and pagination) that applies to every endpoint.

For the schema of the fields inside a profile's `spec`, see the [Profile reference](/products/sandboxes/reference/profile). For task-oriented walkthroughs that use these endpoints, see [Configure a sandbox profile](/products/sandboxes/profiles/configure) and [Deploy and manage a runner](/products/sandboxes/operations/managed-runners).

<Note>
  CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, [CoreWeave Support](https://cloud.coreweave.com/contact), or email [support@coreweave.com](mailto:support@coreweave.com).
</Note>

## Base URL and versioning

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

This is the control plane base URL. It hosts the runner and profile endpoints documented on this page: deploy runners, create profiles, attach bindings, and query state. It's distinct from the sandbox data plane that the [cwsandbox Python client](/products/sandboxes/client) uses to start sandboxes and stream commands and output (`Sandbox.run()`, `sb.exec()`, file operations). Control plane operations create and configure the infrastructure that produces sandboxes. Data plane operations interact with running sandboxes.

The API is versioned `v1beta2`. The version prefix signals an evolving preview surface: additive, backward-compatible changes ship within `v1beta2`. Breaking changes ship behind a new version prefix, and CoreWeave announces them before release.

## Authentication

All requests use bearer-token authentication over TLS:

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

Generate an API access token from the [Tokens](https://console.coreweave.com/tokens) page in the cloud console. Tokens inherit the permissions of the user they belong to, and the server enforces those permissions on every request. To call the endpoints documented on this page, the token's user must be granted either of the following IAM actions in an Access Policy:

* `SANDBOX_ADMIN`: create, update, and delete runners and profiles. Implies `SANDBOX_USER`.
* `SANDBOX_USER`: read runners and profiles, and create sandboxes against them.

Grant either action on the [Access Policies](https://console.coreweave.com/organization/iam/access-policies) page in the cloud console. For background on how Access Policies work and the step-by-step grant flow, see [Identity and Access Management (IAM)](/security/iam) and [Manage Access Policies](/security/iam/access-policies/manage). For more on tokens, see [Manage API Access Tokens](/security/authn-authz/manage-api-access-tokens).

Unauthenticated requests return `401 Unauthenticated` with a `google.rpc.Status`-shaped body.

The [CoreWeave Intelligent CLI](https://github.com/coreweave/cwic) (`cwic`) wraps these REST endpoints. CLI users authenticate once with `cwic auth login`, and `cwic` stores the token in the local `cwic` config. See [Configure a sandbox profile](/products/sandboxes/profiles/configure#before-you-begin) for the CLI workflow.

## Content type

All request and response bodies are JSON:

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

The API runs over HTTP/2 through [connectrpc](https://connectrpc.com/), but standard `curl` or `fetch`-style clients work transparently. You don't need a gRPC client.

## Resource families

The control plane exposes two top-level resource families. The following table summarizes their base paths and supported operations:

| Family            | Base path                            | Operations                                        |
| ----------------- | ------------------------------------ | ------------------------------------------------- |
| Managed runners   | `/v1beta2/sandbox/managed-runners`   | Create, Get, List, Update, Delete, `apply-update` |
| Profile templates | `/v1beta2/sandbox/profile-templates` | Create, Get, List, Update, Delete                 |

Profile bindings aren't independently addressable. Mutate them through a runner update with a `profile_bindings` field mask. For the CoreWeave Intelligent CLI workflow and the binding-update semantics, see [Manage profile bindings](/products/sandboxes/profiles/configure#manage-profile-bindings). Each update replaces the binding list as a whole, so the patch must include every binding you want to keep.

The resource family `profile-templates` retains the legacy `template` suffix in its URL path because that's the on-wire resource name. Throughout the documentation, "profile" and "profile template" refer to the same thing.

For the conceptual model (the four-resource taxonomy and how the gateway brokers runtime requests), see [Sandboxes architecture](/products/sandboxes/architecture). This page documents the endpoint contract.

## Pagination

List endpoints support cursor-based pagination:

* `pageSize`: page size. Default `50`, max `100`.
* `pageToken`: cursor returned as `nextPageToken` on the previous page. An empty string means no more pages.

```bash title="Paginate managed runners" theme={"system"}
curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1beta2/sandbox/managed-runners?pageSize=50'

# Follow the cursor
curl -H "Authorization: Bearer $TOKEN" \
  'https://api.coreweave.com/v1beta2/sandbox/managed-runners?pageSize=50&pageToken=[NEXT-PAGE-TOKEN]'
```

The CoreWeave Intelligent CLI automatically paginates list commands such as `cwic sandbox runner get` and `cwic sandbox profile get`.

## Field masks on updates

Update endpoints accept an optional `update_mask`. When present, only the fields listed in the mask apply, and the API ignores everything else on the request object. When absent, every non-empty mutable field on the request object applies.

Paths use dotted notation and `snake_case` field names (standard `google.protobuf.FieldMask` convention). Commonly used mutable paths:

| Path                              | Applies to       | Purpose                                                                           |
| --------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
| `managed_spec.release_channel`    | Managed runner   | Switch the release channel (`RELEASE_CHANNEL_STABLE` or `RELEASE_CHANNEL_RAPID`). |
| `managed_spec.maintenance_policy` | Managed runner   | Adjust automatic-update maintenance windows.                                      |
| `managed_spec.overrides`          | Managed runner   | Tune the runner pod's tolerations, node selectors, and runtime class.             |
| `profile_bindings`                | Managed runner   | Replace the entire list of profile bindings for the runner.                       |
| `spec`                            | Profile template | Replace the whole profile spec.                                                   |
| `labels`                          | Profile template | Replace the label map.                                                            |

Supply the mask as a single comma-separated string:

```json theme={"system"}
{ "update_mask": "managed_spec.release_channel,managed_spec.maintenance_policy" }
```

The per-endpoint reference lists the mutable paths for each resource.

## Errors

Errors return an appropriate HTTP status and a `google.rpc.Status` body.

```json theme={"system"}
{
  "code":    3,
  "message": "runner.identity.zone is required",
  "details": []
}
```

The following table lists common mappings:

| HTTP | `code`                  | Meaning                                                                                            |
| ---- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| 400  | 3 (`INVALID_ARGUMENT`)  | Missing required field, malformed input, invalid spec.                                             |
| 401  | 16 (`UNAUTHENTICATED`)  | Missing or invalid API token.                                                                      |
| 403  | 7 (`PERMISSION_DENIED`) | Token lacks required permission for the action.                                                    |
| 404  | 5 (`NOT_FOUND`)         | Resource doesn't exist.                                                                            |
| 409  | 6 (`ALREADY_EXISTS`)    | Duplicate `displayName` or `runnerId`, or you tried to create a second runner on the same cluster. |
| 503  | 14 (`UNAVAILABLE`)      | Dependency (for example, cluster validation) temporarily unavailable. Safe to retry.               |
| 500  | 13 (`INTERNAL`)         | Unexpected server error. Retry with exponential backoff.                                           |

Validation messages are part of the stable surface area. You may surface them directly to end users.

## Idempotency

The control plane API has the following idempotency guarantees:

* `Delete*` endpoints are idempotent. Calling `DELETE` on an already-deleted resource returns `404` without side effects.
* `Create*` endpoints aren't idempotent. Supplying the same `runnerId` or `displayName` twice returns `409 Conflict`. To retry safely, use `GET` to check whether the resource already exists.
* `Update*` endpoints are safe to retry when you use a field mask and set only the fields you intend to change.

## Heartbeats

Runner heartbeats track runner liveness. When the control plane hasn't received a heartbeat within the liveness window, a runner's `connectionStatus` flips to `DISCONNECTED`. Expect up to 30 seconds of lag between the runner becoming unreachable and the control plane reflecting it. You can read both `connectionStatus` and the related `installStatus` field from a runner Get response.

## See also

* [Sandboxes architecture](/products/sandboxes/architecture): the four-resource taxonomy and how the gateway brokers runtime requests.
* [Understanding profiles](/products/sandboxes/profiles/profiles): the conceptual walkthrough of profiles, bindings, and overrides.
* [Configure a sandbox profile](/products/sandboxes/profiles/configure): CoreWeave Intelligent CLI workflow plus field-by-field walkthrough of the profile spec.
* [Deploy and manage a runner](/products/sandboxes/operations/managed-runners): CoreWeave Intelligent CLI and REST walkthrough of the runner lifecycle.
* [Profile reference](/products/sandboxes/reference/profile): every field you can set on a profile.