controlplane.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Unikraft Cloud Control Plane API",
    "description": "This specification describes the Unikraft Cloud Control Plane API, which provides mechanisms to interact with globally provided Unikraft Cloud system.",
    "contact": {
      "name": "Unikraft Support",
      "url": "https://unikraft.com/contact",
      "email": "support@unikraft.com"
    },
    "version": "v1.0.0"
  },
  "servers": [
    {
      "url": "https://controlplane.unikraft.cloud",
      "description": "Official Unikraft Cloud Control Plane API"
    }
  ],
  "paths": {
    "/v1/auth": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Get Authorization Status",
        "description": "Get authorization details for a token.",
        "operationId": "GetAuthorization",
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAuthorizationResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/auth/check": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Check Authorization of Sign-In Request",
        "description": "Check the authorization status of a request.  The responses are streamed\nback to the client, indicating whether the signin request is authorized or\nnot.",
        "operationId": "CheckAuthorization",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CheckAuthorizationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/CheckAuthorizationResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/auth/signin": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Request Sign-In",
        "description": "Initiate the sign-in process and return an authorization URL.  The user\nshould be redirected to this URL to complete the sign-in.",
        "operationId": "RequestSignin",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestSigninRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestSigninResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/images": {
      "get": {
        "tags": [
          "Images"
        ],
        "summary": "List Images",
        "description": "ListImages lists all images for the authenticated user.",
        "operationId": "ListImages",
        "parameters": [
          {
            "name": "details",
            "in": "query",
            "description": "Whether to include image tag details.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "namespace",
            "in": "query",
            "description": "Optional namespaces to filter images by.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListImagesResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/metros": {
      "get": {
        "tags": [
          "Metros"
        ],
        "summary": "Get Metros",
        "description": "ListMetros lists all available metros.",
        "operationId": "ListMetros",
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListMetroResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/nodes": {
      "get": {
        "tags": [
          "NodeService"
        ],
        "summary": "List Node Nodes",
        "description": "Get one or more nodes.\n\nReturns nodes matching the specified filters. If no filters are\nprovided, all nodes are returned.",
        "operationId": "ListNodes",
        "parameters": [
          {
            "name": "cloudprovider",
            "in": "query",
            "description": "Optional filter by cloud provider.",
            "schema": {
              "$ref": "#/components/schemas/CloudProvider"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Optional filter by state.",
            "schema": {
              "$ref": "#/components/schemas/NodeState"
            }
          },
          {
            "name": "metro",
            "in": "query",
            "description": "Optional filter by metro.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "region",
            "in": "query",
            "description": "Optional filter by region.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return.",
            "schema": {
              "type": "integer",
              "format": "uint32"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Offset for pagination.",
            "schema": {
              "type": "integer",
              "format": "uint32"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NameOrUUID"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListNodesResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      },
      "post": {
        "tags": [
          "NodeService"
        ],
        "summary": "Create Node Node",
        "description": "Create a new node.\n\nCreates a new compute node on the specified cloud provider. The node\nwill go through provisioning (PROVISIONING state) and configuration\n(CONFIGURING state) before becoming ready (READY state) for use.",
        "operationId": "ProvisionNode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProvisionNodeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvisionNodeResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      },
      "delete": {
        "tags": [
          "NodeService"
        ],
        "summary": "Delete Node Nodes",
        "description": "Delete one or more nodes.\n\nBatch deletion of nodes by their identifiers.",
        "operationId": "DestroyNode",
        "parameters": [
          {
            "name": "force",
            "in": "query",
            "description": "Force deletion even if nodes are in use.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NameOrUUID"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DestroyNodeResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      },
      "patch": {
        "tags": [
          "NodeService"
        ],
        "summary": "Update Node Nodes",
        "description": "Update one or more nodes.\n\nBatch update of mutable properties for multiple nodes.",
        "operationId": "UpdateNodes",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/NameOrUUID"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateNodesResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/nodes/activate": {
      "post": {
        "tags": [
          "NodeActivationService"
        ],
        "description": "Activates a new node, or renews an existing node's license. For first-time\nactivation, a secret must be provided. For renewal, the CSR self-signature\nis used as proof of key possession and the secret is omitted.",
        "operationId": "NodeActivate",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NodeActivateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NodeActivateResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/nodes/heartbeat": {
      "post": {
        "tags": [
          "NodeActivationService"
        ],
        "description": "Sends a heartbeat from a node to report its platform status.",
        "operationId": "NodeHeartbeat",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NodeHeartbeatRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NodeHeartbeatResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/nodes/provider/{cloudprovider}/regions": {
      "get": {
        "tags": [
          "NodeService"
        ],
        "summary": "List Regions",
        "description": "List available regions for a provider.\n\nReturns the regions available for provisioning on the specified cloud\nprovider, including availability zone information.",
        "operationId": "ListRegions",
        "parameters": [
          {
            "name": "cloudprovider",
            "in": "path",
            "description": "The cloud provider to list regions for.",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/CloudProvider"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListRegionsResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/nodes/provider/{cloudprovider}/types": {
      "get": {
        "tags": [
          "NodeService"
        ],
        "summary": "List Machine Types",
        "description": "List available machine types for a provider.\n\nReturns the machine types (instance types) available for provisioning\non the specified cloud provider.",
        "operationId": "ListMachineTypes",
        "parameters": [
          {
            "name": "cloudprovider",
            "in": "path",
            "description": "The cloud provider to list machine types for.",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/CloudProvider"
            }
          },
          {
            "name": "region",
            "in": "query",
            "description": "Optional region filter. Some providers have region-specific availability.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListMachineTypesResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/nodes/wait": {
      "get": {
        "tags": [
          "NodeService"
        ],
        "summary": "Wait for Node Nodes States",
        "description": "Wait for multiple nodes to reach specific states.",
        "operationId": "WaitNodes",
        "parameters": [
          {
            "name": "states",
            "in": "query",
            "description": "The desired state(s) to wait for.",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NodeState"
              }
            }
          },
          {
            "name": "timeout_ms",
            "in": "query",
            "description": "Timeout in milliseconds. Use -1 for infinite wait.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaitNodesResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/nodes/{uuid}": {
      "get": {
        "tags": [
          "NodeService"
        ],
        "summary": "Get Node Node by UUID",
        "description": "Get a single node by its UUID.",
        "operationId": "GetNodeByUUID",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "The UUID of the node to retrieve.",
            "required": true,
            "schema": {
              "example": "123e4567-e89b-12d3-a456-426614174000",
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListNodesResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      },
      "delete": {
        "tags": [
          "NodeService"
        ],
        "summary": "Delete Node Node by UUID",
        "description": "Destroy (delete) a node by its UUID.\n\nDeprovisions and deletes the node. The node will transition to\nDEPROVISIONING state and then be removed. If the node has a delete lock,\nthis operation will fail unless the lock is first removed.",
        "operationId": "DestroyNodeByUUID",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "The UUID of the node to delete.",
            "required": true,
            "schema": {
              "example": "123e4567-e89b-12d3-a456-426614174000",
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "force",
            "in": "query",
            "description": "Force deletion even if the node is in use.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DestroyNodeResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      },
      "patch": {
        "tags": [
          "NodeService"
        ],
        "summary": "Update Node Node by UUID",
        "description": "Update a node by its UUID.\n\nUpdates mutable properties of a node such as tags, delete lock,\nor SSH keys.",
        "operationId": "UpdateNodeByUUID",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "The UUID of the node to update.",
            "required": true,
            "schema": {
              "example": "123e4567-e89b-12d3-a456-426614174000",
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/UpdateNodePayload"
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateNodesResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    },
    "/v1/nodes/{uuid}/wait": {
      "get": {
        "tags": [
          "NodeService"
        ],
        "summary": "Wait for Node Node State by UUID",
        "description": "Wait for a node to reach a specific state.\n\nBlocks until the specified node reaches one of the desired states\nor the timeout is reached.",
        "operationId": "WaitNodeByUUID",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "The UUID of the node to wait for.",
            "required": true,
            "schema": {
              "example": "123e4567-e89b-12d3-a456-426614174000",
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "states",
            "in": "query",
            "description": "The desired state(s) to wait for. The request completes when any of\nthese states is reached.",
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NodeState"
              }
            }
          },
          {
            "name": "timeout_ms",
            "in": "query",
            "description": "Timeout in milliseconds. Use -1 for infinite wait.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "default",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaitNodesResponse"
                }
              }
            }
          }
        },
        "x-package": "controlplane"
      }
    }
  },
  "components": {
    "schemas": {
      "AWSConfig": {
        "required": [
          "dedicated_host",
          "region",
          "machine_type"
        ],
        "type": "object",
        "properties": {
          "vpc_id": {
            "example": "vpc-0123456789abcdef0",
            "type": "string",
            "description": "The VPC ID where the instance will be launched. If not specified, the\ndefault VPC for the region will be used."
          },
          "subnet_id": {
            "example": "subnet-0123456789abcdef0",
            "type": "string",
            "description": "The subnet ID where the instance will be launched. If not specified,\na subnet will be selected from the VPC."
          },
          "security_group_ids": {
            "example": [
              "sg-0123456789abcdef0"
            ],
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Security group IDs to attach to the instance. If not specified, the\ndefault security group for the VPC will be used."
          },
          "iam_instance_profile": {
            "example": "arn:aws:iam::123456789012:instance-profile/MyProfile",
            "type": "string",
            "description": "The IAM instance profile ARN or name to attach to the instance."
          },
          "root_volume": {
            "allOf": [
              {
                "$ref": "#/components/schemas/AWSEBSConfig"
              }
            ],
            "description": "Root EBS volume configuration. If not specified, provider defaults\nwill be used."
          },
          "additional_volumes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AWSEBSConfig"
            },
            "description": "Additional EBS volumes to attach to the instance."
          },
          "dedicated_host": {
            "type": "boolean",
            "description": "Whether to use a dedicated host. Dedicated hosts provide visibility and\ncontrol over how instances are placed on physical servers."
          },
          "placement_group": {
            "example": "my-cluster-placement-group",
            "type": "string",
            "description": "Placement group name for the instance. Placement groups influence how\ninstances are placed on underlying hardware."
          },
          "region": {
            "example": "us-east-1",
            "type": "string",
            "description": "The AWS region where the machine is located."
          },
          "machine_type": {
            "example": "c8i.large",
            "type": "string",
            "description": "The AWS machine type. This determines the compute resources\n(CPU, memory, etc.) available on the machine. The valid values depend\non the chosen provider."
          }
        },
        "description": "AWSConfig contains AWS-specific configuration for node provisioning.",
        "x-package": "controlplane"
      },
      "AWSEBSConfig": {
        "required": [
          "size_gib",
          "volume_type",
          "encrypted",
          "delete_on_termination"
        ],
        "type": "object",
        "properties": {
          "device_name": {
            "example": "/dev/xvdf",
            "type": "string",
            "description": "The device name (e.g., \"/dev/sda1\", \"/dev/xvdf\"). Required for\nadditional volumes."
          },
          "size_gib": {
            "example": 100,
            "type": "integer",
            "description": "Size of the volume in GiB.",
            "format": "uint32"
          },
          "volume_type": {
            "example": "gp3",
            "type": "string",
            "description": "The volume type (gp3, gp2, io1, io2, st1, sc1, standard)."
          },
          "iops": {
            "example": 3000,
            "type": "integer",
            "description": "The number of IOPS. Only valid for io1, io2, and gp3 volumes.",
            "format": "uint32"
          },
          "throughput_mibps": {
            "example": 125,
            "type": "integer",
            "description": "The throughput in MiB/s. Only valid for gp3 volumes.",
            "format": "uint32"
          },
          "encrypted": {
            "type": "boolean",
            "description": "Whether the volume should be encrypted."
          },
          "kms_key_id": {
            "example": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012",
            "type": "string",
            "description": "The KMS key ID for encryption. If encrypted is true and this is not\nspecified, the default EBS encryption key will be used."
          },
          "delete_on_termination": {
            "type": "boolean",
            "description": "Whether to delete the volume when the instance is terminated."
          }
        },
        "description": "AWSEBSConfig defines the configuration for an AWS EBS volume.",
        "x-package": "controlplane"
      },
      "CheckAuthorizationRequest": {
        "required": [
          "request_id"
        ],
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "The request ID is a unique identifier for the request.  This is used to\ntrack the request in the system and should be provided by the client."
          }
        },
        "description": "The request message for checking authorization given a request ID.",
        "x-package": "controlplane"
      },
      "CheckAuthorizationResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CheckAuthorizationResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 56,
            "type": "integer",
            "description": "The operation time in microseconds.  This is the time it took to process\nthe request and generate the response.",
            "format": "uint64"
          }
        },
        "description": "The response message for checking authorization.",
        "x-package": "controlplane"
      },
      "CheckAuthorizationResponseData": {
        "required": [
          "token",
          "organization_name",
          "organization_display_name",
          "registry"
        ],
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "description": "The authorization token which can be used to authenticate requests."
          },
          "organization_name": {
            "type": "string",
            "description": "The organization name the token is associated with."
          },
          "organization_display_name": {
            "type": "string",
            "description": "The display name of the organization the token is associated with."
          },
          "registry": {
            "type": "string",
            "description": "The global image registry."
          }
        },
        "x-package": "controlplane"
      },
      "CloudProvider": {
        "enum": [
          "manual",
          "aws"
        ],
        "type": "string",
        "description": "CloudProvider identifies the cloud infrastructure provider where nodes are\nprovisioned.",
        "format": "enum",
        "x-package": "controlplane"
      },
      "CloudProviderConfig": {
        "type": "object",
        "allOf": [
          {
            "oneOf": [
              {
                "title": "aws",
                "type": "object",
                "properties": {
                  "aws": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/AWSConfig"
                      }
                    ],
                    "description": "AWS-specific configuration."
                  }
                }
              }
            ]
          }
        ],
        "description": "CloudProviderConfig contains provider-specific configuration for node\nprovisioning.  Use this for advanced customization beyond the common\nmachine_type and region fields.",
        "x-package": "controlplane"
      },
      "DestroyNodeResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DestroyNodeResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 2341,
            "type": "integer",
            "description": "The operation time in microseconds.",
            "format": "uint64"
          }
        },
        "description": "Response message for deleting nodes.",
        "x-package": "controlplane"
      },
      "DestroyNodeResponseData": {
        "type": "object",
        "properties": {
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Node"
            },
            "description": "The deleted nodes (with their final state before deletion)."
          }
        },
        "x-package": "controlplane"
      },
      "GetAuthorizationResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GetAuthorizationResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 56,
            "type": "integer",
            "description": "The operation time in microseconds.  This is the time it took to process\nthe request and generate the response.",
            "format": "uint64"
          }
        },
        "description": "The response message for getting authorization details.",
        "x-package": "controlplane"
      },
      "GetAuthorizationResponseData": {
        "required": [
          "organization_name",
          "organization_display_name",
          "registry"
        ],
        "type": "object",
        "properties": {
          "organization_name": {
            "type": "string",
            "description": "The organization name the token is associated with."
          },
          "organization_display_name": {
            "type": "string",
            "description": "The display name of the organization the token is associated with."
          },
          "registry": {
            "type": "string",
            "description": "The global image registry."
          }
        },
        "x-package": "controlplane"
      },
      "Image": {
        "required": [
          "name"
        ],
        "type": "object",
        "properties": {
          "name": {
            "example": "namespace/image1",
            "type": "string",
            "description": "The canonical name of the image."
          },
          "tags": {
            "example": [
              {
                "name": "latest",
                "digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ImageTag"
            },
            "description": "The list of tags for the image.  Only populated when details are requested."
          }
        },
        "x-package": "controlplane"
      },
      "ImageTag": {
        "required": [
          "name",
          "digest",
          "size",
          "push_time"
        ],
        "type": "object",
        "properties": {
          "name": {
            "example": "latest",
            "type": "string",
            "description": "The tag name."
          },
          "digest": {
            "example": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
            "type": "string",
            "description": "The digest for the tag."
          },
          "size": {
            "example": 12345678,
            "type": "integer",
            "description": "The size of the image in bytes.",
            "format": "uint64"
          },
          "push_time": {
            "example": "2024-01-02T15:04:05Z",
            "type": "string",
            "description": "The push time of the image.",
            "format": "date-time"
          }
        },
        "x-package": "controlplane"
      },
      "ListImagesResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ListImagesResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 87,
            "type": "integer",
            "description": "The operation time in microseconds.  This is the time it took to process\nthe request and generate the response.",
            "format": "uint64"
          }
        },
        "x-package": "controlplane"
      },
      "ListImagesResponseData": {
        "type": "object",
        "properties": {
          "images": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Image"
            },
            "description": "The list of images."
          }
        },
        "x-package": "controlplane"
      },
      "ListMachineTypesResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ListMachineTypesResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 123,
            "type": "integer",
            "description": "The operation time in microseconds.",
            "format": "uint64"
          }
        },
        "description": "Response message for listing machine types.",
        "x-package": "controlplane"
      },
      "ListMachineTypesResponseData": {
        "type": "object",
        "properties": {
          "machine_types": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MachineType"
            },
            "description": "The list of available machine types."
          }
        },
        "x-package": "controlplane"
      },
      "ListMetroResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ListMetroResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 87,
            "type": "integer",
            "description": "The operation time in microseconds.  This is the time it took to process\nthe request and generate the response.",
            "format": "uint64"
          }
        },
        "x-package": "controlplane"
      },
      "ListMetroResponseData": {
        "type": "object",
        "properties": {
          "metros": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Metro"
            },
            "description": "The list of metros."
          }
        },
        "x-package": "controlplane"
      },
      "ListNodesResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ListNodesResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 234,
            "type": "integer",
            "description": "The operation time in microseconds.",
            "format": "uint64"
          }
        },
        "description": "Response message for getting nodes.",
        "x-package": "controlplane"
      },
      "ListNodesResponseData": {
        "required": [
          "total_count"
        ],
        "type": "object",
        "properties": {
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Node"
            },
            "description": "The list of nodes matching the request."
          },
          "total_count": {
            "example": 42,
            "type": "integer",
            "description": "Total count of nodes matching the filters (for pagination).",
            "format": "uint32"
          }
        },
        "x-package": "controlplane"
      },
      "ListRegionsResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ListRegionsResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 89,
            "type": "integer",
            "description": "The operation time in microseconds.",
            "format": "uint64"
          }
        },
        "description": "Response message for listing regions.",
        "x-package": "controlplane"
      },
      "ListRegionsResponseData": {
        "type": "object",
        "properties": {
          "regions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Region"
            },
            "description": "The list of available regions."
          }
        },
        "x-package": "controlplane"
      },
      "MachineType": {
        "required": [
          "name",
          "vcpus",
          "memory_mib",
          "nested_virtualization"
        ],
        "type": "object",
        "properties": {
          "name": {
            "example": "m5.xlarge",
            "type": "string",
            "description": "The machine type identifier (e.g., \"m5.xlarge\", \"n2-standard-4\")."
          },
          "description": {
            "example": "General purpose, 4 vCPUs, 16 GiB memory",
            "type": "string",
            "description": "Human-readable description."
          },
          "vcpus": {
            "example": 4,
            "type": "integer",
            "description": "Number of vCPUs.",
            "format": "uint32"
          },
          "memory_mib": {
            "example": 16384,
            "type": "integer",
            "description": "Memory in MiB.",
            "format": "uint64"
          },
          "category": {
            "example": "general-purpose",
            "type": "string",
            "description": "Machine category (e.g., \"general-purpose\", \"compute-optimized\",\n\"memory-optimized\")."
          },
          "available_regions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Regions where this machine type is available."
          },
          "nested_virtualization": {
            "type": "boolean",
            "description": "Whether this machine type supports nested virtualization."
          }
        },
        "description": "Information about an available machine type.",
        "x-package": "controlplane"
      },
      "Metro": {
        "required": [
          "uuid",
          "endpoint",
          "name",
          "iata_code",
          "country"
        ],
        "type": "object",
        "properties": {
          "uuid": {
            "example": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
            "type": "string",
            "description": "The UUID of the metro.",
            "format": "uuid"
          },
          "endpoint": {
            "example": "https://api.metro1.unikraft.cloud/v1",
            "type": "string",
            "description": "The API endpoint for the metro.",
            "format": "uri"
          },
          "name": {
            "example": "metro1",
            "type": "string",
            "description": "The name of the metro."
          },
          "iata_code": {
            "example": "FRA",
            "type": "string",
            "description": "The IATA code of the metro."
          },
          "country": {
            "example": "de",
            "type": "string",
            "description": "The country where the metro is located."
          }
        },
        "x-package": "controlplane"
      },
      "MutableNodeOperation": {
        "enum": [
          "set",
          "add",
          "del"
        ],
        "type": "string",
        "description": "The operations available on a node's mutable properties.",
        "format": "enum",
        "x-package": "controlplane"
      },
      "MutableNodeProperty": {
        "enum": [
          "tags",
          "delete_lock",
          "ssh_keys"
        ],
        "type": "string",
        "description": "The mutable properties of a node which can be updated.",
        "format": "enum",
        "x-package": "controlplane"
      },
      "NameOrUUID": {
        "type": "object",
        "allOf": [
          {
            "type": "object",
            "properties": {
              "metro": {
                "example": "fra",
                "type": "string",
                "description": "(Only applies when using global control plane).\nThe metro of the resource."
              }
            }
          },
          {
            "oneOf": [
              {
                "title": "uuid",
                "required": [
                  "uuid"
                ],
                "type": "object",
                "properties": {
                  "uuid": {
                    "example": "123e4567-e89b-12d3-a456-426614174000",
                    "type": "string",
                    "description": "Mutually exclusive with name.",
                    "format": "uuid"
                  }
                }
              },
              {
                "title": "name",
                "required": [
                  "name"
                ],
                "type": "object",
                "properties": {
                  "name": {
                    "example": "funky-town-g756b5d",
                    "type": "string",
                    "description": "Mutually exclusive with UUID."
                  }
                }
              }
            ]
          }
        ],
        "description": "An identifier for a resource.  Either a name or a UUID.",
        "x-package": "common"
      },
      "Node": {
        "required": [
          "uuid",
          "name",
          "created_at",
          "state",
          "region",
          "machine_type",
          "vcpus",
          "memory_mib",
          "uptime_seconds",
          "delete_lock"
        ],
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "description": "The UUID of the machine.\n\nThis is a unique identifier for the machine that is generated when the\nmachine is created. The UUID is used to reference the machine in API calls and\ncan be used to identify the machine in all API calls that require a machine\nidentifier.",
            "format": "uuid"
          },
          "name": {
            "example": "machine-fra-aws-001",
            "type": "string",
            "description": "The name of the machine.\n\nThis is a human-readable name that can be used to identify the machine.\nThe name must be unique within the context of your account. The name can\nalso be used to identify the machine in API calls."
          },
          "created_at": {
            "example": "2024-01-15T10:30:00Z",
            "type": "string",
            "description": "The time the machine was created.",
            "format": "date-time"
          },
          "updated_at": {
            "example": "2024-01-15T12:45:00Z",
            "type": "string",
            "description": "The time the machine was last updated.",
            "format": "date-time"
          },
          "state": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NodeState"
              }
            ],
            "description": "The current state of the machine."
          },
          "state_message": {
            "example": "Provisioning in progress, waiting for instance to become available",
            "type": "string",
            "description": "An optional message providing additional information about the current\nstate, particularly useful for error states."
          },
          "cloudprovider": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CloudProvider"
              }
            ],
            "description": "The cloud provider where this machine is provisioned."
          },
          "region": {
            "example": "us-east-1",
            "type": "string",
            "description": "The provider's region where the machine is located (e.g., \"us-east-1\" for\nAWS, \"us-central1\" for GCP, \"westeurope\" for Azure)."
          },
          "machine_type": {
            "example": "m5.xlarge",
            "type": "string",
            "description": "The machine type as defined by the provider (e.g., \"m5.xlarge\" for AWS,\n\"n2-standard-4\" for GCP, \"Standard_D4s_v3\" for Azure).\n\nThis determines the compute resources (CPU, memory, etc.) available on\nthe machine. The valid values depend on the chosen provider."
          },
          "vcpus": {
            "example": 4,
            "type": "integer",
            "description": "The number of vCPUs available on this machine.",
            "format": "uint32"
          },
          "memory_mib": {
            "example": 16384,
            "type": "integer",
            "description": "The amount of memory in MiB available on this machine.",
            "format": "uint64"
          },
          "ssh_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SSHKey"
            },
            "description": "The SSH keys configured for access to this machine."
          },
          "public_ipv4": {
            "example": "203.0.113.50",
            "type": "string",
            "description": "The public IPv4 address of the machine, if assigned.",
            "format": "ipv4"
          },
          "public_ipv6": {
            "example": "2001:db8::1",
            "type": "string",
            "description": "The public IPv6 address of the machine, if assigned.",
            "format": "ipv6"
          },
          "private_ipv4": {
            "example": "10.0.1.50",
            "type": "string",
            "description": "The private IPv4 address of the machine within the provider's network.",
            "format": "ipv4"
          },
          "metro": {
            "example": "fra",
            "type": "string",
            "description": "The Unikraft Cloud metro this machine is associated with."
          },
          "provider_instance_id": {
            "example": "i-0123456789abcdef0",
            "type": "string",
            "description": "The provider-specific instance ID or resource identifier."
          },
          "provider_config": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CloudProviderConfig"
              }
            ],
            "description": "Provider-specific configuration that was used to provision this node."
          },
          "tags": {
            "example": {
              "environment": "production",
              "team": "platform"
            },
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "User-defined tags for organizing and filtering nodes."
          },
          "ready_at": {
            "example": "2024-01-15T10:35:00Z",
            "type": "string",
            "description": "The time when the machine became ready (entered READY state).",
            "format": "date-time"
          },
          "uptime_seconds": {
            "example": 86400,
            "type": "integer",
            "description": "The total uptime of the machine in seconds since it became ready.",
            "format": "uint64"
          },
          "delete_lock": {
            "type": "boolean",
            "description": "Whether the machine is protected from deletion. When true, delete operations\nwill fail until this is set to false."
          }
        },
        "description": "Node represents a physical or virtual compute node provisioned on a\ncloud provider for use as part of the Unikraft Cloud infrastructure.\n\nNode nodes are the underlying compute resources where Unikraft Cloud\ninstances run.  They are provisioned on-demand across multiple cloud\nproviders and managed through a unified API.",
        "x-package": "controlplane"
      },
      "NodeActivateRequest": {
        "required": [
          "csr"
        ],
        "type": "object",
        "allOf": [
          {
            "type": "object",
            "properties": {
              "csr": {
                "example": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KLi4uCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQ==",
                "type": "string",
                "description": "The certificate signing request (CSR) for the license which is base64\nencoded."
              }
            }
          },
          {
            "oneOf": [
              {
                "title": "secret",
                "type": "object",
                "properties": {
                  "secret": {
                    "type": "string",
                    "description": "An opaque secret for first-time activation. On renewal (where the node's\npublic key is already known), this field is omitted and the CSR\nself-signature is used as proof of key possession."
                  }
                }
              },
              {
                "title": "serial",
                "type": "object",
                "properties": {
                  "serial": {
                    "type": "string",
                    "description": "The serial number of the last issued certificate."
                  }
                }
              }
            ]
          }
        ],
        "description": "The request message for certificate activation.",
        "x-package": "controlplane"
      },
      "NodeActivateResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "/ An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/NodeActivateResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 234,
            "type": "integer",
            "description": "The operation time in microseconds.",
            "format": "uint64"
          }
        },
        "description": "The response message for certificate activation.",
        "x-package": "controlplane"
      },
      "NodeActivateResponseData": {
        "required": [
          "license"
        ],
        "type": "object",
        "properties": {
          "license": {
            "type": "string",
            "description": "The issued license certificate in base64 URL encoded PEM format."
          }
        },
        "x-package": "controlplane"
      },
      "NodeHeartbeatRequest": {
        "required": [
          "machine_id",
          "platform_status"
        ],
        "type": "object",
        "properties": {
          "machine_id": {
            "type": "string",
            "description": "The unique machine identifier of the node sending the heartbeat."
          },
          "platform_status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PlatformStatus"
              }
            ],
            "description": "The current platform status of the node."
          }
        },
        "description": "The request message for a node heartbeat.",
        "x-package": "controlplane"
      },
      "NodeHeartbeatResponse": {
        "required": [
          "status"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          }
        },
        "description": "The response message for a node heartbeat.",
        "x-package": "controlplane"
      },
      "NodeState": {
        "enum": [
          "unspecified",
          "pending",
          "provisioning",
          "configuring",
          "ready",
          "deprovisioning",
          "deprovisioned",
          "error",
          "maintenance"
        ],
        "type": "string",
        "description": "NodeState defines the provisioning lifecycle state of a machine which will\nrun the Unikraft Cloud Platform.",
        "format": "enum",
        "x-package": "controlplane"
      },
      "PlatformStatus": {
        "enum": [
          "healthy",
          "degraded",
          "unavailable"
        ],
        "type": "string",
        "format": "enum",
        "x-package": "controlplane"
      },
      "ProvisionNodeRequest": {
        "required": [
          "region",
          "machine_type",
          "ssh_keys"
        ],
        "type": "object",
        "properties": {
          "name": {
            "example": "node-fra-aws-001",
            "type": "string",
            "description": "Optional name for the node. If not provided, a name will be\nauto-generated."
          },
          "cloudprovider": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CloudProvider"
              }
            ],
            "description": "The cloud provider where the machine should be provisioned."
          },
          "region": {
            "example": "us-east-1",
            "type": "string",
            "description": "The provider region where the machine should be provisioned."
          },
          "machine_type": {
            "example": "m5.xlarge",
            "type": "string",
            "description": "The machine type to provision. This is provider-specific."
          },
          "ssh_keys": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SSHKey"
            },
            "description": "SSH keys for accessing the node. At least one key is required."
          },
          "tags": {
            "example": {
              "environment": "production"
            },
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Optional user-defined tags."
          },
          "cloudprovider_config": {
            "allOf": [
              {
                "$ref": "#/components/schemas/CloudProviderConfig"
              }
            ],
            "description": "Optional provider-specific configuration for advanced customization."
          },
          "metro": {
            "example": "fra",
            "type": "string",
            "description": "The Unikraft Cloud metro to associate this machine with."
          },
          "platform_config": {
            "example": {
              "vm-user-min-memory": "2048"
            },
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Optional user overrides for platform configuration. Keys should be\nkebab-case (e.g., \"vm-user-min-memory\")."
          },
          "image_pulls": {
            "example": [
              "ghcr.io/myapp:latest",
              "quay.io/image:v1"
            ],
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional image references to pre-pull on the provisioned machine."
          },
          "net_count": {
            "example": 1000,
            "type": "integer",
            "description": "Optional network count override. If not specified, defaults to 1000.",
            "format": "uint32"
          }
        },
        "description": "Request message for creating a new node.",
        "x-package": "controlplane"
      },
      "ProvisionNodeResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProvisionNodeResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 1523,
            "type": "integer",
            "description": "The operation time in microseconds.",
            "format": "uint64"
          }
        },
        "description": "Response message for creating a node.",
        "x-package": "controlplane"
      },
      "ProvisionNodeResponseData": {
        "required": [
          "node"
        ],
        "type": "object",
        "properties": {
          "node": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Node"
              }
            ],
            "description": "The created node."
          }
        },
        "x-package": "controlplane"
      },
      "Region": {
        "required": [
          "name",
          "iata"
        ],
        "type": "object",
        "properties": {
          "name": {
            "example": "us-east-1",
            "type": "string",
            "description": "The region identifier (e.g., \"us-east-1\", \"us-central1\")."
          },
          "iata": {
            "example": "SFO",
            "type": "string",
            "description": "The IATA code for the region."
          }
        },
        "description": "Information about an available region.",
        "x-package": "controlplane"
      },
      "RequestSigninRequest": {
        "required": [
          "hostname"
        ],
        "type": "object",
        "properties": {
          "hostname": {
            "example": "my-machine.local",
            "type": "string",
            "description": "The hostname is the name of the machine making the request.  This is\nmandatory as it consitutes a unique identifier for the machine."
          },
          "os": {
            "example": "linux",
            "type": "string",
            "description": "The operating system of the machine making the request."
          },
          "os_version": {
            "example": "5.10.0-17-amd64",
            "type": "string",
            "description": "The version of the operating system of the machine making the request, if\navailable.\n\nFor Android, it's like \"10\", \"11\", \"12\", etc.  For iOS and macOS it's like\n\"15.6.1\" or \"12.4.0\".  For Windows it's like \"10.0.19044.1889\". For FreeBSD\nit's like \"12.3-STABLE\".  For Linux, this is simply the kernel version on\nLinux, like \"5.10.0-17-amd64\"."
          },
          "container": {
            "example": false,
            "type": "boolean",
            "description": "A best-effort whether the client is running in a container."
          },
          "distro": {
            "example": "ubuntu",
            "type": "string",
            "description": "The OS distribution, if known.  E.g. \"debian\", \"ubuntu\", \"nixos\", ..."
          },
          "distro_version": {
            "example": 20.04,
            "type": "string",
            "description": "The OS distribution version if known.  E.g. \"20.04\", ..."
          },
          "distro_codename": {
            "example": "jammy",
            "type": "string",
            "description": "TThe OS distribution codename if known.  E.g. \"jammy\", \"bullseye\", ..."
          },
          "cli_version": {
            "example": "1.0.0",
            "type": "string",
            "description": "The CLI version is the version of the Unikraft CLI that is making the\nrequest."
          },
          "goarch": {
            "example": "amd64",
            "type": "string",
            "description": "If available, the GOARCH value (of the built binary)."
          },
          "goos": {
            "example": "linux",
            "type": "string",
            "description": "If available, the GOOS value (of the built binary)"
          },
          "go_version": {
            "example": "1.16.0",
            "type": "string",
            "description": "if available, the Go version binary was built with."
          }
        },
        "description": "The request message for a sign-in request.",
        "x-package": "controlplane"
      },
      "RequestSigninResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RequestSigninResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 87,
            "type": "integer",
            "description": "The operation time in microseconds.  This is the time it took to process\nthe request and generate the response.",
            "format": "uint64"
          }
        },
        "description": "The response message for a sign-in request.",
        "x-package": "controlplane"
      },
      "RequestSigninResponseData": {
        "required": [
          "authorization_url",
          "request_id"
        ],
        "type": "object",
        "properties": {
          "authorization_url": {
            "type": "string",
            "description": "The full URL which can be used to remotely confirm the signin."
          },
          "request_id": {
            "type": "string",
            "description": "A unique identifier for the request.  This can be used to track the\nrequest in the system."
          }
        },
        "x-package": "controlplane"
      },
      "ResponseError": {
        "required": [
          "status"
        ],
        "type": "object",
        "properties": {
          "status": {
            "example": 401,
            "type": "integer",
            "description": "The HTTP status code of the error.",
            "format": "uint64"
          }
        },
        "description": "The error response message for an API request.",
        "x-package": "common"
      },
      "ResponseStatus": {
        "enum": [
          "success",
          "error"
        ],
        "type": "string",
        "description": "The response status of an API request.",
        "format": "enum",
        "x-package": "common"
      },
      "SSHKey": {
        "required": [
          "name",
          "public_key"
        ],
        "type": "object",
        "properties": {
          "name": {
            "example": "admin-key",
            "type": "string",
            "description": "A name or label for this SSH key."
          },
          "public_key": {
            "example": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host",
            "type": "string",
            "description": "The SSH public key in OpenSSH format (e.g., \"ssh-rsa AAAA... user@host\"\nor \"ssh-ed25519 AAAA... user@host\")."
          }
        },
        "description": "SSHKey represents an SSH public key for authentication.",
        "x-package": "controlplane"
      },
      "UpdateNodePayload": {
        "required": [
          "property",
          "operation"
        ],
        "type": "object",
        "properties": {
          "property": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MutableNodeProperty"
              }
            ],
            "description": "The property to update."
          },
          "operation": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MutableNodeOperation"
              }
            ],
            "description": "The operation to perform on the property."
          },
          "value": {
            "type": "string",
            "description": "The value for the update operation. The type depends on the property:\n- TAGS: google.protobuf.Struct with key-value pairs\n- DELETE_LOCK: google.protobuf.Value with boolean\n- SSH_KEYS: google.protobuf.ListValue with SSHKey objects",
            "format": "bytes"
          }
        },
        "description": "UpdateNodePayload contains the changes to apply to a node.",
        "x-package": "controlplane"
      },
      "UpdateNodesResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UpdateNodesResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 456,
            "type": "integer",
            "description": "The operation time in microseconds.",
            "format": "uint64"
          }
        },
        "description": "Response message for updating nodes.",
        "x-package": "controlplane"
      },
      "UpdateNodesResponseData": {
        "type": "object",
        "properties": {
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Node"
            },
            "description": "The updated nodes."
          }
        },
        "x-package": "controlplane"
      },
      "WaitNodesResponse": {
        "required": [
          "status",
          "op_time_us"
        ],
        "type": "object",
        "properties": {
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ResponseStatus"
              }
            ],
            "description": "The status of the response."
          },
          "message": {
            "type": "string",
            "description": "An optional message providing additional information about the response."
          },
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/WaitNodesResponseData"
              }
            ],
            "description": "The response data for this request."
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ResponseError"
            },
            "description": "A list of errors which may have occurred during the request."
          },
          "op_time_us": {
            "example": 180234,
            "type": "integer",
            "description": "The operation time in microseconds.",
            "format": "uint64"
          }
        },
        "description": "Response message for wait operations.",
        "x-package": "controlplane"
      },
      "WaitNodesResponseData": {
        "type": "object",
        "properties": {
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Node"
            },
            "description": "The nodes after reaching the desired state."
          }
        },
        "x-package": "controlplane"
      }
    },
    "securitySchemes": {
      "bearerToken": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "tags": [
    {
      "name": "Auth",
      "description": "Authenticate with Unikraft Cloud."
    },
    {
      "name": "Images"
    },
    {
      "name": "Metros"
    },
    {
      "name": "NodeActivationService",
      "description": "NodeActivationService provides APIs for activating and renewing node\nlicenses."
    },
    {
      "name": "NodeService",
      "description": "NodeService service provides APIs for provisioning and managing compute nodes\nacross multiple cloud providers for use in Unikraft Cloud."
    }
  ]
}