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

# API reference (beta)

> The Coreload sandbox API: create short-lived sandboxes, run commands in them and move files in and out. In beta; how a call works.

The sandbox API creates short-lived sandboxes, runs commands in them and moves files in and out. It is in beta, and it
is not offered to outside callers yet.

## How a call works

A call takes two steps:

1. Ask the edge for a ticket to a box, with an API key as a bearer token. The ticket holds the box's address (`url`),
   the name its certificate carries (`servername`), the certificate authority that signs it (`servingCa`) and the
   `authorization` header to send it.
2. Call the box at that address with that header, as it is, until the ticket expires (within a minute). Connect by the
   ticket's name, not the address, and trust only the ticket's certificate authority. Ask for a new ticket after that.

With `curl` and `jq`:

```sh theme={null}
# 1. A ticket for the box.
TICKET=$(curl -sf -X POST "$EDGE_URL/v1/tickets" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"box": "box-1"}')
field() { printf '%s' "$TICKET" | jq -r ".$*"; }

# 2. A sandbox on that box, answered once it is ready: the box's name resolved to the ticket's address.
field servingCa > serving-ca.pem
ADDR=$(field url)
ADDR=${ADDR#*//}
NAME=$(field servername)
curl -sf --proto-default https --cacert serving-ca.pem --resolve "$NAME:${ADDR##*:}:${ADDR%:*}" \
  -X POST "$NAME:${ADDR##*:}/v1/sandboxes" \
  -H "Authorization: $(field authorization)" \
  -d '{"image": "busybox", "ttlMs": 600000, "waitMs": 60000}'
```

## Answers and errors

Answers are JSON, except a file download (the file's bytes) and a tunnel (an HTTP upgrade). An error is JSON too, with
a code and a message, except the relay tunnel's refusals, which have a status and an empty body:

```json theme={null}
{"ok": false, "error": {"code": "not_found", "message": "no such sandbox"}}
```

Each route in the reference lists its notable errors, and any route may answer any code in the error table.

A sandbox belongs to the caller that made it: another caller's sandbox answers as an unknown one.


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