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\"}}}"

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"

​
image
string

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

Example:

"b10/base-image:latest"