Skip to Content
Podyard

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:

ParamTypeDefaultMaxDescription
cursorstring——Pagination cursor
limitint50200Page size
visibilitystring——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 template table has no userId column). 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"
}
FieldTypeRequiredDescription
namestringyesHuman-readable template name (unique per key)
imagestringnoBase image reference. Omit if snapshotId is set.
snapshotIdstringnoPin a specific snapshot as the base filesystem
visibilityprivate | shared | publicnoDefaults 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).


WHERE_TO_GO_NEXT

  • Pods — create pods from templates.
  • Snapshots — create fork points to pin as template bases.
  • Errors — full error code reference.