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:
| Param | Type | Default | Max | Description |
|---|---|---|---|---|
cursor | string | — | — | Opaque pagination cursor from nextCursor |
limit | int | 50 | 200 | Page size |
status | string | — | — | 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.