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

# API Overview

> Conventions, base URL, request/response format, and error handling for the Declaw REST API.

The Declaw API is a JSON REST API that lets you create and manage isolated
sandboxes, run commands inside them, and interact with their filesystems.

## Base URL

```
https://api.declaw.ai
```

Enterprise on-prem customers use the domain issued during provisioning in place of `api.declaw.ai`.

## Protocol

Declaw Cloud (`api.declaw.ai`) requires **HTTP/2**. Clients that connect with HTTP/1.1 will receive a `464` status code from the load balancer. All official SDKs (Python, TypeScript, Go) and the CLI handle this automatically — no configuration needed.

If you are calling the API directly (without an SDK), ensure your HTTP client supports HTTP/2. For example, `curl` must be invoked with `--http2`, and Python's `httpx` must be initialized with `http2=True`.

<Note>Enterprise on-prem deployments may accept HTTP/1.1 depending on your load balancer configuration.</Note>

## Authentication

All requests require an `X-API-Key` header. See [Authentication](/api-reference/authentication)
for details.

## Request Format

All request bodies must be JSON. Set the `Content-Type: application/json` header on
every `POST` and `PATCH` request.

```http theme={null}
POST /sandboxes
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
  "template": "base",
  "timeout": 300
}
```

Request bodies larger than **10 MiB** are rejected with `413 Request Entity Too Large`. The binary streaming endpoint (`/files/raw`) has a higher limit of **500 MiB** to support large file transfers.

## Response Format

All responses are JSON. Successful responses return the resource object or an
operation result directly at the top level. There is no top-level `data` wrapper.

```json theme={null}
{
  "sandbox_id": "sbx-a1b2c3d4",
  "state": "running",
  "started_at": "2024-01-15T10:30:00Z"
}
```

## Error Format

Errors return a JSON object with a single `message` field explaining the problem.

```json theme={null}
{
  "message": "sandbox not found"
}
```

### HTTP Status Codes

| Code  | Meaning                                                         |
| ----- | --------------------------------------------------------------- |
| `200` | Success                                                         |
| `201` | Resource created                                                |
| `400` | Invalid request — check the `message` field                     |
| `401` | Missing or invalid API key                                      |
| `404` | Resource not found                                              |
| `410` | Sandbox has been killed                                         |
| `464` | HTTP/1.1 client — upgrade to HTTP/2 (see [Protocol](#protocol)) |
| `500` | Internal server error                                           |
| `502` | The in-VM envd daemon is unreachable                            |
| `503` | Orchestrator unavailable (VM could not be created)              |

## Resource IDs

All resource IDs use a short-prefix format:

| Resource | Format            | Example         |
| -------- | ----------------- | --------------- |
| Sandbox  | `sbx-` + 8 chars  | `sbx-a1b2c3d4`  |
| Snapshot | `snap-` + 8 chars | `snap-a1b2c3d4` |

## Pagination

The `GET /sandboxes` endpoint returns a `next_token` field alongside the
`sandboxes` array. A `null` value means there are no further pages. Future
endpoints that return large lists will follow the same cursor-based pagination
pattern.

## Timestamps

All timestamps are returned in ISO 8601 format in UTC, for example:
`2024-01-15T10:30:00Z`.

## Path Parameters

Path parameters use snake\_case, for example:

```
GET /sandboxes/{sandbox_id}/commands/{pid}/wait
```

## API Groups

The API is organized into three resource groups:

<CardGroup cols={3}>
  <Card title="Sandbox" icon="box" href="/api-reference/sandbox/create">
    Create, inspect, pause, snapshot, and kill sandbox VMs.
  </Card>

  <Card title="Command" icon="terminal" href="/api-reference/command/run">
    Run commands synchronously or with streaming. Manage background processes.
  </Card>

  <Card title="Filesystem" icon="folder" href="/api-reference/filesystem/read">
    Read, write, list, rename, and watch files inside a sandbox.
  </Card>
</CardGroup>