Skip to main content
Prepare an image on selected providers

Authorizations

Authorization
string
header
required

BoxRouter API key; never an upstream provider key.

Headers

Idempotency-Key
string

Optional for this operation. Preserve the same stable identifier when retrying an uncertain response; never reuse it for new work. If omitted where allowed, Cloud generates a request-scoped key that cannot reconcile a later retry. Do not include credentials or payloads. Stable identifier for one logical mutation.

Required string length: 1 - 128

Body

application/json

Two forms; send exactly one. {image, providers, sizes?} prepares on the named providers. {match, top?} takes the body you send to POST /sandboxes or POST /sandboxes/match: Cloud ranks routes exactly as that create would now, under this workspace's payer rules, and prepares match.image on the first top distinct providers, at match.resources. Fields that do not choose a route, such as env and labels, are ignored. Ranking can change later, for example when prices or measured start times change, so a later create may pick a provider that was not prepared.

providers
required

Provider names or all providers configured for this workspace.

Minimum array length: 1
Minimum string length: 1
image
required if providers is set

Image to prepare. Only with providers. A string is an OCI image reference. Use {private_oci} for an image whose registry needs a login, together with registry_credentials; it is prepared only on routes that use your own provider keys. A Dockerfile object uses the same source text and optional uploaded context artifact as a sandbox create. Only offerings declaring that prepared source and context mode are selected. The whole JSON request is limited to 64 KiB.

Minimum string length: 1
registry_credentials
object

Request-only login for a private_oci image; required with it and refused without it. With match, send it inside the match body instead. Both strings are non-empty, at most 64 KiB UTF-8 bytes together. It is passed to the provider to set up the copy and is never stored, logged, traced or returned.

sizes
integer[]

Optional memory sizes to prepare, expressed in GiB. Only with providers.

Minimum array length: 1
Required range: x >= 1
match
object
required if top is set

A sandbox create body. Its image is an OCI reference or Dockerfile build object, optionally with context_artifact_id. A missing image, provider_default, an existing provider artifact has nothing to prepare and is refused. Only declared prepared source/context variants are eligible. A private_oci image is prepared with the body's registry_credentials, only on routes that use your own provider keys.

top
integer
default:1

With match, how many of the best-ranked distinct providers to prepare on. Fewer are prepared when fewer providers can run the create.

Required range: x >= 1

Response

Preparation started or already in progress.

image
string
required

Resolved OCI reference or the canonical sha256 content selector of a Dockerfile source and context.

providers
object[]
required