---
title: "Import a sandbox image from a registry"
method: POST
path: "/sandbox-images/from-registry"
tags: ["Sandbox Images"]
---

# Import a sandbox image from a registry

`POST /sandbox-images/from-registry`

## Request

- Base URL: `https://api.thundercompute.com:8443/v1`
- URL: `https://api.thundercompute.com:8443/v1/sandbox-images/from-registry`
- Auth: API key in header `Authorization`

## Request body

- ThundertypesSandboxImageRegistryRequest
  - `display_name` string
  - `gatedFeatures` object
  - `password` string
  - `queue` boolean: Queue admits the import without checking future sandbox capacity.
  - `reference` string, required
  - `spec` ThundertypesSandboxResourceSpec
    - `cpu_count` integer, required
    - `gpu_count` integer
    - `gpu_type` 'A6000' | 'A100' | 'A100XL' | 'H100'
    - `memory_gib` integer, required
    - `storage_gib` integer, required
  - `username` string

## Response `200`

OK

- ThundertypesSandboxImageResponse
  - `attempt` integer
  - `created_at` string
  - `display_name` string
  - `failure` string
  - `failure_code` string
  - `id` string
  - `managed_digest` string
  - `managed_reference` string
  - `size_bytes` integer
  - `source_type` string
  - `state` 'BUILDING' | 'READY' | 'FAILED'
  - `updated_at` string
  - `upload` ThundertypesSandboxImageUpload
    - `expires_at` string
    - `host` string
    - `host_public_key` string
    - `path` string
    - `port` integer
    - `username` string

## Other responses

- `202`: Accepted
- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden

## Changes

- **2026-11-04** `62bf97c7bba4`: 2 info
  - added the new optional request property `queue`
  - added the new optional request property `spec`
- **2026-10-17** `d1b3a22ac150`: 1 info
  - added the new optional request property `gatedFeatures`
- **2026-09-18** `e6309ce01c8d`: 3 breaking, 3 info
  - added the new required request property `reference`
  - removed `#/components/schemas/thundertypes.SandboxImageRegistryRequest, subschema #1` from the request body `oneOf` list
  - the request's body type changed from no type to `object`
  - added the new optional request property `display_name`
  - …2 more
- **2026-09-10** `54488acbedcb`: 5 info
  - added the new optional request property `oneOf[#/components/schemas/thundertypes.SandboxImageRegistryRequest]/display_name`
  - added the optional property `display_name` to the response with the `200` status
  - added the optional property `display_name` to the response with the `202` status
  - added the optional property `size_bytes` to the response with the `200` status
  - …1 more
- **2026-09-05** `a2abb3908ae1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/thundercompute/apis/thunder-compute-api/changes/sandbox-images/from-registry/post.md)

---

[API](https://skmtc.dev/thundercompute/apis/thunder-compute-api.md) - [All operations](https://skmtc.dev/thundercompute/apis/thunder-compute-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thundercompute/apis/thunder-compute-api/revisions/62bf97c7bba4?raw)