images

Build a custom image from a Dockerfile, an OCI image or a recipe.

Returns at once with state queued; poll GET /v1/images/{id}, follow GET /v1/images/{id}/logs?follow=true, or send Prefer: wait=N. The build runs in its own Firecracker guest with the same public-web egress as a sandbox, never on the host. An organization runs one build at a time until it holds credit, bought or given, then four. An identical plan in the same organization, last built by the same builder version, is copied instead of rebuilt, and a build that shares its first steps with an earlier one starts from that build's checkpoint. Building is free; the image's storage is recorded as usage.

post/v1/images

Request

  • Base URL: https://api.withruntime.com
  • URL: https://api.withruntime.com/v1/images
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Replaying the same key with the same request within 24 hours returns the first result and never repeats the effect. A refusal is not kept: a request refused before it ran (no_capacity, busy, a limit) runs afresh when sent again with its key. The SDKs send one automatically; the server makes one when absent and returns it in the idempotency-key response header.

Request body

namestring

Your own handle for the resource. Letters, digits, dot, dash, underscore.

labelsobject

Your own key/value tags, at most 32. Filter lists with label=key:value.

regionstring

Omit for the default region.

tagsstring[]

Tags this build takes when it is ready. A named image with none given takes latest.

dockerfilestring

A Dockerfile: multi-stage builds, ARG, COPY --from, heredocs, ADD from a URL. FROM a public or private image, FROM scratch, or FROM runtime for Runtime's own base. COPY reads files or context.

imagestring

An OCI image to use as it is, plus Runtime's guest agent.

dockerignorestring

The context's .dockerignore; excluded files are never copied.

targetstring

Build this stage as the image instead of the last one.

buildArgsobject

Environment every process in the image starts with.

envobject

Environment every process in the image starts with.

cacheboolean

Start from, and keep, checkpoints of earlier builds of this organization. false builds every step and pulls the base again. A base named by its tag is pinned to the digest it names now either way, so a moved tag is never served from an old pull.

Response

Success

idstring required
kind'image' required
statusstring required
state'queued' | 'building' | 'ready' | 'failed' | 'deleting' | 'deleted' required
namestring nullable
versioninteger nullable
tagsstring[]
sizeBytesinteger nullable

The image's whole file, once it is ready. Its storage is charged on this.

sizeMiBinteger nullable
storedBytesinteger nullable

The part of the file that shares nothing with other files on its server, measured when it was built; often 0, since an image is built on a shared base. Not what it is charged on: sizeBytes is.

errorstring nullable
createdAtstring

Changes

No recorded changes to this operation across all 1 revision of this API.