> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes API reference

> Manage sandbox instances and images with the Baseten Management API, including authentication, teams, and pagination.

<Note>
  Sandboxes is in **Private Preview**. [Contact Baseten](mailto:support@baseten.co)
  to request access.
</Note>

Create, inspect, update, and delete sandbox instances and images over HTTP at
the base URL `https://api.baseten.co`.

For a complete resource workflow, follow
[Manage sandboxes](/sandboxes/manage).

## Authentication and teams

Authenticate sandbox and image requests with a short-lived
[sandbox access token](/sandboxes/authentication) as a bearer token, not your
Baseten API key. Create the token with your API key through the
[access token operation](/reference/management-api/sandboxes/create-a-sandbox-access-token).
Select the team that owns the resource with the `X-Team-Id` header:

```http theme={"system"}
Authorization: Bearer <SANDBOX_TOKEN>
X-Team-Id: <TEAM_ID>
```

<ParamField header="X-Team-Id" type="string">
  Team ID for the request. You can also select a team with the `team_id` query
  parameter. If you send both selectors, their values must match. When you omit
  both, the API uses your only accessible team. If you can access
  multiple teams, select one explicitly. The API rejects requests without access
  to a team.
</ParamField>

Sandbox management requests use the API base URL. A sandbox's MCP server, at
its returned `url` followed by `/mcp`, uses the same token.

## Pagination

List operations return an `items` array and a `pagination` object.

<ParamField query="limit" type="integer" default="20">
  Maximum number of items to return, from 1 to 100.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor from the previous page. Omit it for the first request.
</ParamField>

When `pagination.has_more` is `true`, pass `pagination.cursor` as the next
request's `cursor` query parameter. Keep the same team, filters, and sort order
while paging. Stop when `has_more` is `false`.

## Deployment and deletion

Creating a sandbox returns HTTP `201` once the sandbox is ready, with status
`DEPLOYED`.

Deleting a sandbox returns HTTP `202` with status `DELETING`. Baseten deletes the
sandbox and its local data asynchronously. Stop sending work after requesting
deletion. See the [lifecycle guide](/sandboxes/lifecycle) for deployment statuses
and expiration.

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/v1/sandboxes/configuration`](/reference/management-api/sandboxes/get-sandbox-configuration) | Gets the regions where you can create a sandbox. |
| `GET` | [`/v1/sandboxes/instances`](/reference/management-api/sandboxes/list-sandboxes) | Lists a page of sandboxes. |
| `GET` | [`/v1/sandboxes/instances/{sandbox_name}`](/reference/management-api/sandboxes/get-a-sandbox) | Gets a sandbox by name. |
| `GET` | [`/v1/sandboxes/instances/{sandbox_name}/logs`](/reference/management-api/sandboxes/get-sandbox-logs) | Gets a sandbox's runtime logs. |
| `GET` | [`/v1/sandboxes/instances/{sandbox_name}/metrics`](/reference/management-api/sandboxes/get-sandbox-metrics) | Gets a sandbox's metrics over time. |
| `GET` | [`/v1/sandboxes/library_images`](/reference/management-api/sandboxes/list-built-in-sandbox-images) | Lists the built-in sandbox images. |
| `GET` | [`/v1/sandboxes/images`](/reference/management-api/sandboxes/list-sandbox-images) | Lists a page of sandbox images. |
| `GET` | [`/v1/sandboxes/images/{image_name}`](/reference/management-api/sandboxes/get-a-sandbox-image) | Gets a sandbox image and its processing status. |
| `GET` | [`/v1/sandboxes/images/{image_name}/logs`](/reference/management-api/sandboxes/get-image-build-logs) | Gets logs from an image's latest build. |
| `GET` | [`/v1/sandboxes/images/{image_name}/tags`](/reference/management-api/sandboxes/list-image-tags) | Lists a page of tags for a sandbox image. |
| `POST` | [`/v1/token`](/reference/management-api/sandboxes/create-a-sandbox-access-token) | Creates a token for accessing a sandbox. |
| `POST` | [`/v1/sandboxes/instances`](/reference/management-api/sandboxes/create-a-sandbox) | Creates a sandbox from an image. |
| `PATCH` | [`/v1/sandboxes/instances/{sandbox_name}`](/reference/management-api/sandboxes/update-a-sandbox) | Updates the configuration of a sandbox. |
| `DELETE` | [`/v1/sandboxes/instances/{sandbox_name}`](/reference/management-api/sandboxes/delete-a-sandbox) | Deletes a sandbox and its local data. |
| `POST` | [`/v1/sandboxes/images`](/reference/management-api/sandboxes/push-a-sandbox-image) | Imports a sandbox image or starts an image build. |
| `DELETE` | [`/v1/sandboxes/images/{image_name}/tags/{tag_name}`](/reference/management-api/sandboxes/delete-an-image-tag) | Deletes a version of a sandbox image. |
| `DELETE` | [`/v1/sandboxes/images/{image_name}`](/reference/management-api/sandboxes/delete-a-sandbox-image) | Deletes a sandbox image and its tags. |
| `POST` | [`/v1/sandboxes/cleanup_images`](/reference/management-api/sandboxes/clean-up-unused-images) | Removes unused image versions. |