Skip to Content
Podyard

PODS

Create, list, retrieve, and destroy pods.

PODS

Pod lifecycle endpoints. A pod is a running sandbox — the unit of execution.

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


POST /v1/pods — Create a pod

Boots a pod from a template (or the default base) in milliseconds.

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

Body (all fields optional):

{
  "name": "worker-1",
  "templateId": "tpl_01J...",
  "env": { "FOO": "bar" }
}

Response 201:

{
  "id": "pod_01J...",
  "name": "worker-1",
  "templateId": "tpl_01J...",
  "status": "running",
  "createdAt": "2026-01-15T10:30:00Z",
  "engineSessionId": "01J..."
}

Errors: 429 quota_exceeded (concurrent pod limit), 409 conflict (duplicate idempotency key), 422 invalid_request.


GET /v1/pods — List pods

Query params:

ParamTypeDefaultMaxDescription
cursorstring——Opaque pagination cursor from nextCursor
limitint50200Page size
statusstring——Filter: running, sleeping, stopped, error

Response 200:

{
  "items": [ { "id": "pod_...", "status": "running" } ],
  "nextCursor": "eyJpZCI6..."
}

nextCursor is null on the last page.


GET /v1/pods/{id} — Get a pod

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

Errors: 404 not_found.


DELETE /v1/pods/{id} — Destroy a pod

Tears down the pod and releases its resources. Idempotent: destroying an already-destroyed pod returns 204.

Response 204: empty body.

Errors: 404 not_found.


POST /v1/pods/{id}/sleep — Sleep a pod

Puts a running pod to sleep, releasing compute while retaining its filesystem.

Experimental — the engine's sleep scheduler is not yet fully verified. See Limits.

Response 200: { "id": "pod_...", "status": "sleeping" }

Errors: 409 conflict (pod not running), 422 invalid_request (sleep/wake disabled for plan).


POST /v1/pods/{id}/wake — Wake a pod

Wakes a sleeping pod back to running.

Experimental — same caveats as sleep.

Response 200: { "id": "pod_...", "status": "running" }

Errors: 409 conflict (pod not sleeping), 422 invalid_request.


WHERE_TO_GO_NEXT

  • Exec — run commands in a pod.
  • FS — read and write files.
  • Snapshots — capture pod state.
  • Fork — branch a pod or snapshot.