Server

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/stackit/main/json-schema/stackit-server-schema.json",
  "title": "Server",
  "description": "Representation of a single server object.",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stackit-iaas-openapi.yml#/components/schemas/Server",
  "properties": {
    "affinityGroup": {
      "allOf": [
        {
          "$ref": "#/$defs/UUID"
        }
      ],
      "description": "The affinity group the server is assigned to."
    },
    "agent": {
      "$ref": "#/$defs/ServerAgent"
    },
    "availabilityZone": {
      "allOf": [
        {
          "$ref": "#/$defs/AvailabilityZone"
        }
      ],
      "description": "This is the availability zone requested during server creation. If none is provided during the creation request and an existing volume will be used as boot volume it will be set to the same availability zone as the volume. For requests with no volumes involved it will be set to the metro availability zone."
    },
    "bootVolume": {
      "allOf": [
        {
          "$ref": "#/$defs/BootVolume"
        }
      ]
    },
    "configDrive": {
      "$ref": "#/$defs/ServerConfigDrive"
    },
    "createdAt": {
      "allOf": [
        {
          "$ref": "#/$defs/CreatedAt"
        }
      ],
      "readOnly": true
    },
    "errorMessage": {
      "allOf": [
        {
          "$ref": "#/$defs/errorMessage"
        }
      ],
      "readOnly": true
    },
    "id": {
      "allOf": [
        {
          "$ref": "#/$defs/UUID"
        }
      ],
      "readOnly": true
    },
    "imageId": {
      "allOf": [
        {
          "$ref": "#/$defs/UUID"
        }
      ]
    },
    "keypairName": {
      "allOf": [
        {
          "$ref": "#/$defs/KeyPairName"
        }
      ],
      "description": "The SSH keypair used during the server creation."
    },
    "labels": {
      "$ref": "#/$defs/Labels"
    },
    "launchedAt": {
      "allOf": [
        {
          "$ref": "#/$defs/LaunchedAt"
        }
      ],
      "readOnly": true
    },
    "machineType": {
      "allOf": [
        {
          "$ref": "#/$defs/GenericName"
        }
      ],
      "description": "Name of the machine type the server shall belong to."
    },
    "maintenanceWindow": {
      "allOf": [
        {
          "$ref": "#/$defs/ServerMaintenance"
        }
      ],
      "readOnly": true
    },
    "metadata": {
      "$ref": "#/$defs/Metadata"
    },
    "name": {
      "$ref": "#/$defs/ServerName"
    },
    "networking": {
      "description": "The initial networking setup for the server creation. A network, a nic or nothing can be given.",
      "oneOf": [
        {
          "$ref": "#/$defs/CreateServerNetworking"
        },
        {
          "$ref": "#/$defs/CreateServerNetworkingWithNics"
        }
      ]
    },
    "nics": {
      "allOf": [
        {
          "$ref": "#/$defs/ServerNICList"
        }
      ],
      "description": "The list of network interfaces (NICs) attached to the server. Only shown when detailed information is requested.",
      "readOnly": true
    },
    "powerStatus": {
      "allOf": [
        {
          "$ref": "#/$defs/ServerPowerStatus"
        }
      ],
      "readOnly": true
    },
    "securityGroups": {
      "allOf": [
        {
          "$ref": "#/$defs/GenericNameList"
        }
      ],
      "description": "The initial security groups for the server creation.",
      "writeOnly": true
    },
    "serviceAccountMails": {
      "allOf": [
        {
          "$ref": "#/$defs/ServiceAccountMailList"
        }
      ],
      "description": "A list of service account mails. Only shown when detailed information is requested."
    },
    "status": {
      "allOf": [
        {
          "$ref": "#/$defs/ServerStatus"
        }
      ],
      "readOnly": true
    },
    "updatedAt": {
      "allOf": [
        {
          "$ref": "#/$defs/UpdatedAt"
        }
      ],
      "readOnly": true
    },
    "userData": {
      "allOf": [
        {
          "$ref": "#/$defs/ServerUserData"
        }
      ],
      "description": "User Data that is provided to the server. Must be base64 encoded and is passed via cloud-init to the server. Only shown when detailed information is requested."
    },
    "volumes": {
      "allOf": [
        {
          "$ref": "#/$defs/UUIDList"
        }
      ],
      "description": "The list of volumes attached to the server."
    }
  },
  "required": [
    "name",
    "machineType"
  ],
  "type": "object",
  "$defs": {
    "AllowedAddresses": {
      "description": "A list of IPs or CIDR notations.",
      "items": {
        "oneOf": [
          {
            "$ref": "#/$defs/IP"
          },
          {
            "$ref": "#/$defs/CIDR"
          }
        ]
      },
      "type": "array"
    },
    "AvailabilityZone": {
      "description": "Object that represents an availability zone.",
      "type": "string"
    },
    "BootVolume": {
      "description": "The boot device for the server.",
      "properties": {
        "deleteOnTermination": {
          "$ref": "#/$defs/DeleteOnTermination"
        },
        "id": {
          "allOf": [
            {
              "$ref": "#/$defs/UUID"
            }
          ],
          "readOnly": true
        },
        "performanceClass": {
          "allOf": [
            {
              "$ref": "#/$defs/GenericName"
            }
          ],
          "writeOnly": true
        },
        "size": {
          "allOf": [
            {
              "$ref": "#/$defs/SizeInGB"
            }
          ],
          "writeOnly": true
        },
        "source": {
          "allOf": [
            {
              "$ref": "#/$defs/BootVolumeSource"
            }
          ],
          "writeOnly": true
        }
      },
      "type": "object"
    },
    "BootVolumeSource": {
      "description": "The source object of a boot volume.",
      "properties": {
        "id": {
          "$ref": "#/$defs/UUID"
        },
        "type": {
          "$ref": "#/$defs/BootVolumeSourceTypes"
        }
      },
      "required": [
        "type",
        "id"
      ],
      "type": "object"
    },
    "BootVolumeSourceTypes": {
      "description": "The source types of a boot volume.\nPossible values: `image`, `volume`.",
      "type": "string"
    },
    "CIDR": {
      "description": "Classless Inter-Domain Routing (CIDR).",
      "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\/(3[0-2]|2[0-9]|1[0-9]|[0-9]))$|^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))(\\/((1(1[0-9]|2[0-8]))|([0-9][0-9])|([0-9])))?$",
      "type": "string"
    },
    "CreateServerNetworking": {
      "additionalProperties": false,
      "description": "The initial networking setup for the server creation with a network.",
      "properties": {
        "networkId": {
          "$ref": "#/$defs/UUID"
        }
      },
      "type": "object"
    },
    "CreateServerNetworkingWithNics": {
      "additionalProperties": false,
      "description": "The initial networking setup for the server creation with a network interface.",
      "properties": {
        "nicIds": {
          "$ref": "#/$defs/UUIDList"
        }
      },
      "type": "object"
    },
    "CreatedAt": {
      "description": "Date-time when resource was created.",
      "format": "date-time",
      "type": "string"
    },
    "DeleteOnTermination": {
      "description": "Delete the volume during the termination of the server. Defaults to false.",
      "type": "boolean"
    },
    "GenericName": {
      "description": "The name for a General Object. Matches Names and also UUIDs.",
      "maxLength": 127,
      "pattern": "^[A-Za-z0-9]+([ /._-]*[A-Za-z0-9]+)*$",
      "type": "string"
    },
    "GenericNameList": {
      "description": "A list of General Objects.",
      "items": {
        "$ref": "#/$defs/GenericName"
      },
      "type": "array"
    },
    "IP": {
      "description": "Object that represents an IP address.",
      "pattern": "((^\\s*((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]))\\s*$)|(^\\s*((([0-9a-f]{1,4}:){7}([0-9a-f]{1,4}|:))|(([0-9a-f]{1,4}:){6}(:[0-9a-f]{1,4}|((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3})|:))|(([0-9a-f]{1,4}:){5}(((:[0-9a-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3})|:))|(([0-9a-f]{1,4}:){4}(((:[0-9a-f]{1,4}){1,3})|((:[0-9a-f]{1,4})?:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:))|(([0-9a-f]{1,4}:){3}(((:[0-9a-f]{1,4}){1,4})|((:[0-9a-f]{1,4}){0,2}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:))|(([0-9a-f]{1,4}:){2}(((:[0-9a-f]{1,4}){1,5})|((:[0-9a-f]{1,4}){0,3}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:))|(([0-9a-f]{1,4}:){1}(((:[0-9a-f]{1,4}){1,6})|((:[0-9a-f]{1,4}){0,4}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:))|(:(((:[0-9a-f]{1,4}){1,7})|((:[0-9a-f]{1,4}){0,5}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:)))(%.+)?\\s*$))",
      "type": "string"
    },
    "IPv6": {
      "description": "String that represents an IPv6 address.",
      "pattern": "^\\s*((([0-9a-f]{1,4}:){7}([0-9a-f]{1,4}|:))|(([0-9a-f]{1,4}:){6}(:[0-9a-f]{1,4}|((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3})|:))|(([0-9a-f]{1,4}:){5}(((:[0-9a-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3})|:))|(([0-9a-f]{1,4}:){4}(((:[0-9a-f]{1,4}){1,3})|((:[0-9a-f]{1,4})?:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:))|(([0-9a-f]{1,4}:){3}(((:[0-9a-f]{1,4}){1,4})|((:[0-9a-f]{1,4}){0,2}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:))|(([0-9a-f]{1,4}:){2}(((:[0-9a-f]{1,4}){1,5})|((:[0-9a-f]{1,4}){0,3}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:))|(([0-9a-f]{1,4}:){1}(((:[0-9a-f]{1,4}){1,6})|((:[0-9a-f]{1,4}){0,4}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:))|(:(((:[0-9a-f]{1,4}){1,7})|((:[0-9a-f]{1,4}){0,5}:((25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(\\.(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}))|:)))(%.+)?\\s*$",
      "type": "string"
    },
    "KeyPairName": {
      "description": "The name of an SSH keypair. Allowed characters are letters [a-zA-Z], digits [0-9] and the following special characters: [@._-].",
      "maxLength": 127,
      "pattern": "^[A-Za-z0-9@._-]*$",
      "type": "string"
    },
    "Labels": {
      "description": "Object that represents the labels as key-value pairs of a resource.\nKey constraints: - May contain an optional domain prefix separated by a slash (`/`). - Domain prefix must be less than or equal to 250 characters. - Domain prefix must ba a valid DNS subdomain containing only lowercase alphanumerics (`[a-z0-9]`) and dashes (`-`), separated by dots (`.`). - Length (excluding the domain prefix) must be between 1 and 63 characters. - Must begin and end with an alphanumerical character (`[a-z0-9A-Z]`). - May contain dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics in between. - Keys starting with the prefix `stackit-` or having a domain prefix of `stackit.cloud` (including its subdomains, e.g., `*.stackit.cloud/`) are reserved for system use.\nValue constraints: - Must be less than or equal to 63 characters long (can be empty). - If not empty it must begin and end with an alphanumeric character (`[a-z0-9A-Z]`). - May contain dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics in between.\nA resource can have a maximum of 64 labels. Reserved labels are excluded from this count. Providing a `null` value for a key will remove that key.",
      "format": "json",
      "type": "object"
    },
    "LaunchedAt": {
      "description": "Date-time when resource was launched.",
      "format": "date-time",
      "type": "string"
    },
    "MAC": {
      "description": "Object that represents an MAC address.",
      "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
      "type": "string"
    },
    "Metadata": {
      "description": "Object that represents the metadata of an object. Regex for keys: `^[a-zA-Z0-9-_:. ]{1,255}$`. Regex for values: `^.{0,255}$`. Providing a `null` value for a key will remove that key.",
      "format": "json",
      "type": "object"
    },
    "ServerAgent": {
      "description": "STACKIT server agent options for a server.",
      "properties": {
        "provisioned": {
          "description": "Configure the STACKIT server agent provisioning during the first boot of the server. Only works when booting from an images that supports the STACKIT server agent. When `false` the agent IS NOT installed. When `true` the agent IS installed. When its not set the result depend on the used image and its default provisioning setting.",
          "type": "boolean",
          "x-stackit-logging": true
        }
      },
      "type": "object"
    },
    "ServerConfigDrive": {
      "default": false,
      "description": "When true the server is created with a config drive.",
      "type": "boolean"
    },
    "ServerMaintenance": {
      "description": "Object that represents the information about the next planned server maintenance window.",
      "properties": {
        "details": {
          "type": "string",
          "x-stackit-logging": true
        },
        "endsAt": {
          "description": "End of the maintenance window.",
          "format": "date-time",
          "type": "string",
          "x-stackit-logging": true
        },
        "startsAt": {
          "description": "Start of the maintenance window.",
          "format": "date-time",
          "type": "string",
          "x-stackit-logging": true
        },
        "status": {
          "description": "Possible values: `PLANNED`, `ONGOING`.",
          "type": "string",
          "x-extensible-enum": [
            "PLANNED",
            "ONGOING"
          ],
          "x-stackit-logging": true
        }
      },
      "required": [
        "endsAt",
        "startsAt",
        "status"
      ],
      "type": "object"
    },
    "ServerNICList": {
      "description": "A list of networks attached to a server.",
      "items": {
        "$ref": "#/$defs/ServerNetwork"
      },
      "type": "array"
    },
    "ServerName": {
      "description": "The name for a Server.",
      "maxLength": 63,
      "pattern": "^(([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])\\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$",
      "type": "string"
    },
    "ServerNetwork": {
      "description": "Describes the object that matches servers to its networks.",
      "properties": {
        "allowedAddresses": {
          "$ref": "#/$defs/AllowedAddresses"
        },
        "createdAt": {
          "allOf": [
            {
              "$ref": "#/$defs/CreatedAt"
            }
          ],
          "readOnly": true
        },
        "ipv4": {
          "$ref": "#/$defs/IP"
        },
        "ipv6": {
          "$ref": "#/$defs/IPv6"
        },
        "mac": {
          "$ref": "#/$defs/MAC"
        },
        "networkId": {
          "$ref": "#/$defs/UUID"
        },
        "networkName": {
          "$ref": "#/$defs/GenericName"
        },
        "nicId": {
          "$ref": "#/$defs/UUID"
        },
        "nicSecurity": {
          "description": "If this is set to false, then no security groups will apply to this server network interface.",
          "type": "boolean",
          "x-stackit-logging": true
        },
        "publicIp": {
          "$ref": "#/$defs/IP"
        },
        "securityGroups": {
          "$ref": "#/$defs/UUIDList"
        },
        "updatedAt": {
          "allOf": [
            {
              "$ref": "#/$defs/UpdatedAt"
            }
          ],
          "readOnly": true
        }
      },
      "required": [
        "nicId",
        "networkId",
        "networkName",
        "mac",
        "nicSecurity"
      ],
      "type": "object"
    },
    "ServerPowerStatus": {
      "description": "The power status of a server.\nPossible values: `CRASHED`, `ERROR`, `RUNNING`, `STOPPED`.",
      "type": "string"
    },
    "ServerStatus": {
      "description": "The status of a server object.\nPossible values: `ACTIVE`, `BACKING-UP`, `CREATING`, `DEALLOCATED`, `DEALLOCATING`, `DELETED`, `DELETING`, `ERROR`, `INACTIVE`, `MIGRATING`, `PAUSED`, `REBOOT`, `REBOOTING`, `REBUILD`, `REBUILDING`, `RESCUE`, `RESCUING`, `RESIZING`, `RESTORING`, `SNAPSHOTTING`, `STARTING`, `STOPPING`, `UNRESCUING`, `UPDATING`.",
      "type": "string"
    },
    "ServerUserData": {
      "description": "User Data that is provided to the server. Must be base64 encoded and is passed via cloud-init to the server.",
      "format": "byte",
      "type": "string"
    },
    "ServiceAccountMail": {
      "description": "Object that represents an e-mail address of a service account.",
      "format": "email",
      "maxLength": 255,
      "pattern": "[a-z0-9-]+(?:\\.[a-z0-9]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?",
      "type": "string"
    },
    "ServiceAccountMailList": {
      "description": "A list of service account mails.",
      "items": {
        "$ref": "#/$defs/ServiceAccountMail"
      },
      "maxItems": 1,
      "type": "array"
    },
    "SizeInGB": {
      "description": "Size in Gigabyte.",
      "format": "int64",
      "type": "integer"
    },
    "UUID": {
      "description": "Universally Unique Identifier (UUID).",
      "format": "uuid",
      "maxLength": 36,
      "minLength": 36,
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "type": "string"
    },
    "UUIDList": {
      "description": "A list of UUIDs.",
      "items": {
        "$ref": "#/$defs/UUID"
      },
      "type": "array"
    },
    "UpdatedAt": {
      "description": "Date-time when resource was last updated.",
      "format": "date-time",
      "type": "string"
    },
    "errorMessage": {
      "description": "An error message.",
      "type": "string"
    }
  }
}