Get a snapshot

GET/v1/snapshots/{snapshotId}

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <token>` — either the static master token (`ORCH_AUTH_TOKEN`) or a revocable API key issued via /v1/api-keys (API keys require Postgres; without a database only the master token is accepted). Master-only surfaces (exec, attach, API key management) refuse API keys with 403. **Authentication can be disabled entirely.** When neither `ORCH_AUTH_TOKEN` nor an API key store (`DATABASE_URL`) is configured — the default local-development posture — the bearer middleware becomes a pass-through: every operation this document marks as secured is reachable with no credentials, requests carry no principal, and master-only surfaces therefore admit everyone. Never run that configuration on a reachable network; set `ORCH_REQUIRE_AUTH=true` to make the orchestrator refuse to start without a master token.

fuse_sessionAPI key · cookierequired

HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.

Path parameters

snapshotIdstringrequired

Snapshot identifier returned by createSnapshot.

Responses

200Snapshot metadata.

idstringrequired

vm_idstringrequired

task_idstring

tenant_idstring

parent_snapshot_idstring

modestring

Normally "manual" or "auto". Not an enum: the server stores the caller-supplied `mode` verbatim (only an empty value is defaulted to "manual"), so an arbitrary string can appear here. Treat unknown values as opaque rather than rejecting the response.

statestring

Allowed:creatingreadyrestoringdeletingerror

commentstring

layer_keystring

Derived cache key of the setup step this artifact materializes. Absent on any snapshot that is not a build layer.

archstring

Architecture of the host that built the artifact, not of whoever asked for it. An ext4 rootfs does not travel across architectures, so this is what says whether these bytes are bootable for you.

Allowed:amd64arm64

digeststring

Hex sha256 of the artifact rootfs, for verifying a transfer of these exact bytes. It is not an identity two artifacts can share: rebuilding the same recipe produces different bytes, so nothing is looked up by digest. Absent when the host agent does not hash.

kindstring

What this artifact actually contains. "disk" is the rootfs and nothing else, so restoring it cold-boots the guest; "live" additionally carries the vCPU state and the whole guest memory, so restoring it resumes the guest where it stopped. This is what the host agent reports it wrote, never what the caller requested: a `live: true` create served by an agent that could only take a disk snapshot reads back as "disk". Branch on this rather than on your own request. Always present, on every read path. Records written before live snapshots existed read back as "disk".

default: "disk"

Allowed:disklive

size_bytesinteger<int64>

created_atstring<date-time>required

updated_atstring<date-time>

retention_untilstring<date-time> | null

When the snapshot becomes eligible for garbage collection; null/absent when it is kept until deleted.

last_errorstring

export_refstring

exportsSnapshotExport[]

Show properties

Array of SnapshotExport

destinationstringrequired

statusstring

Normally "pending", "ready", or "error". Not an enum: the create handler stores the caller-supplied `export_status` verbatim (only an empty value is defaulted to "pending"), so an arbitrary string can appear here. Treat unknown values as opaque rather than rejecting the response.

requested_atstring<date-time>

updated_atstring<date-time>

last_errorstring

404Snapshot does not exist. Store-level failures also surface as 404, so this endpoint never returns 500.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented

messagestringrequired

Human-readable description.

detailsobject

Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.

Request

curl -X GET "http://localhost:8080/v1/snapshots/string" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("http://localhost:8080/v1/snapshots/string", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "http://localhost:8080/v1/snapshots/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "id": "string",
  "vm_id": "string",
  "task_id": "string",
  "tenant_id": "string",
  "parent_snapshot_id": "string",
  "mode": "manual",
  "state": "creating",
  "comment": "string",
  "layer_key": "string",
  "arch": "amd64",
  "digest": "string",
  "kind": "disk",
  "size_bytes": 0,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "retention_until": "2024-01-01T00:00:00Z",
  "last_error": "string",
  "export_ref": "string",
  "exports": [
    {
      "destination": "string",
      "status": "pending",
      "requested_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "last_error": "string"
    }
  ]
}