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

# HTTP API overview

> Base URL, auth, and a complete session in raw curl.

Base URL defaults to `http://127.0.0.1:7777`. Every route except `/healthz` and `/metrics` requires `Authorization: Bearer <token>` when `SANDKILN_AUTH_TOKEN` is set — see [Auth](/concepts/auth).

## A complete session, in raw HTTP

```bash theme={null}
TOKEN=...
BASE=http://127.0.0.1:7777

# Create, named so it can be found again by name later.
curl -s -X POST "$BASE/sandboxes" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"build-worker","tags":{"env":"ci"},"vcpu_count":2,"mem_size_mib":1024}'
# {"id":"..."}

curl -s -X POST "$BASE/sandboxes/build-worker/exec" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"command":"npm","args":["test"]}'
# {"stdout":"...","stderr":"","exit_code":0}
```

Every id above is written as `build-worker` for readability — the real
`id` a create call actually returns is an opaque UUID; resolve a name
back to its live id first with `GET /sandboxes/by-name/build-worker`
if you only have the name (see [Named sandboxes](/concepts/named-sandboxes)).

```bash theme={null}
# Stop it -- preserves state as a snapshot by default.
curl -s -X DELETE "$BASE/sandboxes/build-worker" -H "Authorization: Bearer $TOKEN"
# {"kept":true,"snapshot_id":"..."}

# Tomorrow: resolve the same name back to a live sandbox in one call,
# resuming the snapshot above automatically.
curl -s -X POST "$BASE/sandboxes/get-or-create" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"build-worker"}'
# {"id":"...","created":false}
```

See [Sandboxes](/api-reference/http-api/sandboxes), [Drives](/api-reference/http-api/drives), [Images](/api-reference/http-api/images), and [Pools](/api-reference/http-api/pools) for the full route tables.

## Operational

| Route | What it does |
| - | - |
| `GET /healthz` | Unauthenticated. Returns `ok`. |
| `GET /metrics` | Unauthenticated. Prometheus text-exposition format. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.