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:
| Param | Type | Default | Max | Description |
|---|---|---|---|---|
cursor | string | — | — | Pagination cursor |
limit | int | 50 | 200 | Page 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.