Skip to main content
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.
Enterprise on-prem deployments may accept HTTP/1.1 depending on your load balancer configuration.

​
Authentication

All requests require an X-API-Key header. See Authentication for details.

​
Request Format

All request bodies must be JSON. Set the Content-Type: application/json header on every POST and PATCH request. 
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. 
{
  "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. 
{
  "message": "sandbox not found"
}

​
HTTP Status Codes

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

​
Resource IDs

All resource IDs use a short-prefix format:
ResourceFormatExample
Sandboxsbx- + 8 charssbx-a1b2c3d4
Snapshotsnap- + 8 charssnap-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:

Sandbox

Create, inspect, pause, snapshot, and kill sandbox VMs.

Command

Run commands synchronously or with streaming. Manage background processes.

Filesystem

Read, write, list, rename, and watch files inside a sandbox.