Skip to content

Image API reference

What a machine boots: a root filesystem, its environment and its start.

Base URL: https://api.withruntime.com. Authentication, idempotency and errors work the same way for every product.

Its states: making, ready, failed, deleted.

Updated .md

Endpoints#

Method Path Description
GET /v2/images/{id} Get a image
GET /v2/images List images
POST /v2/images/context:missing missing
PUT /v2/images/context/{digest} put
DELETE /v2/images/{id} Delete a image
POST /v2/images Create a image
GET /v2/images/{id}/logs logs

Get a image#

GET /v2/images/{id}

Returns an image, by its ID, its name (its newest version) or one of its tags (name:tag).

Its action, for a key's grant: images:get.

Path: id.

Returns a Stored.

In v1: GET /v1/images/{id}.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/images/IMAGE_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.images.get("IMAGE_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.images.get("IMAGE_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.images.get("IMAGE_ID")
Terminalruntime images get IMAGE_ID

List images#

GET /v2/images

Lists the project's images, newest first.

Its action, for a key's grant: images:list.

Query:

Field Type Required Description
name string No Only those of this name.
state string No Only those in these states, comma-separated.
label list of string No Only those with every label given (repeat it for several): key:value, or a key for any value.
cursor string No Where the page starts: a page's next.
limit integer No The most items the page holds. At least 1. At most 200. Default: 50.

Returns a page: items, each a Stored, and next, where the next page starts, none on the last.

In v1: GET /v1/images.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/images" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.images.list();
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.images.list()
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.images.list
Terminalruntime images list

missing#

POST /v2/images/context:missing

Returns which chunks of a build context still need uploading. The chunks it holds count as used, so they are kept for the build that names them: a chunk is kept 24 hours after its last use, and an organization's build context holds at most 200 MiB.

Its action, for a key's grant: images:write.

Body: a ContextAsked.

Returns a ContextMissing.

In v1: POST /v1/images/context/missing.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/images/context:missing" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "digests": ["example"] }'
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.images.missing({ digests: ["example"] });
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.images.missing(digests=["example"])
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.images.missing(digests: ["example"])
Terminalruntime images missing --digests example

put#

PUT /v2/images/context/{digest}

Uploads one chunk of a build context: the request's bytes, 1 byte to 1 MiB, named by their SHA-256. Asked again, it stores nothing more.

Its action, for a key's grant: images:write.

Path: digest.

Body: the bytes, application/octet-stream.

Returns a ChunkStored.

In v1: PUT /v1/images/context/{digest}.

Examples:

Terminalcurl -X PUT "https://api.withruntime.com/v2/images/context/DIGEST_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -H "Content-Type: application/octet-stream" \  --data-binary 'hello'
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.images.put("DIGEST_ID", new TextEncoder().encode("hello\n"));
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.images.put("DIGEST_ID", b"hello\n")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.images.put("DIGEST_ID", "hello\n")
Terminalruntime images put DIGEST_ID < hello.txt

Delete a image#

DELETE /v2/images/{id}

Deletes an image version. Sandboxes already started from it keep running. One an App boots from is refused with image_in_use (409) naming the App.

Its action, for a key's grant: images:delete.

Path: id.

Returns a Stored.

In v1: POST /v1/images/{id}:delete.

Examples:

Terminalcurl -X DELETE "https://api.withruntime.com/v2/images/IMAGE_ID" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.images.delete("IMAGE_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.images.delete("IMAGE_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.images.delete("IMAGE_ID")
Terminalruntime images delete IMAGE_ID

Create a image#

POST /v2/images

Builds an image from an OCI image or a Dockerfile on a machine of its own, and returns it at once, making: ready once built, else failed with error. Each build of a name is its next version. Asked again with the same Idempotency-Key, it returns the same one.

Its action, for a key's grant: images:create.

Body: a ImageCreate.

Returns a Stored.

In v1: POST /v1/images.

Examples:

Terminalcurl -X POST "https://api.withruntime.com/v2/images" \  -H "Authorization: Bearer $RUNTIME_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.images.create();
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.images.create()
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.images.create
Terminalruntime images create

logs#

GET /v2/images/{id}/logs

Returns an image's build log after a line, as the build writes it and once it has ended.

Its action, for a key's grant: images:read.

Path: id.

Query:

Field Type Required Description
after integer No Lines after this one. At least 0. Default: 0.
limit integer No At most this many lines. At least 1. At most 1000. Default: 1000.
follow boolean No Answer as NDJSON events until the build ends: line for each, then done with the image, or continue with the after to follow on from; as Accept: application/x-ndjson does.

Returns a ImageLogs.

In v1: GET /v1/images/{id}/logs.

Examples:

Terminalcurl -X GET "https://api.withruntime.com/v2/images/IMAGE_ID/logs" \  -H "Authorization: Bearer $RUNTIME_API_KEY"
TypeScriptimport { Runtime } from "withruntime";const runtime = new Runtime(); // RUNTIME_API_KEY from the environmentconst result = await runtime.images.logs("IMAGE_ID");
Pythonfrom withruntime import Runtimeruntime = Runtime()  # RUNTIME_API_KEY from the environmentresult = runtime.images.logs("IMAGE_ID")
rubyrequire "withruntime"kit = Withruntime::Generated::Kit.new # RUNTIME_API_KEY from the environmentresult = kit.images.logs("IMAGE_ID")
Terminalruntime images logs IMAGE_ID

Objects#

Stored

Stored data: a snapshot, an image or a volume.

Field Type Required Description
id string Yes Its ID.
object one of snapshot, image, volume Yes Its kind: snapshot, image or volume.
name string No Its name, unique in its project among its kind.
state one of making, ready, failed, deleted Yes Where it is.
labels labels (keys under runtime. are Runtime's) Yes Its labels.
sizeBytes integer Yes What it was made to hold, in bytes.
storedBytes integer Yes What it holds now, in bytes.
parentId string No What it was made from (a snapshot's sandbox, an image's base), if anything.
attachedTo string No The machine it is attached to now, if any.
createdAt string (RFC 3339) No When it was made.
version integer No An image's version of its name: each build or keep of a name is its next.
tags list of string No An image's tags, each name:tag.
error string No Why an image's build failed.
deletedAt string (RFC 3339) No When it was deleted: a delete's answer, its state deleted.

ContextAsked

Chunks of a build's context, by their SHA-256.

Field Type Required Description
digests list of string Yes At most 10,000 SHA-256 digests, each 64 lowercase hex digits.

ContextMissing

Which chunks of a build's context still need uploading.

Field Type Required Description
missing list of string Yes The digests asked for that the organization's build context does not hold, sorted, each once.

ChunkStored

A chunk of a build's context, uploaded.

Field Type Required Description
sha256 string Yes Its SHA-256.
size integer Yes Its size in bytes.
stored boolean Yes Stored by this call: false when the build context held it already.

ImageFile

A file of an image build's context, sent inline.

Field Type Required Description
path string Yes Its path in the build context, which COPY and ADD read.
content string Yes Its content: UTF-8 text, or base64 when encoding says so.
encoding one of utf8, base64 No utf8 (the default) or base64.
mode integer No Its permission bits, 0 to 511 (0777 in octal). At least 0. At most 511.

ImageRecipe

An image described by its packages, files and commands, rendered into a Dockerfile: FROM its base, its env, one RUN each for its apt, pip and npm packages, its files, then its commands in workdir.

Field Type Required Description
base string No The image it starts from: runtime (the default, Runtime's own) or an OCI image, such as python:3.12-slim.
apt list of string No Debian packages, each name or name=version. At most 500 items.
pip list of string No Python packages, each as pip takes one: pandas, numpy==2.1, uvicorn[standard]>=0.30. At most 500 items.
npm list of string No npm packages, installed globally: typescript, @scope/tool@1. At most 500 items.
commands list of string No Shell commands, each run by /bin/sh in workdir after the packages and files. At most 500 items.
env object of strings No Environment set before the packages; $NAME names its base's.
files list of ImageFile No Files written into the image, each path absolute: at most 1 MiB in all. At most 256 items.
workdir string No Where its commands run and its machines start: /workspace by default.

ImageArchive

A build context's archive: a tar (gzip allowed), cut into chunks of at most 1 MiB, each uploaded first (images.context.put).

Field Type Required Description
sha256 string Yes The whole archive's SHA-256, in hex.
size integer Yes Its size in bytes. At least 1.
chunks list of string Yes Its chunks' SHA-256s, in order. At most 200 items.

ImageContextFile

A regular file of a build context's archive.

Field Type Required Description
path string Yes Its path in the context.
sha256 string Yes Its SHA-256, in hex.
size integer Yes Its size in bytes.
mode integer No Its permission bits.

ImageContext

A build context uploaded as chunks: the SDKs and CLI make it from a folder and its .dockerignore.

Field Type Required Description
archive ImageArchive Yes The archive.
files list of ImageContextFile Yes Every regular file in it.

MachineStart

A command a machine starts at every fresh boot.

Field Type Required Description
cmd string (run by bash -lc) or list of strings (the program and its arguments) Yes The command: text, run by bash -lc, or the program and its arguments as a list, run without a shell.
cwd string No The directory it runs in; the user's home when omitted.
env object of strings No Environment variables to add.
readyPort integer No A port it listens on once ready: a create answers once something listens there. At least 1. At most 65535.
readyCommand string No A shell command that exits 0 once it is ready, run by /bin/sh -c in cwd until it does: a create answers once it has.
readyTimeoutSeconds integer No How long a create waits for readyPort or readyCommand, 1 to 300 seconds: 60 when omitted. At least 1. At most 300.

ImageBuild

What an image's build runs on: a machine of its own, deleted once the build ends.

Field Type Required Description
vcpu integer No Its vCPUs. At least 1. At most 8. Default: 2.
memoryGB number No Its memory in GB. At least 1. At most 16. Default: 4.
diskGB number No Its disk in GB: the base image, the earlier stages and the context. At least 4. At most 32. Default: 16.
timeoutSeconds integer No Seconds the build may run before it fails. At least 60. At most 3600. Default: 1800.

ImageCreate

An image to build, from exactly one of image and dockerfile.

Field Type Required Description
name string No Its name, 1 to 64 of a-z, 0-9, ., _ and -: each build of a name is its next version.
labels labels (keys under runtime. are Runtime's) No Labels to find it by.
tags list of string No Tags its name takes for it once it is ready; latest when it has a name and none is given. At most 16 items.
image string No An OCI image to use as it is, from a public registry: python:3.12-slim, ghcr.io/org/app:1.
dockerfile string No A Dockerfile: multi-stage builds, ARG, COPY --from, heredocs. COPY reads files.
recipe ImageRecipe No Packages, files and commands, rendered into a Dockerfile. Not with files or context.
files list of ImageFile No The Dockerfile's build context, inline: at most 1 MiB in all. Not with context. At most 256 items.
context ImageContext No The Dockerfile's build context, uploaded first as chunks: up to 200 MiB. Not with files.
dockerignore string No The context's .dockerignore: what it names is never copied.
target string No The stage to build instead of the last.
buildArgs object of strings No The Dockerfile's ARG values.
env object of strings No Environment every machine from it starts with, over the Dockerfile's ENV.
start MachineStart No What every machine from it starts at each fresh boot, in place of the Dockerfile's ENTRYPOINT and CMD.
build ImageBuild No What its build runs on.

ImageLogLine

One line of an image's build log.

Field Type Required Description
seq integer Yes Its number, from 1.
at string (RFC 3339) Yes When it was written.
stream one of build, system Yes build (the build's output) or system (Runtime's).
text string Yes The line, without its newline.

ImageLogs

An image's build log after a line.

Field Type Required Description
lines list of ImageLogLine Yes The lines after after, in order.
nextAfter integer Yes The last line's number: send it as after to read on.
state one of making, ready, failed, deleted Yes The image's state.
truncated boolean Yes Whether lines before these were dropped.
done boolean Yes Whether the build has ended: no line comes after these.
Try it on your own work.Signing up takes no card. Your first sandbox asks for one, and the trial starts then. Or paste the setup prompt into your agent.
Start your free trial