> ## 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 the policy each one carries. This page covers the cross-cutting behavior (authentication, versioning, error shapes, and pagination) that applies to every endpoint.

For the schema of every field in a policy, see the [Policy reference](/products/sandboxes/reference/profile). For task-oriented walkthroughs that use these endpoints, see [Configure a sandbox policy](/products/sandboxes/profiles/configure) and [Deploy and manage a runner](/products/sandboxes/operations/managed-runners).

## Base URL and versioning

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

This is the control plane base URL. It hosts the runner endpoints documented on this page: deploy runners, set the policy each one carries, 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 `v1`. Additive, backward-compatible changes ship within `v1`. Breaking changes ship behind a new version prefix, and CoreWeave announces them before release.

An earlier `v1beta2` surface remains available and is where profile templates and profile bindings live. They are superseded by policy and are not being added to `v1`. New integrations should target `v1`.

## Authentication

All requests use bearer-token authentication over TLS. Replace `[API-ACCESS-TOKEN]` with a CoreWeave API access token:

```text theme={"system"}
Authorization: Bearer [API-ACCESS-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. Two IAM actions apply to CoreWeave Sandbox:

* `SANDBOX_ADMIN`: create, read, update, and delete runners, and set the policy they carry. Every endpoint documented on this page requires it, including reads. Implies `SANDBOX_USER`.
* `SANDBOX_USER`: create and operate sandboxes. It doesn't grant access to any endpoint on this page.

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 policy](/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. For the published Protobuf definitions behind these endpoints and the generated SDKs built from them, see [Protobuf](/products/sandboxes/reference/protos).

## Resource families

The control plane exposes managed runners as its administrative resource:

| Family | Base path | Operations |
| - | - | - |
| Managed runners | `/v1/sandbox/managedRunners` | Create, Get, List, Update, Delete, `:applyAvailableUpdate` |

A policy is not independently addressable. It is a field on the runner, so you read it by fetching the runner and write it with a runner update masked to `policy`. Each write replaces the whole document. For the workflow, see [Configure a sandbox policy](/products/sandboxes/profiles/configure).

Profile templates remain available on the `v1beta2` surface at `/v1beta2/sandbox/profile-templates`, together with the `profile_bindings` field on a runner. They are superseded by policy, are not part of the `v1` model, and will not be added to it.

For the conceptual model 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/v1/sandbox/managedRunners?pageSize=50'

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

The CoreWeave Intelligent CLI automatically paginates list commands such as `cwic sandbox runner 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 |
| - | - | - |
| `spec.release_channel` | Managed runner | Switch the release channel (`RELEASE_CHANNEL_STABLE` or `RELEASE_CHANNEL_RAPID`). |
| `spec.maintenance_policy` | Managed runner | Adjust automatic-update maintenance windows. |
| `spec.overrides` | Managed runner | Tune the runner pod's tolerations, node selectors, and runtime class. |
| `spec.enforce_resource_limits` | Managed runner | Require sandboxes on the runner to declare CPU and memory limits. |
| `policy` | Managed runner | Replace the whole policy document. The only mask path implemented for policy. |
| `profile_bindings` | Managed runner | Replace the entire list of profile bindings. Legacy, `v1beta2` only; rejected by `v1` writes. |

On the REST surface, supply the mask as a single comma-separated `updateMask` query parameter, using the JSON (camelCase) form of each path, and send the resource itself as the request body with no wrapper:

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

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.
* [Policies overview](/products/sandboxes/profiles/profiles): how a sandbox resolves against a policy.
* [Configure a sandbox policy](/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.
* [Policy reference](/products/sandboxes/reference/profile): every field you can set on a profile.
* [Protobuf](/products/sandboxes/reference/protos): where to find the published Protobuf module, which host serves each service, and how to install a generated SDK.