TEMPLATES
List and create pod templates.
TEMPLATES
Templates are named, immutable bases for pods. Creating a pod from a template guarantees a consistent starting filesystem state.
Base: https://api.podyard.dev/v1
GET /v1/templates — List templates
Query params:
| Param | Type | Default | Max | Description |
|---|---|---|---|---|
cursor | string | — | — | Pagination cursor |
limit | int | 50 | 200 | Page size |
visibility | string | — | — | Filter: private, shared, public |
Response 200:
{
"items": [
{
"id": "tpl_01J...",
"name": "python-base",
"image": "ubuntu:24.04",
"snapshotId": null,
"visibility": "private",
"createdAt": "2026-01-15T10:30:00Z"
}
],
"nextCursor": null
}[DECIDE] — Template ownership model is not fully settled (the
templatetable has nouserIdcolumn). The current behavior lists all templates with a visibility filter. This is flagged in the final report.
POST /v1/templates — Create a template
Headers: Authorization: Bearer <key>, optional Idempotency-Key.
Body:
{
"name": "python-base",
"image": "ubuntu:24.04",
"snapshotId": "snap_01J...",
"visibility": "private"
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Human-readable template name (unique per key) |
image | string | no | Base image reference. Omit if snapshotId is set. |
snapshotId | string | no | Pin a specific snapshot as the base filesystem |
visibility | private | shared | public | no | Defaults to private |
Response 201:
{
"id": "tpl_01J...",
"name": "python-base",
"image": "ubuntu:24.04",
"snapshotId": "snap_01J...",
"visibility": "private",
"engineTemplateId": "01J...",
"createdAt": "2026-01-15T10:30:00Z"
}Errors: 429 quota_exceeded (template quota), 409 conflict (duplicate name or idempotency key), 422 invalid_request (neither image nor snapshotId provided).