Skip to main content
POST
Supply image to import a registry image asynchronously. Without image, the response provides an upload URL for a ZIP archive containing a Dockerfile and its build context. Processing starts after upload. Reusing name adds a version to the repository. The service assigns its tag; the request doesn’t accept a tag name. This operation doesn’t create a sandbox. Poll Get a sandbox image for build status, then list its tags. After a repeat push, the repository can briefly report the previous build’s BUILT or FAILED status. Observe the new build’s processing before interpreting a terminal status. Confirm a new tag is available before selecting that version. For the source archive and registry procedures, see Create a custom image.

Authorizations

​
Authorization
string
header
required

Send Authorization: Bearer <api_key>. The legacy Authorization: Api-Key <api_key> scheme is also accepted.

Headers

​
X-Team-Id
string

Optional team ID. Must match the team_id query parameter when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden.

Minimum string length: 1

Query Parameters

​
team_id
string

Optional team ID. Must match X-Team-Id when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden.

Minimum string length: 1

Body

application/json

Push a sandbox image from a source archive or an existing registry image.

​
name
string
required

Target image repository name. Reusing a name pushes a new version to the existing repository.

Minimum string length: 1
Example:

"base-image"

​
image
string

Optional source registry image reference including a registry hostname. When omitted, the response provides an archive upload URL. The uploaded ZIP archive must not exceed 5 GB.

Example:

"docker.io/b10/base-image:latest"

​
docker_config
string
write-only

Optional serialized registry authentication configuration for importing a private image. Used only when image is supplied; never returned.

Example:

"{\"auths\":{\"https://index.docker.io/v1/\":{\"auth\":\"YjEwLXJldmlldzpkZW1vLW5vdC1hLXZhbGlkLXJlZ2lzdHJ5LXRva2Vu\"}}}"

​
memory
integer

Memory in megabytes of the temporary environment that builds the source archive or imports the registry image. Omit it to use the default size. Does not change the memory of sandboxes created from the image.

Required range: 1 <= x <= 32768
Example:

16384

​
volume
integer

Scratch disk in megabytes attached to the temporary build environment for intermediate layers. Set it for large images that run out of space while building or importing. 0 builds in memory, which is the default. Teams with HIPAA compliance enabled accept only 0.

Required range: 0 <= x <= 131072
Example:

32768

Response

Request accepted.

Accepted image push. Acceptance does not imply readiness; poll GET /sandboxes/images/{image_name} until status is BUILT or FAILED.

​
name
string
required

Target image repository name.

Example:

"base-image"

​
status
enum<string>
required

Image processing status. Only BUILT images are ready to use.

Available options:
UPLOADING,
BUILDING,
BUILT,
FAILED
Example:

"BUILDING"

​
upload_url
string<uri>

Temporary signed URL for uploading the source ZIP archive with HTTP PUT. Present only when no source image was supplied. The uploaded ZIP archive must not exceed 5 GB. Uploading starts asynchronous processing. This storage upload is separate from the API endpoints.

Example:

"https://uploads.b10.run/images/base-image/20260916212658/source.zip?expires=2026-09-16T22%3A26%3A58Z&signature=demo-not-a-valid-upload-signature"

​
upload_headers
object

Headers the source archive upload must send, in addition to Content-Type, with exactly these names and values. Present only with upload_url, when memory or volume was set. upload_url is signed for these headers, so storage rejects an upload that omits or changes them. Treat names and values as opaque.

​
image
string

Registered image reference including its tag, when available. Tags are assigned by the service; GET /sandboxes/images/{image_name}/tags returns the available tags once processing completes.

Example:

"b10/base-image:latest"