Skip to Content
Podyard

SNAPSHOTS

Create, list, retrieve, and delete pod snapshots.

SNAPSHOTS

Snapshots capture a pod's full state (filesystem + process tree) at a point in time. They are the building block for fork and replay workflows.

Base: https://api.podyard.dev/v1


POST /v1/pods/{id}/snapshot — Take a snapshot

Captures the current state of a running pod. The pod keeps running.

Headers: Authorization: Bearer <key>, optional Idempotency-Key.

Body (optional):

{ "name": "before-fork" }

Response 201:

{
  "id": "snap_01J...",
  "podId": "pod_01J...",
  "name": "before-fork",
  "sizeBytes": 104857600,
  "createdAt": "2026-01-15T10:30:00Z",
  "retained": true
}

Errors: 429 quota_exceeded (snapshot quota), 409 conflict (idempotency), 422 invalid_request (pod not running).


GET /v1/snapshots — List snapshots

Lists snapshots in your account (scoped to your API key).

Query params:

ParamTypeDefaultMaxDescription
cursorstring——Pagination cursor
limitint50200Page size

Response 200:

{
  "items": [ { "id": "snap_...", "podId": "pod_...", "sizeBytes": 104857600 } ],
  "nextCursor": null
}

Engine gap: The engine does not expose an HTTP list route for snapshots. Podyard serves this from its own Postgres store. This is noted in the final report.


GET /v1/snapshots/{id} — Get a snapshot

Response 200: full snapshot object (see create response).

Errors: 404 not_found.


DELETE /v1/snapshots/{id} — Delete a snapshot

Deletes the snapshot and frees its quota.

Coming soon — Engine-side deletion (freeing the actual disk blocks in the engine's storage) is not yet routed. Podyard marks the snapshot as deleted in its own store immediately (so your quota is accurate), and the engine-side cleanup runs asynchronously. This is labeled Coming soon until the engine ships the route.

Response 204: empty body.

Errors: 404 not_found.


WHERE_TO_GO_NEXT

  • Fork — branch from a snapshot.
  • Pods — pod lifecycle.
  • Errors — full error code reference.