VM Snapshots

Snapshots capture a running sandbox's state under a project-unique name. A disk snapshot captures the filesystem and can seed new sandboxes anywhere; a full snapshot also captures memory and resumes processes, but is pinned to its home region. Capture is asynchronous — the snapshot starts pending and becomes ready or failed. See the VM Snapshots guide.

POST /vms/:id/snapshots

Capture a snapshot of a running sandbox. The sandbox keeps running; capture happens with a brief pause-copy-resume on its host.

Request

curl -X POST https://api.rl.trydaytona.com/vms/us1-3kTMbBWbdML5UWJHfyPyhF/snapshots \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "worker-1-after-setup", "kind": "disk" }'

{
  "snapshot_id": "8a4f7c1e-2b9d-4e05-a3f6-1c8e9d20b774",
  "job_id": "e17c2f04-6b1a-4d92-b3c8-90f4a2e6d1a5",
  "name": "worker-1-after-setup",
  "vm_id": "us1-3kTMbBWbdML5UWJHfyPyhF",
  "kind": "disk",
  "status": "pending"
}

Errors

• 404 — unknown sandbox id or another project's sandbox.
• 409 — sandbox not running; sandbox not yet placed on a host; sandbox has no image manifest to snapshot from; or the snapshot name already exists.

GET /snapshots

List the project's snapshots, newest first, with cursor pagination (limit default 100, max 200; cursor from a previous next_cursor).

curl "https://api.rl.trydaytona.com/snapshots?limit=1" \
  -H "Authorization: Bearer $RLP_API_KEY"

{
  "snapshots": [
    {
      "id": "8a4f7c1e-2b9d-4e05-a3f6-1c8e9d20b774",
      "name": "worker-1-after-setup",
      "kind": "disk",
      "vm_id": "7f2e6a30-91cd-4b1f-a8d2-3c5e07b9f614",
      "parent_manifest": "mani-7f3a1c.json",
      "manifest_name": "mani-8a4f7c.json",
      "status": "ready",
      "layer_count": 3,
      "bytes": 268435456,
      "no_changes": false,
      "error": null,
      "artifact_ref": null,
      "fc_version": null,
      "cpu_marker": null,
      "mem_bytes": null,
      "runner_id": null
    }
  ],
  "next_cursor": null
}

Statuses: pending → ready | failed (error explains a failure). no_changes is true when the sandbox had no writes since its parent — the snapshot then reuses the parent manifest. The artifact_ref / fc_version / cpu_marker / mem_bytes / runner_id fields are populated for full snapshots.

GET /snapshots/:id

Fetch one snapshot by its UUID, with optional long-polling.

curl "https://api.rl.trydaytona.com/snapshots/8a4f7c1e-2b9d-4e05-a3f6-1c8e9d20b774?wait=ready" \
  -H "Authorization: Bearer $RLP_API_KEY"

The response is a single snapshot object with the same fields as the list items above.

Errors

• 404 — unknown id or another project's snapshot.

DELETE /snapshots/:id

Delete a snapshot. Deletion is refused while other snapshots descend from this one (they were captured on top of its manifest) — delete the descendants first.

curl -X DELETE https://api.rl.trydaytona.com/snapshots/8a4f7c1e-2b9d-4e05-a3f6-1c8e9d20b774 \
  -H "Authorization: Bearer $RLP_API_KEY"

{ "snapshot_id": "8a4f7c1e-2b9d-4e05-a3f6-1c8e9d20b774", "status": "deleted" }

Errors

• 404 — unknown id or another project's snapshot.
• 409 — other snapshots descend from this one.

Restoring

Create a new sandbox from a snapshot by passing a snapshot source as the image on POST /vms:

curl -X POST https://api.rl.trydaytona.com/vms \
  -H "Authorization: Bearer $RLP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "worker-2",
    "image": { "type": "snapshot", "name": "worker-1-after-setup" }
  }'

• The snapshot must be ready (409 otherwise; 404 if the name is unknown).
• Disk snapshots restore in any region — on first cross-region use the artifact is replicated, and the create returns 409 ("replicating…; retry shortly") until the replica is ready.
• Full snapshots are region-pinned: restoring outside the home region fails with 400. A full restore resumes the captured memory, and reuses the source sandbox's attached secrets.