HTTP API reference

Generated from api/openapi.yaml (OpenAPI 3.1.0, API v1). A running server also serves the contract at /openapi.yaml.

One vendor-neutral API for isolated compute environments on infrastructure you own, with optional, policy-gated use of external providers.

Authenticate with Authorization: Bearer dly_<id>_<secret>.
Errors use {"error": {"code", "message", "details", "requestId"}}. Branch on code.
Lists return {"items": [...], "nextCursor": "..."}.
Backends are never named by applications: placement is decided by operator, organization and project policies, which a request can only narrow.

Sandboxes

List sandboxes (newest first)

GET /v1/sandboxes

Parameter	In	Type	Description
`status`	query	`string`	Comma-separated statuses
`projectId`	query	`string`
`pool`	query	`string`
`label`	query	`string`	key=value; repeatable
`cursor`	query	`string`
`limit`	query	`integer`

Status	Response
200	Page — `SandboxList`

Create a sandbox

POST /v1/sandboxes

Admits the request against quota and queues it (202). The scheduler places it on an eligible pool. Returns 422 immediately when no permitted pool could ever satisfy it (no_eligible_pool, unsupported_capability). Requires sandboxes:write.

Parameter	In	Type	Description
`Idempotency-Key`	header	`string`	Replaying the same key within a project returns the live sandbox it created (200). Once that sandbox is terminated or failed, the key creates a new one.

Request body (application/json): CreateSandboxRequest

Status	Response
200	Idempotent replay — `Sandbox`
202	Queued — `Sandbox`
422	Structured error — `ErrorEnvelope`
429	Structured error — `ErrorEnvelope`

Get a sandbox

GET /v1/sandboxes/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Sandbox — `Sandbox`
404	Structured error — `ErrorEnvelope`

Update labels or TTL

PATCH /v1/sandboxes/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Request body (application/json): UpdateSandboxRequest

Status	Response
200	Updated — `Sandbox`

Delete (terminate) a sandbox

DELETE /v1/sandboxes/{id}

Idempotent. Queued sandboxes terminate immediately; others move to terminating.

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
202	Terminating — `Sandbox`

Long-poll until a status is reached

GET /v1/sandboxes/{id}/wait

Parameter	In	Type	Description
`id` *	path	`string`
`status`	query	`SandboxStatus`	Defaults to running
`timeoutSeconds`	query	`integer`

Status	Response
200	Current sandbox (check status) — `Sandbox`

Explain where the sandbox runs and why

GET /v1/sandboxes/{id}/placement

Includes every pool evaluated with reasons. For queued sandboxes, current is a fresh dry-run decision.

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Explanation — `PlacementExplanation`

Exec and files

Run a command

POST /v1/sandboxes/{id}/exec

Requires sandboxes:exec and a running sandbox. With ?stream=1 (or Accept: text/event-stream) the response is server-sent events named stdout, stderr, exit and error, each carrying an ExecEvent as JSON data.

Parameter	In	Type	Description
`id` *	path	`string`
`stream`	query	`string`

Request body (application/json): ExecRequest

Status	Response
200	Result, or an event stream — `ExecResult`
409	Structured error — `ErrorEnvelope`

List a directory

GET /v1/sandboxes/{id}/files

Parameter	In	Type	Description
`id` *	path	`string`
`path` *	query	`string`

Status	Response
200	Entries — `FileList`
501	Structured error — `ErrorEnvelope`

Download a file

GET /v1/sandboxes/{id}/files/content

Parameter	In	Type	Description
`id` *	path	`string`
`path` *	query	`string`

Status	Response
200	File bytes — `string (binary)`

Upload a file (max 100 MiB), creating parent directories

PUT /v1/sandboxes/{id}/files/content

Parameter	In	Type	Description
`id` *	path	`string`
`path` *	query	`string`

Request body (application/octet-stream): string (binary)

Status	Response
204	Written

Lifecycle

Stop (keep disk

POST /v1/sandboxes/{id}/stop

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Sandbox — `Sandbox`
501	Structured error — `ErrorEnvelope`

Start a stopped sandbox from its disk

POST /v1/sandboxes/{id}/start

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Sandbox — `Sandbox`
501	Structured error — `ErrorEnvelope`

Pause (freeze vCPUs; memory stays resident)

POST /v1/sandboxes/{id}/pause

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Sandbox — `Sandbox`
501	Structured error — `ErrorEnvelope`

Resume a paused sandbox. On a full pool whose pause released the slot, the resume is queued: 202 with the sandbox still paused; wait for running

POST /v1/sandboxes/{id}/resume

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Sandbox — `Sandbox`
202	Sandbox — `Sandbox`
501	Structured error — `ErrorEnvelope`

Snapshot a sandbox

POST /v1/sandboxes/{id}/snapshots

Snapshots live on the pool that took them; restoring is only possible there.

Parameter	In	Type	Description
`id` *	path	`string`

Request body (application/json): CreateSnapshotRequest

Status	Response
201	Snapshot — `Snapshot`
501	Structured error — `ErrorEnvelope`

Snapshot and start a copy on the same pool

POST /v1/sandboxes/{id}/fork

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
202	Queued child — `Sandbox`

Expose a service port (backend-dependent)

POST /v1/sandboxes/{id}/ports

Parameter	In	Type	Description
`id` *	path	`string`

Request body (application/json): object

Status	Response
200	URL — `PortURL`
501	Structured error — `ErrorEnvelope`

Record activity so idle auto-stop leaves the sandbox running; wakes an idled sandbox

POST /v1/sandboxes/{id}/keepalive

Exec, file and port calls already count as activity. Call this when the sandbox is in use in ways the control plane does not see, such as a desktop viewer connected to a port URL.

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	The sandbox — `Sandbox`
409	Structured error — `ErrorEnvelope`

List snapshots

GET /v1/snapshots

Status	Response
200	Snapshots — `object`

Get a snapshot

GET /v1/snapshots/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Snapshot — `Snapshot`

Delete a snapshot

DELETE /v1/snapshots/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
204	Deleted

Tenancy

Describe the calling key

GET /v1/me

Status	Response
200	Caller — `Me`

List projects

GET /v1/projects

Status	Response
200	Projects — `object`

Create a project (projects:write)

POST /v1/projects

Request body (application/json): object

Status	Response
201	Project — `Project`

Get a project

GET /v1/projects/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Project — `Project`

Delete an empty project

DELETE /v1/projects/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
204	Deleted
409	Structured error — `ErrorEnvelope`

List keys (keys:write)

GET /v1/api-keys

Status	Response
200	Keys — `object`

Create a scoped key

POST /v1/api-keys

A key can only grant scopes it holds, within its own organization and project. The token is returned once.

Request body (application/json): CreateAPIKeyRequest

Status	Response
201	Key and one-time token — `CreateAPIKeyResponse`
403	Structured error — `ErrorEnvelope`

Get a key (keys:write)

GET /v1/api-keys/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Key — `APIKey`
404	Structured error — `ErrorEnvelope`

Revoke a key

DELETE /v1/api-keys/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
204	Revoked

Rotate a key

POST /v1/api-keys/{id}/rotate

Issues a replacement with the same name, scopes, organization, project and lifetime, and returns its token once. The old key stays valid for graceSeconds (at most a week), or is revoked at once. The caller must be able to grant every scope the key holds.

Parameter	In	Type	Description
`id` *	path	`string`

Request body (application/json): RotateAPIKeyRequest

Status	Response
201	Replacement and one-time token — `CreateAPIKeyResponse`
403	Structured error — `ErrorEnvelope`
409	Structured error — `ErrorEnvelope`

Policy

List visible placement policies

GET /v1/policies

Status	Response
200	Policies — `object`

Set a placement policy

PUT /v1/policies/{scope}

Parameter	In	Type	Description
`scope` *	path	`string`	global (operator), org: or project:

Request body (application/json): PlacementPolicy

Status	Response
200	Stored — `PlacementPolicy`
403	Structured error — `ErrorEnvelope`

Remove a policy

DELETE /v1/policies/{scope}

Parameter	In	Type	Description
`scope` *	path	`string`	global (operator), org: or project:

Status	Response
204	Removed

Pools as tenants see them (no config or credentials): a tenant key gets the pools its placement policies allow, an operator key every pool

GET /v1/capabilities

Status	Response
200	Pools

Resource profiles

GET /v1/profiles

Status	Response
200	Profiles

Image templates

GET /v1/templates

Status	Response
200	Templates

Data classifications

GET /v1/classifications

Status	Response
200	Classifications

Usage and audit

Quota limits and current consumption (usage:read)

GET /v1/quotas

Parameter	In	Type	Description
`projectId`	query	`string`
`orgId`	query	`string`	Operator keys only

Status	Response
200	Report — `QuotaReport`

Estimated usage over a window (usage:read)

GET /v1/usage

Parameter	In	Type
`from`	query	`string (date-time)`
`to`	query	`string (date-time)`
`groupBy`	query	`pool` \| `project` \| `org` \| `trust`

Status	Response
200	Report — `UsageReport`

List audit events in sequence order (audit:read)

GET /v1/audit-events

Parameter	In	Type
`afterSeq`	query	`integer`
`resource`	query	`string`
`action`	query	`string`
`limit`	query	`integer`

Status	Response
200	Events — `object`

Admin

List organizations

GET /v1/admin/organizations

Status	Response
200	Organizations

Create an organization (optionally with a default project)

POST /v1/admin/organizations

Request body (application/json): object

Status	Response
201	Created

Get an organization

GET /v1/admin/organizations/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Organization

Rename or set quota

PATCH /v1/admin/organizations/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Organization

Suspend a tenant (optionally terminating its sandboxes)

POST /v1/admin/organizations/{id}/suspend

Parameter	In	Type	Description
`id` *	path	`string`

Request body (application/json): object

Status	Response
200	Suspended

Lift a suspension

POST /v1/admin/organizations/{id}/resume

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Resumed

Set a project quota

PATCH /v1/admin/projects/{id}

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
200	Project

List pools with health and capacity

GET /v1/admin/pools

Status	Response
200	Pools

Register a pool at runtime

POST /v1/admin/pools

Credentials are references, never values: {"env": NAME} or {"file": PATH} resolved on the server, or {"secret": name} for a credential stored with PUT /v1/admin/secrets/{name}.

Status	Response
201	Pool

Get a pool

GET /v1/admin/pools/{name}

Parameter	In	Type	Description
`name` *	path	`string`

Status	Response
200	Pool

Enable/disable

PATCH /v1/admin/pools/{name}

Parameter	In	Type	Description
`name` *	path	`string`

Status	Response
200	Pool

Remove an API-registered pool with no sandboxes

DELETE /v1/admin/pools/{name}

Parameter	In	Type	Description
`name` *	path	`string`

Status	Response
204	Removed

Stop new placements on a pool

POST /v1/admin/pools/{name}/drain

Parameter	In	Type	Description
`name` *	path	`string`

Status	Response
200	Pool

Send new sandboxes to this pool

POST /v1/admin/pools/{name}/use

Undrains the pool and drains every other one; running sandboxes stay where they are. An external pool must be approved by the global policy, or approved here with approveExternal. Private-only work still never leaves private pools.

Parameter	In	Type	Description
`name` *	path	`string`

Request body (application/json): object

Status	Response
200	What changed — `object`
409	Structured error — `ErrorEnvelope`

Resume placements on a pool

POST /v1/admin/pools/{name}/undrain

Parameter	In	Type	Description
`name` *	path	`string`

Status	Response
200	Pool

Terminate any tenant’s sandbox

POST /v1/admin/sandboxes/{id}/terminate

Parameter	In	Type	Description
`id` *	path	`string`

Status	Response
202	Terminating

List stored provider credentials (fingerprints and the pools using them; never values)

GET /v1/admin/secrets

Status	Response
200	Secrets — `object`

Store or replace a provider credential

PUT /v1/admin/secrets/{name}

The value is sealed with AES-256-GCM under the server’s secrets key and never returned. Pools whose credential is secret: use the new value without a restart. Needs a secrets key on the server (secrets.keyEnv or secrets.keyFile).

Parameter	In	Type	Description
`name` *	path	`string`

Request body (application/json): PutSecretRequest

Status	Response
200	Replaced — `Secret`
201	Stored — `Secret`
409	Structured error — `ErrorEnvelope`

Delete a credential no pool uses

DELETE /v1/admin/secrets/{name}

Parameter	In	Type	Description
`name` *	path	`string`

Status	Response
204	Deleted
409	Structured error — `ErrorEnvelope`

Where work may go

GET /v1/admin/trust-report

Status	Response
200	Trust report

Verify the audit hash chain

GET /v1/admin/audit/verify

Status	Response
200	Result

Run the reconciler now

POST /v1/admin/reconcile

Status	Response
200	Done

System

Liveness

GET /healthz · no authentication

Status	Response
200	OK

Readiness (store reachable)

GET /readyz · no authentication

Status	Response
200	Ready
503	Structured error — `ErrorEnvelope`

Build and installation identity

GET /version · no authentication

Status	Response
200	Version — `VersionInfo`

Prometheus metrics

GET /metrics · no authentication

Status	Response
200	Prometheus text format

Schemas

ErrorEnvelope

Field	Type	Description
`error`	`object`

VersionInfo

Field	Type	Description
`version`	`string`
`commit`	`string`
`apiVersion`	`string`
`installation`	`string`

Me

Field	Type	Description
`keyId`	`string`
`orgId`	`string`
`projectId`	`string`
`scopes`	`string`[]
`operator`	`boolean`

SandboxStatus

Resources

Field	Type	Description
`cpu`	`integer`
`memoryMiB`	`integer`
`diskGiB`	`integer`

Placement

Request-level preference; can only narrow policy.

Field	Type	Description
`strategy`	`private-first` \| `cost` \| `spread`
`allowedPools`	`string`[]
`regions`	`string`[]
`external`	`never` \| `overflow` \| `allowed`

Capability

CreateSandboxRequest

Field	Type	Description
`projectId`	`string`	Required for organization and operator keys
`template`	`string`
`profile`	`string`	Named resource preset
`resources`	`Resources`
`capabilities`	`Capability`[]
`classification`	`string`	Operator-defined, e.g. private-only, internal, public
`placement`	`Placement`
`ttlSeconds`	`integer`
`env`	`object`	Write-only; never returned
`labels`	`object`
`priority`	`integer`
`fromSnapshot`	`string`
`idleTimeoutSeconds`	`integer`	Stop or pause after this many seconds with no exec, file, port or keepalive call (at least 60); the next such call wakes it. 0 uses the operator default, -1 turns it off
`maxRunSeconds`	`integer`	Pause (or stop) after running this long without a break, busy or not (at least 60); the next call resumes it. 0 uses the operator default, -1 turns it off
`maxPausedSeconds`	`integer`	Delete after staying paused or stopped this long (at least 60). 0 uses the operator default, -1 turns it off
`preemptible`	`boolean`	false keeps the scheduler from pausing this sandbox to make room on a full pool. Default true

UpdateSandboxRequest

Field	Type	Description
`labels`	`object`
`ttlSeconds`	`integer`
`idleTimeoutSeconds`	`integer`
`maxRunSeconds`	`integer`
`maxPausedSeconds`	`integer`
`preemptible`	`boolean`

Sandbox

Field	Type	Description
`id` *	`string`
`orgId` *	`string`
`projectId` *	`string`
`status` *	`SandboxStatus`
`statusReason`	`string`
`template`	`string`
`profile`	`string`
`resources` *	`Resources`
`capabilities`	`string`[]
`classification` *	`string`
`placement`	`Placement`
`pool`	`string`
`adapter`	`string`
`trust`	`private` \| `external`
`region`	`string`
`labels`	`object`
`envKeys`	`string`[]
`priority`	`integer`
`ttlSeconds`	`integer`
`expiresAt`	`string (date-time)`
`idleTimeoutSeconds`	`integer`
`maxRunSeconds`	`integer`
`maxPausedSeconds`	`integer`
`preemptible`	`boolean`
`pausedAt`	`string (date-time)`
`slotReleased`	`boolean`	A paused sandbox on a pool that checkpoints on pause holds no pool slot until it resumes
`resumeRequestedAt`	`string (date-time)`	Set while a resume waits for a free slot
`lastActivityAt`	`string (date-time)`
`idledAt`	`string (date-time)`	Set while stopped or paused for being idle; the next exec
`fromSnapshot`	`string`
`attempts`	`integer`
`createdBy`	`string`
`createdAt` *	`string (date-time)`
`updatedAt`	`string (date-time)`
`startedAt`	`string (date-time)`
`endedAt`	`string (date-time)`
`decision`	`PlacementDecision`

SandboxList

Field	Type	Description
`items`	`Sandbox`[]
`nextCursor`	`string`

PlacementDecision

Field	Type	Description
`pool`	`string`
`strategy`	`string`
`external`	`string`
`outcome`	`placed` \| `waiting` \| `rejected`
`reason`	`string`
`policies`	`string`[]
`evaluatedAt`	`string (date-time)`
`candidates`	`object`[]

PlacementExplanation

Field	Type	Description
`sandboxId`	`string`
`status`	`SandboxStatus`
`pool`	`string`
`trust`	`string`
`decision`	`PlacementDecision`
`current`	`PlacementDecision`

ExecRequest

Set command (run by /bin/sh -c) or args (executed directly).

Field	Type	Description
`command`	`string`
`args`	`string`[]
`env`	`object`
`cwd`	`string`
`stdin`	`string`
`timeoutSeconds`	`integer`

ExecResult

Field	Type	Description
`exitCode`	`integer`
`stdout`	`string`
`stderr`	`string`
`durationMs`	`integer`
`truncated`	`boolean`

ExecEvent

Field	Type	Description
`stream`	`stdout` \| `stderr`
`data`	`string`
`exitCode`	`integer`
`error`	`string`

FileInfo

Field	Type	Description
`path`	`string`
`name`	`string`
`size`	`integer`
`mode`	`string`
`isDir`	`boolean`
`modTime`	`string (date-time)`

FileList

Field	Type	Description
`items`	`FileInfo`[]

CreateSnapshotRequest

Field	Type	Description
`kind`	`disk` \| `memory`

Snapshot

Field	Type	Description
`id`	`string`
`sandboxId`	`string`
`orgId`	`string`
`projectId`	`string`
`pool`	`string`
`kind`	`string`
`status`	`string`
`sizeBytes`	`integer`
`createdAt`	`string (date-time)`
`createdBy`	`string`

PortURL

Field	Type	Description
`port`	`integer`
`url`	`string`

Quota

Zero means unlimited at that level.

Field	Type	Description
`maxActiveSandboxes`	`integer`
`maxQueued`	`integer`
`maxCPU`	`integer`
`maxMemoryMiB`	`integer`
`maxDiskGiB`	`integer`
`maxTTLSeconds`	`integer`
`maxSnapshots`	`integer`
`poolBudgetsPerHour`	`object`

QuotaUsage

Field	Type	Description
`activeSandboxes`	`integer`
`queued`	`integer`
`cpu`	`integer`
`memoryMiB`	`integer`
`diskGiB`	`integer`
`snapshots`	`integer`

QuotaReport

Field	Type	Description
`orgId`	`string`
`projectId`	`string`
`orgQuota`	`Quota`
`orgUsage`	`QuotaUsage`
`projectQuota`	`Quota`
`projectUsage`	`QuotaUsage`

Project

Field	Type	Description
`id`	`string`
`orgId`	`string`
`name`	`string`
`quota`	`Quota`
`createdAt`	`string (date-time)`

APIKey

Field	Type	Description
`id`	`string`
`name`	`string`
`orgId`	`string`
`projectId`	`string`
`scopes`	`string`[]
`createdBy`	`string`
`createdAt`	`string (date-time)`
`expiresAt`	`string (date-time)`
`lastUsedAt`	`string (date-time)`
`revoked`	`boolean`
`replacedBy`	`string`	The key a rotation issued in place of this one

CreateAPIKeyRequest

Field	Type	Description
`name` *	`string`
`orgId`	`string`
`projectId`	`string`
`scopes` *	`admin` \| `org:admin` \| `sandboxes:read` \| `sandboxes:write` \| `sandboxes:exec` \| `projects:write` \| `keys:write` \| `usage:read` \| `audit:read` \| `policies:write`[]
`ttlHours`	`integer`

CreateAPIKeyResponse

Type: object

RotateAPIKeyRequest

Field	Type	Description
`graceSeconds`	`integer`	How long the old key stays valid; 0 revokes it at once

Secret

Field	Type	Description
`name`	`string`
`fingerprint`	`string`	Identifies the value without revealing it
`createdAt`	`string (date-time)`
`createdBy`	`string`
`updatedAt`	`string (date-time)`
`updatedBy`	`string`
`usedBy`	`string`[]	Pools whose credential is this secret

PutSecretRequest

Field	Type	Description
`value` *	`string`

PlacementPolicy

Field	Type	Description
`scope`	`string`
`allowedPools`	`string`[]
`deniedPools`	`string`[]
`allowedRegions`	`string`[]
`external`	`never` \| `overflow` \| `allowed`
`externalPools`	`string`[]	External pools explicitly approved; none are approved by default
`strategy`	`private-first` \| `cost` \| `spread`
`maxCostPerHour`	`number`
`maxQueueSeconds`	`integer`

UsageReport

Field	Type	Description
`from`	`string (date-time)`
`to`	`string (date-time)`
`groupBy`	`string`
`note`	`string`
`lines`	`UsageLine`[]
`total`	`UsageLine`

UsageLine

Field	Type	Description
`key`	`string`
`sandboxes`	`integer`
`cpuSeconds`	`number`
`memoryGiBSeconds`	`number`
`runSeconds`	`number`
`queueSeconds`	`number`
`estimatedCost`	`number`

AuditEvent

Field	Type	Description
`seq`	`integer`
`time`	`string (date-time)`
`actor`	`string`
`orgId`	`string`
`projectId`	`string`
`action`	`string`
`resource`	`string`
`outcome`	`string`
`details`	`object`
`requestId`	`string`
`prevHash`	`string`
`hash`	`string`

Fields and parameters marked * are required.