Create Snapshot

POST /v1/snapshots

Create a snapshot from an OCI image (async build via Celery).

Authentication

Requires authentication via: OAuth2PasswordBearer.

Parameters

Name	In	Type	Required	Description	Constraints
X-API-Key	header	string | null	No		nullable

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 worker auto-sizes based on extracted rootfs + 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"
            }
          },
          "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:

Field	Type	Required	Description	Constraints
oci_image	string	Yes	OCI image reference, e.g. 'python:3.12-slim'
name	string | null	No		nullable
vcpu_count	integer	No		default=2, min=1, max=8
memory_mb	integer	No		default=512, min=128, max=8192
build_args	object | null	No		nullable
build_args.extra_apt_packages	string | null	No	Space-separated apt packages	nullable
build_args.extra_pip_packages	string | null	No	Space-separated pip packages	nullable
build_args.extra_npm_packages	string | null	No	Space-separated npm packages	nullable
build_args.git_clone_url	string | null	No	Git repository URL to clone into /app/repo	nullable
build_args.git_clone_branch	string | null	No	Branch to clone (default: repo default)	nullable
build_args.disk_size_gb	integer | null	No	Root filesystem size in GB (1-16). Optional override; if omitted, the worker auto-sizes based on extracted rootfs + 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.envs	object<string, string> | null	No	Environment variables as key-value pairs	nullable
build_args.envs.*	string	No
build_args.post_build_cmd	string | null	No	Shell command to run after all packages are installed	nullable
type	string	No		default="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:

Field	Type	Required	Description	Constraints
id	string	Yes
name	string | null	No		nullable
status	string	Yes
source_vm_id	string | null	No		nullable
snapshot_type	string	Yes
type	string	No		default="user"
oci_image	string | null	No		nullable
vcpu_count	integer | null	No		nullable
memory_mb	integer | null	No		nullable
size_bytes	integer	No		default=0
is_public	boolean	No		default=false
last_error	string | null	No		nullable
created_at	string	Yes
updated_at	string	Yes

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:

Field	Type	Required	Description	Constraints
detail	array<object>	No
detail[]	object	No
detail[].loc	array<string | integer>	No
detail[].loc[]	string | integer	No
detail[].msg	string	No
detail[].type	string	No