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
cursorto page forward; response includesnextCursor(null on last page) andlimit(default 50, max 200). - Idempotency: pass
Idempotency-Keyheader to makecreate/snapshot/forkidempotent. 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
| Method | Path | Description |
|---|---|---|
POST | /v1/pods | Create a pod |
GET | /v1/pods | List pods |
GET | /v1/pods/{id} | Get a pod |
DELETE | /v1/pods/{id} | Destroy a pod |
POST | /v1/pods/{id}/exec | Run 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}/snapshot | Take a snapshot |
POST | /v1/pods/{id}/fork | Fork a running pod |
POST | /v1/pods/{id}/sleep | Put a pod to sleep |
POST | /v1/pods/{id}/wake | Wake a sleeping pod |
GET | /v1/snapshots | List snapshots |
GET | /v1/snapshots/{id} | Get a snapshot |
DELETE | /v1/snapshots/{id} | Delete a snapshot |
POST | /v1/snapshots/{id}/fork | Fork a snapshot (1–64 pods) |
GET | /v1/templates | List templates |
POST | /v1/templates | Create a template |
GET | /v1/usage | Get usage metrics |
GET | /v1/limits | Get plan limits |
GET | /v1/keys | List API keys |
POST | /v1/keys | Create an API key |
DELETE | /v1/keys/{id} | Revoke an API key |
GET | /v1/webhooks | List webhooks |
POST | /v1/webhooks | Create a webhook |
DELETE | /v1/webhooks/{id} | Delete a webhook |