Snapshots

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[]