API overview - CoreWeave Docs

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. For task-oriented walkthroughs that use these endpoints, see Configure a sandbox policy and Deploy and manage a runner.

CoreWeave sandboxes are in public preview. For access, contact your CoreWeave account team, CoreWeave Support, or email support@coreweave.com.

Base URL and versioning

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 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:

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 set the policy they carry. Implies SANDBOX_USER.
SANDBOX_USER: read runners 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 policy 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 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. 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. 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/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
`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.
`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.

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:

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.

​Base URL and versioning

​Authentication

​Content type

​Resource families

​Pagination

​Field masks on updates

​Errors

​Idempotency

​Heartbeats

​See also

Base URL and versioning

Authentication

Content type

Resource families

Pagination

Field masks on updates

Errors

Idempotency

Heartbeats

See also