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

# Sandbox REST API

> Base URL, authentication, and endpoint groups for the Prime sandbox API

The sandbox API creates and manages isolated microVM sandboxes. The [`prime` CLI](https://docs.primeintellect.ai/cli-reference/introduction) and the [`prime_sandboxes` Python SDK](https://docs.primeintellect.ai/sandboxes/sdk) call the same endpoints.

Base URL: `https://api.primeintellect.ai/api/v1/sandbox`

## Authentication

Send a Prime API key as a bearer token. The key needs the `sandbox` scope. Create or check a key in [API keys](https://docs.primeintellect.ai/api-reference/api-keys.md).

```bash theme={null}
curl https://api.primeintellect.ai/api/v1/sandbox \
  --header "Authorization: Bearer $PRIME_API_KEY"
```

Team scoping is per endpoint. `team_id` is a query parameter on list endpoints and on volume get, resize, and delete; create endpoints take it in the request body. Routes addressed by sandbox, checkpoint, or network ID take the team from the resource.

## Create and poll a sandbox

```bash theme={null}
curl --request POST https://api.primeintellect.ai/api/v1/sandbox \
  --header "Authorization: Bearer $PRIME_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name": "hello", "docker_image": "python:3.11-slim"}'
```

Creation is asynchronous. The response contains the sandbox `id` and an initial status. Poll `GET /api/v1/sandbox/{sandbox_id}` until the status is `RUNNING`, or use `POST /api/v1/sandbox/status:batchGet` for several sandboxes at once.

## Endpoint groups

| Group | Covers |
| - | - |
| Sandbox | Create, list, inspect, pause, resume, and delete sandboxes. Fetch logs and error context, issue access tokens and SSH sessions, and read or replace an egress policy. |
| Sandbox Checkpoints | Save a sandbox filesystem, list and delete checkpoints, and restore or fork from one. |
| Sandbox Volumes | Create and resize named volumes, attach one when creating a sandbox, and publish or sync a sandbox's writes. |
| Sandbox Networks | Create private networks, add sandbox members, and set per-port reachability rules. |

Batch lookups use `POST` endpoints with a colon suffix, such as `/status:batchGet` and `/checkpoints:batchGet`. Send the IDs in the JSON body.

## Errors

HTTP errors return `{"detail": "<message>"}`. Validation errors return an `errors` array; each item has `param` and `details` string fields.

| Status | Meaning |
| - | - |
| 401 | Missing, invalid, disabled, or expired API key; missing `sandbox` scope. |
| 402 | Insufficient balance to create or resume a sandbox. |
| 403 | The key lacks access to the sandbox or resource. |
| 404 | Sandbox, checkpoint, volume, or network not found or not accessible. |
| 409 | Conflicting sandbox or checkpoint state. |
| 410 | The request uses a retired behavior. |
| 422 | Request validation failed. |
| 429 | Rate limit exceeded. |
| 500 | Internal server error. |
| 503 | Service temporarily unavailable or at capacity. |

Not every endpoint returns every code. The endpoint reference lists each operation's success and validation responses.

## Related guides

> [card] [Lifecycle](https://docs.primeintellect.ai/sandboxes/lifecycle.md)
>
> Resources, timeouts, labels, and deletion

> [card] [Pause and resume](https://docs.primeintellect.ai/sandboxes/pause-resume.md)
>
> Keep memory and disk in place between runs

> [card] [Checkpoints](https://docs.primeintellect.ai/sandboxes/checkpoints.md)
>
> Save, restore, and fork a sandbox

> [card] [Volumes](https://docs.primeintellect.ai/sandboxes/volumes.md)
>
> Persistent storage and publishing

> [card] [Network isolation](https://docs.primeintellect.ai/sandboxes/network-isolation.md)
>
> Allow or deny outbound traffic

> [card] [Private networks](https://docs.primeintellect.ai/sandboxes/networks.md)
>
> Sandbox-to-sandbox connectivity and public ports
