Skip to main content
The Declaw API is a JSON REST API that lets you create and manage isolated Firecracker microVM 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.

​
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 100 MB are rejected with 413 Request Entity Too Large.

​
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
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.