Skip to main content

Create Snapshot

POST /v1/snapshots

Build a snapshot from an OCI image such as python:3.12-slim. The image must name a fixed tag or a digest (latest and other moving tags are refused). build_args can add apt, pip or npm packages, clone a git repository, set environment variables and run a command after installation; vcpu_count and memory_mb are the VM size it is built at. The call returns at once with status building; poll GET /v1/snapshots/{snapshot_id} until it is ready (or failed, with last_error), then pass its id as snapshot_id to POST /v1/vms.

Authentication​

Requires authentication via: OAuth2PasswordBearer.

Parameters​

NameInTypeRequiredDescriptionConstraints
X-API-Keyheaderstring | nullNonullable

Request Body​

Required: Yes

application/json​

Resolved schema:

{
"properties": {
"oci_image": {
"type": "string",
"title": "Oci Image",
"description": "OCI image reference, e.g. 'python:3.12-slim'"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"vcpu_count": {
"type": "integer",
"maximum": 8,
"minimum": 1,
"title": "Vcpu Count",
"default": 2
},
"memory_mb": {
"type": "integer",
"maximum": 8192,
"minimum": 128,
"title": "Memory Mb",
"default": 512
},
"build_args": {
"anyOf": [
{
"properties": {
"extra_apt_packages": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Extra Apt Packages",
"description": "Space-separated apt packages"
},
"extra_pip_packages": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Extra Pip Packages",
"description": "Space-separated pip packages"
},
"extra_npm_packages": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Extra Npm Packages",
"description": "Space-separated npm packages"
},
"git_clone_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Git Clone Url",
"description": "Git repository URL to clone into /app/repo"
},
"git_clone_branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Git Clone Branch",
"description": "Branch to clone (default: repo default)"
},
"disk_size_gb": {
"anyOf": [
{
"type": "integer",
"maximum": 16,
"minimum": 1
},
{
"type": "null"
}
],
"title": "Disk Size Gb",
"description": "Root filesystem size in GB (1-16). Optional override; if omitted, the build auto-sizes it from the image's contents plus headroom (minimum 3GB, maximum 16GB). If provided but smaller than required, the build fails with the required minimum."
},
"envs": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Envs",
"description": "Environment variables as key-value pairs"
},
"post_build_cmd": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Post Build Cmd",
"description": "Shell command to run after all packages are installed"
},
"template_app_cmd": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Template App Cmd",
"description": "Devbox template app command autostarted at VM boot (baked into the snapshot)"
},
"template_app_cwd": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Template App Cwd",
"description": "Working directory for the autostarted template app command"
}
},
"type": "object",
"title": "SnapshotBuildArgs"
},
{
"type": "null"
}
]
},
"type": {
"type": "string",
"pattern": "^(user|system)$",
"title": "Type",
"default": "user"
}
},
"type": "object",
"required": [
"oci_image"
],
"title": "SnapshotCreateRequest"
}

Field details:

FieldTypeRequiredDescriptionConstraints
oci_imagestringYesOCI image reference, e.g. 'python:3.12-slim'
namestring | nullNonullable
vcpu_countintegerNodefault=2, min=1, max=8
memory_mbintegerNodefault=512, min=128, max=8192
build_argsobject | nullNonullable
build_args.extra_apt_packagesstring | nullNoSpace-separated apt packagesnullable
build_args.extra_pip_packagesstring | nullNoSpace-separated pip packagesnullable
build_args.extra_npm_packagesstring | nullNoSpace-separated npm packagesnullable
build_args.git_clone_urlstring | nullNoGit repository URL to clone into /app/reponullable
build_args.git_clone_branchstring | nullNoBranch to clone (default: repo default)nullable
build_args.disk_size_gbinteger | nullNoRoot filesystem size in GB (1-16). Optional override; if omitted, the build auto-sizes it from the image's contents plus headroom (minimum 3GB, maximum 16GB). If provided but smaller than required, the build fails with the required minimum.min=1, max=16, nullable
build_args.envsobject<string, string> | nullNoEnvironment variables as key-value pairsnullable
build_args.envs.*stringNo
build_args.post_build_cmdstring | nullNoShell command to run after all packages are installednullable
build_args.template_app_cmdstring | nullNoDevbox template app command autostarted at VM boot (baked into the snapshot)nullable
build_args.template_app_cwdstring | nullNoWorking directory for the autostarted template app commandnullable
typestringNodefault="user", pattern=^(user|system)$

Responses​

201​

Successful Response

application/json​

Resolved schema:

{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"status": {
"type": "string",
"title": "Status"
},
"source_vm_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Vm Id"
},
"snapshot_type": {
"type": "string",
"title": "Snapshot Type"
},
"type": {
"type": "string",
"title": "Type",
"default": "user"
},
"oci_image": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Oci Image"
},
"vcpu_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Vcpu Count"
},
"memory_mb": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Memory Mb"
},
"size_bytes": {
"type": "integer",
"title": "Size Bytes",
"default": 0
},
"is_public": {
"type": "boolean",
"title": "Is Public",
"default": false
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"updated_at": {
"type": "string",
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"status",
"snapshot_type",
"created_at",
"updated_at"
],
"title": "SnapshotInfo"
}

Field details:

FieldTypeRequiredDescriptionConstraints
idstringYes
namestring | nullNonullable
statusstringYes
source_vm_idstring | nullNonullable
snapshot_typestringYes
typestringNodefault="user"
oci_imagestring | nullNonullable
vcpu_countinteger | nullNonullable
memory_mbinteger | nullNonullable
size_bytesintegerNodefault=0
is_publicbooleanNodefault=false
last_errorstring | nullNonullable
created_atstringYes
updated_atstringYes

400​

The image has no tag or digest, uses a moving tag such as latest, or vcpu_count is not 1, 2, 4, 6 or 8.

No response body.

401​

No credentials, or the Bearer token / X-API-Key is invalid.

No response body.

403​

The account is disabled, or a guest token was used; or your account cannot start VMs yet (the body's code says why), or only admins may create system snapshots.

No response body.

422​

Validation Error

application/json​

Resolved schema:

{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}

Field details:

FieldTypeRequiredDescriptionConstraints
detailarray<object>No
detail[]objectNo
detail[].locarray<string | integer>No
detail[].loc[]string | integerNo
detail[].msgstringNo
detail[].typestringNo

429​

Rate limit exceeded. Retry later.

No response body.