Skip to main content
DELETE
Delete a sandbox
Deletion permanently removes the sandbox and its local data. Save needed files first. HTTP 202 with status DELETING means the API accepted the request; deletion continues asynchronously. Related guide: Manage sandboxes.

Authorizations

Authorization
string
header
required

Send Authorization: Bearer <api_key>. The legacy Authorization: Api-Key <api_key> scheme is also accepted.

Headers

X-Team-Id
string

Optional team ID. Must match the team_id query parameter when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden.

Minimum string length: 1

Path Parameters

sandbox_name
string
required

Immutable sandbox name returned by creation.

Minimum string length: 1
Example:

"baseten-api-review-0916"

Query Parameters

team_id
string

Optional team ID. Must match X-Team-Id when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden.

Minimum string length: 1

Response

Request accepted.

Sandbox resource with configuration and server-managed fields at the root. No metadata, spec, or runtime wrapper.

name
string
required
read-only

Immutable sandbox name, provided by the client or generated by the server, used in sandbox_name path parameters.

Example:

"baseten-api-review-0916"

url
string<uri>
required
read-only

Base URL of this sandbox's execution API, always present on successful creation. The URL is assigned before deployment completes; inspect status for readiness. Use this exact returned URL; do not reconstruct its hostname. Authenticate requests with your authentication token using Authorization: Bearer . Do not send the Baseten API key directly. No additional routing headers are required. Fetch GET {url}/swagger/doc.json with that header for the API reference served by this sandbox. For example, POST {url}/process with Content-Type: application/json and {"command":"echo hello","waitForCompletion":true} executes a command and waits for its result. Execution API fields use camelCase, independently of this API's snake_case fields.

Example:

"https://sbx-baseten-api-review-0916-esb1qo.us-pdx-1.b10.run"

status
enum<string>
required

Sandbox deployment status.

Available options:
DEPLOYING,
DEPLOYED,
FAILED,
DEACTIVATING,
DEACTIVATED,
DELETING,
TERMINATED,
ARCHIVING,
ARCHIVED,
UNARCHIVING,
BUILDING,
UPLOADING
Example:

"DEPLOYED"

created_at
string<date-time>
required
read-only

Time the sandbox was created.

Example:

"2026-09-16T21:26:58.545765901Z"

lifecycle
object

Lifecycle configuration controlling automatic sandbox deletion based on idle time, max age, or specific dates

Example:
network
object

Network configuration for a sandbox including subnet, domain filtering, and proxy settings

Example:
region
string

Region where the sandbox runs (for example us-pdx-1 or eu-lon-1). When omitted at creation, the closest region is selected.

Example:

"us-pdx-1"

envs
object[]

Environment variables injected into the sandbox.

Example:
image
string

Image reference including its tag. Built-in image references are returned in the canonical baseten/ namespace. Use baseten/base-image:latest to get started with the built-in sandbox execution API. This image is available directly without building, pushing, or listing images through GET /v1/sandboxes/images.

Example:

"baseten/base-image:latest"

memory
integer

Memory allocation in megabytes. Also determines CPU allocation (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs).

Required range: x >= 1
Example:

4096

ports
object[]

Set of ports for a resource

Example:
external_id
string

Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash.

Maximum string length: 64
Pattern: ^[A-Za-z0-9-]+$
Example:

"api-review-20260916-001"

labels
object

Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.

Example:
updated_at
string<date-time>
read-only

Time the sandbox was last updated.

Example:

"2026-09-16T21:31:13Z"

created_by
string
read-only

User or service account that created the sandbox.

Example:

"sandbox-automation"

updated_by
string
read-only

User or service account that last updated the sandbox.

Example:

"sandbox-automation"

last_used_at
string<date-time>
read-only

Time the sandbox was last used.

Example:

"2026-09-16T21:31:13Z"

expires_in
integer
read-only

Seconds remaining before automatic deletion, when expiration is configured.

Required range: x >= 0
Example:

86400