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

# HTTPS API

> Create and operate Sailboxes over plain HTTPS

Sailboxes have a public HTTPS API. The SDKs and the CLI are built on it, and
you can call it directly from any language, or from `curl`. Every endpoint is
listed under [Reference → Sailbox → HTTP API](https://docs.sailresearch.com/api-reference/lifecycle/create-a-sailbox.md).
This page covers what applies to all of them.

```text theme={null}
https://sailbox-api.sailresearch.com/v1
```

The apps endpoints are at `https://api.sailresearch.com/v1`. Your key works
on both.

## Authentication

Send your API key as a bearer token on every request. Create keys in the
[dashboard](https://app.sailresearch.com). A key belongs to one organization
and only ever sees that organization's Sailboxes.

```bash theme={null}
curl https://sailbox-api.sailresearch.com/v1/whoami \
  -H "Authorization: Bearer $SAIL_API_KEY"
```

```json theme={null}
{ "org_id": "org_1a2b3c", "user_id": "user_9z8y" }
```

`user_id` is the member the key belongs to, or `null` for a key that belongs to
the organization rather than a person. Compare it with a Sailbox's
`created_by_user_id` to tell your Sailboxes from a teammate's. A private
Sailbox can only be operated by the user whose key created it. An org admin
can override some operations by sending an `X-Sail-Owner-Override-Reason`
header, which is recorded in the audit log. See
[Access Control](https://docs.sailresearch.com/sailboxes-access-control).

### From inside a Sailbox

Code running inside a Sailbox can read that Sailbox, sleep it, reboot it,
schedule its wake, and manage its cron jobs without an API key. The SDKs do
this for you:
inside a Sailbox, a client built without an API key acts as the Sailbox
itself. See [guest identity](https://docs.sailresearch.com/sailbox-sdk.md#guest-identity).

To call the API directly, send the Sailbox's identity in two headers in place
of the bearer token: `X-Sail-Source-Sailbox-ID` with the id from the
`SAILBOX_ID` environment variable, and `X-Sail-Source-Sailbox-Auth` with the
Sailbox's auth token, which Sail sets in the Sailbox's environment.

```bash theme={null}
curl https://sailbox-api.sailresearch.com/v1/sailboxes/$SAILBOX_ID \
  -H "X-Sail-Source-Sailbox-ID: $SAILBOX_ID" \
  -H "X-Sail-Source-Sailbox-Auth: <the Sailbox's auth token>"
```

This credential belongs to one Sailbox and is accepted for that Sailbox only,
on these operations: retrieve, sleep, reboot, and schedule a wake. Every other
request made with it fails with a permission error, including any request
about a different Sailbox. It works for a private Sailbox too, and every
process inside the Sailbox holds it, so anything running there can put the
Sailbox to sleep or reboot it. The credential stops working once the Sailbox
is terminated or has failed.

From inside a Sailbox, manage cron jobs with the SDK or CLI, which identify
the calling user automatically.

A self-sleep needs care. The Sailbox usually suspends before the response
returns, so if the call returns an error you cannot tell whether the sleep
took effect. Do not send it again; check the Sailbox's state after it next
wakes instead.

A request that also carries an `Authorization` header is served with that
key's authority, and the identity headers are ignored.

## Example

Every Sailbox belongs to an app. Get an app id, then create a Sailbox in it:

```bash theme={null}
export SAIL_API_KEY="sk_..."

curl -X POST https://api.sailresearch.com/v1/apps/find \
  -H "Authorization: Bearer $SAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "batch-jobs", "mint_if_missing": true}'
```

```json theme={null}
{
  "id": "app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03",
  "name": "batch-jobs",
  "created_at": 1753027200
}
```

```bash theme={null}
curl -X POST https://sailbox-api.sailresearch.com/v1/sailboxes \
  -H "Authorization: Bearer $SAIL_API_KEY" \
  -H "Idempotency-Key: create-worker-1-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03",
    "name": "worker-1",
    "vcpu_count": 4,
    "image": { "base": "BASE_IMAGE_DEBIAN" }
  }'
```

```json theme={null}
{ "sailbox_id": "sb_9c8f1e2a-3b4d-4f5a-8c7e-1d2f3a4b5c6d", "status": "running" }
```

What to know about that create:

* **It blocks until the Sailbox is up**, which can take a few minutes while it
  waits for a machine.
* **Read `status`.** A create that is accepted and then cannot bring the
  machine up still returns 200, with `status` set to `failed` and
  `error_message` saying why.
* **The `Idempotency-Key` makes it safe to retry.** Send the same key and body
  again and you get the first answer back instead of a second Sailbox. Use a
  fresh key for every Sailbox you mean to create. See
  [Retrying safely](#retrying-safely).

Terminate it when you are done:

```bash theme={null}
curl -X POST https://sailbox-api.sailresearch.com/v1/sailboxes/$SAILBOX_ID/terminate \
  -H "Authorization: Bearer $SAIL_API_KEY"
```

## Run commands on a Sailbox

Send `command` as a shell string or an argument array. A string supports
`cwd` and `background`. With an array, the program runs directly.

```bash theme={null}
curl --no-buffer -X POST \
  "https://sailbox-api.sailresearch.com/v1/sailboxes/$SAILBOX_ID/exec" \
  -H "Authorization: Bearer $SAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":["sh","-c","printf output; printf error >&2"],"timeout":30}'
```

The response streams newline-delimited JSON. Output bytes are base64 so every
byte value is safe in JSON, and the last event includes the exit code:

```jsonl theme={null}
{"type":"started","exec_request_id":"exec_123"}
{"type":"stdout","data":"b3V0cHV0","seq":1}
{"type":"stderr","data":"ZXJyb3I=","seq":1}
{"type":"exit","status":"succeeded","return_code":0}
```

A `heartbeat` event arrives every 30 seconds while the command runs. If the connection drops
before `exit`, call `POST .../exec/$EXEC_ID/wait` with the id from the
`started` event to get the result and a bounded tail of the output. A failure
after `started` ends the stream with an `error` event whose `error_code` is a
lowercase category such as `unavailable` or `permission_denied`.

> [accordion] Standard input, clipboard, reconnects, and limits
>
> * To write standard input, set `open_stdin` or `pty` when you start the exec,
>   then `PUT .../exec/$EXEC_ID/stdin?offset=N&eof=true` with the raw bytes.
>   Writes include their byte offset, so an overlapping retry does not duplicate
>   input. The response reports `accepted_through`. For interactive sessions,
>   use the [stdin stream](#stream-standard-input).
> * To reconnect to a live exec, send the same `idempotency_key` with the
>   highest `seq` you received for stdout and stderr. Reconnect is best-effort
>   and does not guarantee exact replay. An exec id that does not fit a URL
>   segment goes in the `exec_request_id` query parameter with `-` in the path.
> * The idempotency key can be up to 256 KiB of UTF-8, trimmed. Environment
>   variable names match `[A-Za-z_][A-Za-z0-9_]*`, and names and values cannot
>   contain NUL. The encoded request body can be up to 25 MiB, and up to 4 MiB
>   after decoding.
> * The reference also lists cancel, PTY resize, and PTY resync.
> * `PUT .../clipboard` places the raw request body on the Sailbox's clipboard,
>   with `Content-Type` as its media type: `text/plain` or an `image/*` type.
>   Parameters such as `charset` are ignored, so send text as UTF-8. The body,
>   its media type, the Sailbox id, and a few bytes of framing together fit in
>   4 MiB, so a body only a little under 4 MiB may not. Clipboard writes do not
>   wake the Sailbox. A paused Sailbox answers 409, so resume it first. One that
>   is asleep, mid-transition, or still starting its clipboard answers 503, so
>   retry with backoff. A Sailbox whose image has no clipboard answers 501.

## Stream standard input

The stdin stream carries writes to one exec over a single WebSocket, instead
of one `PUT .../stdin` request per write. Use it for interactive sessions.

Start the exec with `open_stdin` or `pty`, then send
`GET .../exec/$EXEC_ID/stdin/stream` with the standard WebSocket upgrade
headers. A request refused before the upgrade gets the same JSON error a
`PUT .../stdin` would. A paused Sailbox answers `409`, so resume it first. The
exec itself is checked on the first write: one that has ended, or that was
started without `open_stdin` or `pty`, gets a `409` reply.

Send each write as one binary message. Unless you asked for the window
described below, wait for its reply before you send the next. A write sent
before the previous reply ends the stream:

| Bytes | Content |
| - | - |
| 0 to 7 | The write's byte offset, as a big-endian unsigned integer |
| 8 | Flags. The lowest bit means end of input. The other bits must be 0. |
| 9 onward | The bytes to write, which can be empty |

Offsets work the same way as on `PUT .../stdin`: an overlapping retry does not
duplicate input. Each write gets one text message in reply:

* `{"accepted_through":N}` when the write was applied. When `N` is lower than
  the end of your write, the Sailbox's input buffer is full. Resend the rest
  from offset `N` after a short wait.
* `{"status":S,"error":{...}}` when the write failed. `status` and `error` are
  the HTTP status and error body a `PUT .../stdin` would get. Sail then closes
  the stream with close code 1011. A failed write may still have been applied,
  so after a retryable error, open a new stream and resend the same bytes at
  the same offset.

### Keep several writes in flight

To send keystrokes without waiting on each reply, offer the `sail.stdin.v2`
subprotocol in the `Sec-WebSocket-Protocol` header when you open the stream.
When Sail selects it in the upgrade response:

* You can have up to 16 writes in flight at once, each carrying at most
  64 KiB. A 17th write in flight ends the stream.
* Every reply answers your earliest write that is not yet done. A reply short
  of that write's end means the Sailbox's input buffer was full: Sail keeps
  writing the rest itself and sends another `accepted_through` reply after
  each attempt, so there is nothing to resend. A reply at or past the write's
  end finishes it, and the next reply answers your next write, even one that
  ends at the same offset, such as an empty EOF write.
* A failed write closes the stream as described above. Open a new stream and
  resend, at the same offsets, every write that did not get a reply at or
  past its end.

> [accordion] Reopening, pings, and limits
>
> * A stream lasts at most 5 minutes. After that, the next write gets a `503`
>   with code `unavailable` and nothing is written. Open a new stream and resend
>   the same write.
> * If the Sailbox moves between machines, a later write on the stream fails
>   with an error. Open a new stream and resend from the last accepted offset.
> * Sail pings every 30 seconds and drops a stream that does not answer within
>   10 seconds. Keep reading the WebSocket while you are not writing, so your
>   WebSocket library can answer the pings.
> * A write carries at most 256 KiB of data, or 64 KiB under `sail.stdin.v2`.
>   A larger message ends the stream with close code 1009. A text message or a
>   malformed write gets a `400` reply and ends the stream.

## Move files

Files stream in both directions without being buffered whole.

```bash theme={null}
# Upload
curl -X PUT --data-binary @local.bin \
  "https://sailbox-api.sailresearch.com/v1/sailboxes/$SAILBOX_ID/files?path=/workspace/input.bin&mode=420" \
  -H "Authorization: Bearer $SAIL_API_KEY" \
  -H "Content-Type: application/octet-stream"

# Download
curl --fail-with-body \
  "https://sailbox-api.sailresearch.com/v1/sailboxes/$SAILBOX_ID/files?path=/workspace/input.bin" \
  -H "Authorization: Bearer $SAIL_API_KEY" \
  --output local.bin
```

`mode` is decimal, 0 through 511, and `create_parents` defaults to true. A
complete retry of an upload replaces the file safely. An interrupted one
leaves the target unconfirmed. A download's `X-Sail-File-Mode` header contains
the mode, and `Content-Length` may be absent, so read until the response
ends. For directories, run `mkdir`, `find`, `tar`, and `rm` through the
command endpoint, which is what the SDKs do.

## Share a file by URL

Mint a URL that serves one file without an API key, then hand it to a
browser, `curl`, or a CDN:

```bash theme={null}
curl -X POST \
  "https://sailbox-api.sailresearch.com/v1/sailboxes/$SAILBOX_ID/files/download-url" \
  -H "Authorization: Bearer $SAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/workspace/render.png", "expires_in_seconds": 3600}'
```

```json theme={null}
{
  "url": "https://sailbox-api.sailresearch.com/v1/sailboxes/sb_9c8f1e2a-3b4d-4f5a-8c7e-1d2f3a4b5c6d/files/download?expires=1767225600&path=%2Fworkspace%2Frender.png&sig=Yx3n4x1p9Q8b2Vf7K0mZcJtR6wLaHd5eGsUoNiA8PkE",
  "expires_at": "2026-01-01T00:00:00Z"
}
```

The URL authorizes reading that one file until `expires_at`, an hour by
default and up to seven days, and serves whatever the file holds when it is
fetched. `attachment: true` serves it as a download instead of inline, and
`immutable: true` marks it cacheable for a year, for a path you never
overwrite. Fetch it with no header at all:

```bash theme={null}
curl --fail-with-body "$URL" --output render.png
curl -I "$URL"                                        # headers only
curl -H "Range: bytes=1048576-" "$URL" --output rest  # resume from 1 MiB
```

`Content-Type` comes from the file's extension, `Content-Length` is its size,
`ETag` changes whenever the file is written or replaced, and `Last-Modified`
is its modification time.

* A byte range answers 206.
* `If-None-Match` answers 304 while the file is unchanged. A `Range` sent
  with `If-Range` gets the whole file instead when the file has changed, so
  a resume either continues the same version or starts over.
* An expired or altered URL answers 403. Expiry does not touch copies already
  downloaded or cached.
* A deleted file or a terminated Sailbox answers 404.
* A paused Sailbox answers 409 until it is resumed. A sleeping one is woken
  before the first byte.

[Share a file by URL](https://docs.sailresearch.com/sailboxes-filesystem#share-a-file-by-url) in the
filesystem guide covers caching and rewriting a file that has a live URL.

> [accordion] Serving images through Cloudflare
>
> Keep the API key and the mint call on your server; only the minted URL reaches
> a browser or Cloudflare.
>
> A Worker that takes the minted URL as `?url=` and returns a resized image:
>
> ```javascript theme={null}
> export default {
>   async fetch(request) {
>     const src = URL.parse(new URL(request.url).searchParams.get("url") ?? "");
>     if (
>       src?.host !== "sailbox-api.sailresearch.com" ||
>       Number(src.searchParams.get("expires")) * 1000 <= Date.now()
>     ) {
>       return new Response("forbidden", { status: 403 });
>     }
>     return fetch(src, { cf: { image: { width: 800, fit: "scale-down" } } });
>   },
> };
> ```
>
> * The host check keeps the Worker from resizing arbitrary URLs, and the
>   expiry check refuses an expired URL even when Cloudflare still holds a
>   resized copy. Sail checks the signature on every fetch, so the Worker adds
>   no authorization of its own and never holds your API key.
> * Do not set a `cacheKey` that drops the query, or a cached image would be
>   served to a request Sail would have refused. Cloudflare caches the resized
>   image under the full source URL, signature included, and follows the
>   source's caching rules with a one hour minimum. Mint the source URL with
>   `immutable` for a path you never overwrite so the resized copies stay
>   cached.
> * Give the source URL a lifetime that covers how long the page will reference
>   it. After it expires, the Worker answers 403.
> * Cloudflare must be allowed to fetch from `sailbox-api.sailresearch.com`:
>   enable transformations on your zone and add that host under Images >
>   Transformations > Sources.
>
> For video and other large files, return `fetch(src)` without the `cf.image`
> option and forward the client's `Range` header, or point the client straight
> at the minted URL.

## Connect to a port without publishing it

Publishing a port with a [listener](https://docs.sailresearch.com/sailboxes-networking.md) gives it a public
hostname that any client can reach, subject to the access controls you set. A
tunnel is for the other case: a server that should be private to you, such
as a database, a debugger, or a web app you are still working on. Nothing is
published. Your own connection is carried into the Sailbox over this API, with
the same key and TLS as every other call, and it ends when you close it.

Each tunnel forwards one TCP connection, so the natural use is a local port
forwarder, the way `ssh -L` works: listen on a port on your machine and, for
each connection you accept, open a tunnel and copy bytes both ways. Then
`psql -h localhost` or a browser at `http://localhost:3000` reaches the
Sailbox. The interactive shell in the SDKs and the CLI uses tunnels this way
to forward the Sailbox's local servers and browser opens to your machine.

To open a tunnel, send `GET .../tunnel?port=N` with the standard WebSocket
upgrade headers. The program must be listening on 127.0.0.1 or on all
interfaces. Sail authenticates the request, wakes a sleeping Sailbox, and
connects to the port before answering 101, so a failure in any of those steps
arrives as an ordinary JSON error. A paused Sailbox answers `409`, so resume it
first. A port with nothing listening is a `502` with code `unavailable` and the
connection error as its message. A `503` means Sail could not reach the
Sailbox, and retrying may succeed. Once the WebSocket is open, a failure ends it
with close code 1011 and a reason of the form `code: detail`. Close code 1000
means the program in the Sailbox closed the connection. A Sailbox whose
`guest_schema_version` is below 231 connects to the port only after answering
101, so a port with nothing listening there closes with code 1011 and that
same `unavailable` reason. Upgrading the Sailbox changes that for every tunnel
opened once the upgraded Sailbox is running.

> [accordion] Messages, half-close, and limits
>
> * Data in either direction is sent as binary messages. Messages you send are
>   limited to 1 MiB. A larger one ends the tunnel with close code 1009.
> * The text message `{"type":"eof"}` closes your direction while the program
>   in the Sailbox can keep sending, the way a TCP half-close does. When the
>   program finishes sending, Sail sends you that message, closes its connection
>   to the program, and ends the tunnel with close code 1000. A close frame ends
>   the tunnel.
> * Sail pings every 30 seconds and drops a connection that does not answer
>   within 10 seconds. The pings stop idle proxies from closing a tunnel that
>   has no traffic.
> * A tunnel to a program listening on all interfaces stays open when the
>   Sailbox moves between machines. Bytes sent during the move arrive once it
>   completes. A tunnel to a program listening only on 127.0.0.1 can instead end
>   with close code 1011 when the Sailbox moves, so reconnect when that happens.

## What needs an SDK

These tasks happen outside this API:

* **Building an image** with your own packages or files. Creating a Sailbox
  over HTTPS needs an image that is already built: a base image, or one an SDK
  built earlier from the same `image` block. Asking for an unbuilt image
  returns 409.
* **Turning on SSH** inside a Sailbox for the first time. After that the rest
  is HTTPS.

Everything else, from the whole lifecycle to ports, custom domains, secrets,
policies, metrics, and spend, is available over HTTPS. Volumes are in alpha,
so those endpoints can still change.

## Troubleshooting

Failures come back as an HTTP status and a JSON body with the same structure
every time:

```json theme={null}
{
  "error": {
    "message": "app_id is required",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}
```

Match on the status and `type`. `message` is for people and can change.

| Status | `type` | What to do |
| - | - | - |
| 400 | `invalid_request_error` | Fix the field it names. Custom-domain registration is the exception: it answers 400 until your DNS resolves. |
| 401 | `authentication_error` | The key is missing or invalid. |
| 402 | `billing_error` | Add credits, then retry. |
| 403 | `permission_error` | The key cannot do this, or the Sailbox is private and someone else's. |
| 404 | `not_found_error` | No such Sailbox, volume, or checkpoint in your organization. |
| 409 | `conflict_error` | Conflicts with current state. Some clear on their own, such as a volume a terminating Sailbox still mounts. |
| 413 | `invalid_request_error` | The body is too large. Most endpoints cap at 64 KiB. `POST /sailboxes` and `POST /apps/find` allow 256 MiB. |
| 429 | `rate_limit_error` | With `Retry-After`, the request never ran: wait and retry. Without it, the request ran and hit a limit. |
| 501 | `not_implemented_error` | The Sailbox cannot do this, such as a clipboard write to an image with no clipboard. Do it another way. |
| 500, 503, 504 | `server_error` | Retry with backoff. A proxy can also return a 502 or 504 with no body. Treat those the same. |

## Retrying safely

Every `POST` that creates or changes a Sailbox, a listener, or a volume takes an
`Idempotency-Key` header. Generate one key per logical operation, any unique
string up to 255 bytes, and send it on the first attempt and every retry. A
retry with the same key, method, path, and byte-identical body does not run
the request again. It gets the first response back, marked
`Idempotent-Replayed: true`.

> [accordion] The details
>
> * A key is remembered for at least 24 hours and is scoped to the API key that
>   sent it.
> * Sail remembers 400 and 409 answers too, so after fixing a request send it
>   under a fresh key. Reusing a key for a different request returns 409.
> * If the original is still running when the retry arrives, the retry waits
>   for it. After 30 seconds it gets a 504. Retry again with the same key.
> * A 500, 503, or 504 usually means nothing happened and the same key runs the
>   request again. Creating a Sailbox is the case to watch: the error can arrive
>   after the Sailbox exists, and a retry can leave you with two. List your
>   Sailboxes, then continue under a fresh key.
> * Terminating a terminated Sailbox, creating a volume that already exists, and
>   registering a domain the same way twice are safe without a key. Domain
>   registration ignores the header.

> [accordion] Listing, resume results, and unknown fields
>
> * `GET /sailboxes` pages with `limit` (up to 100) and `offset`. Stop when
>   `has_more` is false. `app`, `status`, `exclude_status`, `name`, and `search`
>   filter. `status` and `exclude_status` take a comma-separated list, and
>   `failed` covers every way a Sailbox can fail. A Sailbox is listed when it is
>   in one of the `status` values (any status, if you omit `status`) and in none
>   of the `exclude_status` values, and it must match every other filter you
>   pass. `name` matches the whole name
>   exactly. `manageable_by_caller=true` hides private
>   Sailboxes you cannot operate.
> * Resume returns 200 either way and reports `resume_state`: `running`,
>   `already_running`, or `terminal_unavailable`, in which case `error_message`
>   says why and you should create a new Sailbox.
> * `status` and `resume_state` are open sets and responses grow new fields.
>   Match the values you care about and ignore the rest.
> * For its first ten minutes a new organization is capped on requests in
>   flight. Going over the cap returns a 429 with `Retry-After`.
