Skip to main content

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.

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. For task-oriented walkthroughs that use these endpoints, see Configure a sandbox profile and Deploy and manage a runner.
CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, reach out to CoreWeave Support, or email support@coreweave.com.

​
Base URL and versioning

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 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: 
Authorization: Bearer [COREWEAVE-API-TOKEN]
Generate an API access token from the 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 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) and Manage Access Policies. For more on tokens, see Manage API Access Tokens. Unauthenticated requests return 401 Unauthenticated with a google.rpc.Status-shaped body. The CoreWeave Intelligent CLI (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 for the CLI workflow.

​
Content type

All request and response bodies are JSON: 
Content-Type: application/json
The API runs over HTTP/2 through connectrpc, 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:
FamilyBase pathOperations
Managed runners/v1beta2/sandbox/managed-runnersCreate, Get, List, Update, Delete, apply-update
Profile templates/v1beta2/sandbox/profile-templatesCreate, 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. 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. 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.
Paginate managed runners
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:
PathApplies toPurpose
managed_spec.release_channelManaged runnerSwitch the release channel (RELEASE_CHANNEL_STABLE or RELEASE_CHANNEL_RAPID).
managed_spec.maintenance_policyManaged runnerAdjust automatic-update maintenance windows.
managed_spec.overridesManaged runnerTune the runner pod’s tolerations, node selectors, and runtime class.
profile_bindingsManaged runnerReplace the entire list of profile bindings for the runner.
specProfile templateReplace the whole profile spec.
labelsProfile templateReplace the label map.
Supply the mask as a single comma-separated string: 
{ "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. 
{
  "code":    3,
  "message": "runner.identity.zone is required",
  "details": []
}
The following table lists common mappings:
HTTPcodeMeaning
4003 (INVALID_ARGUMENT)Missing required field, malformed input, invalid spec.
40116 (UNAUTHENTICATED)Missing or invalid API token.
4037 (PERMISSION_DENIED)Token lacks required permission for the action.
4045 (NOT_FOUND)Resource doesn’t exist.
4096 (ALREADY_EXISTS)Duplicate displayName or runnerId, or you tried to create a second runner on the same cluster.
50314 (UNAVAILABLE)Dependency (for example, cluster validation) temporarily unavailable. Safe to retry.
50013 (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

Last modified on May 29, 2026