> ## Documentation Index > Fetch the complete documentation index at: https://docs.baseten.co/llms.txt > Use this file to discover all available pages before exploring further. # Push a sandbox image > Imports a sandbox image or starts an image build. 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](/reference/management-api/sandboxes/get-a-sandbox-image) for build status, then [list its tags](/reference/management-api/sandboxes/list-image-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](/sandboxes/manage-images#create-a-custom-image). ## OpenAPI ````yaml post /v1/sandboxes/images openapi: 3.1.0 info: description: REST API for management of Baseten resources title: Baseten management API version: 1.0.0 servers: - url: https://api.baseten.co security: - BearerAuth: [] paths: /v1/sandboxes/images: post: tags: - Images summary: Push a sandbox image description: >- With image supplied, import the registry image asynchronously. Otherwise return an upload URL for a ZIP source archive containing its Dockerfile and build context. The uploaded ZIP archive must not exceed 5 GB. Processing starts after upload. No sandbox is created. Poll the image until BUILT or FAILED. operationId: PushImage parameters: - $ref: '#/components/parameters/TeamId' - $ref: '#/components/parameters/TeamIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PushSandboxImageRequestV1' examples: archive: $ref: '#/components/examples/PushArchive' registry: $ref: '#/components/examples/PushRegistry' responses: '202': description: Request accepted. content: application/json: schema: $ref: '#/components/schemas/PushSandboxImageResponseV1' examples: archive: $ref: '#/components/examples/PushArchiveAccepted' registry: $ref: '#/components/examples/PushRegistryAccepted' '400': $ref: '#/components/responses/SandboxError400' '401': $ref: '#/components/responses/SandboxError401' '403': $ref: '#/components/responses/SandboxError403' '429': $ref: '#/components/responses/SandboxError429' '500': $ref: '#/components/responses/SandboxError500' components: parameters: TeamId: name: team_id in: query required: false description: >- 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. schema: minLength: 1 type: string TeamIdHeader: name: X-Team-Id in: header required: false description: >- 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. schema: minLength: 1 type: string schemas: PushSandboxImageRequestV1: type: object description: >- Push a sandbox image from a source archive or an existing registry image. properties: name: type: string description: >- Target image repository name. Reusing a name pushes a new version to the existing repository. minLength: 1 example: base-image image: type: string description: >- 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: type: string description: >- Optional serialized registry authentication configuration for importing a private image. Used only when image is supplied; never returned. writeOnly: true example: >- {"auths":{"https://index.docker.io/v1/":{"auth":"YjEwLXJldmlldzpkZW1vLW5vdC1hLXZhbGlkLXJlZ2lzdHJ5LXRva2Vu"}}} required: - name example: name: base-image image: docker.io/b10/base-image:latest docker_config: >- {"auths":{"https://index.docker.io/v1/":{"auth":"YjEwLXJldmlldzpkZW1vLW5vdC1hLXZhbGlkLXJlZ2lzdHJ5LXRva2Vu"}}} PushSandboxImageResponseV1: type: object description: >- Accepted image push. Acceptance does not imply readiness; poll GET /sandboxes/images/{image_name} until status is BUILT or FAILED. properties: name: type: string description: Target image repository name. example: base-image status: description: Image processing status. Only BUILT images are ready to use. allOf: - $ref: '#/components/schemas/SandboxImageStatusV1' example: BUILDING upload_url: type: string description: >- 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. format: uri 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: type: string description: >- 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 required: - name - status example: name: base-image status: BUILDING image: b10/base-image:latest SandboxImageStatusV1: type: string description: Image processing status. Only BUILT images are ready to use. enum: - UPLOADING - BUILDING - BUILT - FAILED readOnly: true example: BUILT examples: PushArchive: summary: Build an image from an uploaded source archive value: name: base-image description: >- Omit image and docker_config to request an upload URL. Those fields do not apply to source-archive uploads. PushRegistry: summary: Import an image with registry authentication value: name: base-image image: docker.io/b10/base-image:latest docker_config: >- {"auths":{"https://index.docker.io/v1/":{"auth":"YjEwLXJldmlldzpkZW1vLW5vdC1hLXZhbGlkLXJlZ2lzdHJ5LXRva2Vu"}}} description: >- Shows every request field. docker_config is serialized registry configuration with a deliberately invalid demonstration credential. PushArchiveAccepted: summary: Source upload required value: name: base-image status: UPLOADING upload_url: >- https://uploads.b10.run/images/base-image/20260916212658/source.zip?expires=2026-09-16T22%3A26%3A58Z&signature=demo-not-a-valid-upload-signature description: >- The signed upload URL is illustrative, with a nonfunctional signature. image is unavailable until processing produces a registered image reference. PushRegistryAccepted: summary: Image import accepted value: name: base-image status: BUILDING image: b10/base-image:latest description: No upload_url is returned for registry imports. responses: SandboxError400: description: >- Invalid request. Returns a JSON error with code, message, and optional details. content: application/json: example: code: INVALID_REQUEST message: One or more request parameters are invalid. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError401: description: >- Missing or invalid authentication. Returns a JSON error with code, message, and optional details. content: application/json: example: code: UNAUTHORIZED message: Provide a valid authentication token in the Authorization header. details: header: Authorization SandboxError403: description: >- Insufficient permissions. Returns a JSON error with code, message, and optional details. content: application/json: example: code: FORBIDDEN message: >- This authentication token does not grant permission to perform this operation. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError429: description: >- Request limit exceeded. Returns a JSON error with code, message, and optional details. content: application/json: example: code: RATE_LIMITED message: Too many requests. Try again in 30 seconds. details: retry_after_seconds: 30 SandboxError500: description: >- Internal server error. Returns a JSON error with code, message, and optional details. content: application/json: example: code: INTERNAL_ERROR message: The request could not be completed. Try again later. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 securitySchemes: BearerAuth: type: http scheme: bearer description: >- Send `Authorization: Bearer `. The legacy `Authorization: Api-Key ` scheme is also accepted. ````