Snapshots and templates

A Snapshot is a point-in-time capture of a Dock's disk, made when the Dock stops or branches. A Template is a Snapshot frozen under a name so new Docks can start from it with from. See Docks. Routes return the Snapshot object and Template object. Shared rules are in Conventions.

Responses carry the listed fields only; the file listing and storage details are not returned.

Snapshot reads need org role member of the Dock's organization.

Both Snapshot lists take the same paging query:

GET /v1/snapshots

List Snapshots of all Docks you can see, newest first.

Response: { "snapshots": [ ... ], "nextCursor": "..." | null } with Snapshot objects. Errors: validation_error.

GET /v1/docks/:id/snapshots

List one Dock's Snapshots, with the same query and response as GET /v1/snapshots. Errors: validation_error, dock_not_found.

GET /v1/docks/:id/snapshots/latest

The Dock's most recent completed Snapshot.

Response: the Snapshot object, or null when the Dock has none. Errors: dock_not_found.

GET /v1/snapshots/:id/tree

List the files in a completed Snapshot.

Response: { "snapshotId": "...", "files": [ { "path": "work/app.js", "size": 120 } ] }. Errors: snapshot_not_found, environment_secrets_admin_only.

GET /v1/snapshots/:id/files

Read the bytes of one file in a completed Snapshot. The response is application/octet-stream and is not enveloped.

Errors: snapshot_not_found (also for an unknown path), environment_secrets_admin_only, not_a_regular_file (422), file_too_large (413).

GET /v1/snapshots/:id/download

List download links for every file in a completed Snapshot.

Response:

{ "snapshotId": "...", "files": [ { "path": "work/app.js", "size": 120, "url": "/v1/snapshots/<id>/files?path=work%2Fapp.js" } ] }

Each url is a relative link to GET /v1/snapshots/:id/files. Errors: snapshot_not_found, environment_secrets_admin_only.

DELETE /v1/snapshots/:id

Delete a Snapshot (202).

Role: admin. Needs x-confirm-delete: <snapshot id>.

Response: { "operation": { ... } }, an operation. Errors: confirm_required, snapshot_not_found, forbidden (not an admin), snapshot_in_use (a newer Snapshot or a Template depends on it).

POST /v1/templates

Freeze a Dock as a named Template (202). A running Dock is captured first and the call returns once the capture finishes; an archived Dock's latest completed Snapshot is referenced without a new capture. Saving over an existing name replaces that Template.

Role: admin.

Response: the Template object with status: "ready". Errors: validation_error, forbidden (not an admin), dock_not_found, dock_not_running (the Dock is in error or unreachable), template_limit_reached, zdr_blocks_templates, conflict (the same name is being saved, or an archived Dock has no completed Snapshot), service_unavailable (the capture failed).

When the Dock has connectors, a running Dock is re-applied after the capture so its connector gateway token is replaced: the copy held by the Template stops working, and the Template is marked as coming from a connector Dock. Processes already running in the source Dock keep the old token until they reload ~/.config/dock/mcp.json or the environment. The rotation is best effort: if the apply fails before the token is replaced, the save still succeeds and the captured token works until the source Dock is applied again or stops.

GET /v1/templates

List Templates in all your organizations, newest first. Templates still saving or failed are included; check status before deploying one.

Response: an array of Template objects.

GET /v1/templates/:name

Read one ready Template.

Response: the Template object. Errors: validation_error, organization_not_found, template_not_found.

DELETE /v1/templates/:name

Delete a Template. It needs no x-confirm-delete header.

Role: admin.

Response: { "operation": { ... } }, an operation. Errors: validation_error, organization_not_found, forbidden (not an admin), template_not_found.

To start a Dock from a Template, pass its name as from to POST /v1/docks. A Template saved from a Dock with connectors (or whose source Dock is unknown, such as a Template that predates this record and whose Dock is gone) can be used only by organization admins; members get 403 connector_admin_only.