API Overview

The Daytona REST API drives everything the SDK and dashboard do: creating and managing sandboxes, building images, capturing snapshots, and attaching volumes, object stores, secrets, and registry credentials.

Base URL

https://api.rl.trydaytona.com

All example requests in this reference use this base URL.

Authentication

There are two authentication planes:

Workload API keys are project-scoped tokens with the rlp_ prefix, minted from the dashboard or via POST /projects/:id/api-keys. Every workload resource is scoped to the key's project — an id belonging to another project returns 404, exactly like a nonexistent one. Management routes use your dashboard login token (an OIDC bearer JWT), not an rlp_ key. See Authentication.

curl https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY"

Conventions

• JSON everywhere. Request and response bodies are JSON unless noted (logs return text/plain; image context uploads are multipart/form-data). Unknown request fields are ignored.
• Async creates + polling. POST /vms, POST /images, and POST /vms/:id/snapshots return immediately with status: "pending" and a job_id. Poll the resource (or GET /jobs/:id) until it reaches a ready/terminal state.
• Long-poll with ?wait=. GET /vms/:id?wait=running&timeout_ms=30000 blocks until the sandbox reaches the target status (or a terminal state), up to 60 s. GET /snapshots/:id?wait=ready works the same way. On timeout you get 200 with the current state — check the status field.
• Cursor pagination. List endpoints (GET /vms, /images, /snapshots) accept limit (default 100, max 200) and cursor. Responses include next_cursor — an opaque token to echo back for the next page; null means the last page.
• External sandbox ids. Sandbox ids in responses are region-tagged tokens (bare UUIDs are also accepted on input). Treat them as opaque strings.

Status codes & errors

Errors return a JSON body of the shape:

{ "error": "conflict: sandbox is stopped, not pausable (must be running)" }

The overload response (429) carries extra fields and a Retry-After header:

{
  "error": "overloaded",
  "message": "create queue at capacity; retry after the indicated delay",
  "retry_after_secs": 2
}

Endpoint index

Note: SDK users targeting the Daytona-compatible facade should see the compatibility guide instead.