openapi: 3.0.3 info: title: Hetzner Cloud Actions Servers API version: 1.0.0 x-summary: 'Manage Hetzner Cloud services and resources linked to them, such as Floating IPs, Volumes and Load Balancers. ' description: "# Overview\n\nThis is the official documentation for the Hetzner Cloud API.\n\n## Introduction\n\nThe Hetzner Cloud API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.\n\nAs an alternative to working directly with our API you may also consider to use:\n\n- Our CLI program [hcloud](https://github.com/hetznercloud/cli)\n- Our [library for Go](https://github.com/hetznercloud/hcloud-go)\n- Our [library for Python](https://github.com/hetznercloud/hcloud-python)\n\nYou can find even more libraries, tools and integrations on our [Awesome List on GitHub](https://github.com/hetznercloud/awesome-hcloud).\n\n### Open source credits\n\nIf you are developing an open-source project that supports or intends to add support for Hetzner APIs, you may be eligible for a free one-time credit of up to € 50 / $ 50 on your account. Please contact us via the support page on your [Hetzner Console](https://console.hetzner.cloud/support) and let us know the following:\n\n- The name of the project you are working on\n- A short description of the project\n- Link to the project website or repo where the project is hosted\n- Affiliation with / role in the project (e.g. project maintainer)\n- Link to some other open-source work you have already done (if you have done so)\n\n**Note:** We only consider rewards for projects that provide Hetzner-specific functionality or integrations. For example, our Object Storage exposes a standard S3 API without any Hetzner-specific extensions. Projects that focus solely on generic S3 capabilities (e.g., general S3 clients or SDKs) are not Hetzner-specific and are therefore not eligible for Hetzner Rewards.\n\n## Getting Started\n\nTo get started using the API you first need an API token. Sign in into the [Hetzner Console](https://console.hetzner.com/) choose a Project, go to `Security` → `API Tokens`, and generate a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is `LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj`.\n\nYou’re now ready to do your first request against the API. To get a list of all Servers in your Project, issue the example request on the right side using [curl](https://curl.se/).\n\nMake sure to replace the token in the example command with the token you have just created. Since your Project probably does not contain any Servers yet, the example response will look like the response on the right side. We will almost always provide a resource root like `servers` inside the example response. A response can also contain a `meta` object with information like [Pagination](#description/pagination).\n\n**Example Request**\n\n```shell\ncurl -H \"Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj\" \\\n https://api.hetzner.cloud/v1/servers\n```\n\n**Example Response**\n\n```json\n{\n \"servers\": [],\n \"meta\": {\n \"pagination\": {\n \"page\": 1,\n \"per_page\": 25,\n \"previous_page\": null,\n \"next_page\": null,\n \"last_page\": 1,\n \"total_entries\": 0\n }\n }\n}\n```\n\n## Authentication\n\nAll requests to the Hetzner Cloud API must be authenticated via a API token. Include your secret API token in every request you send to the API with the `Authorization` HTTP header.\n\nTo create a new API token for your Project, switch into the [Hetzner Console](https://console.hetzner.com/) choose a Project, go to `Security` → `API Tokens`, and generate a new token.\n\n**Example Authorization header**\n\n```http\nAuthorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj\n```\n\n## Query Parameters\n\nThe API makes use of query parameters to sort and filter responses. The parameter names and values must be URI encoded according to [RFC2396](https://datatracker.ietf.org/doc/html/rfc2396). Query parameters of type `array` can be used multiple times:\n\n**Example query parameters for pagination**\n\n```\nhttps://api.hetzner.cloud/v1/certificates?page=1&page_size=12\n```\n\n**Example use of multiple values for a parameter**\n\n```\nhttps://api.hetzner.cloud/v1/certificates?type=uploaded&type=managed\n```\n\n**Example use of an encoded parameter**\n\n```\nhttps://api.hetzner.cloud/v1/certificates?label_selector=key%3Dvalue\n```\n\n## Errors\n\nErrors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code.\n\nThe error response contains the following keys:\n\n| Keys | Meaning |\n| --------- | --------------------------------------------------------------------- |\n| `code` | Short string indicating the type of error (machine-parsable) |\n| `message` | Textual description on what has gone wrong |\n| `details` | An object providing for details on the error (schema depends on code) |\n\n**Example response**\n\n```json\n{\n \"error\": {\n \"code\": \"invalid_input\",\n \"message\": \"invalid input in field 'broken_field': is too long\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"broken_field\",\n \"messages\": [\"is too long\"]\n }\n ]\n }\n }\n}\n```\n\n### Error Codes\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `400` | `json_error` | Invalid JSON input in your request. |\n| `401` | `unauthorized` | Request was made with an invalid or unknown token. |\n| `401` | `token_readonly` | The token is only allowed to perform GET requests. |\n| `403` | `forbidden` | Insufficient permissions for this request. |\n| `403` | `maintenance` | Cannot perform operation due to maintenance. |\n| `403` | `resource_limit_exceeded` | Error when exceeding the maximum quantity of a resource for an account. |\n| `404` | `not_found` | Entity not found. |\n| `405` | `method_not_allowed` | The request method is not allowed |\n| `409` | `uniqueness_error` | One or more of the objects fields must be unique. |\n| `409` | `conflict` | The resource has changed during the request, please retry. |\n| `410` | `deprecated_api_endpoint` | The API endpoint functionality was removed. |\n| `412` | `resource_unavailable` | The requested resource is currently unavailable (e.g. not available for order). |\n| `422` | `invalid_input` | Error while parsing or processing the input. |\n| `422` | `service_error` | Error within a service. |\n| `422` | `unsupported_error` | The corresponding resource does not support the Action. |\n| `423` | `locked` | The item you are trying to access is locked (there is already an Action running). |\n| `423` | `protected` | The Action you are trying to start is protected for this resource. |\n| `429` | `rate_limit_exceeded` | Error when sending too many requests. |\n| `500` | `server_error` | Error within the API backend. |\n| `503` | `unavailable` | A service or product is currently not available. |\n| `504` | `timeout` | The request could not be answered in time, please retry. |\n\n**invalid_input**\n\n```json\n{\n \"error\": {\n \"code\": \"invalid_input\",\n \"message\": \"invalid input in field 'broken_field': is too long\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"broken_field\",\n \"messages\": [\"is too long\"]\n }\n ]\n }\n }\n}\n```\n\n**uniqueness_error**\n\n```json\n{\n \"error\": {\n \"code\": \"uniqueness_error\",\n \"message\": \"SSH key with the same fingerprint already exists\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"public_key\"\n }\n ]\n }\n }\n}\n```\n\n**resource_limit_exceeded**\n\n```json\n{\n \"error\": {\n \"code\": \"resource_limit_exceeded\",\n \"message\": \"project limit exceeded\",\n \"details\": {\n \"limits\": [\n {\n \"name\": \"project_limit\"\n }\n ]\n }\n }\n}\n```\n\n**deprecated_api_endpoint**\n\n```json\n{\n \"error\": {\n \"code\": \"deprecated_api_endpoint\",\n \"message\": \"API functionality was removed\",\n \"details\": {\n \"announcement\": \"https://docs.hetzner.cloud/changelog#2023-07-20-foo-endpoint-is-deprecated\"\n }\n }\n}\n```\n\n## Actions\n\nActions represent asynchronous tasks within the API, targeting one or more resources. Triggering changes in the API may return a `running` action.\n\nAn action should be waited upon, until it reaches either the `success` or `error` state. Avoid polling the action's state too frequently to reduce the risk of exhausting your API requests and hitting the [rate limit](#description/rate-limiting).\n\nIf an action fails, it will contain details about the underlying error.\n\nOnce the asynchronous tasks have completed and the targeted resources are in a consistent state, the action is marked as succeeded.\n\nIn some cases, you may trigger multiple changes at once, and only wait for the returned actions at a later stage.\n\n## Labels\n\nLabels are `key/value` pairs that can be attached to all resources.\n\nValid label keys have two segments: an optional prefix and name, separated by a slash (`/`). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (`.`), not longer than 253 characters in total, followed by a slash (`/`).\n\nValid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.\n\nThe `hetzner.cloud/` prefix is reserved and cannot be used.\n\n**Example Labels**\n\n```json\n{\n \"labels\": {\n \"environment\": \"development\",\n \"service\": \"backend\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\"\n }\n}\n```\n\n## Label Selector\n\nFor resources with labels, you can filter resources by their labels using the label selector query language.\n\n| Expression | Meaning |\n| -------------------- | ---------------------------------------------------- |\n| `k==v` / `k=v` | Value of key `k` does equal value `v` |\n| `k!=v` | Value of key `k` does not equal value `v` |\n| `k` | Key `k` is present |\n| `!k` | Key `k` is not present |\n| `k in (v1,v2,v3)` | Value of key `k` is `v1`, `v2`, or `v3` |\n| `k notin (v1,v2,v3)` | Value of key `k` is neither `v1`, nor `v2`, nor `v3` |\n| `k1==v,!k2` | Value of key `k1` is `v` and key `k2` is not present |\n\n### Examples\n\n- Returns all resources that have a `env=production` label and that don't have a `type=database` label:\n\n `env=production,type!=database`\n\n- Returns all resources that have a `env=testing` or `env=staging` label:\n\n `env in (testing,staging)`\n\n- Returns all resources that don't have a `type` label:\n\n `!type`\n\n## Pagination\n\nResponses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:\n\n- A `page` parameter specifies the page to fetch. The number of the first page is 1.\n- A `per_page` parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation.\n\nResponses contain a `Link` header with pagination information.\n\nAdditionally, if the response body is JSON and the root object is an object, that object has a `pagination` object inside the `meta` object with pagination information:\n\n**Example Pagination**\n\n```json\n{\n \"servers\": [...],\n \"meta\": {\n \"pagination\": {\n \"page\": 2,\n \"per_page\": 25,\n \"previous_page\": 1,\n \"next_page\": 3,\n \"last_page\": 4,\n \"total_entries\": 100\n }\n }\n}\n```\n\nThe keys `previous_page`, `next_page`, `last_page`, and `total_entries` may be `null` when on the first page, last page, or when the total number of entries is unknown.\n\n**Example Pagination Link header**\n\n```http\nLink: ; rel=\"prev\",\n ; rel=\"next\",\n ; rel=\"last\"\n```\n\nLine breaks have been added for display purposes only and responses may only contain some of the above `rel` values.\n\n## Rate Limiting\n\nAll requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a `429 Too Many Requests` error. Burst requests are allowed. Responses contain several headers which provide information about your current rate limit status.\n\n- The `RateLimit-Limit` header contains the total number of requests you can perform per hour.\n- The `RateLimit-Remaining` header contains the number of requests remaining in the current rate limit time frame.\n- The `RateLimit-Reset` header contains a UNIX timestamp of the point in time when your rate limit will have recovered, and you will have the full number of requests available again.\n\nThe default limit is 3600 requests per hour and per Project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second.\n\n## Server Metadata\n\nYour Server can discover metadata about itself by doing a HTTP request to specific URLs. The following data is available:\n\n| Data | Format | Contents |\n| ----------------- | ------ | ------------------------------------------------------------ |\n| hostname | text | Name of the Server as set in the api |\n| instance-id | number | ID of the server |\n| public-ipv4 | text | Primary public IPv4 address |\n| private-networks | yaml | Details about the private networks the Server is attached to |\n| availability-zone | text | Name of the availability zone that Server runs in |\n| region | text | Network zone, e.g. eu-central |\n\n**Example: Summary**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata\n```\n\n```yaml\navailability-zone: hel1-dc2\nhostname: my-server\ninstance-id: 42\npublic-ipv4: 1.2.3.4\nregion: eu-central\n```\n\n**Example: Hostname**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/hostname\nmy-server\n```\n\n**Example: Instance ID**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/instance-id\n42\n```\n\n**Example: Public IPv4**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/public-ipv4\n1.2.3.4\n```\n\n**Example: Private Networks**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/private-networks\n```\n\n```yaml\n- ip: 10.0.0.2\n alias_ips: [10.0.0.3, 10.0.0.4]\n interface_num: 1\n mac_address: 86:00:00:2a:7d:e0\n network_id: 1234\n network_name: nw-test1\n network: 10.0.0.0/8\n subnet: 10.0.0.0/24\n gateway: 10.0.0.1\n- ip: 192.168.0.2\n alias_ips: []\n interface_num: 2\n mac_address: 86:00:00:2a:7d:e1\n network_id: 4321\n network_name: nw-test2\n network: 192.168.0.0/16\n subnet: 192.168.0.0/24\n gateway: 192.168.0.1\n```\n\n**Example: Availability Zone**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/availability-zone\nhel1-dc2\n```\n\n**Example: Region**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/region\neu-central\n```\n\n## Sorting\n\nSome responses which return multiple items support sorting. If they do support sorting the documentation states which fields can be used for sorting. You specify sorting with the `sort` query string parameter. You can sort by multiple fields. You can set the sort direction by appending `:asc` or `:desc` to the field name. By default, ascending sorting is used.\n\n**Example: Sorting**\n\n```\nhttps://api.hetzner.cloud/v1/actions?sort=status\nhttps://api.hetzner.cloud/v1/actions?sort=status:asc\nhttps://api.hetzner.cloud/v1/actions?sort=status:desc\nhttps://api.hetzner.cloud/v1/actions?sort=status:asc&sort=command:desc\n```\n\n## Deprecation Notices\n\nYou can find all announced deprecations in our [Changelog](/changelog).\n" servers: - url: https://api.hetzner.cloud/v1 security: - APIToken: [] tags: - name: Servers description: 'Servers are virtual machines that can be provisioned. ' paths: /servers: get: operationId: list_servers summary: List Servers description: 'Returns all existing Server objects. ' tags: - Servers parameters: - description: 'Filter resources by their name. The response will only contain the resources matching exactly the specified name. ' name: name in: query required: false schema: type: string - description: 'Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "[Label Selector](#description/label-selector)". ' name: label_selector in: query required: false schema: type: string - description: 'Sort resources by field and direction. May be used multiple times. For more information, see "[Sorting](#description/sorting)". ' name: sort in: query required: false schema: type: array items: type: string enum: - id - id:asc - id:desc - name - name:asc - name:desc - created - created:asc - created:desc - description: 'Filter resources by status. May be used multiple times. The response will only contain the resources with the specified status. ' name: status in: query required: false schema: type: array items: description: Status of the Server. type: string enum: - running - initializing - starting - stopping - 'off' - deleting - migrating - rebuilding - unknown - description: Page number to return. For more information, see "[Pagination](#description/pagination)". name: page in: query required: false schema: type: integer format: int64 default: 1 example: 1 - description: Maximum number of entries returned per page. For more information, see "[Pagination](#description/pagination)". name: per_page in: query required: false schema: type: integer format: int64 default: 25 example: 25 responses: '200': description: Request succeeded. headers: x-next: description: A link to the next page of responses. schema: type: string content: application/json: schema: type: object properties: servers: type: array items: type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the Server (must be unique per Project and a valid hostname as per RFC 1123). type: string example: my-resource status: description: Status of the Server. type: string enum: - running - initializing - starting - stopping - 'off' - deleting - migrating - rebuilding - unknown created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' public_net: description: Public network information. The Server's IPv4 address can be found in `public_net->ipv4->ip`. type: object properties: ipv4: description: IP address (v4) and its reverse DNS entry of this Server. type: object nullable: true properties: id: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 ip: description: IP address (v4) of this Server. type: string example: 1.2.3.4 blocked: description: If the IP is blocked by our anti abuse dept. type: boolean example: false dns_ptr: description: Reverse DNS PTR entry for the IPv4 addresses of this Server. type: string example: server01.example.com required: - ip - blocked - dns_ptr ipv6: description: IPv6 network assigned to this Server and its reverse DNS entry. type: object nullable: true properties: id: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 ip: description: IP address (v6) of this Server. type: string example: 2001:db8::/64 blocked: description: If the IP is blocked by our anti abuse dept. type: boolean example: false dns_ptr: description: Reverse DNS PTR entries for the IPv6 addresses of this Server. type: array nullable: true items: type: object properties: ip: description: Single IPv6 address of this Server for which the reverse DNS entry has been set up. type: string example: 2001:db8::1 dns_ptr: description: DNS pointer for the specific IP address. type: string example: server.example.com required: - ip - dns_ptr required: - ip - blocked - dns_ptr floating_ips: description: IDs of Floating IPs assigned to this Server. type: array items: type: integer format: int64 example: - 478 firewalls: description: Firewalls applied to the public network interface of this Server. type: array items: title: ServerPublicNetFirewall type: object properties: id: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 status: description: Status of the Firewall on the Server. type: string enum: - applied - pending example: applied required: - ipv4 - ipv6 - floating_ips private_net: description: Private networks information. type: array items: type: object properties: network: description: The Network ID the server is attached to. type: integer format: int64 example: 4711 ip: description: The server IP address on the network. type: string example: 10.0.0.2 alias_ips: description: Additional IP addresses of the server on the network. type: array items: type: string example: - 10.0.0.3 - 10.0.0.4 mac_address: description: The server MAC address on the network. type: string example: 86:00:ff:2a:7d:e1 server_type: type: object properties: id: description: ID of the Server type. type: integer format: int64 example: 1 name: description: Unique identifier of the Server type. type: string example: cpx22 description: description: Description of the Server type. type: string example: CPX22 cores: description: Number of cpu cores a Server of this type will have. type: number example: 2 memory: description: Memory a Server of this type will have in GB. type: number example: 4 disk: description: Disk size a Server of this type will have in GB. type: number example: 80 deprecated: description: This field is deprecated. Use the deprecation object instead. type: boolean example: false prices: description: Price per [Location](#tag/locations). type: array items: type: object properties: location: description: Name of the [Location](#tag/locations) the price is for. type: string example: fsn1 price_hourly: description: Hourly price in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross price_monthly: description: Monthly price in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross included_traffic: description: Free traffic per month in bytes in this [Location](#tag/locations). type: integer format: int64 example: 654321 price_per_tb_traffic: description: Additional traffic price per TB in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross required: - location - price_hourly - price_monthly - included_traffic - price_per_tb_traffic storage_type: description: Type of Server boot drive. Local has higher speed. Network has better availability. type: string enum: - local - network cpu_type: description: Type of cpu. type: string enum: - shared - dedicated example: shared category: description: Category of Server Type. type: string example: Shared vCPU architecture: description: 'CPU architecture of the Server Type. ' type: string enum: - x86 - arm example: x86 deprecation: deprecated: true description: 'This field is deprecated. Use the `deprecation` object in the `locations` field instead (`.locations[].deprecation`). ' title: DeprecationInfo type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced locations: description: "Supported [Location](#tag/locations) and per [Location](#tag/locations) details for the [Server Type](#tag/server-types).\n\nA [Server Type](#tag/server-types) is:\n - only supported in the [Location](#tag/locations) that are listed.\n - deprecated in the [Location](#tag/locations) when the `deprecation` property is set.\n - permanently unavailable in the [Location](#tag/locations) when the `deprecation.unavailable_after` date is in the past.\n - temporarily unavailable in the [Location](#tag/locations) when the `deprecation.available` is false.\n" type: array items: description: 'A [Location](#tag/locations) (containing only id and name) and Server Type specific metadata. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the [Location](#tag/locations). type: string example: fsn1 deprecation: title: DeprecationInfo description: 'Describes if, when and how the resource is deprecated. If this field is set to `null` the resource is not deprecated. If a value is set, it is considered deprecated. ' type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced recommended: description: 'Whether the [Server Type](#tag/server-types) is recommended in this [Location](#tag/locations). ' type: boolean example: false available: description: 'Whether the [Server Type](#tag/server-types) is temporarily unavailable in this [Location](#tag/locations). ' type: boolean example: true required: - id - name - deprecation - recommended - available required: - id - name - description - cores - memory - disk - deprecated - prices - storage_type - cpu_type - architecture - locations datacenter: deprecated: true description: '**Deprecated**: This property is deprecated and will be removed after the 1 July 2026. Use the `location` property instead. Data Center this Resource is located at. ' type: object properties: id: description: ID of the [Data Center](#tag/data-centers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Unique name for the [Data Center](#tag/data-centers). May be used as a more descriptive identifier. ' type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1-dc8 description: description: 'Descriptive name for the [Data Center](#tag/data-centers). Desired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier. ' type: string example: Falkenstein DC Park 8 location: description: '[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the [Location](#tag/locations). type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1 description: description: Human readable description of the [Location](#tag/locations). type: string example: Falkenstein DC Park 1 country: description: 'Country the [Location](#tag/locations) resides in. ISO 3166-1 alpha-2 code of the country. ' type: string example: DE city: description: 'Name of the closest city to the [Location](#tag/locations). City name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`. ' type: string example: Falkenstein latitude: description: Latitude of the city closest to the [Location](#tag/locations). type: number format: double example: 50.47612 longitude: description: Longitude of the city closest to the [Location](#tag/locations). type: number format: double example: 12.370071 network_zone: description: Name of the Network Zone this [Location](#tag/locations) resides in. type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: eu-central required: - id - name - description - country - city - latitude - longitude - network_zone server_types: deprecated: true description: 'This field is deprecated, as all of it''s properties are deprecated. [Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers). ' type: object properties: supported: deprecated: true description: 'This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead. List of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers). These [Server Types](#tag/server-types) are generally available in this Data Center, but may be temporarily out of stock. ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 available: deprecated: true description: 'This field is deprecated. Use the `available` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].available`). [Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers). These [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable but are supported in this [Data Center](#tag/data-centers) are listed as `supported`. ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 available_for_migration: deprecated: true description: 'This field is deprecated. Use the `available` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].available`). [Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers). Existing [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types). ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 required: - supported - available - available_for_migration required: - id - name - description - location - server_types location: description: 'Location this Resource is located at. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the [Location](#tag/locations). type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1 description: description: Human readable description of the [Location](#tag/locations). type: string example: Falkenstein DC Park 1 country: description: 'Country the [Location](#tag/locations) resides in. ISO 3166-1 alpha-2 code of the country. ' type: string example: DE city: description: 'Name of the closest city to the [Location](#tag/locations). City name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`. ' type: string example: Falkenstein latitude: description: Latitude of the city closest to the [Location](#tag/locations). type: number format: double example: 50.47612 longitude: description: Longitude of the city closest to the [Location](#tag/locations). type: number format: double example: 12.370071 network_zone: description: Name of the Network Zone this [Location](#tag/locations) resides in. type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: eu-central required: - id - name - description - country - city - latitude - longitude - network_zone image: description: Image the server is based on. type: object properties: id: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 type: description: Type of the Image. type: string enum: - system - app - snapshot - backup example: snapshot status: description: Status of the Image. type: string enum: - available - creating - unavailable example: available name: description: Unique identifier of the Image. This value is only set for system Images. type: string nullable: true example: ubuntu-24.04 description: description: Description of the Image. type: string example: Ubuntu 24.04 Standard 64 bit image_size: description: Size of the Image file in our storage in GB. For snapshot Images this is the value relevant for calculating costs for the Image. type: number nullable: true example: 2.3 disk_size: description: Size of the disk contained in the Image in GB. type: number example: 10 created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' created_from: description: Information about the Server the Image was created from. type: object nullable: true properties: id: description: ID of the Server the Image was created from. type: integer format: int64 example: 1 name: description: Server name at the time the Image was created. type: string example: Server required: - id - name bound_to: description: ID of Server the Image is bound to. Only set for Images of type `backup`. type: integer format: int64 nullable: true example: null os_flavor: description: Flavor of operating system contained in the Image. type: string enum: - ubuntu - centos - debian - fedora - rocky - alma - opensuse - unknown example: ubuntu os_version: description: Operating system version. type: string nullable: true example: '24.04' rapid_deploy: description: Indicates that rapid deploy of the Image is available. type: boolean example: false protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete deprecated: description: Point in time when the Image is considered to be deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2018-02-28T00:00:00Z' deleted: description: Point in time where the Image was deleted (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string nullable: true example: null labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' architecture: description: 'CPU architecture compatible with the Image. ' type: string enum: - x86 - arm example: x86 required: - id - type - status - name - description - image_size - disk_size - created - created_from - bound_to - os_flavor - os_version - protection - deprecated - deleted - labels - architecture nullable: true iso: description: ISO Image that is attached to this Server. Null if no ISO is attached. type: object properties: id: description: ID of the [ISO](#tag/isos). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the ISO. Only set for public ISOs. type: string nullable: true example: FreeBSD-11.0-RELEASE-amd64-dvd1 description: description: Description of the ISO. type: string example: FreeBSD 11.0 x64 type: description: Type of the ISO. type: string enum: - public - private nullable: true deprecation: title: DeprecationInfo description: 'Describes if, when and how the resource is deprecated. If this field is set to `null` the resource is not deprecated. If a value is set, it is considered deprecated. ' type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced architecture: description: 'CPU architecture compatible with the ISO. Null indicates no restriction on the architecture (wildcard). ' type: string enum: - x86 - arm example: x86 nullable: true required: - id - name - description - type - deprecation - architecture nullable: true rescue_enabled: description: True if rescue mode is enabled. Server will then boot into rescue system on next reboot. type: boolean example: false locked: description: True if Server has been locked and is not available to user. type: boolean example: false backup_window: description: Time window (UTC) in which the backup will run, or null if the backups are not enabled. type: string nullable: true example: 22-02 outgoing_traffic: description: Outbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 123456 ingoing_traffic: description: Inbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 123456 included_traffic: description: Free Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 654321 protection: description: Protection configuration for the Server. type: object properties: delete: description: If true, prevents the Server from being deleted. type: boolean example: false rebuild: description: If true, prevents the Server from being rebuilt. type: boolean example: false required: - delete - rebuild labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' volumes: description: IDs of Volumes assigned to this Server. type: array items: type: integer format: int64 load_balancers: description: Load Balancer IDs assigned to the server. type: array items: type: integer format: int64 primary_disk_size: description: Size of the primary Disk. type: number example: 50 placement_group: description: The placement group the server is assigned to. title: PlacementGroupNullable type: object properties: id: description: ID of the [Placement Group](#tag/placement-groups). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the Resource. Must be unique per Project. type: string example: my-resource labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' type: description: 'Type of Placement Group. ' type: string enum: - spread example: spread created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' servers: description: Array of IDs of Servers that are part of this Placement Group. type: array items: type: integer format: int64 example: - 42 required: - id - name - labels - type - created - servers nullable: true required: - id - name - status - created - public_net - private_net - server_type - location - datacenter - image - iso - rescue_enabled - locked - backup_window - outgoing_traffic - ingoing_traffic - included_traffic - protection - labels - primary_disk_size meta: title: ListMeta type: object properties: pagination: description: See "[Pagination](#description/pagination)" for more information. type: object properties: page: description: Current page number. type: integer format: int64 example: 3 per_page: description: Maximum number of entries returned per page. type: integer format: int64 example: 25 previous_page: description: Page number of the previous page. Can be null if the current page is the first one. type: integer format: int64 nullable: true example: 2 next_page: description: Page number of the next page. Can be null if the current page is the last one. type: integer format: int64 nullable: true example: 4 last_page: description: Page number of the last page available. Can be null if the current page is the last one. type: integer format: int64 nullable: true example: 4 total_entries: description: Total number of entries that exist for this query. Can be null if unknown. type: integer format: int64 nullable: true example: 100 required: - page - per_page - previous_page - next_page - last_page - total_entries required: - pagination required: - servers - meta 4xx: description: Request failed with a user error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: unauthorized message: unable to authenticate details: null 5xx: description: Request failed with a server error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: timeout message: request timeout details: null security: - APIToken: [] x-codeSamples: - lang: Go label: Go source: "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tservers, err := client.Server.All(ctx)\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client token = environ["HCLOUD_TOKEN"] client = Client(token=token) servers = client.servers.get_all()' - lang: Shell label: CLI source: hcloud server list post: operationId: create_server summary: Create a Server description: 'Creates a new Server. Returns preliminary information about the Server as well as an Action that covers progress of creation. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `412` | `primary_ip_version_mismatch` | The specified Primary IP has the wrong IP Version | | `422` | `placement_error` | An error during the placement occurred | | `422` | `primary_ip_assigned` | The specified Primary IP is already assigned to a server | | `422` | `primary_ip_datacenter_mismatch` | he specified Primary IP is in a different datacenter | ' tags: - Servers requestBody: description: 'Please note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes). For `server_type` you can either use the ID as listed in `/server_types` or its name. For `image` you can either use the ID as listed in `/images` or its name. If you want to create the Server in a Location, you must set `location` to the ID or name as listed in `/locations`. Some properties like `start_after_create` or `automount` will trigger Actions after the Server is created. Those Actions are listed in the `next_actions` field in the response. For accessing your Server we strongly recommend to use SSH keys by passing the respective key IDs in `ssh_keys`. If you do not specify any `ssh_keys` we will generate a root password for you and return it in the response. Please note that provided user-data is stored in our systems. While we take measures to protect it we highly recommend that you don’t use it to store passwords or other sensitive information. ' required: true content: application/json: schema: title: CreateServerRequest type: object properties: name: description: Name of the Server to create (must be unique per Project and a valid hostname as per RFC 1123). type: string example: my-server location: description: ID or name of the Location to create the Server in (must not be used together with `datacenter`). type: string example: nbg1 datacenter: deprecated: true description: '**Deprecated**: This property is deprecated and will be removed after the 1 July 2026. Use the `location` property instead. ID or name of the Data Center to create Server in (must not be used together with `location`). ' type: string example: nbg1-dc3 server_type: description: ID or name of the Server type this Server should be created with. type: string example: cpx22 start_after_create: description: This automatically triggers a [Power on a Server-Server Action](#tag/server-actions/poweron_server) after the creation is finished and is returned in the `next_actions` response object. type: boolean default: true example: true image: description: ID or name of the Image the Server is created from. type: string example: ubuntu-24.04 placement_group: description: ID of the Placement Group the Server should be in. type: integer format: int64 example: 1 ssh_keys: description: SSH key IDs (`integer`) or names (`string`) which should be injected into the Server at creation time. type: array items: type: string example: - my-ssh-key volumes: description: Volume IDs which should be attached to the Server at the creation time. Volumes must be in the same Location. type: array items: type: integer format: int64 example: - 123 networks: description: Network IDs which should be attached to the Server private network interface at the creation time. type: array items: type: integer format: int64 example: - 456 firewalls: description: Firewalls which should be applied on the Server's public network interface at creation time. type: array items: type: object properties: firewall: description: ID of the Firewall. type: integer format: int64 required: - firewall example: - firewall: 38 user_data: description: Cloud-Init user data to use during Server creation. This field is limited to 32KiB. type: string example: '#cloud-config runcmd: - [touch, /root/cloud-init-worked] ' labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' automount: description: Auto-mount Volumes after attach. type: boolean example: false public_net: description: Public Network options. type: object properties: enable_ipv4: description: Attach an IPv4 on the public NIC. If false, no IPv4 address will be attached. type: boolean default: true enable_ipv6: description: Attach an IPv6 on the public NIC. If false, no IPv6 address will be attached. type: boolean default: true ipv4: description: ID of the ipv4 Primary IP to use. If omitted and enable_ipv4 is true, a new ipv4 Primary IP will automatically be created. type: integer nullable: true ipv6: description: ID of the ipv6 Primary IP to use. If omitted and enable_ipv6 is true, a new ipv6 Primary IP will automatically be created. type: integer nullable: true required: - name - server_type - image responses: '201': description: Request succeeded. content: application/json: schema: title: CreateServerResponse type: object properties: server: type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the Server (must be unique per Project and a valid hostname as per RFC 1123). type: string example: my-resource status: description: Status of the Server. type: string enum: - running - initializing - starting - stopping - 'off' - deleting - migrating - rebuilding - unknown created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' public_net: description: Public network information. The Server's IPv4 address can be found in `public_net->ipv4->ip`. type: object properties: ipv4: description: IP address (v4) and its reverse DNS entry of this Server. type: object nullable: true properties: id: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 ip: description: IP address (v4) of this Server. type: string example: 1.2.3.4 blocked: description: If the IP is blocked by our anti abuse dept. type: boolean example: false dns_ptr: description: Reverse DNS PTR entry for the IPv4 addresses of this Server. type: string example: server01.example.com required: - ip - blocked - dns_ptr ipv6: description: IPv6 network assigned to this Server and its reverse DNS entry. type: object nullable: true properties: id: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 ip: description: IP address (v6) of this Server. type: string example: 2001:db8::/64 blocked: description: If the IP is blocked by our anti abuse dept. type: boolean example: false dns_ptr: description: Reverse DNS PTR entries for the IPv6 addresses of this Server. type: array nullable: true items: type: object properties: ip: description: Single IPv6 address of this Server for which the reverse DNS entry has been set up. type: string example: 2001:db8::1 dns_ptr: description: DNS pointer for the specific IP address. type: string example: server.example.com required: - ip - dns_ptr required: - ip - blocked - dns_ptr floating_ips: description: IDs of Floating IPs assigned to this Server. type: array items: type: integer format: int64 example: - 478 firewalls: description: Firewalls applied to the public network interface of this Server. type: array items: title: ServerPublicNetFirewall type: object properties: id: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 status: description: Status of the Firewall on the Server. type: string enum: - applied - pending example: applied required: - ipv4 - ipv6 - floating_ips private_net: description: Private networks information. type: array items: type: object properties: network: description: The Network ID the server is attached to. type: integer format: int64 example: 4711 ip: description: The server IP address on the network. type: string example: 10.0.0.2 alias_ips: description: Additional IP addresses of the server on the network. type: array items: type: string example: - 10.0.0.3 - 10.0.0.4 mac_address: description: The server MAC address on the network. type: string example: 86:00:ff:2a:7d:e1 server_type: type: object properties: id: description: ID of the Server type. type: integer format: int64 example: 1 name: description: Unique identifier of the Server type. type: string example: cpx22 description: description: Description of the Server type. type: string example: CPX22 cores: description: Number of cpu cores a Server of this type will have. type: number example: 2 memory: description: Memory a Server of this type will have in GB. type: number example: 4 disk: description: Disk size a Server of this type will have in GB. type: number example: 80 deprecated: description: This field is deprecated. Use the deprecation object instead. type: boolean example: false prices: description: Price per [Location](#tag/locations). type: array items: type: object properties: location: description: Name of the [Location](#tag/locations) the price is for. type: string example: fsn1 price_hourly: description: Hourly price in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross price_monthly: description: Monthly price in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross included_traffic: description: Free traffic per month in bytes in this [Location](#tag/locations). type: integer format: int64 example: 654321 price_per_tb_traffic: description: Additional traffic price per TB in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross required: - location - price_hourly - price_monthly - included_traffic - price_per_tb_traffic storage_type: description: Type of Server boot drive. Local has higher speed. Network has better availability. type: string enum: - local - network cpu_type: description: Type of cpu. type: string enum: - shared - dedicated example: shared category: description: Category of Server Type. type: string example: Shared vCPU architecture: description: 'CPU architecture of the Server Type. ' type: string enum: - x86 - arm example: x86 deprecation: deprecated: true description: 'This field is deprecated. Use the `deprecation` object in the `locations` field instead (`.locations[].deprecation`). ' title: DeprecationInfo type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced locations: description: "Supported [Location](#tag/locations) and per [Location](#tag/locations) details for the [Server Type](#tag/server-types).\n\nA [Server Type](#tag/server-types) is:\n - only supported in the [Location](#tag/locations) that are listed.\n - deprecated in the [Location](#tag/locations) when the `deprecation` property is set.\n - permanently unavailable in the [Location](#tag/locations) when the `deprecation.unavailable_after` date is in the past.\n - temporarily unavailable in the [Location](#tag/locations) when the `deprecation.available` is false.\n" type: array items: description: 'A [Location](#tag/locations) (containing only id and name) and Server Type specific metadata. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the [Location](#tag/locations). type: string example: fsn1 deprecation: title: DeprecationInfo description: 'Describes if, when and how the resource is deprecated. If this field is set to `null` the resource is not deprecated. If a value is set, it is considered deprecated. ' type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced recommended: description: 'Whether the [Server Type](#tag/server-types) is recommended in this [Location](#tag/locations). ' type: boolean example: false available: description: 'Whether the [Server Type](#tag/server-types) is temporarily unavailable in this [Location](#tag/locations). ' type: boolean example: true required: - id - name - deprecation - recommended - available required: - id - name - description - cores - memory - disk - deprecated - prices - storage_type - cpu_type - architecture - locations datacenter: deprecated: true description: '**Deprecated**: This property is deprecated and will be removed after the 1 July 2026. Use the `location` property instead. Data Center this Resource is located at. ' type: object properties: id: description: ID of the [Data Center](#tag/data-centers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Unique name for the [Data Center](#tag/data-centers). May be used as a more descriptive identifier. ' type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1-dc8 description: description: 'Descriptive name for the [Data Center](#tag/data-centers). Desired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier. ' type: string example: Falkenstein DC Park 8 location: description: '[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the [Location](#tag/locations). type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1 description: description: Human readable description of the [Location](#tag/locations). type: string example: Falkenstein DC Park 1 country: description: 'Country the [Location](#tag/locations) resides in. ISO 3166-1 alpha-2 code of the country. ' type: string example: DE city: description: 'Name of the closest city to the [Location](#tag/locations). City name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`. ' type: string example: Falkenstein latitude: description: Latitude of the city closest to the [Location](#tag/locations). type: number format: double example: 50.47612 longitude: description: Longitude of the city closest to the [Location](#tag/locations). type: number format: double example: 12.370071 network_zone: description: Name of the Network Zone this [Location](#tag/locations) resides in. type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: eu-central required: - id - name - description - country - city - latitude - longitude - network_zone server_types: deprecated: true description: 'This field is deprecated, as all of it''s properties are deprecated. [Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers). ' type: object properties: supported: deprecated: true description: 'This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead. List of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers). These [Server Types](#tag/server-types) are generally available in this Data Center, but may be temporarily out of stock. ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 available: deprecated: true description: 'This field is deprecated. Use the `available` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].available`). [Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers). These [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable but are supported in this [Data Center](#tag/data-centers) are listed as `supported`. ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 available_for_migration: deprecated: true description: 'This field is deprecated. Use the `available` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].available`). [Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers). Existing [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types). ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 required: - supported - available - available_for_migration required: - id - name - description - location - server_types location: description: 'Location this Resource is located at. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the [Location](#tag/locations). type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1 description: description: Human readable description of the [Location](#tag/locations). type: string example: Falkenstein DC Park 1 country: description: 'Country the [Location](#tag/locations) resides in. ISO 3166-1 alpha-2 code of the country. ' type: string example: DE city: description: 'Name of the closest city to the [Location](#tag/locations). City name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`. ' type: string example: Falkenstein latitude: description: Latitude of the city closest to the [Location](#tag/locations). type: number format: double example: 50.47612 longitude: description: Longitude of the city closest to the [Location](#tag/locations). type: number format: double example: 12.370071 network_zone: description: Name of the Network Zone this [Location](#tag/locations) resides in. type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: eu-central required: - id - name - description - country - city - latitude - longitude - network_zone image: description: Image the server is based on. type: object properties: id: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 type: description: Type of the Image. type: string enum: - system - app - snapshot - backup example: snapshot status: description: Status of the Image. type: string enum: - available - creating - unavailable example: available name: description: Unique identifier of the Image. This value is only set for system Images. type: string nullable: true example: ubuntu-24.04 description: description: Description of the Image. type: string example: Ubuntu 24.04 Standard 64 bit image_size: description: Size of the Image file in our storage in GB. For snapshot Images this is the value relevant for calculating costs for the Image. type: number nullable: true example: 2.3 disk_size: description: Size of the disk contained in the Image in GB. type: number example: 10 created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' created_from: description: Information about the Server the Image was created from. type: object nullable: true properties: id: description: ID of the Server the Image was created from. type: integer format: int64 example: 1 name: description: Server name at the time the Image was created. type: string example: Server required: - id - name bound_to: description: ID of Server the Image is bound to. Only set for Images of type `backup`. type: integer format: int64 nullable: true example: null os_flavor: description: Flavor of operating system contained in the Image. type: string enum: - ubuntu - centos - debian - fedora - rocky - alma - opensuse - unknown example: ubuntu os_version: description: Operating system version. type: string nullable: true example: '24.04' rapid_deploy: description: Indicates that rapid deploy of the Image is available. type: boolean example: false protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete deprecated: description: Point in time when the Image is considered to be deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2018-02-28T00:00:00Z' deleted: description: Point in time where the Image was deleted (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string nullable: true example: null labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' architecture: description: 'CPU architecture compatible with the Image. ' type: string enum: - x86 - arm example: x86 required: - id - type - status - name - description - image_size - disk_size - created - created_from - bound_to - os_flavor - os_version - protection - deprecated - deleted - labels - architecture nullable: true iso: description: ISO Image that is attached to this Server. Null if no ISO is attached. type: object properties: id: description: ID of the [ISO](#tag/isos). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the ISO. Only set for public ISOs. type: string nullable: true example: FreeBSD-11.0-RELEASE-amd64-dvd1 description: description: Description of the ISO. type: string example: FreeBSD 11.0 x64 type: description: Type of the ISO. type: string enum: - public - private nullable: true deprecation: title: DeprecationInfo description: 'Describes if, when and how the resource is deprecated. If this field is set to `null` the resource is not deprecated. If a value is set, it is considered deprecated. ' type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced architecture: description: 'CPU architecture compatible with the ISO. Null indicates no restriction on the architecture (wildcard). ' type: string enum: - x86 - arm example: x86 nullable: true required: - id - name - description - type - deprecation - architecture nullable: true rescue_enabled: description: True if rescue mode is enabled. Server will then boot into rescue system on next reboot. type: boolean example: false locked: description: True if Server has been locked and is not available to user. type: boolean example: false backup_window: description: Time window (UTC) in which the backup will run, or null if the backups are not enabled. type: string nullable: true example: 22-02 outgoing_traffic: description: Outbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 123456 ingoing_traffic: description: Inbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 123456 included_traffic: description: Free Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 654321 protection: description: Protection configuration for the Server. type: object properties: delete: description: If true, prevents the Server from being deleted. type: boolean example: false rebuild: description: If true, prevents the Server from being rebuilt. type: boolean example: false required: - delete - rebuild labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' volumes: description: IDs of Volumes assigned to this Server. type: array items: type: integer format: int64 load_balancers: description: Load Balancer IDs assigned to the server. type: array items: type: integer format: int64 primary_disk_size: description: Size of the primary Disk. type: number example: 50 placement_group: description: The placement group the server is assigned to. title: PlacementGroupNullable type: object properties: id: description: ID of the [Placement Group](#tag/placement-groups). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the Resource. Must be unique per Project. type: string example: my-resource labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' type: description: 'Type of Placement Group. ' type: string enum: - spread example: spread created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' servers: description: Array of IDs of Servers that are part of this Placement Group. type: array items: type: integer format: int64 example: - 42 required: - id - name - labels - type - created - servers nullable: true required: - id - name - status - created - public_net - private_net - server_type - location - datacenter - image - iso - rescue_enabled - locked - backup_window - outgoing_traffic - ingoing_traffic - included_traffic - protection - labels - primary_disk_size action: title: Action type: object properties: id: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 command: description: Command executed in the Action. type: string example: start_resource status: description: Status of the Action. type: string enum: - running - success - error started: description: Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' finished: description: Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null. type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true progress: description: Progress of the Action in percent. type: integer format: int32 example: 100 resources: description: Resources the Action relates to. type: array items: type: object properties: id: description: ID of the Resource. type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 type: description: Type of the Resource. type: string example: server required: - id - type error: description: Error message for the Action if an error occurred, otherwise null. type: object nullable: true properties: code: description: Fixed error code for machines. type: string example: action_failed message: description: Error message for humans. type: string example: Action failed required: - code - message required: - id - command - status - progress - started - finished - resources - error next_actions: type: array items: title: Action type: object properties: id: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 command: description: Command executed in the Action. type: string example: start_resource status: description: Status of the Action. type: string enum: - running - success - error started: description: Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' finished: description: Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null. type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true progress: description: Progress of the Action in percent. type: integer format: int32 example: 100 resources: description: Resources the Action relates to. type: array items: type: object properties: id: description: ID of the Resource. type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 type: description: Type of the Resource. type: string example: server required: - id - type error: description: Error message for the Action if an error occurred, otherwise null. type: object nullable: true properties: code: description: Fixed error code for machines. type: string example: action_failed message: description: Error message for humans. type: string example: Action failed required: - code - message required: - id - command - status - progress - started - finished - resources - error root_password: description: Root password when no SSH keys have been specified. type: string nullable: true example: YItygq1v3GYjjMomLaKc required: - server - action - next_actions - root_password examples: default: value: server: id: 42 name: my-server status: initializing created: '2016-01-30T23:50:00Z' public_net: ipv4: ip: 1.2.3.4 blocked: false dns_ptr: server01.example.com ipv6: ip: 2001:db8::/64 blocked: false dns_ptr: - ip: 2001:db8::1 dns_ptr: server.example.com floating_ips: - 478 firewalls: - id: 38 status: applied private_net: - network: 4711 ip: 10.0.0.2 alias_ips: [] mac_address: 86:00:ff:2a:7d:e1 server_type: id: 1 name: cpx22 description: CPX22 cores: 2 memory: 4 disk: 80 deprecated: true prices: - location: fsn1 price_hourly: net: '1.0000000000' gross: '1.1900000000000000' price_monthly: net: '1.0000000000' gross: '1.1900000000000000' included_traffic: 21990232555520 price_per_tb_traffic: net: '1.0000000000' gross: '1.1900000000000000' storage_type: local cpu_type: shared architecture: x86 locations: - id: 1 name: fsn1 deprecation: null available: true recommended: true - id: 2 name: nbg1 deprecation: announced: '2018-02-28T00:00:00Z' unavailable_after: '2018-05-31T00:00:00Z' available: false recommended: false location: id: 1 name: fsn1 description: Falkenstein DC Park 1 country: DE city: Falkenstein latitude: 50.47612 longitude: 12.370071 network_zone: eu-central datacenter: id: 1 name: fsn1-dc8 description: Falkenstein 1 DC 8 location: id: 1 name: fsn1 description: Falkenstein DC Park 1 country: DE city: Falkenstein latitude: 50.47612 longitude: 12.370071 network_zone: eu-central server_types: supported: - 1 - 2 - 3 available: - 1 - 2 - 3 available_for_migration: - 1 - 2 - 3 image: id: 4711 type: snapshot status: available name: ubuntu-24.04 description: Ubuntu 24.04 Standard 64 bit image_size: 2.3 disk_size: 10 created: '2016-01-30T23:50:00Z' created_from: id: 1 name: Server bound_to: null os_flavor: ubuntu os_version: '24.04' rapid_deploy: false protection: delete: false deprecated: '2018-02-28T00:00:00Z' deleted: null labels: key: value architecture: x86 iso: id: 4711 name: FreeBSD-11.0-RELEASE-amd64-dvd1 description: FreeBSD 11.0 x64 type: public deprecation: announced: '2018-02-28T00:00:00Z' unavailable_after: '2018-05-31T00:00:00Z' architecture: x86 rescue_enabled: false locked: false backup_window: 22-02 outgoing_traffic: 123456 ingoing_traffic: 123456 included_traffic: 654321 protection: delete: false rebuild: false labels: key: value volumes: [] load_balancers: [] primary_disk_size: 50 action: id: 1 command: create_server status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed next_actions: - id: 13 command: start_server status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed root_password: YItygq1v3GYjjMomLaKc 4xx: description: Request failed with a user error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: unauthorized message: unable to authenticate details: null 5xx: description: Request failed with a server error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: timeout message: request timeout details: null security: - APIToken: [] x-codeSamples: - lang: Go label: Go source: "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.Server.Create(ctx, hcloud.ServerCreateOpts{\n\t\tAutomount: hcloud.Ptr(false),\n\t\tFirewalls: []*hcloud.ServerCreateFirewall{\n\t\t\t{\n\t\t\t\tFirewall: hcloud.Firewall{ID: 38},\n\t\t\t},\n\t\t},\n\t\tImage: &hcloud.Image{Name: \"ubuntu-24.04\"},\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t\tLocation: &hcloud.Location{Name: \"nbg1\"},\n\t\tName: \"my-server\",\n\t\tNetworks: []*hcloud.Network{\n\t\t\t{\n\t\t\t\tID: 456,\n\t\t\t},\n\t\t},\n\t\tPlacementGroup: &hcloud.PlacementGroup{ID: 1},\n\t\tPublicNet: &hcloud.ServerCreatePublicNet{\n\t\t\tEnableIPv4: false,\n\t\t\tEnableIPv6: false,\n\t\t\tIPv4: nil,\n\t\t\tIPv6: nil,\n\t\t},\n\t\tServerType: &hcloud.ServerType{Name: \"cx23\"},\n\t\tSSHKeys: []*hcloud.SSHKey{\n\t\t\t{\n\t\t\t\tName: \"my-ssh-key\",\n\t\t\t},\n\t\t},\n\t\tStartAfterCreate: hcloud.Ptr(true),\n\t\tUserData: \"#cloud-config\\nruncmd:\\n- [touch, /root/cloud-init-worked]\\n\",\n\t\tVolumes: []*hcloud.Volume{\n\t\t\t{\n\t\t\t\tID: 123,\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tserver := result.Server\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.firewalls import Firewall\nfrom hcloud.images import Image\nfrom hcloud.locations import Location\nfrom hcloud.networks import Network\nfrom hcloud.placement_groups import PlacementGroup\nfrom hcloud.server_types import ServerType\nfrom hcloud.servers import ServerCreatePublicNetwork\nfrom hcloud.ssh_keys import SSHKey\nfrom hcloud.volumes import Volume\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.servers.create(\n automount=False,\n firewalls=[Firewall(id=38)],\n image=Image(name=\"ubuntu-24.04\"),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n location=Location(name=\"hel1\"),\n name=\"my-server\",\n networks=[Network(id=456)],\n placement_group=PlacementGroup(id=1),\n public_net=ServerCreatePublicNetwork(\n enable_ipv4=False,\n enable_ipv6=False,\n ipv4=None,\n ipv6=None,\n ),\n server_type=ServerType(name=\"cpx22\"),\n ssh_keys=[SSHKey(name=\"my-ssh-key\")],\n start_after_create=True,\n user_data=\"#cloud-config\\nruncmd:\\n- [touch, /root/cloud-init-worked]\\n\",\n volumes=[Volume(id=123)],\n)\n\nresponse.action.wait_until_finished()\n\nserver = response.server" - lang: Shell label: CLI source: "hcloud server create \\\n --automount=false \\\n --firewall 38 \\\n --image ubuntu-24.04 \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\" \\\n --location hel1 \\\n --name my-server \\\n --network 456 \\\n --placement-group 1 \\\n --without-ipv4 \\\n --without-ipv6 \\\n --type cpx22 \\\n --ssh-key my-ssh-key \\\n --start-after-create \\\n --volume 123 \\\n --user-data-from-file <(printf '#cloud-config\\nruncmd:\\n- [touch, /root/cloud-init-worked]\\n')" /servers/{id}: get: operationId: get_server summary: Get a Server description: 'Returns a specific Server object. The Server must exist inside the Project. ' tags: - Servers parameters: - description: ID of the Server. name: id in: path required: true schema: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: server: type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the Server (must be unique per Project and a valid hostname as per RFC 1123). type: string example: my-resource status: description: Status of the Server. type: string enum: - running - initializing - starting - stopping - 'off' - deleting - migrating - rebuilding - unknown created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' public_net: description: Public network information. The Server's IPv4 address can be found in `public_net->ipv4->ip`. type: object properties: ipv4: description: IP address (v4) and its reverse DNS entry of this Server. type: object nullable: true properties: id: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 ip: description: IP address (v4) of this Server. type: string example: 1.2.3.4 blocked: description: If the IP is blocked by our anti abuse dept. type: boolean example: false dns_ptr: description: Reverse DNS PTR entry for the IPv4 addresses of this Server. type: string example: server01.example.com required: - ip - blocked - dns_ptr ipv6: description: IPv6 network assigned to this Server and its reverse DNS entry. type: object nullable: true properties: id: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 ip: description: IP address (v6) of this Server. type: string example: 2001:db8::/64 blocked: description: If the IP is blocked by our anti abuse dept. type: boolean example: false dns_ptr: description: Reverse DNS PTR entries for the IPv6 addresses of this Server. type: array nullable: true items: type: object properties: ip: description: Single IPv6 address of this Server for which the reverse DNS entry has been set up. type: string example: 2001:db8::1 dns_ptr: description: DNS pointer for the specific IP address. type: string example: server.example.com required: - ip - dns_ptr required: - ip - blocked - dns_ptr floating_ips: description: IDs of Floating IPs assigned to this Server. type: array items: type: integer format: int64 example: - 478 firewalls: description: Firewalls applied to the public network interface of this Server. type: array items: title: ServerPublicNetFirewall type: object properties: id: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 status: description: Status of the Firewall on the Server. type: string enum: - applied - pending example: applied required: - ipv4 - ipv6 - floating_ips private_net: description: Private networks information. type: array items: type: object properties: network: description: The Network ID the server is attached to. type: integer format: int64 example: 4711 ip: description: The server IP address on the network. type: string example: 10.0.0.2 alias_ips: description: Additional IP addresses of the server on the network. type: array items: type: string example: - 10.0.0.3 - 10.0.0.4 mac_address: description: The server MAC address on the network. type: string example: 86:00:ff:2a:7d:e1 server_type: type: object properties: id: description: ID of the Server type. type: integer format: int64 example: 1 name: description: Unique identifier of the Server type. type: string example: cpx22 description: description: Description of the Server type. type: string example: CPX22 cores: description: Number of cpu cores a Server of this type will have. type: number example: 2 memory: description: Memory a Server of this type will have in GB. type: number example: 4 disk: description: Disk size a Server of this type will have in GB. type: number example: 80 deprecated: description: This field is deprecated. Use the deprecation object instead. type: boolean example: false prices: description: Price per [Location](#tag/locations). type: array items: type: object properties: location: description: Name of the [Location](#tag/locations) the price is for. type: string example: fsn1 price_hourly: description: Hourly price in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross price_monthly: description: Monthly price in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross included_traffic: description: Free traffic per month in bytes in this [Location](#tag/locations). type: integer format: int64 example: 654321 price_per_tb_traffic: description: Additional traffic price per TB in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross required: - location - price_hourly - price_monthly - included_traffic - price_per_tb_traffic storage_type: description: Type of Server boot drive. Local has higher speed. Network has better availability. type: string enum: - local - network cpu_type: description: Type of cpu. type: string enum: - shared - dedicated example: shared category: description: Category of Server Type. type: string example: Shared vCPU architecture: description: 'CPU architecture of the Server Type. ' type: string enum: - x86 - arm example: x86 deprecation: deprecated: true description: 'This field is deprecated. Use the `deprecation` object in the `locations` field instead (`.locations[].deprecation`). ' title: DeprecationInfo type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced locations: description: "Supported [Location](#tag/locations) and per [Location](#tag/locations) details for the [Server Type](#tag/server-types).\n\nA [Server Type](#tag/server-types) is:\n - only supported in the [Location](#tag/locations) that are listed.\n - deprecated in the [Location](#tag/locations) when the `deprecation` property is set.\n - permanently unavailable in the [Location](#tag/locations) when the `deprecation.unavailable_after` date is in the past.\n - temporarily unavailable in the [Location](#tag/locations) when the `deprecation.available` is false.\n" type: array items: description: 'A [Location](#tag/locations) (containing only id and name) and Server Type specific metadata. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the [Location](#tag/locations). type: string example: fsn1 deprecation: title: DeprecationInfo description: 'Describes if, when and how the resource is deprecated. If this field is set to `null` the resource is not deprecated. If a value is set, it is considered deprecated. ' type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced recommended: description: 'Whether the [Server Type](#tag/server-types) is recommended in this [Location](#tag/locations). ' type: boolean example: false available: description: 'Whether the [Server Type](#tag/server-types) is temporarily unavailable in this [Location](#tag/locations). ' type: boolean example: true required: - id - name - deprecation - recommended - available required: - id - name - description - cores - memory - disk - deprecated - prices - storage_type - cpu_type - architecture - locations datacenter: deprecated: true description: '**Deprecated**: This property is deprecated and will be removed after the 1 July 2026. Use the `location` property instead. Data Center this Resource is located at. ' type: object properties: id: description: ID of the [Data Center](#tag/data-centers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Unique name for the [Data Center](#tag/data-centers). May be used as a more descriptive identifier. ' type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1-dc8 description: description: 'Descriptive name for the [Data Center](#tag/data-centers). Desired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier. ' type: string example: Falkenstein DC Park 8 location: description: '[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the [Location](#tag/locations). type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1 description: description: Human readable description of the [Location](#tag/locations). type: string example: Falkenstein DC Park 1 country: description: 'Country the [Location](#tag/locations) resides in. ISO 3166-1 alpha-2 code of the country. ' type: string example: DE city: description: 'Name of the closest city to the [Location](#tag/locations). City name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`. ' type: string example: Falkenstein latitude: description: Latitude of the city closest to the [Location](#tag/locations). type: number format: double example: 50.47612 longitude: description: Longitude of the city closest to the [Location](#tag/locations). type: number format: double example: 12.370071 network_zone: description: Name of the Network Zone this [Location](#tag/locations) resides in. type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: eu-central required: - id - name - description - country - city - latitude - longitude - network_zone server_types: deprecated: true description: 'This field is deprecated, as all of it''s properties are deprecated. [Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers). ' type: object properties: supported: deprecated: true description: 'This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead. List of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers). These [Server Types](#tag/server-types) are generally available in this Data Center, but may be temporarily out of stock. ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 available: deprecated: true description: 'This field is deprecated. Use the `available` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].available`). [Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers). These [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable but are supported in this [Data Center](#tag/data-centers) are listed as `supported`. ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 available_for_migration: deprecated: true description: 'This field is deprecated. Use the `available` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].available`). [Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers). Existing [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types). ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 required: - supported - available - available_for_migration required: - id - name - description - location - server_types location: description: 'Location this Resource is located at. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the [Location](#tag/locations). type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1 description: description: Human readable description of the [Location](#tag/locations). type: string example: Falkenstein DC Park 1 country: description: 'Country the [Location](#tag/locations) resides in. ISO 3166-1 alpha-2 code of the country. ' type: string example: DE city: description: 'Name of the closest city to the [Location](#tag/locations). City name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`. ' type: string example: Falkenstein latitude: description: Latitude of the city closest to the [Location](#tag/locations). type: number format: double example: 50.47612 longitude: description: Longitude of the city closest to the [Location](#tag/locations). type: number format: double example: 12.370071 network_zone: description: Name of the Network Zone this [Location](#tag/locations) resides in. type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: eu-central required: - id - name - description - country - city - latitude - longitude - network_zone image: description: Image the server is based on. type: object properties: id: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 type: description: Type of the Image. type: string enum: - system - app - snapshot - backup example: snapshot status: description: Status of the Image. type: string enum: - available - creating - unavailable example: available name: description: Unique identifier of the Image. This value is only set for system Images. type: string nullable: true example: ubuntu-24.04 description: description: Description of the Image. type: string example: Ubuntu 24.04 Standard 64 bit image_size: description: Size of the Image file in our storage in GB. For snapshot Images this is the value relevant for calculating costs for the Image. type: number nullable: true example: 2.3 disk_size: description: Size of the disk contained in the Image in GB. type: number example: 10 created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' created_from: description: Information about the Server the Image was created from. type: object nullable: true properties: id: description: ID of the Server the Image was created from. type: integer format: int64 example: 1 name: description: Server name at the time the Image was created. type: string example: Server required: - id - name bound_to: description: ID of Server the Image is bound to. Only set for Images of type `backup`. type: integer format: int64 nullable: true example: null os_flavor: description: Flavor of operating system contained in the Image. type: string enum: - ubuntu - centos - debian - fedora - rocky - alma - opensuse - unknown example: ubuntu os_version: description: Operating system version. type: string nullable: true example: '24.04' rapid_deploy: description: Indicates that rapid deploy of the Image is available. type: boolean example: false protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete deprecated: description: Point in time when the Image is considered to be deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2018-02-28T00:00:00Z' deleted: description: Point in time where the Image was deleted (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string nullable: true example: null labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' architecture: description: 'CPU architecture compatible with the Image. ' type: string enum: - x86 - arm example: x86 required: - id - type - status - name - description - image_size - disk_size - created - created_from - bound_to - os_flavor - os_version - protection - deprecated - deleted - labels - architecture nullable: true iso: description: ISO Image that is attached to this Server. Null if no ISO is attached. type: object properties: id: description: ID of the [ISO](#tag/isos). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the ISO. Only set for public ISOs. type: string nullable: true example: FreeBSD-11.0-RELEASE-amd64-dvd1 description: description: Description of the ISO. type: string example: FreeBSD 11.0 x64 type: description: Type of the ISO. type: string enum: - public - private nullable: true deprecation: title: DeprecationInfo description: 'Describes if, when and how the resource is deprecated. If this field is set to `null` the resource is not deprecated. If a value is set, it is considered deprecated. ' type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced architecture: description: 'CPU architecture compatible with the ISO. Null indicates no restriction on the architecture (wildcard). ' type: string enum: - x86 - arm example: x86 nullable: true required: - id - name - description - type - deprecation - architecture nullable: true rescue_enabled: description: True if rescue mode is enabled. Server will then boot into rescue system on next reboot. type: boolean example: false locked: description: True if Server has been locked and is not available to user. type: boolean example: false backup_window: description: Time window (UTC) in which the backup will run, or null if the backups are not enabled. type: string nullable: true example: 22-02 outgoing_traffic: description: Outbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 123456 ingoing_traffic: description: Inbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 123456 included_traffic: description: Free Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 654321 protection: description: Protection configuration for the Server. type: object properties: delete: description: If true, prevents the Server from being deleted. type: boolean example: false rebuild: description: If true, prevents the Server from being rebuilt. type: boolean example: false required: - delete - rebuild labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' volumes: description: IDs of Volumes assigned to this Server. type: array items: type: integer format: int64 load_balancers: description: Load Balancer IDs assigned to the server. type: array items: type: integer format: int64 primary_disk_size: description: Size of the primary Disk. type: number example: 50 placement_group: description: The placement group the server is assigned to. title: PlacementGroupNullable type: object properties: id: description: ID of the [Placement Group](#tag/placement-groups). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the Resource. Must be unique per Project. type: string example: my-resource labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' type: description: 'Type of Placement Group. ' type: string enum: - spread example: spread created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' servers: description: Array of IDs of Servers that are part of this Placement Group. type: array items: type: integer format: int64 example: - 42 required: - id - name - labels - type - created - servers nullable: true required: - id - name - status - created - public_net - private_net - server_type - location - datacenter - image - iso - rescue_enabled - locked - backup_window - outgoing_traffic - ingoing_traffic - included_traffic - protection - labels - primary_disk_size 4xx: description: Request failed with a user error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: unauthorized message: unable to authenticate details: null 5xx: description: Request failed with a server error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: timeout message: request timeout details: null security: - APIToken: [] x-codeSamples: - lang: Go label: Go source: "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tserver, _, err := client.Server.GetByID(ctx, 123)\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client token = environ["HCLOUD_TOKEN"] client = Client(token=token) server = client.servers.get_by_id(123)' - lang: Shell label: CLI source: hcloud server describe $SERVER put: operationId: update_server summary: Update a Server description: 'Updates a Server. You can update a Server’s name and a Server’s labels. Please note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes). ' tags: - Servers parameters: - description: ID of the Server. name: id in: path required: true schema: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: UpdateServerRequest type: object properties: name: description: New name to set. type: string example: my-server labels: description: 'User-defined labels (`key/value` pairs) for the Resource. Note that the set of [Labels](#description/labels) provided in the request will overwrite the existing one. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: server: type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the Server (must be unique per Project and a valid hostname as per RFC 1123). type: string example: my-resource status: description: Status of the Server. type: string enum: - running - initializing - starting - stopping - 'off' - deleting - migrating - rebuilding - unknown created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' public_net: description: Public network information. The Server's IPv4 address can be found in `public_net->ipv4->ip`. type: object properties: ipv4: description: IP address (v4) and its reverse DNS entry of this Server. type: object nullable: true properties: id: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 ip: description: IP address (v4) of this Server. type: string example: 1.2.3.4 blocked: description: If the IP is blocked by our anti abuse dept. type: boolean example: false dns_ptr: description: Reverse DNS PTR entry for the IPv4 addresses of this Server. type: string example: server01.example.com required: - ip - blocked - dns_ptr ipv6: description: IPv6 network assigned to this Server and its reverse DNS entry. type: object nullable: true properties: id: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 ip: description: IP address (v6) of this Server. type: string example: 2001:db8::/64 blocked: description: If the IP is blocked by our anti abuse dept. type: boolean example: false dns_ptr: description: Reverse DNS PTR entries for the IPv6 addresses of this Server. type: array nullable: true items: type: object properties: ip: description: Single IPv6 address of this Server for which the reverse DNS entry has been set up. type: string example: 2001:db8::1 dns_ptr: description: DNS pointer for the specific IP address. type: string example: server.example.com required: - ip - dns_ptr required: - ip - blocked - dns_ptr floating_ips: description: IDs of Floating IPs assigned to this Server. type: array items: type: integer format: int64 example: - 478 firewalls: description: Firewalls applied to the public network interface of this Server. type: array items: title: ServerPublicNetFirewall type: object properties: id: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 status: description: Status of the Firewall on the Server. type: string enum: - applied - pending example: applied required: - ipv4 - ipv6 - floating_ips private_net: description: Private networks information. type: array items: type: object properties: network: description: The Network ID the server is attached to. type: integer format: int64 example: 4711 ip: description: The server IP address on the network. type: string example: 10.0.0.2 alias_ips: description: Additional IP addresses of the server on the network. type: array items: type: string example: - 10.0.0.3 - 10.0.0.4 mac_address: description: The server MAC address on the network. type: string example: 86:00:ff:2a:7d:e1 server_type: type: object properties: id: description: ID of the Server type. type: integer format: int64 example: 1 name: description: Unique identifier of the Server type. type: string example: cpx22 description: description: Description of the Server type. type: string example: CPX22 cores: description: Number of cpu cores a Server of this type will have. type: number example: 2 memory: description: Memory a Server of this type will have in GB. type: number example: 4 disk: description: Disk size a Server of this type will have in GB. type: number example: 80 deprecated: description: This field is deprecated. Use the deprecation object instead. type: boolean example: false prices: description: Price per [Location](#tag/locations). type: array items: type: object properties: location: description: Name of the [Location](#tag/locations) the price is for. type: string example: fsn1 price_hourly: description: Hourly price in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross price_monthly: description: Monthly price in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross included_traffic: description: Free traffic per month in bytes in this [Location](#tag/locations). type: integer format: int64 example: 654321 price_per_tb_traffic: description: Additional traffic price per TB in this [Location](#tag/locations). type: object properties: net: description: Price without VAT. type: string format: decimal example: '1.0000' gross: description: Price with VAT added. type: string format: decimal example: '1.1900' required: - net - gross required: - location - price_hourly - price_monthly - included_traffic - price_per_tb_traffic storage_type: description: Type of Server boot drive. Local has higher speed. Network has better availability. type: string enum: - local - network cpu_type: description: Type of cpu. type: string enum: - shared - dedicated example: shared category: description: Category of Server Type. type: string example: Shared vCPU architecture: description: 'CPU architecture of the Server Type. ' type: string enum: - x86 - arm example: x86 deprecation: deprecated: true description: 'This field is deprecated. Use the `deprecation` object in the `locations` field instead (`.locations[].deprecation`). ' title: DeprecationInfo type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced locations: description: "Supported [Location](#tag/locations) and per [Location](#tag/locations) details for the [Server Type](#tag/server-types).\n\nA [Server Type](#tag/server-types) is:\n - only supported in the [Location](#tag/locations) that are listed.\n - deprecated in the [Location](#tag/locations) when the `deprecation` property is set.\n - permanently unavailable in the [Location](#tag/locations) when the `deprecation.unavailable_after` date is in the past.\n - temporarily unavailable in the [Location](#tag/locations) when the `deprecation.available` is false.\n" type: array items: description: 'A [Location](#tag/locations) (containing only id and name) and Server Type specific metadata. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the [Location](#tag/locations). type: string example: fsn1 deprecation: title: DeprecationInfo description: 'Describes if, when and how the resource is deprecated. If this field is set to `null` the resource is not deprecated. If a value is set, it is considered deprecated. ' type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced recommended: description: 'Whether the [Server Type](#tag/server-types) is recommended in this [Location](#tag/locations). ' type: boolean example: false available: description: 'Whether the [Server Type](#tag/server-types) is temporarily unavailable in this [Location](#tag/locations). ' type: boolean example: true required: - id - name - deprecation - recommended - available required: - id - name - description - cores - memory - disk - deprecated - prices - storage_type - cpu_type - architecture - locations datacenter: deprecated: true description: '**Deprecated**: This property is deprecated and will be removed after the 1 July 2026. Use the `location` property instead. Data Center this Resource is located at. ' type: object properties: id: description: ID of the [Data Center](#tag/data-centers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Unique name for the [Data Center](#tag/data-centers). May be used as a more descriptive identifier. ' type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1-dc8 description: description: 'Descriptive name for the [Data Center](#tag/data-centers). Desired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier. ' type: string example: Falkenstein DC Park 8 location: description: '[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the [Location](#tag/locations). type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1 description: description: Human readable description of the [Location](#tag/locations). type: string example: Falkenstein DC Park 1 country: description: 'Country the [Location](#tag/locations) resides in. ISO 3166-1 alpha-2 code of the country. ' type: string example: DE city: description: 'Name of the closest city to the [Location](#tag/locations). City name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`. ' type: string example: Falkenstein latitude: description: Latitude of the city closest to the [Location](#tag/locations). type: number format: double example: 50.47612 longitude: description: Longitude of the city closest to the [Location](#tag/locations). type: number format: double example: 12.370071 network_zone: description: Name of the Network Zone this [Location](#tag/locations) resides in. type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: eu-central required: - id - name - description - country - city - latitude - longitude - network_zone server_types: deprecated: true description: 'This field is deprecated, as all of it''s properties are deprecated. [Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers). ' type: object properties: supported: deprecated: true description: 'This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead. List of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers). These [Server Types](#tag/server-types) are generally available in this Data Center, but may be temporarily out of stock. ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 available: deprecated: true description: 'This field is deprecated. Use the `available` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].available`). [Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers). These [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable but are supported in this [Data Center](#tag/data-centers) are listed as `supported`. ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 available_for_migration: deprecated: true description: 'This field is deprecated. Use the `available` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].available`). [Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers). Existing [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types). ' type: array items: type: integer format: int64 example: - 1 - 2 - 3 required: - supported - available - available_for_migration required: - id - name - description - location - server_types location: description: 'Location this Resource is located at. ' type: object properties: id: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the [Location](#tag/locations). type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: fsn1 description: description: Human readable description of the [Location](#tag/locations). type: string example: Falkenstein DC Park 1 country: description: 'Country the [Location](#tag/locations) resides in. ISO 3166-1 alpha-2 code of the country. ' type: string example: DE city: description: 'Name of the closest city to the [Location](#tag/locations). City name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`. ' type: string example: Falkenstein latitude: description: Latitude of the city closest to the [Location](#tag/locations). type: number format: double example: 50.47612 longitude: description: Longitude of the city closest to the [Location](#tag/locations). type: number format: double example: 12.370071 network_zone: description: Name of the Network Zone this [Location](#tag/locations) resides in. type: string pattern: ^[a-z0-9]+(-?[a-z0-9]*)*$ example: eu-central required: - id - name - description - country - city - latitude - longitude - network_zone image: description: Image the server is based on. type: object properties: id: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 type: description: Type of the Image. type: string enum: - system - app - snapshot - backup example: snapshot status: description: Status of the Image. type: string enum: - available - creating - unavailable example: available name: description: Unique identifier of the Image. This value is only set for system Images. type: string nullable: true example: ubuntu-24.04 description: description: Description of the Image. type: string example: Ubuntu 24.04 Standard 64 bit image_size: description: Size of the Image file in our storage in GB. For snapshot Images this is the value relevant for calculating costs for the Image. type: number nullable: true example: 2.3 disk_size: description: Size of the disk contained in the Image in GB. type: number example: 10 created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' created_from: description: Information about the Server the Image was created from. type: object nullable: true properties: id: description: ID of the Server the Image was created from. type: integer format: int64 example: 1 name: description: Server name at the time the Image was created. type: string example: Server required: - id - name bound_to: description: ID of Server the Image is bound to. Only set for Images of type `backup`. type: integer format: int64 nullable: true example: null os_flavor: description: Flavor of operating system contained in the Image. type: string enum: - ubuntu - centos - debian - fedora - rocky - alma - opensuse - unknown example: ubuntu os_version: description: Operating system version. type: string nullable: true example: '24.04' rapid_deploy: description: Indicates that rapid deploy of the Image is available. type: boolean example: false protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete deprecated: description: Point in time when the Image is considered to be deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2018-02-28T00:00:00Z' deleted: description: Point in time where the Image was deleted (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string nullable: true example: null labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' architecture: description: 'CPU architecture compatible with the Image. ' type: string enum: - x86 - arm example: x86 required: - id - type - status - name - description - image_size - disk_size - created - created_from - bound_to - os_flavor - os_version - protection - deprecated - deleted - labels - architecture nullable: true iso: description: ISO Image that is attached to this Server. Null if no ISO is attached. type: object properties: id: description: ID of the [ISO](#tag/isos). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Unique identifier of the ISO. Only set for public ISOs. type: string nullable: true example: FreeBSD-11.0-RELEASE-amd64-dvd1 description: description: Description of the ISO. type: string example: FreeBSD 11.0 x64 type: description: Type of the ISO. type: string enum: - public - private nullable: true deprecation: title: DeprecationInfo description: 'Describes if, when and how the resource is deprecated. If this field is set to `null` the resource is not deprecated. If a value is set, it is considered deprecated. ' type: object nullable: true properties: unavailable_after: description: 'Date of the deprecated resource removal. Once this date is reached, the resource will not be returned by resource type "list" endpoint, and the resource can not be used to create new resources. For example, if this is an image, you can not create new servers with this image after the mentioned date. ' type: string format: date-time example: '2023-09-01T00:00:00Z' announced: description: 'Date of the deprecation announcement. ' type: string format: date-time example: '2023-06-01T00:00:00Z' required: - unavailable_after - announced architecture: description: 'CPU architecture compatible with the ISO. Null indicates no restriction on the architecture (wildcard). ' type: string enum: - x86 - arm example: x86 nullable: true required: - id - name - description - type - deprecation - architecture nullable: true rescue_enabled: description: True if rescue mode is enabled. Server will then boot into rescue system on next reboot. type: boolean example: false locked: description: True if Server has been locked and is not available to user. type: boolean example: false backup_window: description: Time window (UTC) in which the backup will run, or null if the backups are not enabled. type: string nullable: true example: 22-02 outgoing_traffic: description: Outbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 123456 ingoing_traffic: description: Inbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 123456 included_traffic: description: Free Traffic for the current billing period in bytes. type: integer format: int64 nullable: true example: 654321 protection: description: Protection configuration for the Server. type: object properties: delete: description: If true, prevents the Server from being deleted. type: boolean example: false rebuild: description: If true, prevents the Server from being rebuilt. type: boolean example: false required: - delete - rebuild labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' volumes: description: IDs of Volumes assigned to this Server. type: array items: type: integer format: int64 load_balancers: description: Load Balancer IDs assigned to the server. type: array items: type: integer format: int64 primary_disk_size: description: Size of the primary Disk. type: number example: 50 placement_group: description: The placement group the server is assigned to. title: PlacementGroupNullable type: object properties: id: description: ID of the [Placement Group](#tag/placement-groups). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: Name of the Resource. Must be unique per Project. type: string example: my-resource labels: description: 'User-defined labels (`key/value` pairs) for the Resource. For more information, see "[Labels](#description/labels)". ' type: object additionalProperties: type: string example: environment: prod example.com/my: label just-a-key: '' type: description: 'Type of Placement Group. ' type: string enum: - spread example: spread created: description: Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' servers: description: Array of IDs of Servers that are part of this Placement Group. type: array items: type: integer format: int64 example: - 42 required: - id - name - labels - type - created - servers nullable: true required: - id - name - status - created - public_net - private_net - server_type - location - datacenter - image - iso - rescue_enabled - locked - backup_window - outgoing_traffic - ingoing_traffic - included_traffic - protection - labels - primary_disk_size 4xx: description: Request failed with a user error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: unauthorized message: unable to authenticate details: null 5xx: description: Request failed with a server error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: timeout message: request timeout details: null security: - APIToken: [] x-codeSamples: - lang: Go label: Go source: "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tserver, _, err := client.Server.Update(ctx, &hcloud.Server{ID: 123}, hcloud.ServerUpdateOpts{\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t\tName: \"my-server\",\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nserver = client.servers.update(\n server=Server(id=123),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"my-server\",\n)" - lang: Shell label: CLI source: "hcloud server update $SERVER --name \"my-server\"\nhcloud server add-label --overwrite $SERVER \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud server remove-label $SERVER \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_server summary: Delete a Server description: 'Deletes a Server. This immediately removes the Server from your account, and it is no longer accessible. Any resources attached to the server (like Volumes, Primary IPs, Floating IPs, Firewalls, Placement Groups) are detached while the server is deleted. ' tags: - Servers parameters: - description: ID of the Server. name: id in: path required: true schema: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: action: title: Action type: object properties: id: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 command: description: Command executed in the Action. type: string example: start_resource status: description: Status of the Action. type: string enum: - running - success - error started: description: Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2016-01-30T23:55:00Z' finished: description: Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null. type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true progress: description: Progress of the Action in percent. type: integer format: int32 example: 100 resources: description: Resources the Action relates to. type: array items: type: object properties: id: description: ID of the Resource. type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 type: description: Type of the Resource. type: string example: server required: - id - type error: description: Error message for the Action if an error occurred, otherwise null. type: object nullable: true properties: code: description: Fixed error code for machines. type: string example: action_failed message: description: Error message for humans. type: string example: Action failed required: - code - message required: - id - command - status - progress - started - finished - resources - error 4xx: description: Request failed with a user error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: unauthorized message: unable to authenticate details: null 5xx: description: Request failed with a server error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: timeout message: request timeout details: null security: - APIToken: [] x-codeSamples: - lang: Go label: Go source: "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.Server.DeleteWithResult(ctx, &hcloud.Server{ID: 123})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.servers.delete(\n server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server delete $SERVER /servers/{id}/metrics: get: operationId: get_server_metrics summary: Get Metrics for a Server description: 'Get Metrics for specified Server. You must specify the type of metric to get: cpu, disk or network. You can also specify more than one type by comma separation, e.g. cpu,disk. Depending on the type you will get different time series data | Type | Timeseries | Unit | Description | |---------|-------------------------|-----------|------------------------------------------------------| | cpu | cpu | percent | Percent CPU usage | | disk | disk.0.iops.read | iop/s | Number of read IO operations per second | | | disk.0.iops.write | iop/s | Number of write IO operations per second | | | disk.0.bandwidth.read | bytes/s | Bytes read per second | | | disk.0.bandwidth.write | bytes/s | Bytes written per second | | network | network.0.pps.in | packets/s | Public Network interface packets per second received | | | network.0.pps.out | packets/s | Public Network interface packets per second sent | | | network.0.bandwidth.in | bytes/s | Public Network interface bytes/s received | | | network.0.bandwidth.out | bytes/s | Public Network interface bytes/s sent | Metrics are available for the last 30 days only. If you do not provide the step argument we will automatically adjust it so that a maximum of 200 samples are returned. We limit the number of samples returned to a maximum of 500 and will adjust the step parameter accordingly. ' tags: - Servers parameters: - description: ID of the Server. name: id in: path required: true schema: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: Type of metrics to get. name: type in: query required: true schema: type: array items: type: string enum: - cpu - disk - network - description: Start of period to get Metrics for (must be in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). name: start in: query required: true schema: type: string - description: End of period to get Metrics for (must be in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). name: end in: query required: true schema: type: string - description: Resolution of results in seconds. name: step in: query required: false schema: type: string responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: metrics: type: object properties: start: description: Start of period of metrics reported (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2017-01-01T00:00:00Z' end: description: End of period of metrics reported (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time example: '2017-01-01T23:00:00Z' step: description: Resolution of results in seconds. type: number example: 60 time_series: description: Hash with timeseries information, containing the name of timeseries as key. type: object additionalProperties: type: object properties: values: type: array items: type: array items: oneOf: - type: number - type: string description: Metrics Timestamps with values. required: - values example: name_of_timeseries: values: - - 1435781470.622 - '42' - - 1435781471.622 - '43' required: - start - end - step - time_series required: - metrics 4xx: description: Request failed with a user error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: unauthorized message: unable to authenticate details: null 5xx: description: Request failed with a server error. content: application/json: schema: type: object properties: error: type: object properties: code: description: Error code for machines. type: string message: description: Error message for humans. type: string details: description: Details about the error. type: object nullable: true required: - code - message required: - error example: error: code: timeout message: request timeout details: null security: - APIToken: [] x-codeSamples: - lang: Go label: Go source: "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\t\"time\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tmetrics, _, err := client.Server.GetMetrics(ctx, &hcloud.Server{ID: 123}, hcloud.ServerGetMetricsOpts{\n\t\tStart: time.Date(2017, 1, 1, 0, 0, 0, 0, time.UTC),\n\t\tEnd: time.Date(2017, 1, 1, 23, 0, 0, 0, time.UTC),\n\t\tStep: 60,\n\t\tTypes: []hcloud.ServerMetricType{\n\t\t\thcloud.ServerMetricCPU,\n\t\t\thcloud.ServerMetricNetwork,\n\t\t\thcloud.ServerMetricDisk,\n\t\t},\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nimport datetime\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.servers.get_metrics(\n server=Server(id=123),\n start=datetime.datetime(2017, 1, 1, 0, 0, 0, 0, datetime.UTC),\n end=datetime.datetime(2017, 1, 1, 23, 0, 0, 0, datetime.UTC),\n step=60,\n type=[\n \"cpu\",\n \"network\",\n \"disk\",\n ],\n)\n\nresponse.action.wait_until_finished()\n\nmetrics = response.metrics" - lang: Shell label: CLI source: "hcloud server metrics $SERVER \\\n --type cpu,network,disk \\\n --start 2017-01-01T00:00:00Z \\\n --end 2017-01-01T23:00:00Z" components: securitySchemes: APIToken: type: http scheme: bearer x-tagGroups: - name: Actions tags: - Actions - name: Servers tags: - Servers - Server Actions - Server Types - Images - Image Actions - ISOs - Placement Groups - Primary IPs - Primary IP Actions - name: Volumes tags: - Volumes - Volume Actions - name: Floating IPs tags: - Floating IPs - Floating IP Actions - name: Firewalls tags: - Firewalls - Firewall Actions - name: Load Balancers tags: - Load Balancers - Load Balancer Actions - Load Balancer Types - name: Networks tags: - Networks - Network Actions - name: DNS tags: - Zones - Zone Actions - Zone RRSets - Zone RRSet Actions - name: Security tags: - Certificates - Certificate Actions - SSH Keys - name: Locations tags: - Locations - Data Centers - name: Billing tags: - Pricing