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

# REST API overview

> Authenticate and manage sandbox lifecycle over HTTP.

Use the REST API directly when the Python SDK is not a fit. All sandbox routes
are under:

```text theme={null}
https://api.thundercompute.com:8443/v1
```

## Authentication

Create an API token in the [Thunder console](https://console.thundercompute.com/settings/tokens)
and send it as a bearer token:

```http theme={null}
Authorization: Bearer <token>
```

Sandbox access is organization-scoped and must be enabled separately. A valid
token without access receives `sandbox_access_denied`.

<Warning>
  The playground sends real production requests. Starting a sandbox may incur
  usage charges; stop it when you finish.
</Warning>

## Lifecycle

1. `POST /sandboxes/start` accepts the request and returns a permanent `id`.
2. Poll `GET /sandboxes/{id}` until `status` is `running` or `failed`.
3. `POST /sandboxes/{id}/stop` stops the sandbox. Repeating a stop is safe.

Use the ID, not the optional name, in every later request. Start and stop return
`202 Accepted` because lifecycle work is asynchronous.

`GET /sandboxes` returns history newest first. The default page size is 50 and
the maximum is 100; pass `next_page_token` back as `page_token` to continue.

## Actionable errors

Every error contains an HTTP `code`, machine-readable `error`, and human-readable
`message`.

| Status                             | What to do                                                        |
| ---------------------------------- | ----------------------------------------------------------------- |
| `400 invalid_request`              | Correct the request or choose a supported resource configuration. |
| `403 sandbox_access_denied`        | Ask Thunder to enable sandboxes for the organization.             |
| `409 sandbox_name_in_use`          | Choose another name or stop the live sandbox using it.            |
| `429 rate_limit_exceeded`          | Wait for the `Retry-After` interval.                              |
| `503 sandbox_capacity_unavailable` | No requested GPU is free; retry later.                            |
| `503/504` with another code        | The request was not accepted; retry after the service recovers.   |

Start and stop allow 30 requests per organization per minute. Get and list
allow 600 per minute, enough for one-second status polling.