{
  "openapi": "3.1.0",
  "info": {
    "title": "Bartender API",
    "version": "1",
    "description": "API for managing sandboxes and snapshots."
  },
  "servers": [
    {
      "url": "/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Tags": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "User-defined key-value labels (both keys and values are strings)."
      },
      "Sandbox": {
        "type": "object",
        "required": [
          "id",
          "organization_id",
          "project_id",
          "snapshot_id",
          "cpu",
          "memory_bytes",
          "agent",
          "ttl",
          "tags",
          "termination_policy",
          "status",
          "status_reason",
          "created_at",
          "started_at",
          "resized_at",
          "recovery_at",
          "terminated_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The sandbox's unique identifier."
          },
          "organization_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "project_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "starting",
              "running",
              "terminating",
              "terminated",
              "failed_to_start",
              "recovering",
              "unrecovered"
            ]
          },
          "snapshot_id": {
            "type": "string",
            "format": "uuid",
            "description": "The snapshot the sandbox boots from. The snapshot produced when the sandbox terminates is aliased as `sandbox:<sandbox id>`.\n"
          },
          "cpu": {
            "type": "number",
            "description": "CPU allocation in cores."
          },
          "memory_bytes": {
            "type": "integer",
            "description": "Memory allocation in bytes."
          },
          "agent": {
            "type": "object",
            "description": "Connection details for the in-sandbox agent.",
            "required": [
              "version",
              "token",
              "url"
            ],
            "properties": {
              "version": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "token": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Null unless the sandbox is running."
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Null unless the sandbox is running."
              }
            }
          },
          "ttl": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Seconds after creation before the sandbox is automatically terminated. Null disables automatic termination.\n"
          },
          "tags": {
            "$ref": "#/components/schemas/Tags"
          },
          "termination_policy": {
            "description": "The termination policy, or null for an ephemeral sandbox (no snapshot is taken and it is deleted on termination).\n",
            "anyOf": [
              {
                "$ref": "#/components/schemas/TerminationPolicy"
              },
              {
                "type": "null"
              }
            ]
          },
          "experimental": {
            "$ref": "#/components/schemas/SandboxExperimental"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "terminated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "status_reason": {
            "type": "string",
            "enum": [
              "cold_start_requested",
              "restore_requested",
              "cold_started",
              "restored",
              "out_of_capacity",
              "internal_error",
              "autoterminated",
              "termination_requested",
              "crashed",
              "oom_killed",
              "evicted",
              "node_lost",
              "cluster_lost"
            ]
          },
          "resized_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "recovery_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TerminationPolicy": {
        "type": "object",
        "description": "The policy applied when a sandbox terminates.",
        "required": [
          "snapshot"
        ],
        "properties": {
          "snapshot": {
            "$ref": "#/components/schemas/TerminationSnapshot"
          }
        }
      },
      "SandboxExperimental": {
        "type": "object",
        "description": "Experimental features. Their API may change at short notice.\n",
        "required": [
          "network_policy"
        ],
        "properties": {
          "network_policy": {
            "description": "The network policy, or null when the sandbox has none.\n",
            "anyOf": [
              {
                "$ref": "#/components/schemas/NetworkPolicy"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "CreateSandboxExperimental": {
        "type": "object",
        "description": "Experimental features. Their API may change at short notice.\n",
        "additionalProperties": false,
        "properties": {
          "network_policy": {
            "description": "Who may reach the sandbox. Omit for no restriction.\n",
            "$ref": "#/components/schemas/NetworkPolicy"
          }
        }
      },
      "NetworkPolicy": {
        "type": "object",
        "description": "Who may reach the sandbox through its URL. Without a network policy, a sandbox can be reached on every port. With one, every inbound request is blocked except those its `inbound_allowlist` admits: a request is admitted when a rule covers its port and its client. Rules can overlap; if any rule covering a request has `requires_token`, the request must present the token, even where another covering rule needs none. An empty allowlist admits nothing. Outbound rules are not supported yet.\n\nThe sandbox's agent port (57468, which the SDKs and the agent URL use) is never filtered; the agent authenticates every request itself.\n",
        "additionalProperties": false,
        "properties": {
          "inbound_allowlist": {
            "type": "array",
            "maxItems": 128,
            "items": {
              "$ref": "#/components/schemas/AllowRule"
            }
          }
        }
      },
      "AllowRule": {
        "type": "object",
        "required": [
          "ports"
        ],
        "properties": {
          "ports": {
            "type": "array",
            "minItems": 1,
            "maxItems": 64,
            "items": {
              "type": "string"
            },
            "description": "The ports the rule admits requests to: ports, inclusive ranges `low-high`, or `*` for every port.\n",
            "examples": [
              [
                "80",
                "8000-8100"
              ]
            ]
          },
          "from": {
            "type": "array",
            "minItems": 1,
            "maxItems": 64,
            "items": {
              "type": "string"
            },
            "description": "The clients the rule admits requests from: `*`, IPs, or CIDRs. Defaults to `[\"*\"]`, every client.\n",
            "examples": [
              [
                "10.0.0.0/8",
                "203.0.113.7"
              ]
            ]
          },
          "requires_token": {
            "type": "boolean",
            "default": false,
            "description": "Admit a request only if it presents the sandbox's agent token (`agent.token`) in the `X-Sandbox-Token` header. The header is removed before the request reaches the sandbox.\n"
          }
        }
      },
      "TerminationSnapshot": {
        "type": "object",
        "description": "The snapshot captured when a sandbox terminates.",
        "properties": {
          "memory": {
            "type": "boolean",
            "default": false,
            "description": "When true both the filesystem and memory are snapshotted (hibernate); when false only the filesystem is snapshotted (stop).\n"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Aliases to apply to the produced snapshot."
          },
          "ttl": {
            "type": "integer",
            "minimum": 1,
            "description": "Seconds after which the snapshot produced on termination expires. Must be > 0. Omit to keep the snapshot indefinitely.\n"
          },
          "tags": {
            "$ref": "#/components/schemas/Tags"
          }
        }
      },
      "Snapshot": {
        "type": "object",
        "required": [
          "id",
          "organization_id",
          "project_id",
          "byte_size",
          "tags",
          "ttl",
          "memory",
          "created_at",
          "retired_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "organization_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "project_id": {
            "type": "string"
          },
          "byte_size": {
            "type": "integer"
          },
          "tags": {
            "$ref": "#/components/schemas/Tags"
          },
          "ttl": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "Seconds after creation before the snapshot is automatically retired, or null if it is kept indefinitely.\n"
          },
          "memory": {
            "type": "boolean",
            "description": "Whether the snapshot includes a memory snapshot."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "retired_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the snapshot was retired, or null if it is still active. A retired snapshot can no longer be used to create new sandboxes and is eventually deleted.\n"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SnapshotAlias": {
        "type": "object",
        "required": [
          "snapshot_id",
          "alias",
          "created_at"
        ],
        "properties": {
          "snapshot_id": {
            "type": "string",
            "format": "uuid"
          },
          "alias": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContainerRegistryCredential": {
        "type": "object",
        "required": [
          "username",
          "password",
          "registry_url",
          "expired_at"
        ],
        "properties": {
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          },
          "registry_url": {
            "type": "string",
            "description": "Registry URL including the namespace path (e.g. registry.example.com/nbswy3dp)."
          },
          "expired_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "SandboxPage": {
        "type": "object",
        "required": [
          "data",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Sandbox"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor for the next page; `null` when there are no more items."
          }
        }
      },
      "SnapshotPage": {
        "type": "object",
        "required": [
          "data",
          "next_cursor"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Snapshot"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cursor for the next page; `null` when there are no more items."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "errors"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "parameter": {
                  "type": "string"
                },
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                },
                "details": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "paths": {
    "/authorize": {
      "post": {
        "operationId": "authorize",
        "summary": "Authorize access to a project or container registry project",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "project_id": {
                    "type": "string",
                    "description": "Project ID to authorize access to. Accepts a plain project ID (proj_* or ws_*) or a base32-encoded project ID from the container registry path."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Authorized."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/container-registries/default/credentials": {
      "post": {
        "operationId": "issueContainerRegistryCredential",
        "summary": "Issue a container registry credential for the authenticated user",
        "description": "Returns credentials (username, password, registry URL) for authenticating with the container registry. The registry URL includes the user's namespace path derived from their project ID.\n",
        "responses": {
          "201": {
            "description": "Credential issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContainerRegistryCredential"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sandboxes": {
      "get": {
        "operationId": "listSandboxes",
        "summary": "List sandboxes",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Sandbox ID returned as `next_cursor` from a previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "statuses[]",
            "in": "query",
            "description": "Filter by status; matches sandboxes in any of the given statuses.",
            "style": "form",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "starting",
                  "running",
                  "terminating",
                  "terminated",
                  "failed_to_start",
                  "recovering",
                  "unrecovered"
                ]
              }
            }
          },
          {
            "name": "snapshot_id",
            "in": "query",
            "description": "Filter by snapshot; matches sandboxes created from the given snapshot.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "description": "Filter by tags; matches sandboxes whose tags contain all given pairs.",
            "style": "deepObject",
            "explode": true,
            "schema": {
              "$ref": "#/components/schemas/Tags"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of sandboxes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createSandbox",
        "summary": "Create a sandbox",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "snapshot_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID of the snapshot to use. One of snapshot_id or snapshot_alias is required.\n"
                  },
                  "snapshot_alias": {
                    "type": "string",
                    "description": "Alias of the snapshot to use. One of snapshot_id or snapshot_alias is required.\n"
                  },
                  "cpu": {
                    "type": "number",
                    "description": "CPU allocation in cores. Defaults to 1 when omitted.\n",
                    "minimum": 0.1,
                    "maximum": 16,
                    "default": 1
                  },
                  "memory_bytes": {
                    "type": "integer",
                    "description": "Memory allocation in bytes. Must be between 1 GB and 8 GB per requested CPU. Defaults to 2 GB when omitted.\n",
                    "minimum": 200000000,
                    "maximum": 32000000000,
                    "default": 2000000000
                  },
                  "ttl": {
                    "type": "integer",
                    "description": "Seconds after creation before the sandbox is automatically terminated. Must be > 0. Omit to disable automatic termination.\n",
                    "minimum": 1
                  },
                  "tags": {
                    "$ref": "#/components/schemas/Tags",
                    "description": "User-defined key-value labels (both keys and values are strings). Keys must be at most 59 letters, digits, hyphens, underscores, and dots, and must start and end with a letter or a digit.\n"
                  },
                  "termination_policy": {
                    "description": "The termination policy. Omit for an ephemeral sandbox (no snapshot, deleted on termination).\n",
                    "$ref": "#/components/schemas/TerminationPolicy"
                  },
                  "experimental": {
                    "$ref": "#/components/schemas/CreateSandboxExperimental"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Sandbox created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Sandbox"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/sandboxes/batch": {
      "get": {
        "operationId": "batchGetSandboxes",
        "summary": "Batch get sandboxes by IDs",
        "parameters": [
          {
            "name": "ids[]",
            "in": "query",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "maxItems": 100
            },
            "style": "form",
            "explode": true,
            "description": "List of sandbox IDs. Maximum 100, no duplicates."
          }
        ],
        "responses": {
          "200": {
            "description": "List of sandboxes (preserves request order; missing IDs are omitted).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Sandbox"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/sandboxes/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid",
            "description": "The sandbox's unique identifier."
          }
        }
      ],
      "get": {
        "operationId": "getSandbox",
        "summary": "Get a sandbox by ID",
        "responses": {
          "200": {
            "description": "Sandbox.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Sandbox"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/sandboxes/{id}/terminate": {
      "post": {
        "operationId": "terminateSandbox",
        "summary": "Terminate a sandbox",
        "description": "Terminates a sandbox. After this operation the sandbox cannot be used again.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The sandbox's unique identifier."
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "snapshot": {
                    "description": "What this teardown snapshots, overriding the snapshot the sandbox's stored termination policy would take. Omit to keep the stored policy; null makes the teardown ephemeral (no snapshot).\n",
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/TerminationSnapshot"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sandbox with updated status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Sandbox"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/sandboxes/{id}/wait": {
      "post": {
        "operationId": "waitForSandbox",
        "summary": "Wait for a sandbox to reach a terminal status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The sandbox's unique identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Sandbox at terminal status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Sandbox"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/snapshots": {
      "get": {
        "operationId": "listSnapshots",
        "summary": "List snapshots",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Snapshot ID returned as `next_cursor` from a previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "description": "Filter by tags; matches snapshots whose tags contain all given pairs.",
            "style": "deepObject",
            "explode": true,
            "schema": {
              "$ref": "#/components/schemas/Tags"
            }
          },
          {
            "name": "exclude_retired",
            "in": "query",
            "description": "When true, retired snapshots are excluded. Defaults to false.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of snapshots.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SnapshotPage"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createSnapshot",
        "summary": "Create a snapshot for a container image",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "image"
                ],
                "properties": {
                  "image": {
                    "type": "string",
                    "description": "Container image reference. Parsed as `[registry/][repository/]name[:tag]`, using Docker Hub and `latest` as defaults when omitted.\n"
                  },
                  "architecture": {
                    "type": "string",
                    "enum": [
                      "amd64",
                      "arm64"
                    ],
                    "description": "Expected image architecture."
                  },
                  "ttl": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Seconds after creation before the snapshot is automatically deleted. Omit to keep the snapshot indefinitely.\n"
                  },
                  "tags": {
                    "$ref": "#/components/schemas/Tags"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Snapshot created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/snapshots/batch": {
      "get": {
        "operationId": "batchGetSnapshots",
        "summary": "Batch get snapshots by IDs",
        "parameters": [
          {
            "name": "ids[]",
            "in": "query",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "maxItems": 100
            },
            "style": "form",
            "explode": true,
            "description": "List of snapshot UUIDs. Maximum 100, no duplicates."
          }
        ],
        "responses": {
          "200": {
            "description": "List of snapshots (preserves request order; missing IDs are omitted).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Snapshot"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/snapshots/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "getSnapshot",
        "summary": "Get a snapshot by ID",
        "responses": {
          "200": {
            "description": "Snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/snapshots/{id}/retire": {
      "post": {
        "operationId": "retireSnapshot",
        "summary": "Retire a snapshot",
        "description": "Retires the snapshot. Once retired, the snapshot can no longer be used to create new sandboxes, and it is eventually deleted, provided no sandbox still references it.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The retired snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/snapshots/@{alias}": {
      "parameters": [
        {
          "name": "alias",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "getSnapshotByAlias",
        "summary": "Get a snapshot by alias",
        "responses": {
          "200": {
            "description": "Snapshot.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Snapshot"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/snapshots/{snapshot_id}/aliases": {
      "parameters": [
        {
          "name": "snapshot_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "operationId": "listSnapshotAliases",
        "summary": "List a snapshot's aliases",
        "responses": {
          "200": {
            "description": "The snapshot's aliases.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SnapshotAlias"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "operationId": "aliasSnapshot",
        "summary": "Assign an alias to a snapshot",
        "description": "Points the alias at the snapshot. If an alias of the same name already exists in the project, it is repointed at this snapshot (an upsert).\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "alias"
                ],
                "properties": {
                  "alias": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Alias assigned."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/snapshot-aliases/{alias}": {
      "parameters": [
        {
          "name": "alias",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "delete": {
        "operationId": "deleteSnapshotAlias",
        "summary": "Delete a snapshot alias",
        "description": "Deletes the alias in the caller's project. Idempotent: succeeds whether or not the alias exists.\n",
        "responses": {
          "204": {
            "description": "Alias deleted."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  }
}