---
title: "Snapshots · API reference · Promigence"
description: "The Promigence API's snapshots routes: 13 in all, with parameters, request bodies and answers."
url: "https://www.promigence.ai/docs/reference/api/snapshots"
site: "Promigence"
---

[API reference](https://www.promigence.ai/docs/reference/api)

# Snapshots

13 routes of the published API contract, generated from it.

### POST/v1/images/resolve

Auth: API key

Turn an image tag into a digest. `python:3.12` comes back as `python@sha256:…`, ready for `POST /v1/snapshots`, and you need no container tooling installed to ask. A reference that is already pinned is answered without contacting the registry. For a tag that names several architectures the answer pins what a pull of that tag would fetch and reports the `linux/amd64` build beside it; a tag with no `linux/amd64` build is refused here rather than at build time. `registry_secret` names a stored secret holding `user:password` for a private registry.

#### Request body ImageResolve · application/json

imagerequiredstring

An image reference, a tag or a digest.

registry_secretstring | null

A stored secret holding the registry credentials.

#### Answer 200 · ImageResolved · application/json

already_pinnedrequiredboolean

True when the reference was already pinned and no registry was asked.

digestrequiredstring

The digest `image` carries — the index's, for a tag that names several architectures, which is what a pull of that tag fetches.

imagerequiredstring

The pinned reference: your own name with `@sha256:…` on the end.

media_typerequiredstring

The media type at that digest.

msrequirednumber

The round trip to the registry, in milliseconds.

okrequiredboolean

platformrequiredstring

`linux/amd64`.

platform_digeststring | null

The `linux/amd64` build beside the index; `null` when the tag names a single manifest.

platformsrequiredstring[]

Every `os/arch` the index offers. Empty for a single manifest.

registryrequiredstring

registry_secretstring | null

The stored secret the registry was asked with, as it was named in the request.

repositoryrequiredstring

tagstring | null

`null` when the reference named a digest rather than a tag.

### GET/v1/snapshots

Auth: none

List snapshots, newest first. With a key: your org's plus every public one. Without a key: the public ones only — this is what `promigence examples` calls before you have signed in. Pages are `?limit=N` (1..=500, default 50) and `?cursor=`; echo back `next_cursor` and stop when it is `null`.

#### Parameters

cursorquery · string

limitquery · integer

#### Answer 200 · SnapshotList · application/json

limitrequiredinteger

The page size that was applied.

next_cursorstring | null

Pass back as `?cursor=` for the next page; `null` on the last page.

snapshotsrequiredSnapshotView[]

### POST/v1/snapshots

Auth: API key

Build and verify a snapshot. Returns 202 with a `build_id`; poll it. A build is billed per second at its tier's rate while it runs, for at most `max_seconds`: `build_price` is the most it can cost. If `verify` exits non-zero nothing is stored, and the time the build ran is billed. Honours `Idempotency-Key`. A private repository is built through your GitHub or GitLab connection: `repo: "github:owner/name"` or `repo: "gitlab:group/project"` (subgroups too) with an optional `ref` (branch, tag or sha; default the default branch), `from` (the snapshot it starts from, default `promigence/base`) and `track` (with an `alias`: every push to the branch builds it again, each a normal build). A repository URL with credentials in it (a user name, password, token, query string or fragment) is refused with `repo_credentials_not_supported`.

#### Parameters

Idempotency-Keyheader · string

Makes a retried create safe: send the same key on every attempt of ONE create and it starts, and bills, once. Kept 24 hours per org. The same key with the same request (method, path and JSON body) answers with the first answer — same status, same ids — marked `Idempotent-Replayed: true`. The same key with a different request is refused with 409 `idempotency_key_reused`. A repeat that arrives while the first is still running waits for its answer, or gets 409 `idempotency_key_in_use` with `Retry-After`. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make.

#### Request body SnapshotCreate · application/json · optional

aliasstring | null

A name for it, unique in the project.

commitstring | null

The full 40-character commit sha to build (the repository form).

dockerfileDockerfileSource | null

Build from a Dockerfile.

envmap of string

Image and Dockerfile forms: environment variables for every command, terminal and SSH session in sandboxes from this snapshot (and for its own `setup`, `verify` and `start`), set over the image's own `ENV` as `docker run -e` sets them. A value may build on a variable the image sets with `${containerEnv:NAME}`, or `${containerEnv:NAME:default}` when the image may not set it: `"PATH": "${containerEnv:PATH}:/opt/tools/bin"`.

fromstring | null

`github:` repositories: the snapshot the build starts from, by id or alias. Default `promigence/base`.

gradeGradeSpec | null

The snapshot's default grader for runs that name none.

grade_outputboolean

Runs that use this default grader keep what it prints, as `grade_output` on `POST /v1/runs` does, unless the run says otherwise. Needs `grade`.

imagestring | null

A container image, `REF@sha256:<digest>`; a tag is resolved to its digest first.

refstring | null

`github:` repositories: a branch, a tag or a commit sha, resolved to the commit it names when the build is accepted. Default: the repository's default branch.

registry_secretstring | null

A stored secret holding the registry credentials for a private `image`.

repostring | null

A public git URL (the repository form), or `github:owner/name`: a repository the organization's GitHub connection can read (`GET /v1/integrations/github/repos`).

setupOneOrMany | null

Commands run once, in order, before `verify`.

setup_userstring | null

Image and Dockerfile forms: the user its `start`, `setup` and `verify` run as (for example the snapshot's own `user`). Default: `root`.

sourcesSourceRequest[]

Extra repositories cloned before `setup` (repository form only, at most 8).

startstring | null

A command that keeps running in every sandbox (image and Dockerfile forms).

tierstring | null

The sandbox size it is built and forked at.

trackboolean

`github:` repositories with a branch `ref` and an `alias`: every push to the branch builds the snapshot again and moves the alias to it. Each automatic build is a normal build, charged to the organization.

userstring | null

Image and Dockerfile forms: the user commands, terminals and SSH sessions in its sandboxes run as when they name none. A user name or uid, with an optional `:group` or `:gid`, as an image's `USER` takes it; `root` for root. Default: the image's own `USER`, as `docker run` does (root when it sets none).

verifyVerifyRequest | null

The command that must exit 0 for the snapshot to be stored. Required in the repository form.

#### Answer 200 · SnapshotCreated · application/json

### GET/v1/snapshots/{id}

Auth: API key

One snapshot by id or alias. `unavailable` is set, with the reason, when this snapshot can no longer be started; it is absent while it can.

#### Parameters

idrequiredpath · string

#### Answer 200 · SnapshotView · application/json

aliasstring | null

The mutable name. The id and the hash behind it are not mutable.

build_idrequiredstring

The build that produced it.

commitrequiredstring

created_atrequiredstring

RFC 3339.

files_digeststring | null

`blake3:<hex>` of the snapshot's files and the record of what built them. The same for as long as the snapshot exists. Only on `GET /v1/snapshots/{id}`; absent when the snapshot records no file digests.

historystring[]

What happened to it, one line per event, oldest first: built and verified, and each time it was verified again (files unchanged). Only on `GET /v1/snapshots/{id}`.

last_verified_atstring | null

RFC 3339.

reporequiredstring

setuprequiredstring[]

The commands run to prepare the workspace.

snapshot_idrequiredstring

sourcerequiredobject

What it was built from: a repository and commit, an image and digest, or a Dockerfile and the digest of its context. The `kind` field says which.

templateSnapshotTemplateRef | null

The template this snapshot is, or was made from, and whether a newer version of it is out. Absent when it comes from no template.

tierrequiredstring

tier_assignedrequiredstring

The tier it was built and verified at. Forking it at another shape is refused.

unavailablestring | null

Set when this snapshot can no longer be started, and why: it could not be saved. A fork of it is refused `snapshot_unavailable`. Absent while it can be started.

userstring | null

The user commands, terminals and SSH sessions in its sandboxes run as when they name none: its image's own `USER`, or the `user` it was created with. Absent: root.

verificationrequiredobject

What the verification command did when it last ran.

verifiedrequiredboolean

True when a verification command was recorded, which is what makes the snapshot reproducible rather than merely saved.

verifyrequiredVerifyCmd

visibilityrequiredstring

`private` | `public`.

warningsstring[]

Things whoever forks this snapshot should know, one `code: sentence` per line. Absent when there are none.

### DELETE/v1/snapshots/{id}

Auth: API key

Remove one of your own snapshots from your catalogue. The record goes and the space is reclaimed; finished runs keep their reports, so last month's numbers stay readable. Refused while a sandbox forked from it is still running — kill those first.

#### Parameters

idrequiredpath · string

#### Answer 200 · SnapshotDeleted · application/json

aliasstring | null

deletedrequiredboolean

okrequiredboolean

snapshot_idrequiredstring

### PUT/v1/snapshots/{id}/alias

Auth: API key

Move the snapshot's alias. The alias is mutable; the snapshot id and its hash are not.

#### Parameters

idrequiredpath · string

#### Request body SnapshotAliasSet · application/json

aliasrequiredstring | null

#### Answer 200 · SnapshotView · application/json

aliasstring | null

The mutable name. The id and the hash behind it are not mutable.

build_idrequiredstring

The build that produced it.

commitrequiredstring

created_atrequiredstring

RFC 3339.

files_digeststring | null

`blake3:<hex>` of the snapshot's files and the record of what built them. The same for as long as the snapshot exists. Only on `GET /v1/snapshots/{id}`; absent when the snapshot records no file digests.

historystring[]

What happened to it, one line per event, oldest first: built and verified, and each time it was verified again (files unchanged). Only on `GET /v1/snapshots/{id}`.

last_verified_atstring | null

RFC 3339.

reporequiredstring

setuprequiredstring[]

The commands run to prepare the workspace.

snapshot_idrequiredstring

sourcerequiredobject

What it was built from: a repository and commit, an image and digest, or a Dockerfile and the digest of its context. The `kind` field says which.

templateSnapshotTemplateRef | null

The template this snapshot is, or was made from, and whether a newer version of it is out. Absent when it comes from no template.

tierrequiredstring

tier_assignedrequiredstring

The tier it was built and verified at. Forking it at another shape is refused.

unavailablestring | null

Set when this snapshot can no longer be started, and why: it could not be saved. A fork of it is refused `snapshot_unavailable`. Absent while it can be started.

userstring | null

The user commands, terminals and SSH sessions in its sandboxes run as when they name none: its image's own `USER`, or the `user` it was created with. Absent: root.

verificationrequiredobject

What the verification command did when it last ran.

verifiedrequiredboolean

True when a verification command was recorded, which is what makes the snapshot reproducible rather than merely saved.

verifyrequiredVerifyCmd

visibilityrequiredstring

`private` | `public`.

warningsstring[]

Things whoever forks this snapshot should know, one `code: sentence` per line. Absent when there are none.

### GET/v1/snapshots/{id}/manifest

Auth: none

The manifest: what a `.promigence` bundle is built from. Reachable without a key for public snapshots only.

#### Parameters

idrequiredpath · string

#### Answer 200 · SealedManifestView · application/json

cached_atrequiredstring

When this copy of the manifest was taken, RFC 3339.

manifestrequiredSealedManifest

The manifest as the API returns it: the sections that describe *how* the environment runs are replaced by their digests under `sealed`; identity, provenance and verification are unchanged. A sealed manifest still names exactly one environment: `manifest_hash` is the full hash of the content keys, and `sealed.*` are the section digests a full bundle would carry, so a `.promigence` built from it can be cited, committed and handed back to the API.

snapshot_idrequiredstring

### POST/v1/snapshots/{id}/verify

Auth: API key

Re-run the snapshot's own verify command in a fresh fork. Costs one sandbox's worth of seconds; it is a real run under the hood.

#### Parameters

idrequiredpath · string

wait_msquery · integer

Idempotency-Keyheader · string

Makes a retried create safe: send the same key on every attempt of ONE create and it starts, and bills, once. Kept 24 hours per org. The same key with the same request (method, path and JSON body) answers with the first answer — same status, same ids — marked `Idempotent-Replayed: true`. The same key with a different request is refused with 409 `idempotency_key_reused`. A repeat that arrives while the first is still running waits for its answer, or gets 409 `idempotency_key_in_use` with `Retry-After`. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make.

#### Request body SnapshotVerify · application/json · optional

spend_capnumber | null

The most it may cost, in USD.

timeout_msinteger | null

Milliseconds the verification may run. Default 15 minutes.

#### Answer 200 · SnapshotVerifyStarted · application/json

aliasstring | null

countrequiredinteger

How many sandboxes were asked for.

idempotent_replayrequiredboolean

True when this is the stored answer to an `Idempotency-Key` that was seen before, and no second run was started.

idempotent_replay_age_sinteger | null

Present when `idempotent_replay` is true: how many seconds ago that first answer was given, so a client can say which earlier request this repeats.

last_verified_atstring | null

When the snapshot was last verified before this run, RFC 3339.

launchedrequiredinteger

How many were started. Fewer than `count` only with `allow_partial`, and the reason is in `warnings`.

per_second_usdrequirednumber

preemptiblerequiredboolean

True when the run was posted at the preemptible rate: its sandboxes can be stopped early, and one stopped that way bills nothing.

pricerequirednumber

What one full run of it may cost, in USD.

quoterequiredQuote

A quote, per second: `max_cost = Σ sandbox_count × seconds_per_sandbox × per_second_usd`, where `per_second_usd = vcpus × vcpu_second_usd + mem_gib × gib_second_usd`. The most the run can cost if every sandbox runs its whole timeout; billing is for the seconds actually used.

run_idrequiredstring

sandboxesrequiredRunSandboxRef[]

secondsrequiredinteger

snapshotrequiredstring

The snapshot, resolved.

snapshot_argrequiredstring

The snapshot as you named it — an id, an alias, or a path.

snapshot_idstring | null

The snapshot's id, as `GET /v1/runs/{id}` and the report give it: `""` for the built-in base. Never `null` from this API; typed nullable for older answers.

spend_caprequirednumber

The most this run may cost, in USD.

staterequiredstring

`"running"`.

tierrequiredstring

timeout_msrequiredinteger

verifyrequiredstring

The verification command, as it was recorded.

warningsrequiredstring[]

What was **not** started and why, said when it is decided rather than discovered in the report.

workspacerequiredstring

The directory it runs in.

### GET/v1/snapshots/builds

Auth: API key

List your org's builds.

#### Parameters

cursorquery · string

limitquery · integer

statequery · string

#### Answer 200 · BuildList · application/json

buildsrequiredBuildView[]

next_cursorstring | null

Pass as `?cursor=` for the next page; `null` on the last one.

### GET/v1/snapshots/builds/{id}

Auth: API key

One build. `?wait_ms=N` long-polls until the build reaches a terminal state, capped at 30 s server-side.

#### Parameters

idrequiredpath · string

wait_msquery · integer

#### Answer 200 · BuildView · application/json

aliasstring | null

The name the snapshot holds now, or the one asked for while the build runs. `null` once the snapshot is deleted: the name may belong to another snapshot by then.

billable_secondsinteger | null

Once the build has ended, the seconds it is billed for: the time it ran, whether it was stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed on our side. Absent while it is queued or running, and for a build priced per build.

build_idrequiredstring

build_pricerequirednumber

The most the build can cost, in USD, as said when it was started: `max_seconds` at `per_second_usd`. What it was billed is `cost_usd`.

commitrequiredstring

cost_usdnumber | null

Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it is queued or running.

created_atrequiredstring

RFC 3339.

errorobject

Why it failed. `null` while it is going and for a build that worked.

finished_atstring | null

RFC 3339.

max_secondsinteger | null

The longest the build may run, in seconds: it is billed for at most this long. Absent for a build priced per build.

nextrequiredstring[]

What to do next, ready to run.

per_second_usdnumber | null

What one second of the build costs, in USD: its tier's per-second rate. Absent for a build priced per build, before builds were billed per second.

reporequiredstring

setuprequiredstring[]

snapshot_deletedboolean

`true` when the snapshot this build made has since been deleted. Absent otherwise.

snapshot_idstring | null

The snapshot it produced; `null` until it is finished, and for a build that failed.

sourcerequiredobject

What it is being built from. The `kind` field says which of the three forms it is.

staterequiredstring

`queued` | `running` | `verified` | `built` | `rejected` | `failed`. `built` is a finished build that stored its snapshot with no verification command to run (an image built without `verify`): done and ready to start, like `verified`, but nothing was verified.

tierrequiredstring

tier_assignedrequiredstring

verificationobject

What the verification command did. `null` until there is a snapshot to report it for.

verifiedrequiredboolean

True when the build finished `verified` and its verification command passed. False while it is queued or running, when it failed or was rejected, and for an image built without `verify` (state `built`: stored, but nothing was verified). Nothing is stored if the command exits non-zero; the time the build ran is billed.

verifyrequiredstring

The verification command, as it was given.

### GET/v1/snapshots/builds/{id}/build-log

Auth: API key

The tail of the build log. `?tail=N` lines.

#### Parameters

idrequiredpath · string

tailquery · integer

#### Answer 200 · BuildLogView · application/json

build_idrequiredstring

logrequiredstring[]

The last `tail` lines of the build's output, oldest first. Empty while the build is `queued`.

staterequiredstring

`queued` | `running` | `verified` | `built` | `rejected` | `failed` (`built`: stored with no verification command to run).

### GET/v1/templates

Auth: none

The templates: ready-made starting points to fork (languages, app starters, agent tools, benchmarks). Each names the snapshot to fork, its version, what it starts from, and a count of what it has installed. No key needed.

#### Answer 200 · TemplateList · application/json

templatesrequiredTemplateSummary[]

### GET/v1/templates/{name}

Auth: none

One template: its setup steps, everything it has installed (each package and its version, by package manager, and each tool's version), and every version with what changed. A newer version, or one that fixes a security problem, is listed here first. No key needed.

#### Parameters

namerequiredpath · string

#### Answer 200 · TemplateDetail · application/json

categoryrequiredstring

dependenciesTemplateDependencies | null

imagerequiredstring

namerequiredstring

published_atstring | null

setuprequiredstring[]

snapshot_idrequiredstring

summaryrequiredstring

tierrequiredstring

titlerequiredstring

verifyrequiredstring

versionrequiredinteger

versionsrequiredTemplateVersionView[]

[Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)