Skip to Content
Podyard

API_OVERVIEW

Base URL, authentication, request conventions, and the full endpoint list.

API_OVERVIEW

The Podyard API is a REST API that maps 1:1 onto the sandbox engine's verbs. Base URL: https://api.podyard.dev/v1.

AUTHENTICATION

All requests require a Bearer token:

Authorization: Bearer pyd_live_...

Keys are created in the dashboard. The env var convention is PODYARD_API_KEY.

REQUEST_CONVENTIONS

  • IDs: pod_, snap_, tpl_, cmd_, key_ + ULID.
  • Timestamps: ISO-8601 UTC (2026-01-15T10:30:00Z).
  • Pagination: cursor-based. Pass cursor to page forward; response includes nextCursor (null on last page) and limit (default 50, max 200).
  • Idempotency: pass Idempotency-Key header to make create/snapshot/fork idempotent. The same key within 24h returns the original result.
  • Request ID: every response includes x-request-id.

ERROR_ENVELOPE

All errors use a consistent envelope:

{
  "error": {
    "code": "not_found",
    "message": "Pod pod_01J... not found.",
    "requestId": "req_01J...",
    "docsUrl": "https://docs.podyard.dev/api/errors#not_found"
  }
}

See Errors for the full code list.

ENDPOINTS

MethodPathDescription
POST/v1/podsCreate a pod
GET/v1/podsList pods
GET/v1/pods/{id}Get a pod
DELETE/v1/pods/{id}Destroy a pod
POST/v1/pods/{id}/execRun a command (NDJSON stream)
GET/v1/pods/{id}/fs/{path}Read a file
PUT/v1/pods/{id}/fs/{path}Write a file
DELETE/v1/pods/{id}/fs/{path}Delete a file
POST/v1/pods/{id}/snapshotTake a snapshot
POST/v1/pods/{id}/forkFork a running pod
POST/v1/pods/{id}/sleepPut a pod to sleep
POST/v1/pods/{id}/wakeWake a sleeping pod
GET/v1/snapshotsList snapshots
GET/v1/snapshots/{id}Get a snapshot
DELETE/v1/snapshots/{id}Delete a snapshot
POST/v1/snapshots/{id}/forkFork a snapshot (1–64 pods)
GET/v1/templatesList templates
POST/v1/templatesCreate a template
GET/v1/usageGet usage metrics
GET/v1/limitsGet plan limits
GET/v1/keysList API keys
POST/v1/keysCreate an API key
DELETE/v1/keys/{id}Revoke an API key
GET/v1/webhooksList webhooks
POST/v1/webhooksCreate a webhook
DELETE/v1/webhooks/{id}Delete a webhook

WHERE_TO_GO_NEXT

  • Pods — pod lifecycle endpoints.
  • Exec — NDJSON streaming exec.
  • Errors — full error code reference.