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 Create 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: register runners, create profiles, attach bindings, and query state. It is 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, backwards-compatible changes ship within v1beta2; breaking changes ship behind a new version prefix and are announced 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; permissions are enforced on every request server-side. 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 the token is stored 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 is served over HTTP/2 through connectrpc, but standard curl or fetch-style clients work transparently. No gRPC client is required.

​
Resource families

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 are not independently addressable. They are mutated through a runner update with a profile_bindings field mask. See Manage profile bindings for the cwic workflow and the binding-update semantics (the list is replaced as a whole on each update, 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 is the on-wire resource name. Throughout the documentation, “profile” and “profile template” refer to the same thing.

​
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 cwic CLI auto-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. 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 does not exist.
4096 (ALREADY_EXISTS)Duplicate displayName or runnerId, or attempted 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 are not 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. A runner’s connectionStatus flips to DISCONNECTED when the control plane hasn’t received a heartbeat within the liveness window. Expect up to 30 seconds of lag between the runner becoming unreachable and the control plane reflecting it. connectionStatus and the related installStatus field are both readable from a runner Get response.

​
See also

  • Configure a sandbox profile: cwic workflow plus field-by-field walkthrough of the profile spec.
  • Create and manage a runner: cwic and REST walkthrough of the runner lifecycle (page pending merge).
  • Profile reference: every field you can set on a profile.
Last modified on May 14, 2026