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

# HTTP API

> Complete REST API reference

The full interactive API reference is available in the [API Reference](/api-reference/sandboxes/create) tab.

## Base URL & Authentication

All API requests go through the control plane:

| Base URL                           | Auth Header        |
| ---------------------------------- | ------------------ |
| `https://app.opencomputer.dev/api` | `X-API-Key: <key>` |

The control plane handles sandbox lifecycle (create, list, kill, hibernate, wake) and transparently proxies data-plane requests (exec, files, agents, PTY) to the worker that owns the sandbox.

SDK users only need the API key.

## WebSocket Binary Protocol

Exec and PTY WebSocket sessions use binary frames with a 1-byte stream prefix:

| Byte   | Direction       | Meaning                             |
| ------ | --------------- | ----------------------------------- |
| `0x00` | Client → Server | stdin data                          |
| `0x01` | Server → Client | stdout data                         |
| `0x02` | Server → Client | stderr data                         |
| `0x03` | Server → Client | Exit code (4-byte big-endian int32) |
| `0x04` | Server → Client | Scrollback end marker               |

**Connection flow:**

1. Client opens WebSocket with `?api_key=<key>`
2. Server replays scrollback buffer (historical output)
3. Server sends `0x04` to mark end of scrollback
4. Live output streams as `0x01`/`0x02` frames
5. When the process exits, server sends `0x03` with the exit code
6. Server closes the connection

**Sending input:** Prefix your data with `0x00` and send as a binary frame.

**PTY sessions** use the same binary framing but without stream prefixes — raw bidirectional terminal data.

## Error Format

All errors use a consistent envelope:

```json theme={null}
{
  "error": "descriptive error message"
}
```

| Status Code | Meaning                                             |
| ----------- | --------------------------------------------------- |
| `400`       | Invalid request (missing fields, bad values)        |
| `401`       | Missing or invalid authentication                   |
| `403`       | Insufficient permissions                            |
| `404`       | Resource not found                                  |
| `409`       | Conflict (duplicate resource, e.g. checkpoint name) |
| `429`       | Quota exceeded                                      |
| `500`       | Internal server error                               |
| `503`       | Feature unavailable in current deployment mode      |