openapi: 3.0.3 info: title: Hetzner Cloud 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\n\ hostname: 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\n\ hel1-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\n\ https://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: Actions description: 'Actions represent asynchronous tasks within the API, targeting one or more resources. See [Actions](#description/actions) for more details. ' - name: Certificates description: 'TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic. ' - name: Certificate Actions - name: Data Centers description: 'Each Datacenter represents a _virtual_ Datacenter which may consist of possibly many physical Datacenters. A physical Datacenter is where [Servers](#tag/servers) are hosted. See the [Hetzner Locations Docs](https://docs.hetzner.com/cloud/general/locations/#what-datacenters-are-there) for more details about Datacenters. ' - name: Firewalls description: 'Firewalls can limit the network access to or from your resources. - When applying a firewall with no `in` rule all inbound traffic will be dropped. The default for `in` is `DROP`. - When applying a firewall with no `out` rule all outbound traffic will be accepted. The default for `out` is `ACCEPT`. ' - name: Firewall Actions - name: Floating IPs description: 'Floating IPs help you to create highly available setups. You can assign a Floating IP to any Server. The Server can then use this IP. You can reassign it to a different Server at any time, or you can choose to unassign the IP from Servers all together. Floating IPs can be used globally. This means you can assign a Floating IP to a Server in one Location and later reassign it to a Server in a different Location. For optimal routing and latency Floating IPs should be used in the Location they were created in. For Floating IPs to work with your Server, you must configure them inside your operation system. Floating IPs of type `ipv4` use a single IPv4 address as their `ip` property. Floating IPs of type `ipv6` use a /64 network such as `fc00::/64` as their `ip` property. Any IP address within that network can be used on your host. Floating IPs are billed on a monthly basis. ' - name: Floating IP Actions - name: Images description: 'Images are blueprints for your VM disks. They can be of different types: ### System Images Distribution Images maintained by us, e.g. “Ubuntu 20.04” ### Snapshot Images Maintained by you, for example “Ubuntu 20.04 with my own settings”. These are billed per GB per month. ### Backup Images Daily Backups of your Server. Will automatically be created for Servers which have backups enabled (`POST /servers/{id}/actions/enable_backup`) Bound to exactly one Server. If you delete the Server, you also delete all backups bound to it. You may convert backup Images to snapshot Images to keep them. These are billed at 20% of your server price for 7 backup slots. ### App Images Prebuild images with specific software configurations, e.g. “Wordpress”. All app images are created by us. ' - name: Image Actions - name: ISOs description: 'ISOs are read-only Images of DVDs. While we recommend using our Image functionality to install your Servers we also provide some stock ISOs so you can install more exotic operating systems by yourself. On request our support uploads a private ISO just for you. These are marked with type `private` and only visible in your Project. To attach an ISO to your Server use `POST /servers/{id}/actions/attach_iso`. ' - name: Load Balancers - name: Load Balancer Actions - name: Load Balancer Types description: 'Load Balancer types define kinds of Load Balancers offered. Each type has an hourly and a monthly cost. You will pay whichever amount is lower for your usage of this specific Load Balancer. Costs may differ between Locations. All prices are displayed in the currency of the project owner''s account. ' - name: Locations description: 'Datacenters are organized by Locations. Datacenters in the same Location are connected with very low latency links. ' - name: Networks description: 'Networks is a private networks feature. These Networks are optional and they coexist with the public network that every Server has by default. They allow Servers to talk to each other over a dedicated network interface using private IP addresses not available publicly. The IP addresses are allocated and managed via the API, they must conform to [RFC1918](https://tools.ietf.org/html/rfc1918#section-3) standard. IPs and network interfaces defined under Networks do not provide public internet connectivity, you will need to use the already existing public network interface for that. Each network has a user selected `ip_range` which defines all available IP addresses which can be used for Subnets within the Network. To assign individual IPs to Servers you will need to create Network Subnets, described below. Currently Networks support IPv4 only. ### Subnets Subnets divide the `ip_range` from the parent Network object into multiple Subnetworks that you can use for different specific purposes. For each subnet you need to specify its own `ip_range` which must be contained within the parent Network’s `ip_range`. Additionally each subnet must belong to one of the available Network Zones described below. Subnets can not have overlapping IP ranges. Currently there are three types of subnet: - type `cloud` is used to connect cloud Resources into your Network. - type `server` was used to connect only cloud Servers into your Network. This type is deprecated and is replaced by type cloud. - type `vswitch` allows you to connect [Dedicated Server vSwitch](https://docs.hetzner.com/robot/dedicated-server/network/vswitch) - and all Dedicated Servers attached to it - into your Network Subnets of type `vswitch` must set a `vswitch_id` which is the ID of the existing vSwitch in Hetzner Robot that should be coupled. ### Network Zones Network Zones are groups of Locations which have special high-speed network connections between them. The [Location object](https://docs.hetzner.cloud/reference/cloud#locations-get-a-location) contains the `network_zone` property each Location belongs to. Currently these network zones exist: | Network Zone | Contains Locations | | ------------ | ------------------ | | eu-central | nbg1, fsn1, hel1 | | us-east | ash | | us-west | hil | | ap-southeast | sin | ### IP address management When a cloud Server is attached to a network without the user specifying an IP it automatically gets an IP address assigned from a subnet of type `server` in the same network zone. If you specify the optional `ip` parameter when attaching then we will try to assign that IP. Keep in mind that the Server’s location must be covered by the Subnet’s Network Zone if you specify an IP, or that at least one Subnet with the zone covering Server’s location must exist. A cloud Server can also have more than one IP address in a Network by specifying aliases. For details see the [attach to network action](https://docs.hetzner.cloud/reference/cloud#server-actions-attach-a-server-to-a-network). The following IP addresses are reserved in networks and can not be used: - the first IP of the network `ip_range` as it will be used as a default gateway for the private Network interface. - `172.31.1.1` as it is being used as default gateway for our public Network interfaces. ### Coupling Dedicated Servers By using subnets of type `vswitch` you can couple the Cloud Networks with an existing [Dedicated Server vSwitch](https://docs.hetzner.com/robot/dedicated-server/network/vswitch) and enable dedicated and cloud servers to talk to each other over the Network. In order for this to work the dedicated servers may only use IPs from the subnet and must have a special network configuration. Please refer to [FAQ](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch). vSwitch Layer 2 features are not supported. ### Routes Networks also support the notion of routes which are automatically applied to private traffic. A route makes sure that all packets for a given `destination` IP prefix will be sent to the address specified in its `gateway`. ' - name: Network Actions - name: Placement Groups description: 'Placement groups are used to influence the location of interdependent virtual servers in our data centers. The distribution of the different servers within a group is based on a pattern specified in the type. By enforcing certain rules on the placement of servers within our infrastructure, availability can be influenced in a way that fits your needs best. In `spread` placement groups, all virtual servers will run on different physical servers. This decreases the probability that some servers might fail together. ' - name: Pricing description: 'Returns prices for resources. ' - name: Primary IPs description: 'Primary IPs help you to create more flexible networking setups. You can assign at most one Primary IP of type `ipv4` and one of type `ipv6` per Server. This Server then uses these IPs. You can only unassign a Primary IP from a Server when it''s powered off. This Primary IP can then be assigned to a different powered off Server, or you can keep it around for later use. Primary IPs are bound to a specific Location. You can not assign a Primary IP from one Location to a Server in a different Location. If you need this capability use Floating IPs instead. If your Server''s operating system supports cloud-init there is no further configuration needed to make Primary IPs work. Primary IPs of type `ipv4` use a single IPv4 address as their `ip` property. Primary IPs of type `ipv6` use a /64 network such as `fc00::/64` as their `ip` property. Any IP address within that network can be used on your host. Primary IPs are billed on an hourly basis. ' - name: Primary IP Actions - name: Servers description: 'Servers are virtual machines that can be provisioned. ' - name: Server Actions - name: Server Types description: 'Server types define kinds of Servers offered. Each type has an hourly and a monthly cost. You will pay whichever cost is lower for your usage of this specific Server. Costs may differ between Locations. All prices are displayed in the currency of the project owner''s account. ' - name: SSH Keys description: 'SSH keys are public keys you provide to the cloud system. They can be injected into Servers at creation time. We highly recommend that you use keys instead of passwords to manage your Servers. ' - name: Volumes description: 'A Volume is a highly-available, scalable, and SSD-based block storage for Servers. Pricing for Volumes depends on the Volume size and Location, not the actual used storage. Please see [Hetzner Docs](https://docs.hetzner.com/cloud/#Volumes) for more details about Volumes. ' - name: Volume Actions - name: Zones description: "A Zone represents a [Domain Name System (DNS) zone](https://wikipedia.org/wiki/DNS_zone) managed by Hetzner\ \ authoritative nameservers.\nPlease see [Hetzner Docs](https://docs.hetzner.com/dns-console/dns/general/dns-overview#the-difference-between-domain-and-zone)\ \ for the difference between zones and domains.\n\nThis API supports all zone names with [well-known public suffixes](https://publicsuffix.org/)\ \ (e.g. `.de`, `.com`, `.co.uk`).\nSubdomains are not supported.\n\n

Zone Modes

\n\n\ This API supports two types of zone modes.\n\n- In _primary_ mode, resource record sets ([RRSets](#tag/zone-rrsets)) and\ \ resource records (RRs) are managed via the Cloud API or Hetzner Console.\n- In _secondary_ mode, Hetzner's nameservers\ \ query [RRSets](#tag/zone-rrsets) and RRs from given primary nameservers via [AXFR](https://en.wikipedia.org/wiki/DNS_zone_transfer).\n\ \nThe zone mode cannot be changed, the zone must be deleted and re-created with a new mode.\n\n### SOA Serial\n\nFor zones\ \ in primary mode, Hetzner automatically increases the `SOA` record serial number.\nAs convention, a `YYYYMMDDnn` format\ \ with incrementing `nn` is used.\n\n

Zone file import

\n\nThis API supports\ \ importing a zone file in BIND (RFC [1034](https://datatracker.ietf.org/doc/html/rfc1034)/[1035](https://datatracker.ietf.org/doc/html/rfc1035))\ \ format.\n\nImporting a zone file is only applicable for [Zones](#tag/zones) in primary mode.\n\nDuring an import:\n\n\ - An `$ORIGIN` directive may be present, it must match the [Zone](#tag/zones)'s name with an ending dot\n- A `$TTL` directive\ \ may be present, it is used as new default [Zone](#tag/zones) Time To Live (TTL)\n- Only `IN` (internet) class records\ \ are allowed\n- The assigned authoritative Hetzner nameservers must be present as `NS` records\n- A `SOA` record must\ \ be present\n- Comments for individual records are imported, comments on their own lines are discarded\n\nZone file example:\n\ \n```dns\n$ORIGIN\texample.com.\n$TTL\t3600\n\n@\tIN\tSOA\thydrogen.ns.hetzner.com. dns.hetzner.com. 2024010100 86400\ \ 10800 3600000 3600\n\n@\tIN\t10800\tNS\thydrogen.ns.hetzner.com. ; Some comment.\n@\tIN\t10800\tNS\toxygen.ns.hetzner.com.\n\ @\tIN\t10800\tNS\thelium.ns.hetzner.de.\n```\n" - name: Zone Actions - name: Zone RRSets description: 'This API operates on resource record sets (RRSets) instead of individual resource records (RRs). An RRSet is identified by a name and type. For example, the two RRs - (name: `@`, type: `MX`, value: `10 smtp.example.com.`) and - (name: `@`, type: `MX`, value: `20 smtp-backup.example.com.`) are part of the RRSet identified by (name: `@`, type: `MX`). Please see [Hetzner Docs](https://docs.hetzner.com/networking/dns/record-types/overview) for more information on types. ' - name: Zone RRSet Actions paths: /actions: get: operationId: get_actions summary: Get multiple Actions description: 'Returns multiple Action objects specified by the `id` parameter. **Note**: This endpoint previously allowed listing all actions in the project. This functionality was deprecated in July 2023 and removed on 30 January 2025. - Announcement: https://docs.hetzner.cloud/changelog#2023-07-20-actions-list-endpoint-is-deprecated - Removal: https://docs.hetzner.cloud/changelog#2025-01-30-listing-arbitrary-actions-in-the-actions-list-endpoint-is-removed ' tags: - Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: true schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionListResponse type: object properties: 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 required: - actions 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\tactions, err := client.Action.AllWithOpts(ctx, hcloud.ActionListOpts{ID: []int64{123,\ \ 456}})\n}" /actions/{id}: get: operationId: get_action summary: Get an Action description: 'Returns a specific Action object. ' tags: - Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.Action.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) action = client.actions.get_by_id(123)' /certificates: get: operationId: list_certificates summary: List Certificates description: 'Returns all Certificate objects. ' tags: - Certificates parameters: - 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 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: 'Filter resources by type. May be used multiple times. The response will only contain the resources with the specified type. ' name: type in: query required: false schema: type: array items: description: Type of the Certificate. type: string enum: - uploaded - managed example: uploaded - 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. content: application/json: schema: title: CertificatesResponse type: object properties: certificates: type: array items: title: Certificate type: object properties: id: description: ID of the [Certificate](#tag/certificates). 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 the Certificate. type: string enum: - uploaded - managed example: uploaded certificate: description: Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. type: string nullable: true example: '-----BEGIN CERTIFICATE----- ...' 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' not_valid_before: description: Point in time when the Certificate becomes valid (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2019-01-08T10:00:00Z' not_valid_after: description: 'Point in time when the Certificate stops being valid (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). ' type: string format: date-time nullable: true example: '2019-07-08T09:59:59Z' domain_names: description: Domains and subdomains covered by the Certificate. type: array items: type: string example: - example.com - webmail.example.com - www.example.com fingerprint: description: SHA256 fingerprint of the Certificate. type: string nullable: true example: 03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f status: description: Current status of a type `managed` Certificate, always *null* for type `uploaded` Certificates. type: object nullable: true properties: issuance: description: Status of the issuance process of the Certificate. type: string enum: - pending - completed - failed example: completed renewal: description: Status of the renewal process of the Certificate. type: string enum: - scheduled - pending - failed - unavailable example: scheduled error: description: If issuance or renewal reports `failed`, this property contains information about what happened. type: object nullable: true properties: code: type: string message: type: string example: null used_by: description: Resources currently using the Certificate. type: array items: type: object properties: id: description: ID of resource referenced. type: integer format: int64 example: 4711 type: description: Type of resource referenced. type: string example: load_balancer required: - id - type required: - id - name - labels - certificate - created - not_valid_before - not_valid_after - domain_names - fingerprint - used_by 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: - certificates - meta examples: default: value: certificates: - id: 897 name: my website cert labels: key: value type: uploaded certificate: '-----BEGIN CERTIFICATE----- ...' created: '2019-01-08T12:10:00Z' not_valid_before: '2019-01-08T10:00:00Z' not_valid_after: '2019-07-08T09:59:59Z' domain_names: - example.com - webmail.example.com - www.example.com fingerprint: 03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f status: null used_by: - id: 4711 type: load_balancer meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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\tcertificates, err := client.Certificate.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) certificates = client.certificates.get_all()' - lang: Shell label: CLI source: hcloud certificate list post: operationId: create_certificate summary: Create a Certificate description: 'Creates a new Certificate. The default type **uploaded** allows for uploading your existing `certificate` and `private_key` in PEM format. You have to monitor its expiration date and handle renewal yourself. In contrast, type **managed** requests a new Certificate from *Let''s Encrypt* for the specified `domain_names`. Only domains managed by *Hetzner DNS* are supported. We handle renewal and timely alert the project owner via email if problems occur. For type `managed` Certificates the `action` key of the response contains the Action that allows for tracking the issuance process. For type `uploaded` Certificates the `action` is always null. ' tags: - Certificates requestBody: required: true content: application/json: schema: title: CreateCertificateRequest type: object properties: name: description: Name of the Certificate. type: string example: my website cert 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: Choose between uploading a Certificate in PEM format or requesting a managed *Let's Encrypt* Certificate. type: string enum: - uploaded - managed default: uploaded example: uploaded certificate: description: Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. Required for type `uploaded` Certificates. type: string example: '-----BEGIN CERTIFICATE----- ...' private_key: description: Certificate key in PEM format. Required for type `uploaded` Certificates. type: string example: '-----BEGIN PRIVATE KEY----- ...' domain_names: description: Domains and subdomains that should be contained in the Certificate issued by *Let's Encrypt*. Required for type `managed` Certificates. type: array items: type: string example: - example.com - www.example.com required: - name examples: uploaded: summary: Creating a type `uploaded` Certificate value: name: my website cert type: uploaded certificate: '-----BEGIN CERTIFICATE----- ...' private_key: '-----BEGIN PRIVATE KEY----- ...' managed: summary: Creating a type `managed` Certificate value: name: my website cert type: managed domain_names: - example.com - webmail.example.com - www.example.com responses: '201': description: Request succeeded. content: application/json: schema: title: CreateCertificateResponse type: object properties: certificate: title: Certificate type: object properties: id: description: ID of the [Certificate](#tag/certificates). 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 the Certificate. type: string enum: - uploaded - managed example: uploaded certificate: description: Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. type: string nullable: true example: '-----BEGIN CERTIFICATE----- ...' 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' not_valid_before: description: Point in time when the Certificate becomes valid (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2019-01-08T10:00:00Z' not_valid_after: description: 'Point in time when the Certificate stops being valid (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). ' type: string format: date-time nullable: true example: '2019-07-08T09:59:59Z' domain_names: description: Domains and subdomains covered by the Certificate. type: array items: type: string example: - example.com - webmail.example.com - www.example.com fingerprint: description: SHA256 fingerprint of the Certificate. type: string nullable: true example: 03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f status: description: Current status of a type `managed` Certificate, always *null* for type `uploaded` Certificates. type: object nullable: true properties: issuance: description: Status of the issuance process of the Certificate. type: string enum: - pending - completed - failed example: completed renewal: description: Status of the renewal process of the Certificate. type: string enum: - scheduled - pending - failed - unavailable example: scheduled error: description: If issuance or renewal reports `failed`, this property contains information about what happened. type: object nullable: true properties: code: type: string message: type: string example: null used_by: description: Resources currently using the Certificate. type: array items: type: object properties: id: description: ID of resource referenced. type: integer format: int64 example: 4711 type: description: Type of resource referenced. type: string example: load_balancer required: - id - type required: - id - name - labels - certificate - created - not_valid_before - not_valid_after - domain_names - fingerprint - used_by action: title: ActionNullable 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 nullable: true required: - certificate examples: uploaded: summary: Response when creating a type `uploaded` Certificate value: certificate: id: 897 name: my website cert labels: key: value type: uploaded certificate: '-----BEGIN CERTIFICATE----- ...' created: '2019-01-08T12:10:00Z' not_valid_before: '2019-01-08T10:00:00Z' not_valid_after: '2019-07-08T09:59:59Z' domain_names: - example.com - webmail.example.com - www.example.com fingerprint: 03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f status: null used_by: - id: 4711 type: load_balancer action: null managed: summary: Response when creating a type `managed` Certificate value: certificate: id: 897 name: my website cert labels: key: value type: managed certificate: null created: '2019-01-08T12:10:00Z' not_valid_before: null not_valid_after: null domain_names: - example.com - webmail.example.com - www.example.com fingerprint: null status: issuance: pending renewal: unavailable error: null used_by: - id: 4711 type: load_balancer action: id: 13 command: create_certificate status: running progress: 0 started: '2019-01-08T12:10:00Z' finished: null resources: - id: 879 type: certificate error: code: action_failed message: Action failed 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 (managed) 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\tcertificate, _, err := client.Certificate.Create(ctx, hcloud.CertificateCreateOpts{\n\ \t\tDomainNames: []string{\n\t\t\t\"example.com\",\n\t\t\t\"webmail.example.com\",\n\t\t\t\"www.example.com\",\n\ \t\t},\n\t\tName: \"my website cert\",\n\t\tType: hcloud.CertificateTypeManaged,\n\t})\n}" - lang: Go label: Go (uploaded) 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\tcertificate, _, err := client.Certificate.Create(ctx, hcloud.CertificateCreateOpts{\n\ \t\tCertificate: \"-----BEGIN CERTIFICATE-----\\n...\",\n\t\tName: \"my website cert\",\n\t\tPrivateKey:\ \ \"-----BEGIN PRIVATE KEY-----\\n...\",\n\t\tType: hcloud.CertificateTypeUploaded,\n\t})\n}" - lang: Python label: Python (managed) source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"\ HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ncertificate = client.certificates.create_managed(\n domain_names=[\n\ \ \"example.com\",\n \"webmail.example.com\",\n \"www.example.com\",\n ],\n name=\"my\ \ website cert\",\n)" - lang: Python label: Python (uploaded) source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"\ HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ncertificate = client.certificates.create(\n certificate=\"-----BEGIN\ \ CERTIFICATE-----\\n...\",\n name=\"my website cert\",\n private_key=\"-----BEGIN PRIVATE KEY-----\\n...\"\ ,\n)" - lang: Shell label: CLI (managed) source: "hcloud certificate create \\\n --name \"my website cert\" \\\n --type managed \\\n --domain example.com\ \ \\\n --domain webmail.example.com \\\n --domain www.example.com" - lang: Shell label: CLI (uploaded) source: "hcloud certificate create \\\n --name \"my website cert\" \\\n --type uploaded \\\n --cert-file\ \ my-cert.pem \\\n --key-file my-key.pem" /certificates/actions: get: operationId: list_certificates_actions summary: List Actions description: 'Returns all Action objects. You can `sort` the results by using the sort URI parameter, and filter them with the `status` and `id` parameter. ' tags: - Certificate Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.Certificate.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.certificates.actions.get_all()' /certificates/actions/{id}: get: operationId: get_certificates_action summary: Get an Action description: 'Returns a specific Action object. ' tags: - Certificate Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.Certificate.Action.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) action = client.certificates.actions.get_by_id(123)' /certificates/{id}: get: operationId: get_certificate summary: Get a Certificate description: 'Gets a specific Certificate object. ' tags: - Certificates parameters: - description: ID of the Certificate. name: id in: path required: true schema: description: ID of the [Certificate](#tag/certificates). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: CertificateResponse type: object properties: certificate: title: Certificate type: object properties: id: description: ID of the [Certificate](#tag/certificates). 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 the Certificate. type: string enum: - uploaded - managed example: uploaded certificate: description: Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. type: string nullable: true example: '-----BEGIN CERTIFICATE----- ...' 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' not_valid_before: description: Point in time when the Certificate becomes valid (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2019-01-08T10:00:00Z' not_valid_after: description: 'Point in time when the Certificate stops being valid (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). ' type: string format: date-time nullable: true example: '2019-07-08T09:59:59Z' domain_names: description: Domains and subdomains covered by the Certificate. type: array items: type: string example: - example.com - webmail.example.com - www.example.com fingerprint: description: SHA256 fingerprint of the Certificate. type: string nullable: true example: 03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f status: description: Current status of a type `managed` Certificate, always *null* for type `uploaded` Certificates. type: object nullable: true properties: issuance: description: Status of the issuance process of the Certificate. type: string enum: - pending - completed - failed example: completed renewal: description: Status of the renewal process of the Certificate. type: string enum: - scheduled - pending - failed - unavailable example: scheduled error: description: If issuance or renewal reports `failed`, this property contains information about what happened. type: object nullable: true properties: code: type: string message: type: string example: null used_by: description: Resources currently using the Certificate. type: array items: type: object properties: id: description: ID of resource referenced. type: integer format: int64 example: 4711 type: description: Type of resource referenced. type: string example: load_balancer required: - id - type required: - id - name - labels - certificate - created - not_valid_before - not_valid_after - domain_names - fingerprint - used_by required: - certificate examples: default: value: certificate: id: 897 name: my website cert labels: key: value type: uploaded certificate: '-----BEGIN CERTIFICATE----- ...' created: '2019-01-08T12:10:00Z' not_valid_before: '2019-01-08T10:00:00Z' not_valid_after: '2019-07-08T09:59:59Z' domain_names: - example.com - webmail.example.com - www.example.com fingerprint: 03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f status: null used_by: - id: 4711 type: load_balancer 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\tcertificate, _, err := client.Certificate.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) certificate = client.certificates.get_by_id(123)' - lang: Shell label: CLI source: hcloud certificate describe $CERTIFICATE put: operationId: update_certificate summary: Update a Certificate description: 'Updates the Certificate properties. Note: if the Certificate object changes during the request, the response will be a “conflict” error. ' tags: - Certificates parameters: - description: ID of the Certificate. name: id in: path required: true schema: description: ID of the [Certificate](#tag/certificates). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: UpdateCertificateRequest type: object properties: name: description: New Certificate name. type: string example: my website cert 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: title: CertificateResponse type: object properties: certificate: title: Certificate type: object properties: id: description: ID of the [Certificate](#tag/certificates). 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 the Certificate. type: string enum: - uploaded - managed example: uploaded certificate: description: Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. type: string nullable: true example: '-----BEGIN CERTIFICATE----- ...' 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' not_valid_before: description: Point in time when the Certificate becomes valid (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2019-01-08T10:00:00Z' not_valid_after: description: 'Point in time when the Certificate stops being valid (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). ' type: string format: date-time nullable: true example: '2019-07-08T09:59:59Z' domain_names: description: Domains and subdomains covered by the Certificate. type: array items: type: string example: - example.com - webmail.example.com - www.example.com fingerprint: description: SHA256 fingerprint of the Certificate. type: string nullable: true example: 03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f status: description: Current status of a type `managed` Certificate, always *null* for type `uploaded` Certificates. type: object nullable: true properties: issuance: description: Status of the issuance process of the Certificate. type: string enum: - pending - completed - failed example: completed renewal: description: Status of the renewal process of the Certificate. type: string enum: - scheduled - pending - failed - unavailable example: scheduled error: description: If issuance or renewal reports `failed`, this property contains information about what happened. type: object nullable: true properties: code: type: string message: type: string example: null used_by: description: Resources currently using the Certificate. type: array items: type: object properties: id: description: ID of resource referenced. type: integer format: int64 example: 4711 type: description: Type of resource referenced. type: string example: load_balancer required: - id - type required: - id - name - labels - certificate - created - not_valid_before - not_valid_after - domain_names - fingerprint - used_by required: - certificate examples: default: value: certificate: id: 897 name: my website cert labels: key: value type: uploaded certificate: '-----BEGIN CERTIFICATE----- ...' created: '2019-01-08T12:10:00Z' not_valid_before: '2019-01-08T10:00:00Z' not_valid_after: '2019-07-08T09:59:59Z' domain_names: - example.com - webmail.example.com - www.example.com fingerprint: 03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f status: null used_by: - id: 4711 type: load_balancer 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\tcertificate, _, err := client.Certificate.Update(ctx, &hcloud.Certificate{ID: 123},\ \ hcloud.CertificateUpdateOpts{\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 website cert\",\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.certificates\ \ import Certificate\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ncertificate = client.certificates.update(\n\ \ certificate=Certificate(id=123),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\"\ : \"label\",\n \"just-a-key\": \"\",\n },\n name=\"my website cert\",\n)" - lang: Shell label: CLI source: "hcloud certificate update $CERTIFICATE --name \"my website cert\"\nhcloud certificate add-label --overwrite\ \ $CERTIFICATE \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud certificate remove-label\ \ $CERTIFICATE \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_certificate summary: Delete a Certificate description: 'Deletes a Certificate. ' tags: - Certificates parameters: - description: ID of the Certificate. name: id in: path required: true schema: description: ID of the [Certificate](#tag/certificates). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.Certificate.Delete(ctx, &hcloud.Certificate{ID: 123})\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.certificates import Certificate token = environ["HCLOUD_TOKEN"] client = Client(token=token) client.certificates.delete(certificate=Certificate(id=123))' - lang: Shell label: CLI source: hcloud certificate delete $CERTIFICATE /certificates/{id}/actions: get: operationId: list_certificate_actions summary: List Actions for a Certificate description: 'Returns all Action objects for a Certificate. You can sort the results by using the `sort` URI parameter, and filter them with the `status` parameter. Only type `managed` Certificates can have Actions. For type `uploaded` Certificates the `actions` key will always contain an empty array. ' tags: - Certificate Actions parameters: - description: ID of the Certificate. name: id in: path required: true schema: description: ID of the [Certificate](#tag/certificates). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - meta examples: default: value: actions: - id: 14 command: issue_certificate status: success progress: 100 started: '2021-01-30T23:55:00Z' finished: '2021-01-30T23:57:00Z' resources: - id: 896 type: certificate error: code: action_failed message: Action failed meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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: [] /certificates/{id}/actions/retry: post: operationId: retry_certificate summary: Retry Issuance or Renewal description: 'Retry a failed Certificate issuance or renewal. Only applicable if the type of the Certificate is `managed` and the issuance or renewal status is `failed`. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | | `caa_record_does_not_allow_ca` | CAA record does not allow certificate authority | | | `ca_dns_validation_failed` | Certificate Authority: DNS validation failed | | | `ca_too_many_authorizations_failed_recently` | Certificate Authority: Too many authorizations failed recently | | | `ca_too_many_certificates_issued_for_registered_domain` | Certificate Authority: Too many certificates issued for registered domain | | | `ca_too_many_duplicate_certificates` | Certificate Authority: Too many duplicate certificates | | | `could_not_verify_domain_delegated_to_zone` | Could not verify domain delegated to zone | | | `dns_zone_not_found` | DNS zone not found | | | `dns_zone_is_secondary_zone` | DNS zone is a secondary zone | ' tags: - Certificate Actions parameters: - description: ID of the Certificate. name: id in: path required: true schema: description: ID of the [Certificate](#tag/certificates). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 14 command: issue_certificate status: success progress: 100 started: '2021-01-30T23:55:00Z' finished: '2021-01-30T23:57:00Z' resources: - id: 896 type: certificate error: code: action_failed message: Action failed 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\taction, _, err := client.Certificate.RetryIssuance(ctx, &hcloud.Certificate{ID: 123})\n\ \n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.certificates import Certificate token = environ["HCLOUD_TOKEN"] client = Client(token=token) action = client.certificates.retry_issuance(certificate=Certificate(id=123)) action.wait_until_finished()' - lang: Shell label: CLI source: hcloud certificate retry $CERTIFICATE /certificates/{id}/actions/{action_id}: get: deprecated: true operationId: get_certificate_action summary: Get an Action for a Certificate description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific Action for a Certificate. Only type `managed` Certificates have Actions. ' tags: - Certificate Actions parameters: - description: ID of the Certificate. name: id in: path required: true schema: description: ID of the [Certificate](#tag/certificates). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 14 command: issue_certificate status: success progress: 100 started: '2021-01-30T23:55:00Z' finished: '2021-01-30T23:57:00Z' resources: - id: 896 type: certificate error: code: action_failed message: Action failed 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: [] /datacenters: get: operationId: list_datacenters summary: List Data Centers description: 'Returns all [Data Centers](#tag/data-centers). ' tags: - Data Centers 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: '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 - 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. content: application/json: schema: type: object properties: datacenters: description: List of [Data Centers](#tag/data-centers). type: array items: 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 recommendation: deprecated: true description: 'This field is deprecated. Use the `recommended` flag in the [Server Type](#tag/server-types) `locations` field instead (`server_type.locations[].recommended`). Recommended [Data Center](#tag/data-centers) for creating new resources. ' type: integer format: int64 example: 1 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: - datacenters - recommendation - 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\tdatacenters, err := client.Datacenter.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) datacenters = client.datacenters.get_all()' - lang: Shell label: CLI source: hcloud datacenter list /datacenters/{id}: get: operationId: get_datacenter summary: Get a Data Center description: 'Returns a single [Data Center](#tag/data-centers). ' tags: - Data Centers parameters: - description: ID of the Data Center. name: id in: path required: true schema: description: ID of the [Data Center](#tag/data-centers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: datacenter: 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 required: - datacenter 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\tdatacenter, _, err := client.Datacenter.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) datacenter = client.datacenters.get_by_id(123)' - lang: Shell label: CLI source: hcloud datacenter describe $DATACENTER /firewalls: get: operationId: list_firewalls summary: List Firewalls description: 'Returns all [Firewalls](#tag/firewalls). Use the provided URI parameters to modify the result. ' tags: - Firewalls parameters: - 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 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: 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. content: application/json: schema: title: FirewallsResponse type: object properties: firewalls: type: array items: title: FirewallResponse type: object properties: id: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Firewall](#tag/firewalls). Limited to a maximum of 128 characters. Must be unique per Project. ' type: string example: new-name 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: '' 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' rules: type: array items: title: RuleResponse type: object properties: description: description: Description of the rule. type: string nullable: true maxLength: 255 direction: description: 'Traffic direction in which the rule should be applied to. Use `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs. ' type: string enum: - in - out example: in source_ips: description: 'List of permitted IPv4/IPv6 addresses for incoming traffic. The `direction` must be set to `in`. IPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 destination_ips: description: 'List of permitted IPv4/IPv6 addresses for outgoing traffic. The `direction` must be set to `out`. IPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: [] protocol: description: Network protocol to apply the rule for. type: string enum: - tcp - udp - icmp - esp - gre port: description: 'Port or port range to apply the rule for. Only applicable for protocols `tcp` and `udp`. A port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include all ports starting from 1024 up to port 5000. ' type: string example: '80' nullable: true required: - direction - protocol - destination_ips - source_ips - port applied_to: type: array items: type: object properties: type: description: The type of resource to apply. type: string enum: - server - label_selector example: server server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id label_selector: description: '[Label Selector](#description/label-selector) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `label_selector`, otherwise `null`. ' type: object properties: selector: description: The selector. type: string example: env=prod required: - selector applied_to_resources: description: 'Resources applied to via this [Label Selector](#description/label-selector). ' type: array items: type: object properties: type: description: Type of resource. type: string enum: - server example: server server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id required: - type required: - id - name - created - rules - applied_to 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: - firewalls - 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\tfirewalls, err := client.Firewall.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) firewalls = client.firewalls.get_all()' - lang: Shell label: CLI source: hcloud firewall list post: operationId: create_firewall summary: Create a Firewall description: 'Create a [Firewall](#tag/firewalls). #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `server_already_added` | The [Server](#tag/servers) was applied more than once. | | `422` | `incompatible_network_type` | The resources network type is not supported by [Firewalls](#tag/firewalls). | | `422` | `firewall_resource_not_found` | The resource the [Firewall](#tag/firewalls) should be attached to was not found. | ' tags: - Firewalls requestBody: required: true content: application/json: schema: title: CreateFirewallRequest type: object properties: name: description: 'Name of the [Firewall](#tag/firewalls). Limited to a maximum of 128 characters. Must be unique per Project. ' type: string example: new-name 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: '' rules: description: 'Array of rules. Rules are limited to 50 entries per [Firewall](#tag/firewalls) and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits). ' type: array items: title: Rule type: object properties: description: description: Description of the rule. type: string nullable: true maxLength: 255 direction: description: 'Traffic direction in which the rule should be applied to. Use `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs. ' type: string enum: - in - out example: in source_ips: description: 'List of permitted IPv4/IPv6 addresses for incoming traffic. The `direction` must be set to `in`. IPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 destination_ips: description: 'List of permitted IPv4/IPv6 addresses for outgoing traffic. The `direction` must be set to `out`. IPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: [] protocol: description: Network protocol to apply the rule for. type: string enum: - tcp - udp - icmp - esp - gre port: description: 'Port or port range to apply the rule for. Only applicable for protocols `tcp` and `udp`. A port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include all ports starting from 1024 up to port 5000. ' type: string example: '80' required: - direction - protocol example: - direction: in source_ips: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 protocol: tcp port: '80' apply_to: description: 'Resources to apply the [Firewall](#tag/firewalls) to. Resources added directly are taking precedence over those added via a [Label Selector](#description/label-selector). ' type: array items: title: FirewallResource type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 required: - id label_selector: description: '[Label Selector](#description/label-selector) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `label_selector`, otherwise `null`. ' type: object properties: selector: description: The selector. type: string example: env=prod required: - selector required: - type required: - name examples: default: value: name: Corporate Intranet Protection labels: key: value rules: - description: Allow port 80 direction: in source_ips: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 protocol: tcp port: '80' apply_to: - type: server server: id: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: CreateFirewallResponse type: object properties: firewall: title: FirewallResponse type: object properties: id: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Firewall](#tag/firewalls). Limited to a maximum of 128 characters. Must be unique per Project. ' type: string example: new-name 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: '' 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' rules: type: array items: title: RuleResponse type: object properties: description: description: Description of the rule. type: string nullable: true maxLength: 255 direction: description: 'Traffic direction in which the rule should be applied to. Use `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs. ' type: string enum: - in - out example: in source_ips: description: 'List of permitted IPv4/IPv6 addresses for incoming traffic. The `direction` must be set to `in`. IPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 destination_ips: description: 'List of permitted IPv4/IPv6 addresses for outgoing traffic. The `direction` must be set to `out`. IPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: [] protocol: description: Network protocol to apply the rule for. type: string enum: - tcp - udp - icmp - esp - gre port: description: 'Port or port range to apply the rule for. Only applicable for protocols `tcp` and `udp`. A port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include all ports starting from 1024 up to port 5000. ' type: string example: '80' nullable: true required: - direction - protocol - destination_ips - source_ips - port applied_to: type: array items: type: object properties: type: description: The type of resource to apply. type: string enum: - server - label_selector example: server server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id label_selector: description: '[Label Selector](#description/label-selector) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `label_selector`, otherwise `null`. ' type: object properties: selector: description: The selector. type: string example: env=prod required: - selector applied_to_resources: description: 'Resources applied to via this [Label Selector](#description/label-selector). ' type: array items: type: object properties: type: description: Type of resource. type: string enum: - server example: server server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id required: - type required: - id - name - created - rules - applied_to 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 example: - id: 13 command: set_firewall_rules status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 38 type: firewall error: code: action_failed message: Action failed - id: 14 command: apply_firewall status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server - id: 38 type: firewall error: code: action_failed message: Action failed 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\"net\"\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.Firewall.Create(ctx, hcloud.FirewallCreateOpts{\n\t\tApplyTo:\ \ []hcloud.FirewallResource{\n\t\t\t{\n\t\t\t\tType: hcloud.FirewallResourceTypeServer,\n\t\t\t\tServer: &hcloud.FirewallResourceServer{\n\ \t\t\t\t\tID: 42,\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t\tLabels: map[string]string{\n\t\t\t\"env\": \"dev\",\n\t\t},\n\ \t\tName: \"Corporate Intranet Protection\",\n\t\tRules: []hcloud.FirewallRule{\n\t\t\t{\n\t\t\t\tDescription: hcloud.Ptr(\"\ Allow port 80\"),\n\t\t\t\tDirection: hcloud.FirewallRuleDirectionIn,\n\t\t\t\tPort: hcloud.Ptr(\"80\"\ ),\n\t\t\t\tProtocol: hcloud.FirewallRuleProtocolTCP,\n\t\t\t\tSourceIPs: []net.IPNet{\n\t\t\t\t\t{\n\t\t\t\t\ \t\tIP: net.ParseIP(\"192.0.2.2\"),\n\t\t\t\t\t\tMask: net.CIDRMask(32, 32),\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\ \t\t\tIP: net.ParseIP(\"192.0.2.0\"),\n\t\t\t\t\t\tMask: net.CIDRMask(24, 32),\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\ \t\t\t\tIP: net.ParseIP(\"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b\"),\n\t\t\t\t\t\tMask: net.CIDRMask(128, 128),\n\ \t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Actions...)\n\n\t\ firewall := result.Firewall\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.firewalls\ \ import FirewallResource, FirewallRule\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\n\ client = Client(token=token)\n\nresponse = client.firewalls.create(\n resources=[\n FirewallResource(\n\ \ type=\"server\",\n server=Server(id=42),\n )\n ],\n labels={\n \"env\"\ : \"dev\",\n },\n name=\"Corporate Intranet Protection\",\n rules=[\n FirewallRule(\n \ \ description=\"Allow port 80\",\n direction=\"in\",\n port=\"80\",\n protocol=\"\ tcp\",\n source_ips=[\n \"192.0.2.2\",\n \"192.0.2.0/24\",\n \ \ \"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b\",\n ],\n )\n ],\n)\n\nfor action in response.actions:\n\ \ action.wait_until_finished()\n\nfirewall = response.firewall" - lang: Shell label: CLI source: "hcloud firewall create \\\n --name \"Corporate Intranet Protection\" \\\n --label \"env=dev\" \\\n\ \ --rules-file <(echo '[\n {\n \"description\": \"Allow port 80\",\n \"direction\": \"in\",\n \"port\"\ : \"80\",\n \"protocol\": \"tcp\",\n \"source_ips\": [\n \"192.0.2.2/32\",\n \"192.0.2.0/24\",\n\ \ \"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128\"\n ]\n }\n]')" /firewalls/actions: get: operationId: list_firewalls_actions summary: List Actions description: 'Returns all [Actions](#tag/actions) for [Firewalls](#tag/firewalls). Use the provided URI parameters to modify the result. ' tags: - Firewall Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.Firewall.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.firewalls.actions.get_all()' /firewalls/actions/{id}: get: operationId: get_firewalls_action summary: Get an Action description: 'Returns the specific [Action](#tag/actions). ' tags: - Firewall Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.Firewall.Action.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) action = client.firewalls.actions.get_by_id(123)' /firewalls/{id}: get: operationId: get_firewall summary: Get a Firewall description: 'Returns a single [Firewall](#tag/firewalls). ' tags: - Firewalls parameters: - description: ID of the Firewall. name: id in: path required: true schema: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: FirewallResponse type: object properties: firewall: title: FirewallResponse type: object properties: id: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Firewall](#tag/firewalls). Limited to a maximum of 128 characters. Must be unique per Project. ' type: string example: new-name 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: '' 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' rules: type: array items: title: RuleResponse type: object properties: description: description: Description of the rule. type: string nullable: true maxLength: 255 direction: description: 'Traffic direction in which the rule should be applied to. Use `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs. ' type: string enum: - in - out example: in source_ips: description: 'List of permitted IPv4/IPv6 addresses for incoming traffic. The `direction` must be set to `in`. IPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 destination_ips: description: 'List of permitted IPv4/IPv6 addresses for outgoing traffic. The `direction` must be set to `out`. IPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: [] protocol: description: Network protocol to apply the rule for. type: string enum: - tcp - udp - icmp - esp - gre port: description: 'Port or port range to apply the rule for. Only applicable for protocols `tcp` and `udp`. A port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include all ports starting from 1024 up to port 5000. ' type: string example: '80' nullable: true required: - direction - protocol - destination_ips - source_ips - port applied_to: type: array items: type: object properties: type: description: The type of resource to apply. type: string enum: - server - label_selector example: server server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id label_selector: description: '[Label Selector](#description/label-selector) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `label_selector`, otherwise `null`. ' type: object properties: selector: description: The selector. type: string example: env=prod required: - selector applied_to_resources: description: 'Resources applied to via this [Label Selector](#description/label-selector). ' type: array items: type: object properties: type: description: Type of resource. type: string enum: - server example: server server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id required: - type required: - id - name - created - rules - applied_to required: - firewall 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\tfirewall, _, err := client.Firewall.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) firewall = client.firewalls.get_by_id(123)' - lang: Shell label: CLI source: hcloud firewall describe $FIREWALL put: operationId: update_firewall summary: Update a Firewall description: 'Update a [Firewall](#tag/firewalls). In case of a parallel running change on the [Firewall](#tag/firewalls) a `conflict` error will be returned. ' tags: - Firewalls parameters: - description: ID of the Firewall. name: id in: path required: true schema: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: UpdateFirewallRequest type: object properties: name: description: 'Name of the [Firewall](#tag/firewalls). Limited to a maximum of 128 characters. Must be unique per Project. ' type: string example: new-name 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: title: FirewallResponse type: object properties: firewall: title: FirewallResponse type: object properties: id: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Firewall](#tag/firewalls). Limited to a maximum of 128 characters. Must be unique per Project. ' type: string example: new-name 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: '' 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' rules: type: array items: title: RuleResponse type: object properties: description: description: Description of the rule. type: string nullable: true maxLength: 255 direction: description: 'Traffic direction in which the rule should be applied to. Use `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs. ' type: string enum: - in - out example: in source_ips: description: 'List of permitted IPv4/IPv6 addresses for incoming traffic. The `direction` must be set to `in`. IPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 destination_ips: description: 'List of permitted IPv4/IPv6 addresses for outgoing traffic. The `direction` must be set to `out`. IPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: [] protocol: description: Network protocol to apply the rule for. type: string enum: - tcp - udp - icmp - esp - gre port: description: 'Port or port range to apply the rule for. Only applicable for protocols `tcp` and `udp`. A port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include all ports starting from 1024 up to port 5000. ' type: string example: '80' nullable: true required: - direction - protocol - destination_ips - source_ips - port applied_to: type: array items: type: object properties: type: description: The type of resource to apply. type: string enum: - server - label_selector example: server server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id label_selector: description: '[Label Selector](#description/label-selector) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `label_selector`, otherwise `null`. ' type: object properties: selector: description: The selector. type: string example: env=prod required: - selector applied_to_resources: description: 'Resources applied to via this [Label Selector](#description/label-selector). ' type: array items: type: object properties: type: description: Type of resource. type: string enum: - server example: server server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id required: - type required: - id - name - created - rules - applied_to required: - firewall 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\tfirewall, _, err := client.Firewall.Update(ctx, &hcloud.Firewall{ID: 123}, hcloud.FirewallUpdateOpts{\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: \"new-name\",\n\t})\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\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nclient.firewalls.update(\n\ \ firewall=Firewall(id=123),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"\ label\",\n \"just-a-key\": \"\",\n },\n name=\"new-name\",\n)" - lang: Shell label: CLI source: "hcloud firewall update $FIREWALL --name \"new-name\"\nhcloud firewall add-label --overwrite $FIREWALL \\\n\ \ \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud firewall remove-label $FIREWALL \\\n\ \ \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_firewall summary: Delete a Firewall description: 'Deletes the [Firewall](#tag/firewalls). #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `resource_in_use` | [Firewall](#tag/firewalls) still applied to a resource | ' tags: - Firewalls parameters: - description: ID of the Firewall. name: id in: path required: true schema: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.Firewall.Delete(ctx, &hcloud.Firewall{ID: 123})\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.firewalls import Firewall token = environ["HCLOUD_TOKEN"] client = Client(token=token) client.firewalls.delete(firewall=Firewall(id=123))' - lang: Shell label: CLI source: hcloud firewall delete $FIREWALL /firewalls/{id}/actions: get: operationId: list_firewall_actions summary: List Actions for a Firewall description: 'Returns all [Actions](#tag/actions) for the [Firewall](#tag/firewalls). Use the provided URI parameters to modify the result. ' tags: - Firewall Actions parameters: - description: ID of the Firewall. name: id in: path required: true schema: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - meta examples: default: value: actions: - id: 13 command: set_firewall_rules status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 38 type: firewall error: code: action_failed message: Action failed meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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: [] /firewalls/{id}/actions/apply_to_resources: post: operationId: apply_firewall_to_resources summary: Apply to Resources description: 'Applies a [Firewall](#tag/firewalls) to multiple resources. Supported resources: - [Servers](#tag/servers) (with a public network interface) - [Label Selectors](#description/label-selector) A [Server](#tag/servers) can be applied to [a maximum of 5 Firewalls](https://docs.hetzner.com/cloud/firewalls/overview#limits). This limit applies to [Servers](#tag/servers) applied via a matching [Label Selector](#description/label-selector) as well. Updates to resources matching or no longer matching a [Label Selector](#description/label-selector) can take up to a few seconds to be processed. A [Firewall](#tag/firewalls) is applied to a resource once the related [Action](#tag/actions) with command `apply_firewall` successfully finished. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `404` | `firewall_resource_not_found` | The resource the [Firewall](#tag/firewalls) should be applied to was not found | | `422` | `firewall_already_applied` | [Firewall](#tag/firewalls) is already applied to resource | | `422` | `incompatible_network_type` | The network type of the resource is not supported by [Firewalls](#tag/firewalls) | | `422` | `private_net_only_server` | The [Server](#tag/servers) the [Firewall](#tag/firewalls) should be applied to has no public interface | ' tags: - Firewall Actions parameters: - description: ID of the Firewall. name: id in: path required: true schema: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: ApplyToResourcesRequest type: object properties: apply_to: description: 'Resources to apply the [Firewall](#tag/firewalls) to. Extends existing resources. ' type: array items: title: FirewallResource type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 required: - id label_selector: description: '[Label Selector](#description/label-selector) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `label_selector`, otherwise `null`. ' type: object properties: selector: description: The selector. type: string example: env=prod required: - selector required: - type required: - apply_to examples: default: value: apply_to: - type: server server: id: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: ActionListResponse type: object properties: 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 required: - actions examples: default: value: actions: - id: 14 command: apply_firewall status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server - id: 38 type: firewall error: code: action_failed message: Action failed 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\tactions, _, err := client.Firewall.ApplyResources(ctx, &hcloud.Firewall{ID: 123}, []hcloud.FirewallResource{\n\ \t\t{\n\t\t\tType: hcloud.FirewallResourceTypeServer,\n\t\t\tServer: &hcloud.FirewallResourceServer{\n\t\t\t\tID:\ \ 42,\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, actions...)\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, FirewallResource\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient\ \ = Client(token=token)\n\nactions = client.firewalls.apply_to_resources(\n firewall=Firewall(id=123),\n resources=[\n\ \ FirewallResource(\n type=\"server\",\n server=Server(id=42),\n )\n ],\n\ )\n\nfor action in actions:\n action.wait_until_finished()" - lang: Shell label: CLI source: "hcloud firewall apply-to-resource $FIREWALL \\\n --type server \\\n --server $SERVER" /firewalls/{id}/actions/remove_from_resources: post: operationId: remove_firewall_from_resources summary: Remove from Resources description: 'Removes a [Firewall](#tag/firewalls) from multiple resources. Supported resources: - [Servers](#tag/servers) (with a public network interface) A [Firewall](#tag/firewalls) is removed from a resource once the related [Action](#tag/actions) with command `remove_firewall` successfully finished. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `404` | `firewall_resource_not_found` | The resource the [Firewall](#tag/firewalls) should be removed from was not found | | `422` | `firewall_managed_by_label_selector` | [Firewall](#tag/firewall) is applied via a [Label Selector](#description/label-selector) and cannot be removed manually | ' tags: - Firewall Actions parameters: - description: ID of the Firewall. name: id in: path required: true schema: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: RemoveFromResourcesRequest type: object properties: remove_from: description: Resources to remove the [Firewall](#tag/firewalls) from. type: array items: title: FirewallResource type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector server: description: '[Server](#tag/servers) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `server`, otherwise `null`. ' type: object properties: id: description: ID of the [Server](#tag/servers). type: integer format: int64 required: - id label_selector: description: '[Label Selector](#description/label-selector) the [Firewall](#tag/firewalls) is applied to. Only set for `type` `label_selector`, otherwise `null`. ' type: object properties: selector: description: The selector. type: string example: env=prod required: - selector required: - type required: - remove_from examples: default: value: remove_from: - type: server server: id: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: ActionListResponse type: object properties: 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 required: - actions examples: default: value: actions: - id: 14 command: remove_firewall status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server - id: 38 type: firewall error: code: action_failed message: Action failed 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\tactions, _, err := client.Firewall.RemoveResources(ctx, &hcloud.Firewall{ID: 123},\ \ []hcloud.FirewallResource{\n\t\t{\n\t\t\tType: hcloud.FirewallResourceTypeServer,\n\t\t\tServer: &hcloud.FirewallResourceServer{\n\ \t\t\t\tID: 42,\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, actions...)\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, FirewallResource\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient\ \ = Client(token=token)\n\nactions = client.firewalls.remove_from_resources(\n firewall=Firewall(id=123),\n \ \ resources=[\n FirewallResource(\n type=\"server\",\n server=Server(id=42),\n \ \ )\n ],\n)\n\nfor action in actions:\n action.wait_until_finished()" - lang: Shell label: CLI source: "hcloud firewall remove-from-resource $FIREWALL \\\n --type server \\\n --server $SERVER" /firewalls/{id}/actions/set_rules: post: operationId: set_firewall_rules summary: Set Rules description: 'Set the rules of a [Firewall](#tag/firewalls). Overwrites the existing rules with the given ones. Pass an empty array to remove all rules. Rules are limited to 50 entries per [Firewall](#tag/firewalls) and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits). ' tags: - Firewall Actions parameters: - description: ID of the Firewall. name: id in: path required: true schema: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: SetRulesRequest type: object properties: rules: description: 'Array of rules. Rules are limited to 50 entries per [Firewall](#tag/firewalls) and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits). Existing rules will be replaced. ' type: array items: title: Rule type: object properties: description: description: Description of the rule. type: string nullable: true maxLength: 255 direction: description: 'Traffic direction in which the rule should be applied to. Use `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs. ' type: string enum: - in - out example: in source_ips: description: 'List of permitted IPv4/IPv6 addresses for incoming traffic. The `direction` must be set to `in`. IPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 destination_ips: description: 'List of permitted IPv4/IPv6 addresses for outgoing traffic. The `direction` must be set to `out`. IPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR blocks at most. The CIDR blocks may refer to networks (with empty host bits) or single hosts. For example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`, and a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`. Use `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses. IPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4). ' type: array items: type: string example: [] protocol: description: Network protocol to apply the rule for. type: string enum: - tcp - udp - icmp - esp - gre port: description: 'Port or port range to apply the rule for. Only applicable for protocols `tcp` and `udp`. A port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include all ports starting from 1024 up to port 5000. ' type: string example: '80' required: - direction - protocol maxItems: 50 required: - rules examples: default: value: rules: - description: Allow port 80 direction: in source_ips: - 192.0.2.2/32 - 192.0.2.0/24 - 2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128 protocol: tcp port: '80' responses: '201': description: Request succeeded. content: application/json: schema: title: ActionListResponse type: object properties: 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 required: - actions examples: default: value: actions: - id: 13 command: set_firewall_rules status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 38 type: firewall error: code: action_failed message: Action failed - id: 14 command: apply_firewall status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 38 type: firewall - id: 42 type: server error: code: action_failed message: Action failed 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\"net\"\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\tactions, _, err := client.Firewall.SetRules(ctx, &hcloud.Firewall{ID: 123}, hcloud.FirewallSetRulesOpts{\n\ \t\tRules: []hcloud.FirewallRule{\n\t\t\t{\n\t\t\t\tDescription: hcloud.Ptr(\"Allow port 80\"),\n\t\t\t\tDirection:\ \ hcloud.FirewallRuleDirectionIn,\n\t\t\t\tPort: hcloud.Ptr(\"80\"),\n\t\t\t\tProtocol: hcloud.FirewallRuleProtocolTCP,\n\ \t\t\t\tSourceIPs: []net.IPNet{\n\t\t\t\t\t{\n\t\t\t\t\t\tIP: net.ParseIP(\"192.0.2.2\"),\n\t\t\t\t\t\tMask: net.CIDRMask(32,\ \ 32),\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\tIP: net.ParseIP(\"192.0.2.0\"),\n\t\t\t\t\t\tMask: net.CIDRMask(24,\ \ 32),\n\t\t\t\t\t},\n\t\t\t\t\t{\n\t\t\t\t\t\tIP: net.ParseIP(\"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b\"),\n\t\ \t\t\t\t\tMask: net.CIDRMask(128, 128),\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ actions...)\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, FirewallRule\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions =\ \ client.firewalls.set_rules(\n firewall=Firewall(id=123),\n rules=[\n FirewallRule(\n description=\"\ Allow port 80\",\n direction=\"in\",\n port=\"80\",\n protocol=\"tcp\",\n \ \ source_ips=[\n \"192.0.2.2\",\n \"192.0.2.0/24\",\n \"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b\"\ ,\n ],\n )\n ],\n)\n\nfor action in actions:\n action.wait_until_finished()" - lang: Shell label: CLI source: "hcloud firewall replace-rules $FIREWALL --rules-file <(echo '[\n {\n \"description\": \"Allow port 80\"\ ,\n \"direction\": \"in\",\n \"port\": \"80\",\n \"protocol\": \"tcp\",\n \"source_ips\": [\n \"\ 192.0.2.2/32\",\n \"192.0.2.0/24\",\n \"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128\"\n ]\n }\n]')" /firewalls/{id}/actions/{action_id}: get: deprecated: true operationId: get_firewall_action summary: Get an Action for a Firewall description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific [Action](#tag/actions) for a [Firewall](#tag/firewalls). ' tags: - Firewall Actions parameters: - description: ID of the Firewall. name: id in: path required: true schema: description: ID of the [Firewall](#tag/firewalls). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 13 command: set_firewall_rules status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 38 type: firewall error: code: action_failed message: Action failed 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: [] /floating_ips: get: operationId: list_floating_ips summary: List Floating IPs description: 'List multiple [Floating IPs](#tag/floating-ips). Use the provided URI parameters to modify the result. ' tags: - Floating IPs 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 - created - created:asc - created:desc - 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. content: application/json: schema: type: object properties: floating_ips: type: array items: type: object properties: id: description: ID of the [Floating IP](#tag/floating-ips). 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 description: description: Description of the Resource. type: string nullable: true example: This describes my resource ip: description: IP address. type: string example: 2001:db8::/64 type: description: The Floating IP type. type: string enum: - ipv4 - ipv6 example: ipv6 server: description: '[Server](#tag/servers) the [Floating IP](#tag/floating-ips) is assigned to. `null` if not assigned. ' type: integer format: int64 nullable: true example: 42 dns_ptr: description: 'List of reverse DNS entries for the [Floating IP](#tag/floating-ips). ' type: array items: type: object properties: ip: description: 'Single IPv4 or IPv6 address of the record. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. ' type: string example: server.example.com required: - ip - dns_ptr home_location: 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 blocked: description: Indicates whether the [Floating IP](#tag/floating-ips) is blocked. 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 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: '' 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' required: - id - name - description - ip - type - server - dns_ptr - home_location - blocked - protection - labels - created 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: - floating_ips - 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\tfloatingIPs, err := client.FloatingIP.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) floating_ips = client.floating_ips.get_all()' - lang: Shell label: CLI source: hcloud floating-ip list post: operationId: create_floating_ip summary: Create a Floating IP description: 'Create a [Floating IP](#tag/floating-ips). Provide the `server` attribute to assign the [Floating IP](#tag/floating-ips) to that server or provide a `home_location` to locate the [Floating IP](#tag/floating-ips) at. Note that the [Floating IP](#tag/floating-ips) can be assigned to a [Server](#tag/servers) in any [Location](#tag/locations) later on. For optimal routing it is advised to use the [Floating IP](#tag/floating-ips) in the same [Location](#tag/locations) it was created in. ' tags: - Floating IPs requestBody: description: The `type` argument is required while `home_location` and `server` are mutually exclusive. required: true content: application/json: schema: title: FloatingIPCreateRequest type: object properties: type: description: The Floating IP type. type: string enum: - ipv4 - ipv6 example: ipv6 server: description: '[Server](#tag/servers) the [Floating IP](#tag/floating-ips) is assigned to. `null` if not assigned. ' type: integer format: int64 nullable: true example: 42 home_location: description: 'Home [Location](#tag/locations) for the [Floating IP](#tag/floating-ips). Either the ID or the name of the [Location](#tag/locations). Only optional if no [Server](#tag/servers) is provided. Routing is optimized for this [Locations](#tag/locations). ' oneOf: - description: 'Home [Location](#tag/locations) for the [Floating IP](#tag/floating-ips). Either the ID or the name of the [Location](#tag/locations). Only optional if no [Server](#tag/servers) is provided. Routing is optimized for this [Locations](#tag/locations). ' type: string example: fsn1 - description: 'Home [Location](#tag/locations) for the [Floating IP](#tag/floating-ips). Either the ID or the name of the [Location](#tag/locations). Only optional if no [Server](#tag/servers) is provided. Routing is optimized for this [Locations](#tag/locations). ' type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 description: description: Description of the Resource. type: string nullable: true example: This describes my resource 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: '' required: - type responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: floating_ip: type: object properties: id: description: ID of the [Floating IP](#tag/floating-ips). 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 description: description: Description of the Resource. type: string nullable: true example: This describes my resource ip: description: IP address. type: string example: 2001:db8::/64 type: description: The Floating IP type. type: string enum: - ipv4 - ipv6 example: ipv6 server: description: '[Server](#tag/servers) the [Floating IP](#tag/floating-ips) is assigned to. `null` if not assigned. ' type: integer format: int64 nullable: true example: 42 dns_ptr: description: 'List of reverse DNS entries for the [Floating IP](#tag/floating-ips). ' type: array items: type: object properties: ip: description: 'Single IPv4 or IPv6 address of the record. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. ' type: string example: server.example.com required: - ip - dns_ptr home_location: 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 blocked: description: Indicates whether the [Floating IP](#tag/floating-ips) is blocked. 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 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: '' 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' required: - id - name - description - ip - type - server - dns_ptr - home_location - blocked - protection - labels - created 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 required: - floating_ip examples: default: value: floating_ip: id: 4711 name: Web Frontend description: Web Frontend ip: 2001:db8::/64 type: ipv6 server: 42 dns_ptr: - ip: 2001:db8::1 dns_ptr: server.example.com home_location: id: 1 name: fsn1 description: Falkenstein DC Park 1 country: DE city: Falkenstein latitude: 50.47612 longitude: 12.370071 network_zone: eu-central blocked: false protection: delete: false labels: key: value created: '2016-01-30T23:50:00Z' action: id: 13 command: assign_floating_ip status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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.FloatingIP.Create(ctx, hcloud.FloatingIPCreateOpts{\n\t\t\ Description: hcloud.Ptr(\"This describes my resource\"),\n\t\tHomeLocation: &hcloud.Location{Name: \"fsn1\"},\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: hcloud.Ptr(\"my-resource\"),\n\t\tServer: &hcloud.Server{ID: 42},\n\ \t\tType: hcloud.FloatingIPTypeIPv4,\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tfloatingIP\ \ := result.FloatingIP\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.locations\ \ import Location\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \nresponse = client.floating_ips.create(\n description=\"This describes my resource\",\n home_location=Location(name=\"\ fsn1\"),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\"\ : \"\",\n },\n name=\"my-resource\",\n server=Server(id=42),\n type=\"ipv4\",\n)\n\nresponse.action.wait_until_finished()\n\ \nfloating_ip = response.floating_ip" - lang: Shell label: CLI source: "hcloud floating-ip create \\\n --description \"This describes my resource\" \\\n --home-location fsn1\ \ \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\"\ \ \\\n --name my-resource \\\n --server 42 \\\n --type ipv4" /floating_ips/actions: get: operationId: list_floating_ips_actions summary: List Actions description: 'Lists multiple [Actions](#tag/actions). Use the provided URI parameters to modify the result. ' tags: - Floating IP Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.FloatingIP.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.floating_ips.actions.get_all()' /floating_ips/actions/{id}: get: operationId: get_floating_ips_action summary: Get an Action description: 'Returns a single [Action](#tag/actions). ' tags: - Floating IP Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.FloatingIP.Action.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) action = client.floating_ips.actions.get_by_id(123)' /floating_ips/{id}: get: operationId: get_floating_ip summary: Get a Floating IP description: 'Returns a single [Floating IP](#tag/floating-ips). ' tags: - Floating IPs parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: floating_ip: type: object properties: id: description: ID of the [Floating IP](#tag/floating-ips). 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 description: description: Description of the Resource. type: string nullable: true example: This describes my resource ip: description: IP address. type: string example: 2001:db8::/64 type: description: The Floating IP type. type: string enum: - ipv4 - ipv6 example: ipv6 server: description: '[Server](#tag/servers) the [Floating IP](#tag/floating-ips) is assigned to. `null` if not assigned. ' type: integer format: int64 nullable: true example: 42 dns_ptr: description: 'List of reverse DNS entries for the [Floating IP](#tag/floating-ips). ' type: array items: type: object properties: ip: description: 'Single IPv4 or IPv6 address of the record. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. ' type: string example: server.example.com required: - ip - dns_ptr home_location: 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 blocked: description: Indicates whether the [Floating IP](#tag/floating-ips) is blocked. 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 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: '' 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' required: - id - name - description - ip - type - server - dns_ptr - home_location - blocked - protection - labels - created required: - floating_ip 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\tfloatingIP, _, err := client.FloatingIP.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) floating_ip = client.floating_ips.get_by_id(123)' - lang: Shell label: CLI source: hcloud floating-ip describe $FLOATINGIP put: operationId: update_floating_ip summary: Update a Floating IP description: 'Update a [Floating IP](#tag/floating-ips). ' tags: - Floating IPs parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: FloatingIPUpdateRequest type: object properties: description: description: Description of the Resource. type: string nullable: true example: This describes my resource 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. 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: floating_ip: type: object properties: id: description: ID of the [Floating IP](#tag/floating-ips). 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 description: description: Description of the Resource. type: string nullable: true example: This describes my resource ip: description: IP address. type: string example: 2001:db8::/64 type: description: The Floating IP type. type: string enum: - ipv4 - ipv6 example: ipv6 server: description: '[Server](#tag/servers) the [Floating IP](#tag/floating-ips) is assigned to. `null` if not assigned. ' type: integer format: int64 nullable: true example: 42 dns_ptr: description: 'List of reverse DNS entries for the [Floating IP](#tag/floating-ips). ' type: array items: type: object properties: ip: description: 'Single IPv4 or IPv6 address of the record. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. ' type: string example: server.example.com required: - ip - dns_ptr home_location: 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 blocked: description: Indicates whether the [Floating IP](#tag/floating-ips) is blocked. 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 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: '' 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' required: - id - name - description - ip - type - server - dns_ptr - home_location - blocked - protection - labels - created required: - floating_ip examples: default: value: floating_ip: id: 4711 name: Web Frontend description: Web Frontend ip: 2001:db8::/64 type: ipv6 server: 42 dns_ptr: - ip: 2001:db8::1 dns_ptr: server.example.com home_location: id: 1 name: fsn1 description: Falkenstein DC Park 1 country: DE city: Falkenstein latitude: 50.47612 longitude: 12.370071 network_zone: eu-central blocked: false protection: delete: false labels: key: value created: '2016-01-30T23:50:00Z' 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\tfloatingIP, _, err := client.FloatingIP.Update(ctx, &hcloud.FloatingIP{ID: 123}, hcloud.FloatingIPUpdateOpts{\n\ \t\tDescription: \"This describes my resource\",\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-resource\",\n\t\ })\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.floating_ips\ \ import FloatingIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nclient.floating_ips.update(\n\ \ floating_ip=FloatingIP(id=123),\n description=\"This describes my resource\",\n labels={\n \"\ environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"\ my-resource\",\n)" - lang: Shell label: CLI source: "hcloud floating-ip update $FLOATINGIP \\\n --description \"This describes my resource\" \\\n --name\ \ my-resource\nhcloud floating-ip add-label --overwrite $FLOATINGIP \\\n \"environment=prod\" \"example.com/my=label\"\ \ \"just-a-key=\"\nhcloud floating-ip remove-label $FLOATINGIP \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_floating_ip summary: Delete a Floating IP description: 'Deletes a [Floating IP](#tag/floating-ips). If assigned to a [Server](#tag/servers) the [Floating IP](#tag/floating-ips) will be unassigned automatically until 1 May 2026. After this date, the [Floating IP](#tag/floating-ips) needs to be unassigned before it can be deleted. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `must_be_unassigned` | Error when IP is still assigned to a Resource. This error will appear as of 1 May 2026. | ' tags: - Floating IPs parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.FloatingIP.Delete(ctx, &hcloud.FloatingIP{ID: 123})\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.floating_ips import FloatingIP token = environ["HCLOUD_TOKEN"] client = Client(token=token) client.floating_ips.delete(floating_ip=FloatingIP(id=123))' - lang: Shell label: CLI source: hcloud floating-ip delete $FLOATINGIP /floating_ips/{id}/actions: get: operationId: list_floating_ip_actions summary: List Actions for a Floating IP description: 'Lists [Actions](#tag/actions) for a [Floating IP](#tag/floating-ips). Use the provided URI parameters to modify the result. ' tags: - Floating IP Actions parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: type: object properties: 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 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: - actions - meta examples: default: value: actions: - id: 13 command: assign_floating_ip status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: server - id: 4712 type: floating_ip error: code: action_failed message: Action failed meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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: [] /floating_ips/{id}/actions/assign: post: operationId: assign_floating_ip summary: Assign a Floating IP to a Server description: 'Assigns a [Floating IP](#tag/floating-ips) to a [Server](#tag/servers). #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `floating_ip_assigned` | The [Floating IP](#tag/floating-ips) is already assigned | ' tags: - Floating IP Actions parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: FloatingIPActionsAssignRequest type: object properties: server: description: '[Server](#tag/servers) the [Floating IP](#tag/floating-ips) is assigned to. `null` if not assigned. ' type: integer format: int64 nullable: true example: 42 required: - server responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: assign_floating_ip status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server - id: 4711 type: floating_ip error: code: action_failed message: Action failed 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\taction, _, err := client.FloatingIP.Assign(ctx, &hcloud.FloatingIP{ID: 123}, &hcloud.Server{ID:\ \ 456})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.floating_ips\ \ import FloatingIP\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.floating_ips.assign(\n floating_ip=FloatingIP(id=123),\n server=Server(id=42),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud floating-ip assign $FLOATINGIP $SERVER /floating_ips/{id}/actions/change_dns_ptr: post: operationId: change_floating_ip_dns_ptr summary: Change reverse DNS records for a Floating IP description: 'Change the reverse DNS records for this [Floating IP](#tag/floating-ips). Allows to modify the PTR records set for the IP address. ' tags: - Floating IP Actions parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: description: 'The `ip` attributes specifies for which IP address the record is set. For IPv4 addresses this must be the exact address of the [Floating IP](#tag/floating-ips). For IPv6 addresses this must be a single address within the `/64` subnet of the [Floating IP](#tag/floating-ips). The `dns_ptr` attribute specifies the hostname used for the IP address. Must be a fully qualified domain name (FQDN) without trailing dot. For IPv6 [Floating IPs](#tag/floating-ips) up to 100 entries can be created. ' required: true content: application/json: schema: type: object properties: ip: description: 'Single IPv4 or IPv6 address to create pointer for. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. Set to null to reset (IPv4) to the default value or remove (IPv6) the record. ' type: string nullable: true example: server.example.com required: - ip responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_dns_ptr status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: floating_ip error: code: action_failed message: Action failed 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\taction, _, err := client.FloatingIP.ChangeDNSPtr(ctx, &hcloud.FloatingIP{ID: 123},\ \ \"2001:db8::1\", hcloud.Ptr(\"server.example.com\"))\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.floating_ips\ \ import FloatingIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.floating_ips.change_dns_ptr(\n\ \ floating_ip=FloatingIP(id=123),\n dns_ptr=\"server.example.com\",\n ip=\"2001:db8::1\",\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud floating-ip set-rdns $FLOATINGIP \\\n --ip 2001:db8::1 \\\n --hostname server.example.com" /floating_ips/{id}/actions/change_protection: post: operationId: change_floating_ip_protection summary: Change Floating IP Protection description: 'Changes the protection settings configured for the [Floating IP](#tag/floating-ips). ' tags: - Floating IP Actions parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: floating_ip error: code: action_failed message: Action failed 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\taction, _, err := client.FloatingIP.ChangeProtection(ctx, &hcloud.FloatingIP{ID: 123},\n\ \t\thcloud.FloatingIPChangeProtectionOpts{Delete: hcloud.Ptr(false)})\n\n\terr = client.Action.WaitFor(ctx, action)\n\ }" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.floating_ips\ \ import FloatingIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.floating_ips.change_protection(\n\ \ floating_ip=FloatingIP(id=123), delete=False\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud floating-ip enable-protection $FLOATINGIP delete hcloud floating-ip disable-protection $FLOATINGIP delete' /floating_ips/{id}/actions/unassign: post: operationId: unassign_floating_ip summary: Unassign a Floating IP description: 'Unassigns a [Floating IP](#tag/floating-ips). Results in the IP being unreachable. Can be assigned to another resource again. ' tags: - Floating IP Actions parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: unassign_floating_ip status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server - id: 4711 type: floating_ip error: code: action_failed message: Action failed 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\taction, _, err := client.FloatingIP.Unassign(ctx, &hcloud.FloatingIP{ID: 123})\n\n\t\ err = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.floating_ips\ \ import FloatingIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.floating_ips.unassign(\n\ \ floating_ip=FloatingIP(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud floating-ip unassign $FLOATINGIP /floating_ips/{id}/actions/{action_id}: get: deprecated: true operationId: get_floating_ip_action summary: Get an Action for a Floating IP description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific [Action](#tag/actions) for a [Floating IP](#tag/floating-ips). ' tags: - Floating IP Actions parameters: - description: ID of the Floating IP. name: id in: path required: true schema: description: ID of the [Floating IP](#tag/floating-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 13 command: assign_floating_ip status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server - id: 4711 type: floating_ip error: code: action_failed message: Action failed 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: [] /images: get: operationId: list_images summary: List Images description: 'Returns all Image objects. You can select specific Image types only and sort the results by using URI parameters. ' tags: - Images parameters: - 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 type. May be used multiple times. The response will only contain the resources with the specified type. ' name: type in: query required: false schema: type: array items: description: Type of the Image. type: string enum: - system - app - snapshot - backup example: snapshot - 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 Image. type: string enum: - available - creating - unavailable example: available - description: 'Filter Images by their linked Server ID. May be used multiple times. Only available for Images of type `backup`. ' name: bound_to in: query required: false schema: type: array items: type: string - description: Include deprecated Images. name: include_deprecated in: query required: false schema: type: boolean - 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: 'Filter resources by cpu architecture. The response will only contain the resources with the specified cpu architecture. ' name: architecture in: query required: false schema: description: CPU architecture of the Resource. type: string enum: - x86 - arm example: x86 - 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. content: application/json: schema: type: object properties: images: type: array items: 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 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: - images - 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\timages, err := client.Image.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) images = client.images.get_all()' - lang: Shell label: CLI source: hcloud image list /images/actions: get: operationId: list_images_actions summary: List Actions description: 'Returns all Action objects. You can `sort` the results by using the sort URI parameter, and filter them with the `status` and `id` parameter. ' tags: - Image Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.Image.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.images.actions.get_all()' /images/actions/{id}: get: operationId: get_images_action summary: Get an Action description: 'Returns a specific Action object. ' tags: - Image Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.Image.Action.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) action = client.images.actions.get_by_id(123)' /images/{id}: get: operationId: get_image summary: Get an Image description: 'Returns a specific Image object. ' tags: - Images parameters: - description: ID of the Image. name: id in: path required: true schema: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: image: 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 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\timage, _, err := client.Image.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) image = client.images.get_by_id(123)' - lang: Shell label: CLI source: hcloud image describe $IMAGE put: operationId: update_image summary: Update an Image description: 'Updates the Image. You may change the description, convert a Backup Image to a Snapshot Image or change the Image labels. Only Images of type `snapshot` and `backup` can be updated. ' tags: - Images parameters: - description: ID of the Image. name: id in: path required: true schema: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: UpdateImageRequest type: object properties: description: description: New description of Image. type: string example: My new Image description type: description: Destination Image type to convert to. type: string enum: - snapshot 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: image: 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 examples: default: value: image: id: 4711 type: snapshot status: available name: null description: My new Image description 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: '20.04' rapid_deploy: false protection: delete: false deprecated: '2018-02-28T00:00:00Z' deleted: null labels: key: value architecture: x86 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\timage, _, err := client.Image.Update(ctx, &hcloud.Image{ID: 123}, hcloud.ImageUpdateOpts{\n\ \t\tDescription: hcloud.Ptr(\"My new Image description\"),\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\tType: hcloud.ImageTypeSnapshot,\n\ \t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.images\ \ import Image\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nimage = client.images.update(\n\ \ image=Image(id=123),\n description=\"My new Image description\",\n labels={\n \"environment\"\ : \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n type=\"snapshot\"\ ,\n)" - lang: Shell label: CLI source: "hcloud image update $IMAGE --description \"My new Image description\"\nhcloud image add-label --overwrite\ \ $IMAGE \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud image remove-label $IMAGE\ \ \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_image summary: Delete an Image description: 'Deletes an Image. Only Images of type `snapshot` and `backup` can be deleted. ' tags: - Images parameters: - description: ID of the Image. name: id in: path required: true schema: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.Image.Delete(ctx, &hcloud.Image{ID: 123})\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.images import Image token = environ["HCLOUD_TOKEN"] client = Client(token=token) image = client.images.delete(Image(id=123))' - lang: Shell label: CLI source: hcloud image delete $IMAGE /images/{id}/actions: get: operationId: list_image_actions summary: List Actions for an Image description: 'Returns all Action objects for an Image. You can sort the results by using the `sort` URI parameter, and filter them with the `status` parameter. ' tags: - Image Actions parameters: - description: ID of the Image. name: id in: path required: true schema: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - meta examples: default: value: actions: - id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: image error: code: action_failed message: Action failed meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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: [] /images/{id}/actions/change_protection: post: operationId: change_image_protection summary: Change Image Protection description: 'Changes the protection configuration of the Image. Can only be used on snapshots. ' tags: - Image Actions parameters: - description: ID of the Image. name: id in: path required: true schema: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: delete: description: If true, prevents the snapshot from being deleted. type: boolean example: true responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: image error: code: action_failed message: Action failed 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\taction, _, err := client.Image.ChangeProtection(ctx, &hcloud.Image{ID: 123},\n\t\t\ hcloud.ImageChangeProtectionOpts{Delete: hcloud.Ptr(true)})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.images import Image token = environ["HCLOUD_TOKEN"] client = Client(token=token) action = client.images.change_protection(image=Image(id=123), delete=True) action.wait_until_finished()' - lang: Shell label: CLI source: 'hcloud image enable-protection $IMAGE delete hcloud image disable-protection $IMAGE delete' /images/{id}/actions/{action_id}: get: deprecated: true operationId: get_image_action summary: Get an Action for an Image description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific Action for an Image. ' tags: - Image Actions parameters: - description: ID of the Image. name: id in: path required: true schema: description: ID of the [Image](#tag/images). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: image error: code: action_failed message: Action failed 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: [] /isos: get: operationId: list_isos summary: List ISOs description: 'Returns all available ISO objects. ' tags: - ISOs 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 cpu architecture. The response will only contain the resources with the specified cpu architecture. ' name: architecture in: query required: false schema: description: CPU architecture of the Resource. type: string enum: - x86 - arm example: x86 - description: Include Images with wildcard architecture (architecture is null). Architecture filter must be specified. name: include_architecture_wildcard in: query required: false schema: type: boolean - 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. content: application/json: schema: type: object properties: isos: type: array items: 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 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: - isos - 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\tisos, err := client.ISO.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) isos = client.isos.get_all()' - lang: Shell label: CLI source: hcloud iso list /isos/{id}: get: operationId: get_iso summary: Get an ISO description: 'Returns a specific ISO object. ' tags: - ISOs parameters: - description: ID of the ISO. name: id in: path required: true schema: description: ID of the [ISO](#tag/isos). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: iso: 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 required: - iso 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\tiso, _, err := client.ISO.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) iso = client.isos.get_by_id(123)' - lang: Shell label: CLI source: hcloud iso describe $ISO /load_balancer_types: get: operationId: list_load_balancer_types summary: List Load Balancer Types description: 'Gets all Load Balancer type objects. ' tags: - Load Balancer Types 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: 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. content: application/json: schema: type: object properties: load_balancer_types: type: array items: type: object properties: id: description: ID of the Load Balancer type. type: integer format: int64 example: 1 name: description: Unique identifier of the Load Balancer type. type: string example: lb11 description: description: Description of the Load Balancer type. type: string example: LB11 max_connections: description: Number of maximum simultaneous open connections. type: integer format: int64 example: 20000 max_services: description: Number of services a Load Balancer of this type can have. type: integer format: int64 example: 5 max_targets: description: Number of targets a single Load Balancer can have. type: integer format: int64 example: 25 max_assigned_certificates: description: Number of SSL Certificates that can be assigned to a single Load Balancer. type: integer format: int64 example: 10 deprecated: description: Point in time when the Load Balancer type is deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2016-01-30T23:50:00Z' 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 required: - id - name - description - max_connections - max_services - max_targets - max_assigned_certificates - deprecated - prices 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: - load_balancer_types - 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\tloadBalancerTypes, err := client.LoadBalancerType.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) load_balancer_types = client.load_balancer_types.get_all()' - lang: Shell label: CLI source: hcloud load-balancer-type list /load_balancer_types/{id}: get: operationId: get_load_balancer_type summary: Get a Load Balancer Type description: 'Gets a specific Load Balancer type object. ' tags: - Load Balancer Types parameters: - description: ID of the Load Balancer Type. name: id in: path required: true schema: description: ID of the [Load Balancer Type](#tag/load-balancer-types). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: load_balancer_type: type: object properties: id: description: ID of the Load Balancer type. type: integer format: int64 example: 1 name: description: Unique identifier of the Load Balancer type. type: string example: lb11 description: description: Description of the Load Balancer type. type: string example: LB11 max_connections: description: Number of maximum simultaneous open connections. type: integer format: int64 example: 20000 max_services: description: Number of services a Load Balancer of this type can have. type: integer format: int64 example: 5 max_targets: description: Number of targets a single Load Balancer can have. type: integer format: int64 example: 25 max_assigned_certificates: description: Number of SSL Certificates that can be assigned to a single Load Balancer. type: integer format: int64 example: 10 deprecated: description: Point in time when the Load Balancer type is deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2016-01-30T23:50:00Z' 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 required: - id - name - description - max_connections - max_services - max_targets - max_assigned_certificates - deprecated - prices required: - load_balancer_type 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\tloadBalancerType, _, err := client.LoadBalancerType.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) load_balancer_type = client.load_balancer_types.get_by_id(123)' - lang: Shell label: CLI source: hcloud load-balancer-type describe $LOADBALANCERTYPE /load_balancers: get: operationId: list_load_balancers summary: List Load Balancers description: 'Gets all existing Load Balancers that you have available. ' tags: - Load Balancers parameters: - 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 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: 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. content: application/json: schema: type: object properties: load_balancers: type: array items: type: object properties: id: description: ID of the [Load Balancer](#tag/load-balancers). 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 public_net: description: Public network information. type: object properties: enabled: description: Public Interface enabled or not. type: boolean ipv4: description: IP address (v4). type: object properties: ip: description: IP address (v4) of this Load Balancer. type: string nullable: true example: 1.2.3.4 dns_ptr: description: Reverse DNS PTR entry for the IPv4 address of this Load Balancer. type: string nullable: true example: lb1.example.com required: - ip - dns_ptr ipv6: description: IP address (v6). type: object properties: ip: description: IP address (v6) of this Load Balancer. type: string nullable: true example: 2001:db8::1 dns_ptr: description: Reverse DNS PTR entry for the IPv6 address of this Load Balancer. type: string nullable: true example: lb1.example.com required: - ip - dns_ptr required: - enabled - ipv4 - ipv6 private_net: description: Private networks information. type: array items: type: object properties: network: description: ID of the Network. type: integer format: int64 example: 4711 ip: description: IP address (v4) of this Load Balancer in this Network. type: string example: 10.0.0.2 required: - network - ip location: 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 load_balancer_type: type: object properties: id: description: ID of the Load Balancer type. type: integer format: int64 example: 1 name: description: Unique identifier of the Load Balancer type. type: string example: lb11 description: description: Description of the Load Balancer type. type: string example: LB11 max_connections: description: Number of maximum simultaneous open connections. type: integer format: int64 example: 20000 max_services: description: Number of services a Load Balancer of this type can have. type: integer format: int64 example: 5 max_targets: description: Number of targets a single Load Balancer can have. type: integer format: int64 example: 25 max_assigned_certificates: description: Number of SSL Certificates that can be assigned to a single Load Balancer. type: integer format: int64 example: 10 deprecated: description: Point in time when the Load Balancer type is deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2016-01-30T23:50:00Z' 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 required: - id - name - description - max_connections - max_services - max_targets - max_assigned_certificates - deprecated - prices protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' 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' services: description: List of services that belong to this Load Balancer. type: array items: title: LoadBalancerService oneOf: - title: LoadBalancerServiceTCP allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - tcp example: tcp - title: LoadBalancerServiceHTTPProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - http example: http http: title: LoadBalancerServiceHTTPConfig description: Configuration option for protocol http. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - sticky_sessions required: - http - title: LoadBalancerServiceHTTPSProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - https example: https http: title: LoadBalancerServiceHTTPSConfig description: Configuration option for protocol https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - certificates - redirect_http - sticky_sessions required: - http discriminator: propertyName: protocol mapping: tcp: '#/components/schemas/ServiceTCP' http: '#/components/schemas/ServiceHTTPProtocol' https: '#/components/schemas/ServiceHTTPSProtocol' targets: description: List of targets that belong to this Load Balancer. type: array items: title: LoadBalancerTarget oneOf: - title: LoadBalancerTargetTypeServer allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - server example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - server - health_status - use_private_ip - title: LoadBalancerTargetTypeLabelSelector allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - label_selector example: label_selector label_selector: title: LoadBalancerTargetLabelSelector description: Label selector used to determine targets. Only present for target type "label_selector". type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector targets: description: List of resolved label selector target Servers. type: array items: title: LoadBalancerTargetTarget type: object properties: type: description: Type of the resource. Here always "server". type: string example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - type - server - health_status - use_private_ip use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - label_selector - targets - use_private_ip - title: LoadBalancerTargetTypeIP allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - ip example: ip ip: title: LoadBalancerTargetIP description: IP target where the traffic should be routed to. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only present for target type `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status required: - ip - health_status discriminator: propertyName: type mapping: server: '#/components/schemas/TargetTypeServer' label_selector: '#/components/schemas/TargetTypeLabelSelector' ip: '#/components/schemas/TargetTypeIP' algorithm: description: Algorithm of the Load Balancer. type: object properties: type: description: Type of the algorithm. type: string enum: - round_robin - least_connections required: - type outgoing_traffic: description: Outbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true ingoing_traffic: description: Inbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true included_traffic: description: Free Traffic for the current billing period in bytes. type: integer format: int64 example: 10000 required: - id - name - public_net - private_net - location - load_balancer_type - protection - labels - created - services - targets - algorithm - outgoing_traffic - ingoing_traffic - included_traffic 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: - load_balancers - 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\tloadBalancers, err := client.LoadBalancer.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) load_balancers = client.load_balancers.get_all()' - lang: Shell label: CLI source: hcloud load-balancer list post: operationId: create_load_balancer summary: Create a Load Balancer description: 'Creates a Load Balancer. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `412` | `source_port_already_used` | The source port you are trying to add is already in use | | `422` | `ip_not_owned` | The IP is not owned by the owner of the project of the Load Balancer | | `422` | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network | | `422` | `resolve_cloud_private_targets_error` | The server you are trying to add as a target is not attached to the same network as the Load Balancer | | `422` | `resolve_cloud_public_targets_error` | The server that you are trying to add as a public target does not have a public IPv4 address | | `422` | `target_already_defined` | The Load Balancer target you are trying to define is already defined | ' tags: - Load Balancers requestBody: required: true content: application/json: schema: title: CreateLoadBalancerRequest type: object properties: name: description: Name of the Load Balancer. type: string minLength: 1 maxLength: 128 pattern: ^\S(.*\S)?$ example: Web Frontend load_balancer_type: description: ID or name of the Load Balancer type this Load Balancer should be created with. type: string example: lb11 algorithm: title: LoadBalancerAlgorithm description: Algorithm of the Load Balancer. type: object properties: type: description: Type of the algorithm. type: string enum: - round_robin - least_connections required: - type default: type: round_robin services: description: Array of services. type: array items: title: LoadBalancerService oneOf: - title: LoadBalancerServiceTCP allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - tcp example: tcp - title: LoadBalancerServiceHTTPProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - http example: http http: title: LoadBalancerServiceHTTPConfig description: Configuration option for protocol http. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - sticky_sessions required: - http - title: LoadBalancerServiceHTTPSProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - https example: https http: title: LoadBalancerServiceHTTPSConfig description: Configuration option for protocol https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - certificates - redirect_http - sticky_sessions required: - http discriminator: propertyName: protocol mapping: tcp: '#/components/schemas/ServiceTCP' http: '#/components/schemas/ServiceHTTPProtocol' https: '#/components/schemas/ServiceHTTPSProtocol' targets: description: Array of targets. type: array items: allOf: - title: LoadBalancerTarget description: Configuration of a Load Balancer target. type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip server: title: LoadBalancerTargetServer description: Configuration for type Server, only valid and required if type is `server`. type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 additionalProperties: false required: - id label_selector: title: LoadBalancerTargetLabelSelector description: Configuration for label selector targets, only valid and required if type is `label_selector`. type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector ip: title: LoadBalancerTargetIP description: Configuration for an IP target. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only valid and required if type is `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip required: - type - type: object properties: use_private_ip: description: Use the private network IP instead of the public IP of the Server, requires the Server and Load Balancer to be in the same network. Only valid for target types `server` and `label_selector`. type: boolean default: false example: true 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: '' public_interface: description: Enable or disable the public interface of the Load Balancer. type: boolean example: true network: description: ID of the network the Load Balancer should be attached to on creation. type: integer format: int64 example: 123 network_zone: description: Name of network zone. type: string example: eu-central location: description: ID or name of Location to create Load Balancer in. type: string example: fsn1 required: - name - load_balancer_type responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: load_balancer: type: object properties: id: description: ID of the [Load Balancer](#tag/load-balancers). 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 public_net: description: Public network information. type: object properties: enabled: description: Public Interface enabled or not. type: boolean ipv4: description: IP address (v4). type: object properties: ip: description: IP address (v4) of this Load Balancer. type: string nullable: true example: 1.2.3.4 dns_ptr: description: Reverse DNS PTR entry for the IPv4 address of this Load Balancer. type: string nullable: true example: lb1.example.com required: - ip - dns_ptr ipv6: description: IP address (v6). type: object properties: ip: description: IP address (v6) of this Load Balancer. type: string nullable: true example: 2001:db8::1 dns_ptr: description: Reverse DNS PTR entry for the IPv6 address of this Load Balancer. type: string nullable: true example: lb1.example.com required: - ip - dns_ptr required: - enabled - ipv4 - ipv6 private_net: description: Private networks information. type: array items: type: object properties: network: description: ID of the Network. type: integer format: int64 example: 4711 ip: description: IP address (v4) of this Load Balancer in this Network. type: string example: 10.0.0.2 required: - network - ip location: 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 load_balancer_type: type: object properties: id: description: ID of the Load Balancer type. type: integer format: int64 example: 1 name: description: Unique identifier of the Load Balancer type. type: string example: lb11 description: description: Description of the Load Balancer type. type: string example: LB11 max_connections: description: Number of maximum simultaneous open connections. type: integer format: int64 example: 20000 max_services: description: Number of services a Load Balancer of this type can have. type: integer format: int64 example: 5 max_targets: description: Number of targets a single Load Balancer can have. type: integer format: int64 example: 25 max_assigned_certificates: description: Number of SSL Certificates that can be assigned to a single Load Balancer. type: integer format: int64 example: 10 deprecated: description: Point in time when the Load Balancer type is deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2016-01-30T23:50:00Z' 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 required: - id - name - description - max_connections - max_services - max_targets - max_assigned_certificates - deprecated - prices protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' 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' services: description: List of services that belong to this Load Balancer. type: array items: title: LoadBalancerService oneOf: - title: LoadBalancerServiceTCP allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - tcp example: tcp - title: LoadBalancerServiceHTTPProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - http example: http http: title: LoadBalancerServiceHTTPConfig description: Configuration option for protocol http. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - sticky_sessions required: - http - title: LoadBalancerServiceHTTPSProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - https example: https http: title: LoadBalancerServiceHTTPSConfig description: Configuration option for protocol https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - certificates - redirect_http - sticky_sessions required: - http discriminator: propertyName: protocol mapping: tcp: '#/components/schemas/ServiceTCP' http: '#/components/schemas/ServiceHTTPProtocol' https: '#/components/schemas/ServiceHTTPSProtocol' targets: description: List of targets that belong to this Load Balancer. type: array items: title: LoadBalancerTarget oneOf: - title: LoadBalancerTargetTypeServer allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - server example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - server - health_status - use_private_ip - title: LoadBalancerTargetTypeLabelSelector allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - label_selector example: label_selector label_selector: title: LoadBalancerTargetLabelSelector description: Label selector used to determine targets. Only present for target type "label_selector". type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector targets: description: List of resolved label selector target Servers. type: array items: title: LoadBalancerTargetTarget type: object properties: type: description: Type of the resource. Here always "server". type: string example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - type - server - health_status - use_private_ip use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - label_selector - targets - use_private_ip - title: LoadBalancerTargetTypeIP allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - ip example: ip ip: title: LoadBalancerTargetIP description: IP target where the traffic should be routed to. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only present for target type `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status required: - ip - health_status discriminator: propertyName: type mapping: server: '#/components/schemas/TargetTypeServer' label_selector: '#/components/schemas/TargetTypeLabelSelector' ip: '#/components/schemas/TargetTypeIP' algorithm: description: Algorithm of the Load Balancer. type: object properties: type: description: Type of the algorithm. type: string enum: - round_robin - least_connections required: - type outgoing_traffic: description: Outbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true ingoing_traffic: description: Inbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true included_traffic: description: Free Traffic for the current billing period in bytes. type: integer format: int64 example: 10000 required: - id - name - public_net - private_net - location - load_balancer_type - protection - labels - created - services - targets - algorithm - outgoing_traffic - ingoing_traffic - included_traffic 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 required: - load_balancer - action examples: default: value: load_balancer: id: 4711 name: Web Frontend public_net: enabled: false ipv4: ip: 1.2.3.4 dns_ptr: lb1.example.com ipv6: ip: 2001:db8::1 dns_ptr: lb1.example.com private_net: - network: 4711 ip: 10.0.0.2 location: id: 1 name: fsn1 description: Falkenstein DC Park 1 country: DE city: Falkenstein latitude: 50.47612 longitude: 12.370071 network_zone: eu-central load_balancer_type: id: 1 name: lb11 description: LB11 max_connections: 20000 max_services: 5 max_targets: 25 max_assigned_certificates: 10 deprecated: '2016-01-30T23:50:00Z' prices: - location: fsn1 price_hourly: net: '1.0000000000' gross: '1.1900000000000000' price_monthly: net: '1.0000000000' gross: '1.1900000000000000' included_traffic: 654321 price_per_tb_traffic: net: '1.0000000000' gross: '1.1900000000000000' protection: delete: false labels: key: value created: '2016-01-30T23:50:00Z' services: - protocol: https listen_port: 443 destination_port: 80 proxyprotocol: false health_check: protocol: http port: 4711 interval: 15 timeout: 10 retries: 3 http: domain: example.com path: / response: '{"status": "ok"}' status_codes: - 2??,3?? tls: false http: cookie_name: HCLBSTICKY cookie_lifetime: 300 certificates: - 897 redirect_http: true sticky_sessions: true timeout_idle: 50 targets: - type: server server: id: 80 health_status: - listen_port: 443 status: healthy use_private_ip: true targets: - type: server server: id: 80 health_status: - listen_port: 443 status: healthy use_private_ip: true algorithm: type: round_robin outgoing_traffic: 123456 ingoing_traffic: 123456 included_traffic: 654321 action: id: 13 command: create_load_balancer status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\tresult, _, err := client.LoadBalancer.Create(ctx, hcloud.LoadBalancerCreateOpts{\n\t\ \tAlgorithm: &hcloud.LoadBalancerAlgorithm{\n\t\t\tType: hcloud.LoadBalancerAlgorithmTypeRoundRobin,\n\t\t},\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\tLoadBalancerType: &hcloud.LoadBalancerType{Name: \"lb11\"},\n\t\tLocation:\ \ &hcloud.Location{Name: \"fsn1\"},\n\t\tName: \"Web Frontend\",\n\t\tNetwork: &hcloud.Network{ID:\ \ 123},\n\t\tNetworkZone: hcloud.NetworkZoneEUCentral,\n\t\tPublicInterface: hcloud.Ptr(true),\n\t\tServices:\ \ []hcloud.LoadBalancerCreateOptsService{\n\t\t\t{\n\t\t\t\tDestinationPort: hcloud.Ptr(80),\n\t\t\t\tHealthCheck:\ \ &hcloud.LoadBalancerCreateOptsServiceHealthCheck{\n\t\t\t\t\tHTTP: &hcloud.LoadBalancerCreateOptsServiceHealthCheckHTTP{\n\ \t\t\t\t\t\tDomain: hcloud.Ptr(\"example.com\"),\n\t\t\t\t\t\tPath: hcloud.Ptr(\"/\"),\n\t\t\t\t\t\t\ Response: hcloud.Ptr(`{\"status\": \"ok\"}`),\n\t\t\t\t\t\tStatusCodes: []string{\"2??\", \"3??\"},\n\t\t\t\t\ \t\tTLS: hcloud.Ptr(false),\n\t\t\t\t\t},\n\t\t\t\t\tInterval: hcloud.Ptr(15 * time.Second),\n\t\t\t\t\t\ Port: hcloud.Ptr(4711),\n\t\t\t\t\tProtocol: hcloud.LoadBalancerServiceProtocolHTTP,\n\t\t\t\t\tRetries: hcloud.Ptr(3),\n\ \t\t\t\t\tTimeout: hcloud.Ptr(10 * time.Second),\n\t\t\t\t},\n\t\t\t\tHTTP: &hcloud.LoadBalancerCreateOptsServiceHTTP{\n\ \t\t\t\t\tCertificates: []*hcloud.Certificate{{ID: 897}},\n\t\t\t\t\tCookieLifetime: hcloud.Ptr(300 * time.Second),\n\ \t\t\t\t\tCookieName: hcloud.Ptr(\"HCLBSTICKY\"),\n\t\t\t\t\tRedirectHTTP: hcloud.Ptr(true),\n\t\t\t\t\tStickySessions:\ \ hcloud.Ptr(true),\n\t\t\t\t},\n\t\t\t\tListenPort: hcloud.Ptr(443),\n\t\t\t\tProtocol: hcloud.LoadBalancerServiceProtocolHTTPS,\n\ \t\t\t\tProxyprotocol: hcloud.Ptr(false),\n\t\t\t},\n\t\t},\n\t\tTargets: []hcloud.LoadBalancerCreateOptsTarget{\n\ \t\t\t{\n\t\t\t\tIP: hcloud.LoadBalancerCreateOptsTargetIP{\n\t\t\t\t\tIP: \"203.0.113.1\",\n\t\t\t\t},\n\t\t\t\t\ LabelSelector: hcloud.LoadBalancerCreateOptsTargetLabelSelector{\n\t\t\t\t\tSelector: \"env=prod\",\n\t\t\t\t},\n\ \t\t\t\tServer: hcloud.LoadBalancerCreateOptsTargetServer{\n\t\t\t\t\tServer: &hcloud.Server{ID: 80},\n\t\t\t\t\ },\n\t\t\t\tType: hcloud.LoadBalancerTargetTypeServer,\n\t\t\t\tUsePrivateIP: hcloud.Ptr(false),\n\t\t\t\ },\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tloadBalancer := result.LoadBalancer\n\ }" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.certificates\ \ import Certificate\nfrom hcloud.load_balancer_types import LoadBalancerType\nfrom hcloud.load_balancers import\ \ (\n LoadBalancerAlgorithm,\n LoadBalancerHealtCheckHttp,\n LoadBalancerHealthCheck,\n LoadBalancerService,\n\ \ LoadBalancerServiceHttp,\n LoadBalancerTarget,\n LoadBalancerTargetIP,\n LoadBalancerTargetLabelSelector,\n\ )\nfrom hcloud.locations import Location\nfrom hcloud.networks import Network\nfrom hcloud.servers import Server\n\ \ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.load_balancers.create(\n\ \ algorithm=LoadBalancerAlgorithm(type=\"round_robin\"),\n labels={\n \"environment\": \"prod\",\n\ \ \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n load_balancer_type=LoadBalancerType(name=\"\ lb11\"),\n location=Location(name=\"fsn1\"),\n name=\"Web Frontend\",\n network=Network(id=123),\n network_zone=\"\ eu-central\",\n public_interface=True,\n services=[\n LoadBalancerService(\n destination_port=80,\n\ \ health_check=LoadBalancerHealthCheck(\n http=LoadBalancerHealtCheckHttp(\n \ \ domain=\"example.com\",\n path=\"/\",\n response='{\"status\"\ : \"ok\"}',\n status_codes=[\"2??\", \"3??\"],\n tls=False,\n \ \ ),\n interval=15,\n port=4711,\n protocol=\"http\",\n \ \ retries=3,\n timeout=10,\n ),\n http=LoadBalancerServiceHttp(\n \ \ certificates=[Certificate(id=897)],\n cookie_lifetime=300,\n cookie_name=\"\ HCLBSTICKY\",\n redirect_http=True,\n sticky_sessions=True,\n ),\n \ \ listen_port=443,\n protocol=\"https\",\n proxyprotocol=False,\n )\n ],\n\ \ targets=[\n LoadBalancerTarget(\n ip=LoadBalancerTargetIP(\n ip=\"203.0.113.1\"\ ,\n ),\n label_selector=LoadBalancerTargetLabelSelector(\n selector=\"env=prod\"\ ,\n ),\n server=Server(\n id=80,\n ),\n type=\"server\"\ ,\n use_private_ip=True,\n )\n ],\n)\n\nresponse.action.wait_until_finished()\n\nload_balancer\ \ = response.load_balancer" - lang: Shell label: CLI source: "hcloud load-balancer create \\\n --algorithm-type round_robin \\\n --label \"environment=prod\" \\\n\ \ --label \"example.com/my=label\" \\\n --label \"just-a-key=\" \\\n --type lb11 \\\n --location fsn1\ \ \\\n --name \"Web Frontend\"\n\nhcloud load-balancer enable-public-interface \"Web Frontend\"\n\nhcloud load-balancer\ \ add-service \"Web Frontend\" \\\n --destination-port 80 \\\n --health-check-http-domain example.com \\\n\ \ --health-check-http-path \"/\" \\\n --health-check-http-response '{\"status\": \"ok\"}' \\\n --health-check-http-status-codes\ \ \"2??,3??\" \\\n --health-check-http-tls=false \\\n --health-check-interval 15s \\\n --health-check-port\ \ 4711 \\\n --health-check-protocol http \\\n --health-check-retries 3 \\\n --health-check-timeout 10s\ \ \\\n --http-certificates 897 \\\n --http-cookie-lifetime 300s \\\n --http-cookie-name HCLBSTICKY \\\n\ \ --http-redirect-http=true \\\n --http-sticky-sessions=true \\\n --listen-port 443 \\\n --protocol\ \ https \\\n --proxy-protocol=false\n\nhcloud load-balancer add-target \"Web Frontend\" --ip 203.0.113.1\nhcloud\ \ load-balancer add-target \"Web Frontend\" --label-selector \"env=prod\"\nhcloud load-balancer add-target \"Web\ \ Frontend\" --server 80 --use-private-ip" /load_balancers/actions: get: operationId: list_load_balancers_actions summary: List Actions description: 'Returns all Action objects. You can `sort` the results by using the sort URI parameter, and filter them with the `status` and `id` parameter. ' tags: - Load Balancer Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.LoadBalancer.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.load_balancers.actions.get_all()' /load_balancers/actions/{id}: get: operationId: get_load_balancers_action summary: Get an Action description: 'Returns a specific Action object. ' tags: - Load Balancer Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.LoadBalancer.Action.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) action = client.load_balancers.actions.get_by_id(123)' /load_balancers/{id}: get: operationId: get_load_balancer summary: Get a Load Balancer description: 'Gets a specific Load Balancer object. ' tags: - Load Balancers parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: load_balancer: type: object properties: id: description: ID of the [Load Balancer](#tag/load-balancers). 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 public_net: description: Public network information. type: object properties: enabled: description: Public Interface enabled or not. type: boolean ipv4: description: IP address (v4). type: object properties: ip: description: IP address (v4) of this Load Balancer. type: string nullable: true example: 1.2.3.4 dns_ptr: description: Reverse DNS PTR entry for the IPv4 address of this Load Balancer. type: string nullable: true example: lb1.example.com required: - ip - dns_ptr ipv6: description: IP address (v6). type: object properties: ip: description: IP address (v6) of this Load Balancer. type: string nullable: true example: 2001:db8::1 dns_ptr: description: Reverse DNS PTR entry for the IPv6 address of this Load Balancer. type: string nullable: true example: lb1.example.com required: - ip - dns_ptr required: - enabled - ipv4 - ipv6 private_net: description: Private networks information. type: array items: type: object properties: network: description: ID of the Network. type: integer format: int64 example: 4711 ip: description: IP address (v4) of this Load Balancer in this Network. type: string example: 10.0.0.2 required: - network - ip location: 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 load_balancer_type: type: object properties: id: description: ID of the Load Balancer type. type: integer format: int64 example: 1 name: description: Unique identifier of the Load Balancer type. type: string example: lb11 description: description: Description of the Load Balancer type. type: string example: LB11 max_connections: description: Number of maximum simultaneous open connections. type: integer format: int64 example: 20000 max_services: description: Number of services a Load Balancer of this type can have. type: integer format: int64 example: 5 max_targets: description: Number of targets a single Load Balancer can have. type: integer format: int64 example: 25 max_assigned_certificates: description: Number of SSL Certificates that can be assigned to a single Load Balancer. type: integer format: int64 example: 10 deprecated: description: Point in time when the Load Balancer type is deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2016-01-30T23:50:00Z' 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 required: - id - name - description - max_connections - max_services - max_targets - max_assigned_certificates - deprecated - prices protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' 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' services: description: List of services that belong to this Load Balancer. type: array items: title: LoadBalancerService oneOf: - title: LoadBalancerServiceTCP allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - tcp example: tcp - title: LoadBalancerServiceHTTPProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - http example: http http: title: LoadBalancerServiceHTTPConfig description: Configuration option for protocol http. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - sticky_sessions required: - http - title: LoadBalancerServiceHTTPSProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - https example: https http: title: LoadBalancerServiceHTTPSConfig description: Configuration option for protocol https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - certificates - redirect_http - sticky_sessions required: - http discriminator: propertyName: protocol mapping: tcp: '#/components/schemas/ServiceTCP' http: '#/components/schemas/ServiceHTTPProtocol' https: '#/components/schemas/ServiceHTTPSProtocol' targets: description: List of targets that belong to this Load Balancer. type: array items: title: LoadBalancerTarget oneOf: - title: LoadBalancerTargetTypeServer allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - server example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - server - health_status - use_private_ip - title: LoadBalancerTargetTypeLabelSelector allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - label_selector example: label_selector label_selector: title: LoadBalancerTargetLabelSelector description: Label selector used to determine targets. Only present for target type "label_selector". type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector targets: description: List of resolved label selector target Servers. type: array items: title: LoadBalancerTargetTarget type: object properties: type: description: Type of the resource. Here always "server". type: string example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - type - server - health_status - use_private_ip use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - label_selector - targets - use_private_ip - title: LoadBalancerTargetTypeIP allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - ip example: ip ip: title: LoadBalancerTargetIP description: IP target where the traffic should be routed to. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only present for target type `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status required: - ip - health_status discriminator: propertyName: type mapping: server: '#/components/schemas/TargetTypeServer' label_selector: '#/components/schemas/TargetTypeLabelSelector' ip: '#/components/schemas/TargetTypeIP' algorithm: description: Algorithm of the Load Balancer. type: object properties: type: description: Type of the algorithm. type: string enum: - round_robin - least_connections required: - type outgoing_traffic: description: Outbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true ingoing_traffic: description: Inbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true included_traffic: description: Free Traffic for the current billing period in bytes. type: integer format: int64 example: 10000 required: - id - name - public_net - private_net - location - load_balancer_type - protection - labels - created - services - targets - algorithm - outgoing_traffic - ingoing_traffic - included_traffic required: - load_balancer 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\tloadBalancer, _, err := client.LoadBalancer.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) load_balancer = client.load_balancers.get_by_id(123)' - lang: Shell label: CLI source: hcloud load-balancer describe $LOADBALANCER put: operationId: update_load_balancer summary: Update a Load Balancer description: 'Updates a Load Balancer. You can update a Load Balancer’s name and a Load Balancer’s labels. Note: if the Load Balancer object changes during the request, the response will be a “conflict” error. ' tags: - Load Balancers parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: name: description: New Load Balancer name. type: string minLength: 1 maxLength: 128 pattern: ^\S(.*\S)?$ example: new-name 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: load_balancer: type: object properties: id: description: ID of the [Load Balancer](#tag/load-balancers). 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 public_net: description: Public network information. type: object properties: enabled: description: Public Interface enabled or not. type: boolean ipv4: description: IP address (v4). type: object properties: ip: description: IP address (v4) of this Load Balancer. type: string nullable: true example: 1.2.3.4 dns_ptr: description: Reverse DNS PTR entry for the IPv4 address of this Load Balancer. type: string nullable: true example: lb1.example.com required: - ip - dns_ptr ipv6: description: IP address (v6). type: object properties: ip: description: IP address (v6) of this Load Balancer. type: string nullable: true example: 2001:db8::1 dns_ptr: description: Reverse DNS PTR entry for the IPv6 address of this Load Balancer. type: string nullable: true example: lb1.example.com required: - ip - dns_ptr required: - enabled - ipv4 - ipv6 private_net: description: Private networks information. type: array items: type: object properties: network: description: ID of the Network. type: integer format: int64 example: 4711 ip: description: IP address (v4) of this Load Balancer in this Network. type: string example: 10.0.0.2 required: - network - ip location: 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 load_balancer_type: type: object properties: id: description: ID of the Load Balancer type. type: integer format: int64 example: 1 name: description: Unique identifier of the Load Balancer type. type: string example: lb11 description: description: Description of the Load Balancer type. type: string example: LB11 max_connections: description: Number of maximum simultaneous open connections. type: integer format: int64 example: 20000 max_services: description: Number of services a Load Balancer of this type can have. type: integer format: int64 example: 5 max_targets: description: Number of targets a single Load Balancer can have. type: integer format: int64 example: 25 max_assigned_certificates: description: Number of SSL Certificates that can be assigned to a single Load Balancer. type: integer format: int64 example: 10 deprecated: description: Point in time when the Load Balancer type is deprecated (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). type: string format: date-time nullable: true example: '2016-01-30T23:50:00Z' 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 required: - id - name - description - max_connections - max_services - max_targets - max_assigned_certificates - deprecated - prices protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' 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' services: description: List of services that belong to this Load Balancer. type: array items: title: LoadBalancerService oneOf: - title: LoadBalancerServiceTCP allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - tcp example: tcp - title: LoadBalancerServiceHTTPProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - http example: http http: title: LoadBalancerServiceHTTPConfig description: Configuration option for protocol http. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - sticky_sessions required: - http - title: LoadBalancerServiceHTTPSProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - https example: https http: title: LoadBalancerServiceHTTPSConfig description: Configuration option for protocol https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - certificates - redirect_http - sticky_sessions required: - http discriminator: propertyName: protocol mapping: tcp: '#/components/schemas/ServiceTCP' http: '#/components/schemas/ServiceHTTPProtocol' https: '#/components/schemas/ServiceHTTPSProtocol' targets: description: List of targets that belong to this Load Balancer. type: array items: title: LoadBalancerTarget oneOf: - title: LoadBalancerTargetTypeServer allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - server example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - server - health_status - use_private_ip - title: LoadBalancerTargetTypeLabelSelector allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - label_selector example: label_selector label_selector: title: LoadBalancerTargetLabelSelector description: Label selector used to determine targets. Only present for target type "label_selector". type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector targets: description: List of resolved label selector target Servers. type: array items: title: LoadBalancerTargetTarget type: object properties: type: description: Type of the resource. Here always "server". type: string example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - type - server - health_status - use_private_ip use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - label_selector - targets - use_private_ip - title: LoadBalancerTargetTypeIP allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - ip example: ip ip: title: LoadBalancerTargetIP description: IP target where the traffic should be routed to. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only present for target type `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status required: - ip - health_status discriminator: propertyName: type mapping: server: '#/components/schemas/TargetTypeServer' label_selector: '#/components/schemas/TargetTypeLabelSelector' ip: '#/components/schemas/TargetTypeIP' algorithm: description: Algorithm of the Load Balancer. type: object properties: type: description: Type of the algorithm. type: string enum: - round_robin - least_connections required: - type outgoing_traffic: description: Outbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true ingoing_traffic: description: Inbound Traffic for the current billing period in bytes. type: integer format: int64 nullable: true included_traffic: description: Free Traffic for the current billing period in bytes. type: integer format: int64 example: 10000 required: - id - name - public_net - private_net - location - load_balancer_type - protection - labels - created - services - targets - algorithm - outgoing_traffic - ingoing_traffic - included_traffic required: - load_balancer examples: default: value: load_balancer: id: 4711 name: new-name public_net: enabled: false ipv4: ip: 1.2.3.4 dns_ptr: lb1.example.com ipv6: ip: 2001:db8::1 dns_ptr: lb1.example.com private_net: - network: 4711 ip: 10.0.0.2 location: id: 1 name: fsn1 description: Falkenstein DC Park 1 country: DE city: Falkenstein latitude: 50.47612 longitude: 12.370071 network_zone: eu-central load_balancer_type: id: 1 name: lb11 description: LB11 max_connections: 20000 max_services: 5 max_targets: 25 max_assigned_certificates: 10 deprecated: '2016-01-30T23:50:00Z' prices: - location: fsn1 price_hourly: net: '1.0000000000' gross: '1.1900000000000000' price_monthly: net: '1.0000000000' gross: '1.1900000000000000' included_traffic: 654321 price_per_tb_traffic: net: '1.0000000000' gross: '1.1900000000000000' protection: delete: false labels: key: value created: '2016-01-30T23:50:00Z' services: - protocol: https listen_port: 443 destination_port: 80 proxyprotocol: false health_check: protocol: http port: 4711 interval: 15 timeout: 10 retries: 3 http: domain: example.com path: / response: '{"status": "ok"}' status_codes: - 2??,3?? tls: false http: cookie_name: HCLBSTICKY cookie_lifetime: 300 certificates: - 897 redirect_http: true sticky_sessions: true timeout_idle: 50 targets: - type: server server: id: 80 health_status: - listen_port: 443 status: healthy use_private_ip: true label_selector: selector: env=prod ip: ip: 203.0.113.1 targets: - type: server server: id: 80 health_status: - listen_port: 443 status: healthy use_private_ip: true algorithm: type: round_robin outgoing_traffic: 123456 ingoing_traffic: 123456 included_traffic: 654321 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\tloadBalancer, _, err := client.LoadBalancer.Update(ctx, &hcloud.LoadBalancer{ID: 123},\ \ hcloud.LoadBalancerUpdateOpts{\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: \"new-name\",\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nload_balancer = client.load_balancers.update(\n\ \ load_balancer=LoadBalancer(id=123),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\"\ : \"label\",\n \"just-a-key\": \"\",\n },\n name=\"new-name\",\n)" - lang: Shell label: CLI source: "hcloud load-balancer update $LOADBALANCER --name new-name\nhcloud load-balancer add-label --overwrite $LOADBALANCER\ \ \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud load-balancer remove-label $LOADBALANCER\ \ \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_load_balancer summary: Delete a Load Balancer description: 'Deletes a Load Balancer. ' tags: - Load Balancers parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.LoadBalancer.Delete(ctx, &hcloud.LoadBalancer{ID: 123})\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.load_balancers import LoadBalancer token = environ["HCLOUD_TOKEN"] client = Client(token=token) client.load_balancers.delete(load_balancer=LoadBalancer(id=123))' - lang: Shell label: CLI source: hcloud load-balancer delete $LOADBALANCER /load_balancers/{id}/actions: get: operationId: list_load_balancer_actions summary: List Actions for a Load Balancer description: 'Returns all Action objects for a Load Balancer. You can sort the results by using the `sort` URI parameter, and filter them with the `status` parameter. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - meta examples: default: value: actions: - id: 13 command: add_service status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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: [] /load_balancers/{id}/actions/add_service: post: operationId: add_load_balancer_service summary: Add Service description: 'Adds a service to a Load Balancer. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `412` | `source_port_already_used` | The source port you are trying to add is already in use | ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: allOf: - title: LoadBalancerService type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https example: https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: allOf: - title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false additionalProperties: false - type: object required: - protocol - port - interval - timeout - retries - type: object properties: http: title: LoadBalancerServiceHTTP description: Configuration option for protocols http and https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough or if `protocol` is `http`. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. Only available if `protocol` is `https`. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. Only available if `protocol` is `http` or `https`. type: boolean default: false example: true required: - protocol - listen_port - destination_port - proxyprotocol - health_check responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: add_service status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.AddService(ctx, &hcloud.LoadBalancer{ID: 123},\ \ hcloud.LoadBalancerAddServiceOpts{\n\t\tDestinationPort: hcloud.Ptr(80),\n\t\tHealthCheck: &hcloud.LoadBalancerAddServiceOptsHealthCheck{\n\ \t\t\tHTTP: &hcloud.LoadBalancerAddServiceOptsHealthCheckHTTP{\n\t\t\t\tDomain: hcloud.Ptr(\"example.com\"\ ),\n\t\t\t\tPath: hcloud.Ptr(\"/\"),\n\t\t\t\tResponse: hcloud.Ptr(`{\"status\": \"ok\"}`),\n\t\t\t\t\ StatusCodes: []string{\"2??\", \"3??\"},\n\t\t\t\tTLS: hcloud.Ptr(false),\n\t\t\t},\n\t\t\tInterval: hcloud.Ptr(15\ \ * time.Second),\n\t\t\tPort: hcloud.Ptr(4711),\n\t\t\tProtocol: hcloud.LoadBalancerServiceProtocolHTTP,\n\t\ \t\tRetries: hcloud.Ptr(3),\n\t\t\tTimeout: hcloud.Ptr(10 * time.Second),\n\t\t},\n\t\tHTTP: &hcloud.LoadBalancerAddServiceOptsHTTP{\n\ \t\t\tCertificates: []*hcloud.Certificate{{ID: 897}},\n\t\t\tCookieLifetime: hcloud.Ptr(300 * time.Second),\n\t\ \t\tCookieName: hcloud.Ptr(\"HCLBSTICKY\"),\n\t\t\tRedirectHTTP: hcloud.Ptr(true),\n\t\t\tStickySessions:\ \ hcloud.Ptr(true),\n\t\t},\n\t\tListenPort: hcloud.Ptr(443),\n\t\tProtocol: hcloud.LoadBalancerServiceProtocolHTTPS,\n\ \t\tProxyprotocol: hcloud.Ptr(false),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.certificates\ \ import Certificate\nfrom hcloud.load_balancers import (\n LoadBalancer,\n LoadBalancerHealtCheckHttp,\n\ \ LoadBalancerHealthCheck,\n LoadBalancerService,\n LoadBalancerServiceHttp,\n)\n\ntoken = environ[\"HCLOUD_TOKEN\"\ ]\nclient = Client(token=token)\n\naction = client.load_balancers.add_service(\n load_balancer=LoadBalancer(id=123),\n\ \ service=LoadBalancerService(\n destination_port=80,\n health_check=LoadBalancerHealthCheck(\n\ \ http=LoadBalancerHealtCheckHttp(\n domain=\"example.com\",\n path=\"\ /\",\n response='{\"status\": \"ok\"}',\n status_codes=[\"2??\", \"3??\"],\n \ \ tls=False,\n ),\n interval=15,\n port=4711,\n protocol=\"\ http\",\n retries=3,\n timeout=10,\n ),\n http=LoadBalancerServiceHttp(\n \ \ certificates=[Certificate(id=897)],\n cookie_lifetime=300,\n cookie_name=\"HCLBSTICKY\"\ ,\n redirect_http=True,\n sticky_sessions=True,\n ),\n listen_port=443,\n \ \ protocol=\"https\",\n proxyprotocol=False,\n ),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud load-balancer add-service $LOADBALANCER \\\n --destination-port 80 \\\n --health-check-http-domain\ \ example.com \\\n --health-check-http-path \"/\" \\\n --health-check-http-response '{\"status\": \"ok\"}'\ \ \\\n --health-check-http-status-codes \"2??,3??\" \\\n --health-check-http-tls=false \\\n --health-check-interval\ \ 15s \\\n --health-check-port 4711 \\\n --health-check-protocol http \\\n --health-check-retries 3 \\\n\ \ --health-check-timeout 10s \\\n --http-certificates 897 \\\n --http-cookie-lifetime 300s \\\n --http-cookie-name\ \ HCLBSTICKY \\\n --http-redirect-http=true \\\n --http-sticky-sessions=true \\\n --listen-port 443 \\\n\ \ --protocol https \\\n --proxy-protocol=false" /load_balancers/{id}/actions/add_target: post: operationId: add_load_balancer_target summary: Add Target description: 'Adds a target to a Load Balancer. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `ip_not_in_vswitch_subnet` | The IP you are trying to add does not belong to the vswitch subnet of the attached network | | `422` | `ip_not_owned` | The IP you are trying to add as a target is not owned by the Project owner | | `422` | `load_balancer_public_interface_disabled` | The Load Balancer''s public network interface is disabled | | `422` | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network | | `422` | `network_has_no_vswitch_subnet` | The given IP is private but attached network does not have a vswitch subnet | | `422` | `resolve_cloud_private_targets_error` | The server you are trying to add as a target is not attached to the same network as the Load Balancer | | `422` | `resolve_cloud_public_targets_error` | The server that you are trying to add as a public target does not have a public IPv4 address | | `422` | `target_already_defined` | The Load Balancer target you are trying to define is already defined | ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: allOf: - title: LoadBalancerTarget description: Configuration of a Load Balancer target. type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip server: title: LoadBalancerTargetServer description: Configuration for type Server, only valid and required if type is `server`. type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 additionalProperties: false required: - id label_selector: title: LoadBalancerTargetLabelSelector description: Configuration for label selector targets, only valid and required if type is `label_selector`. type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector ip: title: LoadBalancerTargetIP description: Configuration for an IP target. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only valid and required if type is `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip required: - type - type: object properties: use_private_ip: description: Use the private network IP instead of the public IP of the Server, requires the Server and Load Balancer to be in the same network. Only valid for target types `server` and `label_selector`. type: boolean default: false example: true responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: add_target status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\"net\"\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\taction1, _, err := client.LoadBalancer.AddIPTarget(ctx, &hcloud.LoadBalancer{ID: 123},\ \ hcloud.LoadBalancerAddIPTargetOpts{\n\t\tIP: net.ParseIP(\"203.0.113.1\"),\n\t})\n\n\taction2, _, err := client.LoadBalancer.AddLabelSelectorTarget(ctx,\ \ &hcloud.LoadBalancer{ID: 123}, hcloud.LoadBalancerAddLabelSelectorTargetOpts{\n\t\tSelector: \"env=prod\",\n\t\ })\n\n\taction3, _, err := client.LoadBalancer.AddServerTarget(ctx, &hcloud.LoadBalancer{ID: 123}, hcloud.LoadBalancerAddServerTargetOpts{\n\ \t\tServer: &hcloud.Server{ID: 80},\n\t\tUsePrivateIP: hcloud.Ptr(true),\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action1, action2, action3)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import (\n LoadBalancer,\n LoadBalancerTarget,\n LoadBalancerTargetIP,\n LoadBalancerTargetLabelSelector,\n\ )\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction\ \ = client.load_balancers.add_target(\n load_balancer=LoadBalancer(id=123),\n target=LoadBalancerTarget(\n\ \ ip=LoadBalancerTargetIP(\n ip=\"203.0.113.1\",\n ),\n label_selector=LoadBalancerTargetLabelSelector(\n\ \ selector=\"env=prod\",\n ),\n server=Server(\n id=80,\n ),\n \ \ type=\"server\",\n use_private_ip=True,\n ),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud load-balancer add-target $LOADBALANCER --ip 203.0.113.1 hcloud load-balancer add-target $LOADBALANCER --label-selector "env=prod" hcloud load-balancer add-target $LOADBALANCER --server 80 --use-private-ip' /load_balancers/{id}/actions/attach_to_network: post: operationId: attach_load_balancer_to_network summary: Attach a Load Balancer to a Network description: 'Attach a Load Balancer to a Network. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `load_balancer_already_attached` | The Load Balancer is already attached to a network | | `422` | `ip_not_available` | The provided Network IP is not available | | `422` | `no_subnet_available` | No Subnet or IP is available for the Load Balancer within the network | ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: network: description: ID of an existing network to attach the Load Balancer to. type: integer format: int64 example: 123 ip: description: IP to request to be assigned to this Load Balancer; if you do not provide this then you will be auto assigned an IP address. type: string example: 10.0.1.1 ip_range: description: 'IP range in CIDR block notation of the subnet to attach to. This allows for auto assigning an IP address for a specific subnet. Providing `ip` that is not part of `ip_range` will result in an error. ' type: string example: 10.0.1.0/24 required: - network responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: attach_to_network status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\"net\"\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\taction, _, err := client.LoadBalancer.AttachToNetwork(ctx, &hcloud.LoadBalancer{ID:\ \ 123}, hcloud.LoadBalancerAttachToNetworkOpts{\n\t\tIP: net.ParseIP(\"10.0.1.1\"),\n\t\tNetwork: &hcloud.Network{ID:\ \ 4711},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer\nfrom hcloud.networks import Network\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.load_balancers.attach_to_network(\n load_balancer=LoadBalancer(id=123),\n ip=\"10.0.1.1\"\ ,\n network=Network(id=4711),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud load-balancer attach-to-network $LOADBALANCER \\\n --ip 10.0.1.1 \\\n --network 4711" /load_balancers/{id}/actions/change_algorithm: post: operationId: change_load_balancer_algorithm summary: Change Algorithm description: 'Change the algorithm that determines to which target new requests are sent. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: LoadBalancerAlgorithm description: Algorithm of the Load Balancer. type: object properties: type: description: Type of the algorithm. type: string enum: - round_robin - least_connections required: - type default: type: round_robin responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_algorithm status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.ChangeAlgorithm(ctx, &hcloud.LoadBalancer{ID:\ \ 123}, hcloud.LoadBalancerChangeAlgorithmOpts{\n\t\tType: hcloud.LoadBalancerAlgorithmTypeRoundRobin,\n\t})\n\n\ \terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer, LoadBalancerAlgorithm\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.load_balancers.change_algorithm(\n load_balancer=LoadBalancer(id=123),\n algorithm=LoadBalancerAlgorithm(type=\"\ round_robin\"),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud load-balancer change-algorithm $LOADBALANCER \\\n --algorithm-type round_robin" /load_balancers/{id}/actions/change_dns_ptr: post: operationId: change_load_balancer_dns_ptr summary: Change reverse DNS entry for this Load Balancer description: 'Changes the hostname that will appear when getting the hostname belonging to the public IPs (IPv4 and IPv6) of this Load Balancer. Floating IPs assigned to the Server are not affected by this. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: description: Select the IP address for which to change the DNS entry by passing `ip`. It can be either IPv4 or IPv6. The target hostname is set by passing `dns_ptr`, which must be a fully qualified domain name (FQDN) without trailing dot. required: true content: application/json: schema: type: object properties: ip: description: 'Single IPv4 or IPv6 address to create pointer for. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. Set to null to reset (IPv4) to the default value or remove (IPv6) the record. ' type: string nullable: true example: server.example.com required: - ip responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_dns_ptr status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: load_balancer error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.ChangeDNSPtr(ctx, &hcloud.LoadBalancer{ID: 123},\ \ \"1.2.3.4\", hcloud.Ptr(\"lb1.example.com\"))\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.load_balancers.change_dns_ptr(\n\ \ load_balancer=LoadBalancer(id=123),\n dns_ptr=\"lb1.example.com\",\n ip=\"1.2.3.4\",\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud load-balancer set-rdns $LOADBALANCER \\\n --ip 1.2.3.4 \\\n --hostname lb1.example.com" /load_balancers/{id}/actions/change_protection: post: operationId: change_load_balancer_protection summary: Change Load Balancer Protection description: 'Changes the protection configuration of a Load Balancer. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: delete: description: If true, prevents the Load Balancer from being deleted. type: boolean example: true responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.ChangeProtection(ctx, &hcloud.LoadBalancer{ID:\ \ 123},\n\t\thcloud.LoadBalancerChangeProtectionOpts{Delete: hcloud.Ptr(true)})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.load_balancers.change_protection(\n\ \ load_balancer=LoadBalancer(id=123),\n delete=True,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud load-balancer enable-protection $LOADBALANCER delete hcloud load-balancer disable-protection $LOADBALANCER delete' /load_balancers/{id}/actions/change_type: post: operationId: change_load_balancer_type summary: Change the Type of a Load Balancer description: 'Changes the type (Max Services, Max Targets and Max Connections) of a Load Balancer. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `invalid_load_balancer_type` | The Load Balancer type does not fit for the given Load Balancer | ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: ChangeTypeRequest type: object properties: load_balancer_type: description: ID or name of Load Balancer type the Load Balancer should migrate to. type: string example: lb11 required: - load_balancer_type responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_load_balancer_type status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.ChangeType(ctx, &hcloud.LoadBalancer{ID: 123},\ \ hcloud.LoadBalancerChangeTypeOpts{\n\t\tLoadBalancerType: &hcloud.LoadBalancerType{Name: \"lb21\"},\n\t})\n\n\t\ err = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancer_types\ \ import LoadBalancerType\nfrom hcloud.load_balancers import LoadBalancer\n\ntoken = environ[\"HCLOUD_TOKEN\"]\n\ client = Client(token=token)\n\naction = client.load_balancers.change_type(\n load_balancer=LoadBalancer(id=123),\n\ \ load_balancer_type=LoadBalancerType(name=\"lb21\"),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud load-balancer change-type $LOADBALANCER lb21 /load_balancers/{id}/actions/delete_service: post: operationId: delete_load_balancer_service summary: Delete Service description: 'Delete a service of a Load Balancer. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: listen_port: description: The listen port of the service you want to delete. type: integer example: 443 required: - listen_port responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: delete_service status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.DeleteService(ctx, &hcloud.LoadBalancer{ID: 123},\ \ 443)\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer, LoadBalancerService\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\n\ action = client.load_balancers.delete_service(\n load_balancer=LoadBalancer(id=123), service=LoadBalancerService(listen_port=443)\n\ )\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud load-balancer delete-service $LOADBALANCER \\\n --listen-port 443" /load_balancers/{id}/actions/detach_from_network: post: operationId: detach_load_balancer_from_network summary: Detach a Load Balancer from a Network description: 'Detaches a Load Balancer from a network. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: network: description: ID of an existing network to detach the Load Balancer from. type: integer format: int64 example: 4711 required: - network responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: detach_from_network status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 4711 type: network error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.DetachFromNetwork(ctx, &hcloud.LoadBalancer{ID:\ \ 123}, hcloud.LoadBalancerDetachFromNetworkOpts{\n\t\tNetwork: &hcloud.Network{ID: 4711},\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer\nfrom hcloud.networks import Network\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.load_balancers.detach_from_network(\n load_balancer=LoadBalancer(id=123), network=Network(id=4711)\n\ )\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud load-balancer detach-from-network $LOADBALANCER \\\n --network $NETWORK" /load_balancers/{id}/actions/disable_public_interface: post: operationId: disable_load_balancer_public_interface summary: Disable the public interface of a Load Balancer description: 'Disable the public interface of a Load Balancer. The Load Balancer will be not accessible from the internet via its public IPs. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network | | `422` | `targets_without_use_private_ip` | The Load Balancer has targets that use the public IP instead of the private IP | ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: disable_public_interface status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 4711 type: network error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.DisablePublicInterface(ctx, &hcloud.LoadBalancer{ID:\ \ 123})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.load_balancers.disable_public_interface(\n\ \ load_balancer=LoadBalancer(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud load-balancer disable-public-interface $LOADBALANCER /load_balancers/{id}/actions/enable_public_interface: post: operationId: enable_load_balancer_public_interface summary: Enable the public interface of a Load Balancer description: 'Enable the public interface of a Load Balancer. The Load Balancer will be accessible from the internet via its public IPs. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: enable_public_interface status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 4711 type: network error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.EnablePublicInterface(ctx, &hcloud.LoadBalancer{ID:\ \ 123})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import LoadBalancer\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.load_balancers.enable_public_interface(\n\ \ load_balancer=LoadBalancer(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud load-balancer enable-public-interface $LOADBALANCER /load_balancers/{id}/actions/remove_target: post: operationId: remove_load_balancer_target summary: Remove Target description: 'Removes a target from a Load Balancer. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: LoadBalancerTarget description: Configuration of a Load Balancer target. type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip server: title: LoadBalancerTargetServer description: Configuration for type Server, only valid and required if type is `server`. type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 additionalProperties: false required: - id label_selector: title: LoadBalancerTargetLabelSelector description: Configuration for label selector targets, only valid and required if type is `label_selector`. type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector ip: title: LoadBalancerTargetIP description: Configuration for an IP target. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only valid and required if type is `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip required: - type responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: remove_target status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\"net\"\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\taction1, _, err := client.LoadBalancer.RemoveIPTarget(ctx, &hcloud.LoadBalancer{ID:\ \ 123}, net.ParseIP(\"203.0.113.1\"))\n\n\taction2, _, err := client.LoadBalancer.RemoveLabelSelectorTarget(ctx,\ \ &hcloud.LoadBalancer{ID: 123}, \"env=prod\")\n\n\taction3, _, err := client.LoadBalancer.RemoveServerTarget(ctx,\ \ &hcloud.LoadBalancer{ID: 123}, &hcloud.Server{ID: 80})\n\n\terr = client.Action.WaitFor(ctx, action1, action2,\ \ action3)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.load_balancers\ \ import (\n LoadBalancer,\n LoadBalancerTarget,\n LoadBalancerTargetIP,\n LoadBalancerTargetLabelSelector,\n\ )\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction\ \ = client.load_balancers.remove_target(\n load_balancer=LoadBalancer(id=123),\n target=LoadBalancerTarget(\n\ \ ip=LoadBalancerTargetIP(\n ip=\"203.0.113.1\",\n ),\n label_selector=LoadBalancerTargetLabelSelector(\n\ \ selector=\"env=prod\",\n ),\n server=Server(\n id=80,\n ),\n \ \ type=\"server\",\n ),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud load-balancer remove-target $LOADBALANCER --ip 203.0.113.1 hcloud load-balancer remove-target $LOADBALANCER --label-selector "env=prod" hcloud load-balancer remove-target $LOADBALANCER --server 80 --use-private-ip' /load_balancers/{id}/actions/update_service: post: operationId: update_load_balancer_service summary: Update Service description: 'Updates a Load Balancer Service. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `source_port_already_used` | The source port you are trying to add is already in use | ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: UpdateLoadBalancerService allOf: - title: LoadBalancerService type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https example: https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: allOf: - title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false additionalProperties: false - type: object required: - protocol - port - interval - timeout - retries - type: object properties: health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false additionalProperties: false http: title: LoadBalancerServiceHTTP description: Configuration option for protocols http and https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough or if `protocol` is `http`. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. Only available if `protocol` is `https`. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. Only available if `protocol` is `http` or `https`. type: boolean default: false example: true required: - listen_port responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: update_service status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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\taction, _, err := client.LoadBalancer.UpdateService(ctx, &hcloud.LoadBalancer{ID: 123},\ \ 443, hcloud.LoadBalancerUpdateServiceOpts{\n\t\tDestinationPort: hcloud.Ptr(80),\n\t\tHealthCheck: &hcloud.LoadBalancerUpdateServiceOptsHealthCheck{\n\ \t\t\tHTTP: &hcloud.LoadBalancerUpdateServiceOptsHealthCheckHTTP{\n\t\t\t\tDomain: hcloud.Ptr(\"example.com\"\ ),\n\t\t\t\tPath: hcloud.Ptr(\"/\"),\n\t\t\t\tResponse: hcloud.Ptr(`{\"status\": \"ok\"}`),\n\t\t\t\t\ StatusCodes: []string{\"2??\", \"3??\"},\n\t\t\t\tTLS: hcloud.Ptr(false),\n\t\t\t},\n\t\t\tInterval: hcloud.Ptr(15\ \ * time.Second),\n\t\t\tPort: hcloud.Ptr(4711),\n\t\t\tProtocol: hcloud.LoadBalancerServiceProtocolHTTP,\n\t\ \t\tRetries: hcloud.Ptr(3),\n\t\t\tTimeout: hcloud.Ptr(10 * time.Second),\n\t\t},\n\t\tHTTP: &hcloud.LoadBalancerUpdateServiceOptsHTTP{\n\ \t\t\tCertificates: []*hcloud.Certificate{{ID: 897}},\n\t\t\tCookieLifetime: hcloud.Ptr(300 * time.Second),\n\t\ \t\tCookieName: hcloud.Ptr(\"HCLBSTICKY\"),\n\t\t\tRedirectHTTP: hcloud.Ptr(true),\n\t\t\tStickySessions:\ \ hcloud.Ptr(true),\n\t\t},\n\t\tProtocol: hcloud.LoadBalancerServiceProtocolHTTPS,\n\t\tProxyprotocol: hcloud.Ptr(false),\n\ \t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.certificates\ \ import Certificate\nfrom hcloud.load_balancers import (\n LoadBalancer,\n LoadBalancerHealtCheckHttp,\n\ \ LoadBalancerHealthCheck,\n LoadBalancerService,\n LoadBalancerServiceHttp,\n)\n\ntoken = environ[\"HCLOUD_TOKEN\"\ ]\nclient = Client(token=token)\n\naction = client.load_balancers.update_service(\n load_balancer=LoadBalancer(id=123),\n\ \ service=LoadBalancerService(\n destination_port=80,\n health_check=LoadBalancerHealthCheck(\n\ \ http=LoadBalancerHealtCheckHttp(\n domain=\"example.com\",\n path=\"\ /\",\n response='{\"status\": \"ok\"}',\n status_codes=[\"2??\", \"3??\"],\n \ \ tls=False,\n ),\n interval=15,\n port=4711,\n protocol=\"\ http\",\n retries=3,\n timeout=10,\n ),\n http=LoadBalancerServiceHttp(\n \ \ certificates=[Certificate(id=897)],\n cookie_lifetime=300,\n cookie_name=\"HCLBSTICKY\"\ ,\n redirect_http=True,\n sticky_sessions=True,\n ),\n listen_port=443,\n \ \ protocol=\"https\",\n proxyprotocol=False,\n ),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud load-balancer update-service $LOADBALANCER \\\n --listen-port 443 \\\n --destination-port 80\ \ \\\n --health-check-http-domain example.com \\\n --health-check-http-path \"/\" \\\n --health-check-http-response\ \ '{\"status\": \"ok\"}' \\\n --health-check-http-status-codes \"2??,3??\" \\\n --health-check-http-tls=false\ \ \\\n --health-check-interval 15s \\\n --health-check-port 4711 \\\n --health-check-protocol http \\\n\ \ --health-check-retries 3 \\\n --health-check-timeout 10s \\\n --http-certificates 897 \\\n --http-cookie-lifetime\ \ 300s \\\n --http-cookie-name HCLBSTICKY \\\n --http-redirect-http=true \\\n --http-sticky-sessions=true\ \ \\\n --protocol https \\\n --proxy-protocol=false" /load_balancers/{id}/actions/{action_id}: get: deprecated: true operationId: get_load_balancer_action summary: Get an Action for a Load Balancer description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific Action for a Load Balancer. ' tags: - Load Balancer Actions parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: load_balancer error: code: action_failed message: Action failed 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: [] /load_balancers/{id}/metrics: get: operationId: get_load_balancer_metrics summary: Get Metrics for a LoadBalancer description: 'You must specify the type of metric to get: `open_connections`, `connections_per_second`, `requests_per_second` or `bandwidth`. You can also specify more than one type by comma separation, e.g. `requests_per_second,bandwidth`. Depending on the type you will get different time series data: |Type | Timeseries | Unit | Description | |---- |------------|------|-------------| | open_connections | open_connections | number | Open connections | | connections_per_second | connections_per_second | connections/s | Connections per second | | requests_per_second | requests_per_second | requests/s | Requests per second | | bandwidth | bandwidth.in | bytes/s | Ingress bandwidth | || bandwidth.out | bytes/s | Egress bandwidth | Metrics are available for the last 30 days only. If you do not provide the step argument we will automatically adjust it so that 200 samples are returned. We limit the number of samples to a maximum of 500 and will adjust the step parameter accordingly. ' tags: - Load Balancers parameters: - description: ID of the Load Balancer. name: id in: path required: true schema: description: ID of the [Load Balancer](#tag/load-balancers). 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: - open_connections - connections_per_second - requests_per_second - bandwidth - 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.LoadBalancer.GetMetrics(ctx, &hcloud.LoadBalancer{ID: 123},\ \ hcloud.LoadBalancerGetMetricsOpts{\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.LoadBalancerMetricType{\n\t\t\thcloud.LoadBalancerMetricBandwidth,\n\ \t\t\thcloud.LoadBalancerMetricOpenConnections,\n\t\t\thcloud.LoadBalancerMetricConnectionsPerSecond,\n\t\t\thcloud.LoadBalancerMetricRequestsPerSecond,\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\n\ from hcloud.load_balancers import LoadBalancer\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \nresponse = client.load_balancers.get_metrics(\n load_balancer=LoadBalancer(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 \"bandwidth\",\n \"open_connections\",\n \"connections_per_second\",\n \ \ \"requests_per_second\",\n ],\n)\n\nresponse.action.wait_until_finished()\n\nmetrics = response.metrics" - lang: Shell label: CLI source: "hcloud load-balancer metrics $LOADBALANCER \\\n --type open_connections,connections_per_second,requests_per_second,bandwidth\ \ \\\n --start 2017-01-01T00:00:00Z \\\n --end 2017-01-01T23:00:00Z" /locations: get: operationId: list_locations summary: List Locations description: 'Returns all [Locations](#tag/locations). ' tags: - Locations 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: '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 - 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. content: application/json: schema: type: object properties: locations: description: List of [Locations](#tag/locations). type: array items: 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 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: - locations - 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\tlocations, err := client.Location.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) locations = client.locations.get_all()' - lang: Shell label: CLI source: hcloud location list /locations/{id}: get: operationId: get_location summary: Get a Location description: 'Returns a [Location](#tag/locations). ' tags: - Locations parameters: - description: ID of the Location. name: id in: path required: true schema: description: ID of the [Location](#tag/locations). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: location: 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 required: - location 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\tlocation, _, err := client.Location.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) location = client.locations.get_by_id(123)' - lang: Shell label: CLI source: hcloud location describe $LOCATION /networks: get: operationId: list_networks summary: List Networks description: 'List multiple [Networks](#tag/networks). Use the provided URI parameters to modify the result. ' tags: - Networks parameters: - 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 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: 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. content: application/json: schema: type: object properties: networks: type: array items: type: object properties: id: description: ID of the [Network](#tag/networks). type: integer format: int64 example: 4711 name: description: Name of the [Network](#tag/networks). type: string example: mynet ip_range: description: 'IP range of the [Network](#tag/networks). Uses CIDR notation. ' type: string example: 10.0.0.0/16 subnets: description: List of subnets allocated in this [Network](#tag/networks). type: array items: type: object properties: type: description: 'Type of subnet. ' type: string enum: - cloud - server - vswitch x-enumDescriptions: cloud: Used to connect cloud [Servers](#tag/servers) and [Load Balancers](#tag/load-balancers). server: Same as the `cloud` type. **Deprecated**, use the `cloud` type instead. vswitch: Used to [connect cloud Servers and Load Balancers with dedicated Servers](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch). ip_range: description: 'IP range of the subnet. Uses CIDR notation. ' type: string example: 10.0.1.0/24 network_zone: description: 'Name of the [Network Zone](#tag/network-zones). The [Location](#tag/locations) contains the `network_zone` property it belongs to. ' type: string example: eu-central gateway: description: 'Gateway for [Servers](#tag/servers) attached to this subnet. For subnets of type `server` this is always the first IP of the subnets IP range. ' type: string example: 10.0.0.1 vswitch_id: description: ID of the robot vSwitch if the subnet is of type `vswitch`. type: integer format: int64 nullable: true example: 1000 required: - type - network_zone - gateway routes: description: Array of routes set in this [Network](#tag/networks). type: array items: type: object properties: destination: description: 'Destination network or host of the route. Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway. Must be one of * private IPv4 ranges of RFC1918 * or `0.0.0.0/0`. Must not overlap with * an existing ip_range in any subnets * or with any destinations in other routes * or with `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.100.1.0/24 gateway: description: 'Gateway of the route. Packages addressed for the specified destination will be send to this IP address. Cannot be * the first IP of the networks ip_range, * an IP behind a vSwitch or * `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.0.1.1 required: - destination - gateway servers: description: Array of IDs of [Servers](#tag/servers) attached to this [Network](#tag/networks). type: array items: type: integer format: int64 example: - 42 load_balancers: description: Array of IDs of [Load Balancers](#tag/load-balancers) attached to this [Network](#tag/networks). type: array items: type: integer format: int64 example: - 42 protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' 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' expose_routes_to_vswitch: description: Indicates if the routes from this [Network](#tag/networks) should be exposed to the vSwitch connection. type: boolean example: false required: - id - name - ip_range - subnets - routes - servers - protection - labels - created - expose_routes_to_vswitch 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: - networks - 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\tnetworks, err := client.Network.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) networks = client.networks.get_all()' - lang: Shell label: CLI source: hcloud network list post: operationId: create_network summary: Create a Network description: 'Creates a [Network](#tag/networks). The provided `ip_range` can only be extended later on, but not reduced. Subnets can be added now or later on using the [add subnet action](#tag/network-actions/add_network_subnet). If you do not specify an `ip_range` for the subnet the first available /24 range will be used. Routes can be added now or later by using the [add route action](#tag/network-actions/add_network_route). ' tags: - Networks requestBody: required: true content: application/json: schema: title: NetworkCreateRequest type: object properties: name: description: Name of the [Network](#tag/networks). type: string example: mynet ip_range: example: 10.0.0.0/16 description: 'IP range of the [Network](#tag/networks). Uses CIDR notation. Must span all included subnets. Must be one of the private IPv4 ranges of RFC1918. Minimum network size is /24. We highly recommend that you pick a larger [Network](#tag/networks) with a /16 netmask. ' type: string 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: '' subnets: description: Array of subnets to allocate. type: array items: type: object properties: type: description: 'Type of subnet. ' type: string enum: - cloud - server - vswitch x-enumDescriptions: cloud: Used to connect cloud [Servers](#tag/servers) and [Load Balancers](#tag/load-balancers). server: Same as the `cloud` type. **Deprecated**, use the `cloud` type instead. vswitch: Used to [connect cloud Servers and Load Balancers with dedicated Servers](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch). ip_range: description: 'IP range of the subnet. Uses CIDR notation. Must be a subnet of the parent [Networks](#tag/networks) `ip_range`. Must not overlap with any other subnets or with any destinations in routes. Minimum network size is /30. We highly recommend that you pick a larger subnet with a /24 netmask. ' type: string example: 10.0.1.0/24 network_zone: description: 'Name of the [Network Zone](#tag/network-zones). The [Location](#tag/locations) contains the `network_zone` property it belongs to. ' type: string example: eu-central vswitch_id: description: 'ID of the robot vSwitch. Must only be supplied for subnets of type `vswitch`. ' type: integer format: int64 example: 1000 required: - type - network_zone routes: description: Array of routes set in this [Network](#tag/networks). type: array items: type: object properties: destination: description: 'Destination network or host of the route. Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway. Must be one of * private IPv4 ranges of RFC1918 * or `0.0.0.0/0`. Must not overlap with * an existing ip_range in any subnets * or with any destinations in other routes * or with `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.100.1.0/24 gateway: description: 'Gateway of the route. Packages addressed for the specified destination will be send to this IP address. Cannot be * the first IP of the networks ip_range, * an IP behind a vSwitch or * `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.0.1.1 required: - destination - gateway expose_routes_to_vswitch: description: 'Toggle to expose routes to the [Networks](#tag/networks) vSwitch. Indicates if the routes from this [Network](#tag/networks) should be exposed to the vSwitch in this [Network](#tag/networks). Only takes effect if a [vSwitch is setup](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch) in this [Network](#tag/networks). ' type: boolean example: false required: - name - ip_range responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: network: type: object properties: id: description: ID of the [Network](#tag/networks). type: integer format: int64 example: 4711 name: description: Name of the [Network](#tag/networks). type: string example: mynet ip_range: description: 'IP range of the [Network](#tag/networks). Uses CIDR notation. ' type: string example: 10.0.0.0/16 subnets: description: List of subnets allocated in this [Network](#tag/networks). type: array items: type: object properties: type: description: 'Type of subnet. ' type: string enum: - cloud - server - vswitch x-enumDescriptions: cloud: Used to connect cloud [Servers](#tag/servers) and [Load Balancers](#tag/load-balancers). server: Same as the `cloud` type. **Deprecated**, use the `cloud` type instead. vswitch: Used to [connect cloud Servers and Load Balancers with dedicated Servers](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch). ip_range: description: 'IP range of the subnet. Uses CIDR notation. ' type: string example: 10.0.1.0/24 network_zone: description: 'Name of the [Network Zone](#tag/network-zones). The [Location](#tag/locations) contains the `network_zone` property it belongs to. ' type: string example: eu-central gateway: description: 'Gateway for [Servers](#tag/servers) attached to this subnet. For subnets of type `server` this is always the first IP of the subnets IP range. ' type: string example: 10.0.0.1 vswitch_id: description: ID of the robot vSwitch if the subnet is of type `vswitch`. type: integer format: int64 nullable: true example: 1000 required: - type - network_zone - gateway routes: description: Array of routes set in this [Network](#tag/networks). type: array items: type: object properties: destination: description: 'Destination network or host of the route. Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway. Must be one of * private IPv4 ranges of RFC1918 * or `0.0.0.0/0`. Must not overlap with * an existing ip_range in any subnets * or with any destinations in other routes * or with `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.100.1.0/24 gateway: description: 'Gateway of the route. Packages addressed for the specified destination will be send to this IP address. Cannot be * the first IP of the networks ip_range, * an IP behind a vSwitch or * `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.0.1.1 required: - destination - gateway servers: description: Array of IDs of [Servers](#tag/servers) attached to this [Network](#tag/networks). type: array items: type: integer format: int64 example: - 42 load_balancers: description: Array of IDs of [Load Balancers](#tag/load-balancers) attached to this [Network](#tag/networks). type: array items: type: integer format: int64 example: - 42 protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' 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' expose_routes_to_vswitch: description: Indicates if the routes from this [Network](#tag/networks) should be exposed to the vSwitch connection. type: boolean example: false required: - id - name - ip_range - subnets - routes - servers - protection - labels - created - expose_routes_to_vswitch 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\"net\"\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\tnetwork, _, err := client.Network.Create(ctx, hcloud.NetworkCreateOpts{\n\t\tExposeRoutesToVSwitch:\ \ false,\n\t\tIPRange: &net.IPNet{\n\t\t\tIP: net.ParseIP(\"10.0.0.0\"),\n\t\t\tMask: net.CIDRMask(16, 32),\n\t\ \t},\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: \"mynet\",\n\t\tRoutes: []hcloud.NetworkRoute{\n\t\t\t{\n\t\t\ \t\tDestination: &net.IPNet{\n\t\t\t\t\tIP: net.ParseIP(\"10.100.1.0\"),\n\t\t\t\t\tMask: net.CIDRMask(24, 32),\n\ \t\t\t\t},\n\t\t\t\tGateway: net.ParseIP(\"10.0.1.1\"),\n\t\t\t},\n\t\t},\n\t\tSubnets: []hcloud.NetworkSubnet{\n\ \t\t\t{\n\t\t\t\tIPRange: &net.IPNet{\n\t\t\t\t\tIP: net.ParseIP(\"10.0.1.0\"),\n\t\t\t\t\tMask: net.CIDRMask(24,\ \ 32),\n\t\t\t\t},\n\t\t\t\tNetworkZone: hcloud.NetworkZoneEUCentral,\n\t\t\t\tType: hcloud.NetworkSubnetTypeCloud,\n\ \t\t\t\tVSwitchID: 1000,\n\t\t\t},\n\t\t},\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import NetworkRoute, NetworkSubnet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nnetwork\ \ = client.networks.create(\n expose_routes_to_vswitch=False,\n ip_range=\"10.0.0.0/16\",\n labels={\n\ \ \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n \ \ },\n name=\"mynet\",\n routes=[\n NetworkRoute(\n destination=\"10.100.1.0/24\",\n \ \ gateway=\"10.0.1.1\",\n )\n ],\n subnets=[\n NetworkSubnet(\n ip_range=\"\ 10.0.1.0/24\",\n network_zone=\"eu-central\",\n type=\"cloud\",\n vswitch_id=1000,\n\ \ )\n ],\n)" - lang: Shell label: CLI source: "hcloud network create \\\n --expose-routes-to-vswitch=false \\\n --ip-range 10.0.0.0/16 \\\n --label\ \ \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\" \\\n --name mynet\n\ \nhcloud network add-route mynet \\\n --destination 10.100.1.0/24 \\\n --gateway 10.0.1.1\n\nhcloud network\ \ add-subnet mynet \\\n --ip-range 10.0.1.0/24 \\\n --network-zone eu-central \\\n --type cloud \\\n \ \ --vswitch-id 1000" /networks/actions: get: operationId: list_networks_actions summary: List Actions description: 'Lists multiple [Actions](#tag/actions). Use the provided URI parameters to modify the result. ' tags: - Network Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.Network.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.networks.actions.get_all()' /networks/actions/{id}: get: operationId: get_networks_action summary: Get an Action description: 'Returns a single [Action](#tag/actions). ' tags: - Network Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.Network.Action.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) action = client.networks.actions.get_by_id(123)' /networks/{id}: get: operationId: get_network summary: Get a Network description: 'Get a specific [Network](#tag/networks). ' tags: - Networks parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: network: type: object properties: id: description: ID of the [Network](#tag/networks). type: integer format: int64 example: 4711 name: description: Name of the [Network](#tag/networks). type: string example: mynet ip_range: description: 'IP range of the [Network](#tag/networks). Uses CIDR notation. ' type: string example: 10.0.0.0/16 subnets: description: List of subnets allocated in this [Network](#tag/networks). type: array items: type: object properties: type: description: 'Type of subnet. ' type: string enum: - cloud - server - vswitch x-enumDescriptions: cloud: Used to connect cloud [Servers](#tag/servers) and [Load Balancers](#tag/load-balancers). server: Same as the `cloud` type. **Deprecated**, use the `cloud` type instead. vswitch: Used to [connect cloud Servers and Load Balancers with dedicated Servers](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch). ip_range: description: 'IP range of the subnet. Uses CIDR notation. ' type: string example: 10.0.1.0/24 network_zone: description: 'Name of the [Network Zone](#tag/network-zones). The [Location](#tag/locations) contains the `network_zone` property it belongs to. ' type: string example: eu-central gateway: description: 'Gateway for [Servers](#tag/servers) attached to this subnet. For subnets of type `server` this is always the first IP of the subnets IP range. ' type: string example: 10.0.0.1 vswitch_id: description: ID of the robot vSwitch if the subnet is of type `vswitch`. type: integer format: int64 nullable: true example: 1000 required: - type - network_zone - gateway routes: description: Array of routes set in this [Network](#tag/networks). type: array items: type: object properties: destination: description: 'Destination network or host of the route. Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway. Must be one of * private IPv4 ranges of RFC1918 * or `0.0.0.0/0`. Must not overlap with * an existing ip_range in any subnets * or with any destinations in other routes * or with `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.100.1.0/24 gateway: description: 'Gateway of the route. Packages addressed for the specified destination will be send to this IP address. Cannot be * the first IP of the networks ip_range, * an IP behind a vSwitch or * `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.0.1.1 required: - destination - gateway servers: description: Array of IDs of [Servers](#tag/servers) attached to this [Network](#tag/networks). type: array items: type: integer format: int64 example: - 42 load_balancers: description: Array of IDs of [Load Balancers](#tag/load-balancers) attached to this [Network](#tag/networks). type: array items: type: integer format: int64 example: - 42 protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' 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' expose_routes_to_vswitch: description: Indicates if the routes from this [Network](#tag/networks) should be exposed to the vSwitch connection. type: boolean example: false required: - id - name - ip_range - subnets - routes - servers - protection - labels - created - expose_routes_to_vswitch 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\tnetwork, _, err := client.Network.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) network = client.networks.get_by_id(123)' - lang: Shell label: CLI source: hcloud network describe $NETWORK put: operationId: update_network summary: Update a Network description: 'Update a [Network](#tag/networks). If a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned. ' tags: - Networks parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: NetworkUpdateRequest type: object properties: name: description: New [Network](#tag/networks) name. type: string example: new-name 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: '' expose_routes_to_vswitch: description: 'Toggle to expose routes to the [Networks](#tag/networks) vSwitch. Indicates if the routes from this [Network](#tag/networks) should be exposed to the vSwitch in this [Network](#tag/networks). Only takes effect if a [vSwitch is setup](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch) in this [Network](#tag/networks). ' type: boolean example: false responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: network: type: object properties: id: description: ID of the [Network](#tag/networks). type: integer format: int64 example: 4711 name: description: Name of the [Network](#tag/networks). type: string example: mynet ip_range: description: 'IP range of the [Network](#tag/networks). Uses CIDR notation. ' type: string example: 10.0.0.0/16 subnets: description: List of subnets allocated in this [Network](#tag/networks). type: array items: type: object properties: type: description: 'Type of subnet. ' type: string enum: - cloud - server - vswitch x-enumDescriptions: cloud: Used to connect cloud [Servers](#tag/servers) and [Load Balancers](#tag/load-balancers). server: Same as the `cloud` type. **Deprecated**, use the `cloud` type instead. vswitch: Used to [connect cloud Servers and Load Balancers with dedicated Servers](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch). ip_range: description: 'IP range of the subnet. Uses CIDR notation. ' type: string example: 10.0.1.0/24 network_zone: description: 'Name of the [Network Zone](#tag/network-zones). The [Location](#tag/locations) contains the `network_zone` property it belongs to. ' type: string example: eu-central gateway: description: 'Gateway for [Servers](#tag/servers) attached to this subnet. For subnets of type `server` this is always the first IP of the subnets IP range. ' type: string example: 10.0.0.1 vswitch_id: description: ID of the robot vSwitch if the subnet is of type `vswitch`. type: integer format: int64 nullable: true example: 1000 required: - type - network_zone - gateway routes: description: Array of routes set in this [Network](#tag/networks). type: array items: type: object properties: destination: description: 'Destination network or host of the route. Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway. Must be one of * private IPv4 ranges of RFC1918 * or `0.0.0.0/0`. Must not overlap with * an existing ip_range in any subnets * or with any destinations in other routes * or with `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.100.1.0/24 gateway: description: 'Gateway of the route. Packages addressed for the specified destination will be send to this IP address. Cannot be * the first IP of the networks ip_range, * an IP behind a vSwitch or * `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.0.1.1 required: - destination - gateway servers: description: Array of IDs of [Servers](#tag/servers) attached to this [Network](#tag/networks). type: array items: type: integer format: int64 example: - 42 load_balancers: description: Array of IDs of [Load Balancers](#tag/load-balancers) attached to this [Network](#tag/networks). type: array items: type: integer format: int64 example: - 42 protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' 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' expose_routes_to_vswitch: description: Indicates if the routes from this [Network](#tag/networks) should be exposed to the vSwitch connection. type: boolean example: false required: - id - name - ip_range - subnets - routes - servers - protection - labels - created - expose_routes_to_vswitch examples: default: value: network: id: 4711 name: new-name ip_range: 10.0.0.0/16 subnets: - type: cloud ip_range: 10.0.1.0/24 network_zone: eu-central gateway: 10.0.0.1 routes: - destination: 10.100.1.0/24 gateway: 10.0.1.1 servers: - 42 load_balancers: - 42 protection: delete: false labels: key: value created: '2016-01-30T23:50:00Z' expose_routes_to_vswitch: true 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\tnetwork, _, err := client.Network.Update(ctx, &hcloud.Network{ID: 123}, hcloud.NetworkUpdateOpts{\n\ \t\tExposeRoutesToVSwitch: hcloud.Ptr(false),\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: \"new-name\",\n\t})\n\ }" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nnetwork = client.networks.update(\n\ \ network=Network(id=123),\n expose_routes_to_vswitch=False,\n labels={\n \"environment\": \"prod\"\ ,\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"new-name\",\n)" - lang: Shell label: CLI source: "hcloud network update $NETWORK --name new-name\nhcloud network expose-routes-to-vswitch --disable $NETWORK\n\ hcloud network add-label --overwrite $NETWORK \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\ \nhcloud network remove-label $NETWORK \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_network summary: Delete a Network description: 'Deletes a [Network](#tag/networks). Attached resources will be detached automatically. ' tags: - Networks parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.Network.Delete(ctx, &hcloud.Network{ID: 123})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nclient.networks.delete(\n\ \ network=Network(id=123),\n)" - lang: Shell label: CLI source: hcloud network delete $NETWORK /networks/{id}/actions: get: operationId: list_network_actions summary: List Actions for a Network description: 'Lists [Actions](#tag/actions) for a [Network](#tag/networks). Use the provided URI parameters to modify the result. ' tags: - Network Actions parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - meta examples: default: value: actions: - id: 13 command: add_subnet status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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: [] /networks/{id}/actions/add_route: post: operationId: add_network_route summary: Add a route to a Network description: 'Adds a route entry to a [Network](#tag/networks). If a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned. ' tags: - Network Actions parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: AddRouteRequest type: object properties: destination: description: 'Destination network or host of the route. Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway. Must be one of * private IPv4 ranges of RFC1918 * or `0.0.0.0/0`. Must not overlap with * an existing ip_range in any subnets * or with any destinations in other routes * or with `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.100.1.0/24 gateway: description: 'Gateway of the route. Packages addressed for the specified destination will be send to this IP address. Cannot be * the first IP of the networks ip_range, * an IP behind a vSwitch or * `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.0.1.1 required: - destination - gateway responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: add_route status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 4711 type: network error: code: action_failed message: Action failed 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\"net\"\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\taction, _, err := client.Network.AddRoute(ctx, &hcloud.Network{ID: 123}, hcloud.NetworkAddRouteOpts{\n\ \t\tRoute: hcloud.NetworkRoute{\n\t\t\tDestination: &net.IPNet{\n\t\t\t\tIP: net.ParseIP(\"10.100.1.0\"),\n\t\t\ \t\tMask: net.CIDRMask(24, 32),\n\t\t\t},\n\t\t\tGateway: net.ParseIP(\"10.0.1.1\"),\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network, NetworkRoute\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.networks.add_route(\n\ \ network=Network(id=123),\n route=NetworkRoute(\n destination=\"10.100.1.0/24\",\n gateway=\"\ 10.0.1.1\",\n ),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud network add-route $NETWORK \\\n --destination 10.100.1.0/24 \\\n --gateway 10.0.1.1" /networks/{id}/actions/add_subnet: post: operationId: add_network_subnet summary: Add a subnet to a Network description: 'Adds a new subnet to the [Network](#tag/networks). If the subnet `ip_range` is not provided, the first available `/24` IP range will be used. If a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned. ' tags: - Network Actions parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: AddSubnetRequest type: object properties: type: description: 'Type of subnet. ' type: string enum: - cloud - server - vswitch x-enumDescriptions: cloud: Used to connect cloud [Servers](#tag/servers) and [Load Balancers](#tag/load-balancers). server: Same as the `cloud` type. **Deprecated**, use the `cloud` type instead. vswitch: Used to [connect cloud Servers and Load Balancers with dedicated Servers](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch). ip_range: description: 'IP range of the subnet. Uses CIDR notation. Must be a subnet of the parent [Networks](#tag/networks) `ip_range`. Must not overlap with any other subnets or with any destinations in routes. Minimum network size is /30. We highly recommend that you pick a larger subnet with a /24 netmask. ' type: string example: 10.0.1.0/24 network_zone: description: 'Name of the [Network Zone](#tag/network-zones). The [Location](#tag/locations) contains the `network_zone` it belongs to. ' type: string example: eu-central vswitch_id: description: 'ID of the robot vSwitch. Must be supplied if the subnet is of type `vswitch`. ' type: integer format: int64 example: 1000 required: - type - network_zone responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: add_subnet status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 4711 type: network error: code: action_failed message: Action failed 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\"net\"\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\taction, _, err := client.Network.AddSubnet(ctx, &hcloud.Network{ID: 123}, hcloud.NetworkAddSubnetOpts{\n\ \t\tSubnet: hcloud.NetworkSubnet{\n\t\t\tIPRange: &net.IPNet{\n\t\t\t\tIP: net.ParseIP(\"10.0.1.0\"),\n\t\t\t\t\ Mask: net.CIDRMask(24, 32),\n\t\t\t},\n\t\t\tNetworkZone: hcloud.NetworkZoneEUCentral,\n\t\t\tType: hcloud.NetworkSubnetTypeCloud,\n\ \t\t\tVSwitchID: 1000,\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network, NetworkSubnet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.networks.add_subnet(\n\ \ network=Network(id=123),\n subnet=NetworkSubnet(\n ip_range=\"10.0.1.0/24\",\n network_zone=\"\ eu-central\",\n type=\"cloud\",\n vswitch_id=1000,\n ),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud network add-subnet $NETWORK \\\n --ip-range 10.0.1.0/24 \\\n --network-zone eu-central \\\n\ \ --type cloud \\\n --vswitch-id 1000" /networks/{id}/actions/change_ip_range: post: operationId: change_network_ip_range summary: Change IP range of a Network description: 'Changes the IP range of a [Network](#tag/networks). The following restrictions apply to changing the IP range: - IP ranges can only be extended and never shrunk. - IPs can only be added to the end of the existing range, therefore only the netmask is allowed to be changed. To update the routes on the connected [Servers](#tag/servers), they need to be rebooted or the routes to be updated manually. For example if the [Network](#tag/networks) has a range of `10.0.0.0/16` to extend it the new range has to start with the IP `10.0.0.0` as well. The netmask `/16` can be changed to a smaller one then `16` therefore increasing the IP range. A valid entry would be `10.0.0.0/15`, `10.0.0.0/14` or `10.0.0.0/13` and so on. If a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned. ' tags: - Network Actions parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: ChangeIPRangeRequest type: object properties: ip_range: description: 'IP range of the [Network](#tag/networks). Uses CIDR notation. Must span all included subnets. Must be one of the private IPv4 ranges of RFC1918. Minimum network size is /24. We highly recommend that you pick a larger [Network](#tag/networks) with a /16 netmask. ' type: string example: 10.0.0.0/16 required: - ip_range responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_ip_range status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: network error: code: action_failed message: Action failed 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\"net\"\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\taction, _, err := client.Network.ChangeIPRange(ctx, &hcloud.Network{ID: 123}, hcloud.NetworkChangeIPRangeOpts{\n\ \t\tIPRange: &net.IPNet{\n\t\t\tIP: net.ParseIP(\"10.0.0.0\"),\n\t\t\tMask: net.CIDRMask(16, 32),\n\t\t},\n\t\ })\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.networks.change_ip_range(\n\ \ network=Network(id=123), ip_range=\"10.0.0.0/16\"\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud network change-ip-range $NETWORK \\\n --ip-range 10.0.0.0/16" /networks/{id}/actions/change_protection: post: operationId: change_network_protection summary: Change Network Protection description: 'Changes the protection settings of a [Network](#tag/networks). If a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned. ' tags: - Network Actions parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: ChangeProtectionRequest type: object properties: delete: description: 'Delete protection setting. If true, prevents the [Network](#tag/networks) from being deleted. ' type: boolean example: true responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: network error: code: action_failed message: Action failed 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\taction, _, err := client.Network.ChangeProtection(ctx, &hcloud.Network{ID: 123},\n\t\ \thcloud.NetworkChangeProtectionOpts{Delete: hcloud.Ptr(true)})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.networks.change_protection(\n\ \ network=Network(id=123),\n delete=True,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud network enable-protection $NETWORK delete hcloud network disable-protection $NETWORK delete' /networks/{id}/actions/delete_route: post: operationId: delete_network_route summary: Delete a route from a Network description: 'Delete a route entry from a [Network](#tag/networks). If a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned. ' tags: - Network Actions parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: DeleteRouteRequest type: object properties: destination: description: 'Destination network or host of the route. Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway. Must be one of * private IPv4 ranges of RFC1918 * or `0.0.0.0/0`. Must not overlap with * an existing ip_range in any subnets * or with any destinations in other routes * or with `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.100.1.0/24 gateway: description: 'Gateway of the route. Packages addressed for the specified destination will be send to this IP address. Cannot be * the first IP of the networks ip_range, * an IP behind a vSwitch or * `172.31.1.1`. `172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers). ' type: string example: 10.0.1.1 required: - destination - gateway responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: delete_route status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 4711 type: network error: code: action_failed message: Action failed 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\"net\"\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\taction, _, err := client.Network.DeleteRoute(ctx, &hcloud.Network{ID: 123}, hcloud.NetworkDeleteRouteOpts{\n\ \t\tRoute: hcloud.NetworkRoute{\n\t\t\tDestination: &net.IPNet{\n\t\t\t\tIP: net.ParseIP(\"10.100.1.0\"),\n\t\t\ \t\tMask: net.CIDRMask(24, 32),\n\t\t\t},\n\t\t\tGateway: net.ParseIP(\"10.0.1.1\"),\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network, NetworkRoute\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.networks.delete_route(\n\ \ network=Network(id=123),\n route=NetworkRoute(\n destination=\"10.100.1.0/24\",\n gateway=\"\ 10.0.1.1\",\n ),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud network remove-route $NETWORK \\\n --destination 10.100.1.0/24 \\\n --gateway 10.0.1.1" /networks/{id}/actions/delete_subnet: post: operationId: delete_network_subnet summary: Delete a subnet from a Network description: 'Deletes a single subnet entry from a [Network](#tag/networks). Subnets containing attached resources can not be deleted, they must be detached beforehand. If a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned. ' tags: - Network Actions parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: DeleteSubnetRequest type: object properties: ip_range: description: IP range in CIDR block notation of the subnet to delete. type: string example: 10.0.1.0/24 required: - ip_range responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: delete_subnet status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 4711 type: network error: code: action_failed message: Action failed 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\"net\"\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\taction, _, err := client.Network.DeleteSubnet(ctx, &hcloud.Network{ID: 123}, hcloud.NetworkDeleteSubnetOpts{\n\ \t\tSubnet: hcloud.NetworkSubnet{\n\t\t\tIPRange: &net.IPNet{\n\t\t\t\tIP: net.ParseIP(\"10.0.1.0\"),\n\t\t\t\t\ Mask: net.CIDRMask(24, 32),\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network, NetworkSubnet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.networks.delete_subnet(\n\ \ network=Network(id=123), subnet=NetworkSubnet(ip_range=\"10.0.1.0/24\")\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud network remove-subnet $NETWORK \\\n --ip-range 10.0.1.0/24" /networks/{id}/actions/{action_id}: get: deprecated: true operationId: get_network_action summary: Get an Action for a Network description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific [Action](#tag/actions) for a [Network](#tag/networks). ' tags: - Network Actions parameters: - description: ID of the Network. name: id in: path required: true schema: description: ID of the [Network](#tag/networks). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 13 command: add_subnet status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: network error: code: action_failed message: Action failed 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: [] /placement_groups: get: operationId: list_placement_groups summary: List Placement Groups description: 'Returns all Placement Group objects. ' tags: - Placement Groups parameters: - 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 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: 'Filter resources by type. May be used multiple times. The response will only contain the resources with the specified type. ' name: type in: query required: false schema: type: array items: description: 'Type of Placement Group. ' type: string enum: - spread example: spread - 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. content: application/json: schema: title: PlacementGroupsResponse type: object properties: placement_groups: type: array items: title: PlacementGroup 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 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: - placement_groups - meta examples: default: value: placement_groups: - id: 897 name: my Placement Group labels: key: value type: spread created: '2019-01-08T12:10:00Z' servers: - 4711 - 4712 meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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\tplacementGroups, err := client.PlacementGroup.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) placement_groups = client.placement_groups.get_all()' - lang: Shell label: CLI source: hcloud placement-group list post: operationId: create_placement_group summary: Create a PlacementGroup description: 'Creates a new Placement Group. ' tags: - Placement Groups requestBody: required: true content: application/json: schema: title: CreatePlacementGroupRequest type: object properties: name: description: Name of the Placement Group. type: string example: my Placement Group 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: Define the Placement Group Type. type: string enum: - spread example: spread required: - name - type examples: default: value: name: my Placement Group type: spread responses: '201': description: Request succeeded. content: application/json: schema: title: CreatePlacementGroupResponse type: object properties: placement_group: title: PlacementGroup 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 action: title: ActionNullable 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 nullable: true required: - placement_group examples: default: value: placement_group: id: 897 name: my Placement Group labels: key: value type: spread created: '2019-01-08T12:10:00Z' servers: [] 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.PlacementGroup.Create(ctx, hcloud.PlacementGroupCreateOpts{\n\ \t\tName: \"my Placement Group\",\n\t\tType: hcloud.PlacementGroupTypeSpread,\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ result.Action)\n\n\tplacementGroup := result.PlacementGroup\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"\ HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.placement_groups.create(\n name=\"my Placement\ \ Group\",\n type=\"spread\",\n)\n\nresponse.action.wait_until_finished()\n\nplacement_group = response.placement_group" - lang: Shell label: CLI source: "hcloud placement-group create \\\n --name \"my Placement Group\" \\\n --type spread" /placement_groups/{id}: get: operationId: get_placement_group summary: Get a PlacementGroup description: 'Gets a specific Placement Group object. ' tags: - Placement Groups parameters: - description: ID of the Placement Group. name: id in: path required: true schema: description: ID of the [Placement Group](#tag/placement-groups). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: PlacementGroupResponse type: object properties: placement_group: title: PlacementGroup 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 required: - placement_group examples: default: value: placement_group: id: 897 name: my Placement Group labels: key: value type: spread created: '2019-01-08T12:10:00Z' servers: - 4711 - 4712 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\tplacementGroups, _, err := client.PlacementGroup.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) placement_group = client.placement_groups.get_by_id(123)' - lang: Shell label: CLI source: hcloud placement-group describe $PLACEMENTGROUP put: operationId: update_placement_group summary: Update a PlacementGroup description: 'Updates the Placement Group properties. Note: if the Placement Group object changes during the request, the response will be a “conflict” error. ' tags: - Placement Groups parameters: - description: ID of the Placement Group. name: id in: path required: true schema: description: ID of the [Placement Group](#tag/placement-groups). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: UpdatePlacementGroupRequest type: object properties: name: description: New Placement Group name. type: string example: my Placement Group 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: title: PlacementGroupResponse type: object properties: placement_group: title: PlacementGroup 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 required: - placement_group examples: default: value: placement_group: id: 897 name: my Placement Group labels: key: value type: spread created: '2019-01-08T12:10:00Z' servers: - 4711 - 4712 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\tplacementGroup, _, err := client.PlacementGroup.Update(ctx, &hcloud.PlacementGroup{ID:\ \ 123}, hcloud.PlacementGroupUpdateOpts{\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 Placement Group\",\n\ \t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.placement_groups\ \ import PlacementGroup\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nplacement_group =\ \ client.placement_groups.update(\n placement_group=PlacementGroup(id=123),\n labels={\n \"environment\"\ : \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"my Placement\ \ Group\",\n)" - lang: Shell label: CLI source: "hcloud placement-group update $PLACEMENTGROUP --name \"my Placement Group\"\nhcloud placement-group add-label\ \ --overwrite $PLACEMENTGROUP \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud placement-group\ \ remove-label $PLACEMENTGROUP \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_placement_group summary: Delete a PlacementGroup description: 'Deletes a Placement Group. ' tags: - Placement Groups parameters: - description: ID of the Placement Group. name: id in: path required: true schema: description: ID of the [Placement Group](#tag/placement-groups). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.PlacementGroup.Delete(ctx, &hcloud.PlacementGroup{ID: 123})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.placement_groups\ \ import PlacementGroup\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nclient.placement_groups.delete(\n\ \ placement_group=PlacementGroup(id=123),\n)" - lang: Shell label: CLI source: hcloud placement-group delete $PLACEMENTGROUP /pricing: get: operationId: get_pricing summary: Get all prices description: 'Returns prices for all resources available on the platform. VAT and currency of the Project owner are used for calculations. Both net and gross prices are included in the response. ' tags: - Pricing responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: pricing: type: object properties: currency: description: Currency the returned prices are expressed in, coded according to [ISO 4217](https://wikipedia.org/wiki/ISO_4217). type: string example: EUR vat_rate: description: VAT rate used for calculating prices with VAT. type: string format: decimal example: '19.00' primary_ips: description: Price of [Primary IPs](#tag/primary-ips) per type and per [Location](#tag/locations). type: array items: type: object properties: type: description: Type of [Primary IP](#tag/primary-ips) the price is for. type: string enum: - ipv4 - ipv6 example: ipv4 prices: description: Price of the [Primary IP](#tag/primary-ips) type 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 required: - location - price_hourly - price_monthly required: - type - prices floating_ips: description: Price of [Floating IPs](#tag/floating-ips) per type and per [Location](#tag/locations). type: array items: type: object properties: type: description: Type of [Floating IP](#tag/floating-ips) the price is for. type: string enum: - ipv4 - ipv6 example: ipv4 prices: description: Price of the [Floating IP](#tag/floating-ips) type 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_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 required: - location - price_monthly required: - type - prices image: description: Price of [Images](#tag/images). type: object properties: price_per_gb_month: description: Price of [Images](#tag/images) per GB/month. 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: - price_per_gb_month volume: description: Price of [Volumes](#tag/volumes). type: object properties: price_per_gb_month: description: Price of [Volumes](#tag/volumes) per GB/month. 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: - price_per_gb_month server_backup: description: Price of [Server](#tag/servers) backups. type: object properties: percentage: description: Price increase of the [Server](#tag/servers) base price in percentage. type: string format: decimal example: '20.00' required: - percentage server_types: description: Price of Server per [type](#tag/server-types) and per [Location](#tag/locations). type: array items: type: object properties: id: description: ID of the [Server Types](#tag/server-types) the price is for. type: integer format: int64 example: 104 name: description: Name of the [Server Types](#tag/server-types) the price is for. type: string example: cpx22 prices: description: Price of the [Server Types](#tag/server-types) 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 required: - id - name - prices load_balancer_types: description: Price of Load Balancer per [type](#tag/load-balancer-types) and per [Location](#tag/locations). type: array items: type: object properties: id: description: ID of the [Load Balancer Types](#tag/load-balancer-types) the price is for. type: integer format: int64 example: 1 name: description: Name of the [Load Balancer Types](#tag/load-balancer-types) the price is for. type: string example: lb11 prices: description: Price of the [Load Balancer Types](#tag/load-balancer-types) 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 required: - id - name - prices floating_ip: deprecated: true description: 'Price of [Floating IPs](#tag/floating-ips). **Deprecated**: This field is deprecated, please refer to the `floating_ips` field instead. See the [Changelog](https://docs.hetzner.cloud/changelog#2024-08-29-field-floating_ip-in-pricing-response-is-now-deprecated) for more details. ' type: object properties: price_monthly: description: Price of one [Floating IP](#tag/floating-ips) per month. 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: - price_monthly required: - currency - vat_rate - primary_ips - floating_ips - image - volume - server_backup - server_types - load_balancer_types - floating_ip required: - pricing 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\tpricing, _, err := client.Pricing.Get(ctx)\n}" /primary_ips: get: operationId: list_primary_ips summary: List Primary IPs description: 'List multiple [Primary IPs](#tag/primary-ips). Use the provided URI parameters to modify the result. ' tags: - Primary IPs 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: Filter results by IP address. name: ip in: query required: false schema: type: string example: 127.0.0.1 - 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 - 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 - created - created:asc - created:desc responses: '200': description: Request succeeded. content: application/json: schema: title: PrimaryIPsResponse type: object properties: primary_ips: type: array items: title: PrimaryIP type: object properties: id: description: ID of the [Primary IP](#tag/primary-ips). 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: '' 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' blocked: description: Blocked state of the [Primary IP](#tag/primary-ips). type: boolean example: false 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](#tag/data-centers) of the [Primary IP](#tag/primary-ips). ' 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](#tag/locations) of the [Primary IP](#tag/primary-ips). ' 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 ip: description: IP address. type: string example: 2001:db8::/64 dns_ptr: description: List of reverse DNS records. type: array items: type: object properties: ip: description: 'Single IPv4 or IPv6 address of the record. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. ' type: string example: server.example.com required: - ip - dns_ptr protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete type: description: '[Primary IP](#tag/primary-ips) type.' type: string enum: - ipv4 - ipv6 example: ipv6 auto_delete: description: 'Auto deletion state. If enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted. ' type: boolean default: false example: true assignee_type: description: 'Type of resource the [Primary IP](#tag/primary-ips) can get assigned to. ' type: string enum: - server example: server assignee_id: description: 'ID of resource the [Primary IP](#tag/primary-ips) is assigned to. `null` if the [Primary IP](#tag/primary-ips) is not assigned. ' type: integer format: int64 nullable: true example: 17 required: - id - name - labels - created - blocked - location - datacenter - ip - dns_ptr - protection - type - auto_delete - assignee_type - assignee_id 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: - primary_ips - 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\tprimaryIPs, err := client.PrimaryIP.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) primary_ips = client.primary_ips.get_all()' - lang: Shell label: CLI source: hcloud primary-ip list post: operationId: create_primary_ip summary: Create a Primary IP description: 'Create a new [Primary IP](#tag/primary-ips). Can optionally be assigned to a resource by providing an `assignee_id` and `assignee_type`. If not assigned to a resource the `location` key needs to be provided. This can be either the ID or the name of the [Location](#tag/locations) this [Primary IP](#tag/primary-ips) shall be created in. A [Primary IP](#tag/primary-ips) can only be assigned to resource in the same [Location](#tag/locations) later on. The `datacenter` key is deprecated in favor of `location` and will be removed after 01 July 2026. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `server_not_stopped` | The specified [Server](#tag/servers) is running, but needs to be powered off | | `422` | `server_has_ipv4` | The [Server](#tag/servers) already has an ipv4 address | | `422` | `server_has_ipv6` | The [Server](#tag/servers) already has an ipv6 address | ' tags: - Primary IPs requestBody: description: 'Request Body for creating a new [Primary IP](#tag/primary-ips). The `location`, `datacenter` and `assignee_id`/`assignee_type` attributes are mutually exclusive. ' required: true content: application/json: schema: title: PrimaryIPCreateRequest type: object properties: 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: '[Primary IP](#tag/primary-ips) type.' type: string enum: - ipv4 - ipv6 example: ipv6 datacenter: deprecated: true description: '**Deprecated**: This property is deprecated and will be removed after 1 July 2026. Use the `location` key instead. [Data Center](#tag/data-centers) ID or name. The [Primary IP](#tag/primary-ips) will be bound to this [Data Center](#tag/data-centers). Omit if `assignee_id`/`assignee_type` or `location` are provided. ' oneOf: - description: '**Deprecated**: This property is deprecated and will be removed after 1 July 2026. Use the `location` key instead. [Data Center](#tag/data-centers) ID or name. The [Primary IP](#tag/primary-ips) will be bound to this [Data Center](#tag/data-centers). Omit if `assignee_id`/`assignee_type` or `location` are provided. ' type: string example: fsn1-dc8 - description: '**Deprecated**: This property is deprecated and will be removed after 1 July 2026. Use the `location` key instead. [Data Center](#tag/data-centers) ID or name. The [Primary IP](#tag/primary-ips) will be bound to this [Data Center](#tag/data-centers). Omit if `assignee_id`/`assignee_type` or `location` are provided. ' type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 location: description: '[Location](#tag/locations) ID or name the [Primary IP](#tag/primary-ips) will be bound to. Omit if `assignee_id`/`assignee_type` or `datacenter` are provided. ' oneOf: - description: '[Location](#tag/locations) ID or name the [Primary IP](#tag/primary-ips) will be bound to. Omit if `assignee_id`/`assignee_type` or `datacenter` are provided. ' type: string example: fsn1 - description: '[Location](#tag/locations) ID or name the [Primary IP](#tag/primary-ips) will be bound to. Omit if `assignee_id`/`assignee_type` or `datacenter` are provided. ' type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 assignee_type: description: 'Type of resource the [Primary IP](#tag/primary-ips) can get assigned to. Currently [Primary IPs](#tag/primary-ips) can only be assigned to [Servers](#tag/servers), therefore this field must be set to `server`. ' type: string enum: - server example: server assignee_id: description: 'ID of resource to assign the [Primary IP](#tag/primary-ips) to. Omitted if the [Primary IP](#tag/primary-ips) should not get assigned. ' type: integer format: int64 nullable: true example: 17 auto_delete: example: false description: 'Auto deletion state. If enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted. ' type: boolean default: false required: - name - type - assignee_type responses: '201': description: Request succeeded. content: application/json: schema: title: CreatePrimaryIPResponse type: object properties: primary_ip: title: PrimaryIP type: object properties: id: description: ID of the [Primary IP](#tag/primary-ips). 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: '' 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' blocked: description: Blocked state of the [Primary IP](#tag/primary-ips). type: boolean example: false 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](#tag/data-centers) of the [Primary IP](#tag/primary-ips). ' 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](#tag/locations) of the [Primary IP](#tag/primary-ips). ' 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 ip: description: IP address. type: string example: 2001:db8::/64 dns_ptr: description: List of reverse DNS records. type: array items: type: object properties: ip: description: 'Single IPv4 or IPv6 address of the record. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. ' type: string example: server.example.com required: - ip - dns_ptr protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete type: description: '[Primary IP](#tag/primary-ips) type.' type: string enum: - ipv4 - ipv6 example: ipv6 auto_delete: description: 'Auto deletion state. If enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted. ' type: boolean default: false example: true assignee_type: description: 'Type of resource the [Primary IP](#tag/primary-ips) can get assigned to. ' type: string enum: - server example: server assignee_id: description: 'ID of resource the [Primary IP](#tag/primary-ips) is assigned to. `null` if the [Primary IP](#tag/primary-ips) is not assigned. ' type: integer format: int64 nullable: true example: 17 required: - id - name - labels - created - blocked - location - datacenter - ip - dns_ptr - protection - type - auto_delete - assignee_type - assignee_id 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 required: - primary_ip examples: default: value: primary_ip: id: 42 name: my-ip labels: key: value created: '2016-01-30T23:50:00Z' blocked: 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: 42 name: fsn1-dc8 description: Falkenstein DC Park 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 ip: 2001:db8::/64 dns_ptr: - ip: 2001:db8::1 dns_ptr: server.example.com protection: delete: false type: ipv6 auto_delete: true assignee_type: server assignee_id: 17 action: id: 13 command: assign_primary_ip status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 17 type: server error: code: action_failed message: Action failed 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.PrimaryIP.Create(ctx, hcloud.PrimaryIPCreateOpts{\n\t\tAssigneeID:\ \ hcloud.Ptr(int64(17)),\n\t\tAssigneeType: \"server\",\n\t\tAutoDelete: hcloud.Ptr(false),\n\t\tLocation: \ \ \"hel1\",\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-ip\",\n\t\tType: \"ipv4\",\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ result.Action)\n\n\tprimaryIP := result.PrimaryIP\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"\ HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.primary_ips.create(\n assignee_id=17,\n \ \ assignee_type=\"server\",\n auto_delete=False,\n location=\"hel1\",\n labels={\n \"environment\"\ : \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"my-resource\"\ ,\n type=\"ipv4\",\n)\n\nresponse.action.wait_until_finished()\n\nprimary_ip = response.primary_ip" - lang: Shell label: CLI source: "hcloud primary-ip create \\\n --assignee-id 17 \\\n --auto-delete=false \\\n --location hel1 \\\n\ \ --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\" \\\n\ \ --name my-ip \\\n --type ipv4" /primary_ips/actions: get: operationId: list_primary_ips_actions summary: List Actions description: 'Lists multiple [Actions](#tag/actions). Use the provided URI parameters to modify the result. ' tags: - Primary IP Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.PrimaryIP.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.primary_ips.actions.get_all()' /primary_ips/actions/{id}: get: operationId: get_primary_ips_action summary: Get an Action description: 'Returns a single [Action](#tag/actions). ' tags: - Primary IP Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.PrimaryIP.Action.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) action = client.primary_ips.actions.get_by_id(123)' /primary_ips/{id}/actions: get: operationId: list_primary_ip_actions summary: List Actions for a Primary IP description: 'Returns all [Actions](#tag/actions) for a [Primary IP](#tag/primary-ips). Use the provided URI parameters to modify the result. ' tags: - Primary IP Actions parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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: [] /primary_ips/{id}/actions/{action_id}: get: deprecated: true operationId: get_primary_ip_action summary: Get an Action for a Primary IP description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific [Action](#tag/actions) for a [Primary IP](#tag/primary-ips). ' tags: - Primary IP Actions parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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: [] /primary_ips/{id}: get: operationId: get_primary_ip summary: Get a Primary IP description: 'Returns a [Primary IP](#tag/primary-ips). ' tags: - Primary IPs parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: PrimaryIPResponse type: object properties: primary_ip: title: PrimaryIP type: object properties: id: description: ID of the [Primary IP](#tag/primary-ips). 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: '' 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' blocked: description: Blocked state of the [Primary IP](#tag/primary-ips). type: boolean example: false 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](#tag/data-centers) of the [Primary IP](#tag/primary-ips). ' 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](#tag/locations) of the [Primary IP](#tag/primary-ips). ' 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 ip: description: IP address. type: string example: 2001:db8::/64 dns_ptr: description: List of reverse DNS records. type: array items: type: object properties: ip: description: 'Single IPv4 or IPv6 address of the record. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. ' type: string example: server.example.com required: - ip - dns_ptr protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete type: description: '[Primary IP](#tag/primary-ips) type.' type: string enum: - ipv4 - ipv6 example: ipv6 auto_delete: description: 'Auto deletion state. If enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted. ' type: boolean default: false example: true assignee_type: description: 'Type of resource the [Primary IP](#tag/primary-ips) can get assigned to. ' type: string enum: - server example: server assignee_id: description: 'ID of resource the [Primary IP](#tag/primary-ips) is assigned to. `null` if the [Primary IP](#tag/primary-ips) is not assigned. ' type: integer format: int64 nullable: true example: 17 required: - id - name - labels - created - blocked - location - datacenter - ip - dns_ptr - protection - type - auto_delete - assignee_type - assignee_id required: - primary_ip 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\tprimaryIP, _, err := client.PrimaryIP.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) primary_ip = client.primary_ips.get_by_id(123)' - lang: Shell label: CLI source: hcloud primary-ip describe $PRIMARYIP put: operationId: update_primary_ip summary: Update a Primary IP description: 'Update a [Primary IP](#tag/primary-ips). If another change is concurrently performed on this [Primary IP](#tag/primary-ips), a error response with code `conflict` will be returned. ' tags: - Primary IPs parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: PrimaryIPUpdateRequest type: object properties: 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. 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: '' auto_delete: description: 'Auto deletion state. If enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted. ' type: boolean default: false example: true responses: '200': description: Request succeeded. content: application/json: schema: title: PrimaryIPResponse type: object properties: primary_ip: title: PrimaryIP type: object properties: id: description: ID of the [Primary IP](#tag/primary-ips). 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: '' 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' blocked: description: Blocked state of the [Primary IP](#tag/primary-ips). type: boolean example: false 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](#tag/data-centers) of the [Primary IP](#tag/primary-ips). ' 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](#tag/locations) of the [Primary IP](#tag/primary-ips). ' 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 ip: description: IP address. type: string example: 2001:db8::/64 dns_ptr: description: List of reverse DNS records. type: array items: type: object properties: ip: description: 'Single IPv4 or IPv6 address of the record. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. ' type: string example: server.example.com required: - ip - dns_ptr protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete type: description: '[Primary IP](#tag/primary-ips) type.' type: string enum: - ipv4 - ipv6 example: ipv6 auto_delete: description: 'Auto deletion state. If enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted. ' type: boolean default: false example: true assignee_type: description: 'Type of resource the [Primary IP](#tag/primary-ips) can get assigned to. ' type: string enum: - server example: server assignee_id: description: 'ID of resource the [Primary IP](#tag/primary-ips) is assigned to. `null` if the [Primary IP](#tag/primary-ips) is not assigned. ' type: integer format: int64 nullable: true example: 17 required: - id - name - labels - created - blocked - location - datacenter - ip - dns_ptr - protection - type - auto_delete - assignee_type - assignee_id required: - primary_ip 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\tprimaryIP, _, err := client.PrimaryIP.Update(ctx, &hcloud.PrimaryIP{ID: 123}, hcloud.PrimaryIPUpdateOpts{\n\ \t\tAutoDelete: hcloud.Ptr(true),\n\t\tLabels: hcloud.Ptr(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-ip\",\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.primary_ips\ \ import PrimaryIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nprimary_ip = client.primary_ips.update(\n\ \ primary_ip=PrimaryIP(id=123),\n auto_delete=True,\n labels={\n \"environment\": \"prod\",\n \ \ \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"my-resource\",\n)" - lang: Shell label: CLI source: "hcloud primary-ip update $PRIMARYIP \\\n --auto-delete=false \\\n --name \"new-name\"\nhcloud primary-ip\ \ add-label --overwrite $PRIMARYIP \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud\ \ primary-ip remove-label $PRIMARYIP \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_primary_ip summary: Delete a Primary IP description: 'Deletes a [Primary IP](#tag/primary-ips). The [Server](#tag/servers) must be powered off (status `off`) in order for this operation to succeed. If assigned to a [Server](#tag/servers) the [Primary IP](#tag/primary-ips) will be unassigned automatically until 1 May 2026. After this date, the [Primary IP](#tag/primary-ips) needs to be unassigned before it can be deleted. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `must_be_unassigned` | Error when IP is still assigned to a Resource. This error will appear as of 1 May 2026. | ' tags: - Primary IPs parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.PrimaryIP.Delete(ctx, &hcloud.PrimaryIP{ID: 123})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.primary_ips\ \ import PrimaryIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nclient.primary_ips.delete(\n\ \ primary_ip=PrimaryIP(id=123),\n)" - lang: Shell label: CLI source: hcloud primary-ip delete $PRIMARYIP /primary_ips/{id}/actions/assign: post: operationId: assign_primary_ip summary: Assign a Primary IP to a resource description: 'Assign a [Primary IP](#tag/primary-ips) to a resource. A [Server](#tag/servers) can only have one [Primary IP](#tag/primary-ips) of type `ipv4` and one of type `ipv6` assigned. If you need more IPs use [Floating IPs](#tag/floating-ips). A [Server](#tag/servers) must be powered off (status `off`) in order for this operation to succeed. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `server_not_stopped` | The [Server](#tag/servers) is running, but needs to be powered off | | `422` | `primary_ip_already_assigned` | [Primary IP](#tag/primary-ips) is already assigned to a different [Server](#tag/servers) | | `422` | `server_has_ipv4` | The [Server](#tag/servers) already has an IPv4 address | | `422` | `server_has_ipv6` | The [Server](#tag/servers) already has an IPv6 address | ' tags: - Primary IP Actions parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: PrimaryIPActionsAssignRequest type: object properties: assignee_type: description: Type of resource assigning the Primary IP to. type: string enum: - server example: server assignee_id: description: ID of a resource of type `assignee_type`. type: integer format: int64 example: 4711 required: - assignee_type - assignee_id responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: assign_primary_ip status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 4711 type: primary_ip error: code: action_failed message: Action failed 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\taction, _, err := client.PrimaryIP.Assign(ctx, hcloud.PrimaryIPAssignOpts{\n\t\tID:\ \ 123,\n\t\tAssigneeID: 4711,\n\t\tAssigneeType: \"server\",\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.primary_ips\ \ import PrimaryIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.primary_ips.assign(\n\ \ primary_ip=PrimaryIP(id=123),\n assignee_id=4711,\n assignee_type=\"server\",\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud primary-ip assign --server 4711 $PRIMARYIP /primary_ips/{id}/actions/change_dns_ptr: post: operationId: change_primary_ip_dns_ptr summary: Change reverse DNS records for a Primary IP description: 'Change the reverse DNS records for this [Primary IP](#tag/primary-ips). Allows to modify the PTR records set for the IP address. ' tags: - Primary IP Actions parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: description: 'The `ip` attributes specifies for which IP address the record is set. For IPv4 addresses this must be the exact address of the [Primary IP](#tag/primary-ips). For IPv6 addresses this must be a single address within the `/64` subnet of the [Primary IP](#tag/primary-ips). The `dns_ptr` attribute specifies the hostname used for the IP address. Must be a fully qualified domain name (FQDN) without trailing dot. For IPv6 [Primary IPs](#tag/primary-ips) up to 100 entries can be created. ' required: true content: application/json: schema: type: object properties: ip: description: 'Single IPv4 or IPv6 address to create pointer for. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. Set to null to reset (IPv4) to the default value or remove (IPv6) the record. ' type: string nullable: true example: server.example.com required: - ip responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_dns_ptr status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: primary_ip error: code: action_failed message: Action failed 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\taction, _, err := client.PrimaryIP.ChangeDNSPtr(ctx, hcloud.PrimaryIPChangeDNSPtrOpts{\n\ \t\tID: 123,\n\t\tDNSPtr: \"server02.example.com\",\n\t\tIP: \"1.2.3.4\",\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.primary_ips\ \ import PrimaryIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.primary_ips.change_dns_ptr(\n\ \ primary_ip=PrimaryIP(id=123),\n dns_ptr=\"server.example.com\",\n ip=\"2001:db8::1\",\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud primary-ip set-rdns $PRIMARYIP \\\n --ip 1.2.3.4 \\\n --hostname server02.example.com" /primary_ips/{id}/actions/change_protection: post: operationId: change_primary_ip_protection summary: Change Primary IP Protection description: 'Changes the protection configuration of a [Primary IP](#tag/primary-ips). A [Primary IPs](#tag/primary-ips) deletion protection can only be enabled if its `auto_delete` property is set to `false`. ' tags: - Primary IP Actions parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 4711 type: primary_ip error: code: action_failed message: Action failed 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\taction, _, err := client.PrimaryIP.ChangeProtection(ctx, hcloud.PrimaryIPChangeProtectionOpts{\n\ \t\tID: 123,\n\t\tDelete: true,\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.primary_ips\ \ import PrimaryIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.primary_ips.change_protection(\n\ \ primary_ip=PrimaryIP(id=123),\n delete=False,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud primary-ip enable-protection $PRIMARYIP delete hcloud primary-ip disable-protection $PRIMARYIP delete' /primary_ips/{id}/actions/unassign: post: operationId: unassign_primary_ip summary: Unassign a Primary IP from a resource description: 'Unassign a [Primary IP](#tag/primary-ips) from a resource. A [Server](#tag/servers) must be powered off (status `off`) in order for this operation to succeed. A [Server](#tag/servers) requires at least one network interface (public or private) to be powered on. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `server_not_stopped` | The [Server](#tag/servers) is running, but needs to be powered off | | `422` | `server_is_load_balancer_target` | The [Server](#tag/servers) IPv4 address is a loadbalancer target | ' tags: - Primary IP Actions parameters: - description: ID of the Primary IP. name: id in: path required: true schema: description: ID of the [Primary IP](#tag/primary-ips). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: unassign_primary_ip status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 4711 type: primary_ip error: code: action_failed message: Action failed 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\taction, _, err := client.PrimaryIP.Unassign(ctx, 123)\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.primary_ips\ \ import PrimaryIP\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.primary_ips.unassign(\n\ \ primary_ip=PrimaryIP(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud primary-ip unassign $PRIMARYIP /server_types: get: operationId: list_server_types summary: List Server Types description: 'Gets all Server type objects. ' tags: - Server Types 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: 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. content: application/json: schema: type: object properties: server_types: type: array items: 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 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: - server_types - 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\tserverTypes, err := client.ServerType.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) server_types = client.server_types.get_all()' - lang: Shell label: CLI source: hcloud server-type list /server_types/{id}: get: operationId: get_server_type summary: Get a Server Type description: 'Gets a specific Server type object. ' tags: - Server Types parameters: - description: ID of the Server Type. name: id in: path required: true schema: description: ID of the [Server Type](#tag/server-types). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: 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 required: - server_type 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\tserverType, _, err := client.ServerType.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_type = client.server_types.get_by_id(123)' - lang: Shell label: CLI source: hcloud server-type describe $SERVERTYPE /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\n\ from 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/actions: get: operationId: list_servers_actions summary: List Actions description: 'Returns all Action objects. You can `sort` the results by using the sort URI parameter, and filter them with the `status` and `id` parameter. ' tags: - Server Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.Server.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.servers.actions.get_all()' /servers/actions/{id}: get: operationId: get_servers_action summary: Get an Action description: 'Returns a specific Action object. ' tags: - Server Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.Server.Action.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) action = client.servers.actions.get_by_id(123)' /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\t\ err = 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}/actions: get: operationId: list_server_actions summary: List Actions for a Server description: 'Returns all Action objects for a Server. You can `sort` the results by using the sort URI parameter, and filter them with the `status` parameter. ' tags: - Server Actions 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: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - meta examples: default: value: actions: - id: 13 command: start_server status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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: [] /servers/{id}/actions/add_to_placement_group: post: operationId: add_server_to_placement_group summary: Add a Server to a Placement Group description: 'Adds a Server to a Placement Group. Server must be powered off for this command to succeed. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `server_not_stopped` | The action requires a stopped server | | `422` | `already_in_placement_group` | The server is already part of a placement group | ' tags: - Server Actions 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: AddToPlacementGroupRequest type: object properties: placement_group: description: ID of Placement Group the Server should be added to. type: integer format: int64 example: 1 required: - placement_group responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: add_to_placement_group status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.AddToPlacementGroup(ctx, &hcloud.Server{ID: 123}, &hcloud.PlacementGroup{ID:\ \ 1})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.placement_groups\ \ import PlacementGroup\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.servers.add_to_placement_group(\n server=Server(id=123), placement_group=PlacementGroup(id=1)\n\ )\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server add-to-placement-group --placement-group 1 $SERVER /servers/{id}/actions/attach_iso: post: operationId: attach_server_iso summary: Attach an ISO to a Server description: 'Attaches an ISO to a Server. The Server will immediately see it as a new disk. An already attached ISO will automatically be detached before the new ISO is attached. Servers with attached ISOs have a modified boot order: They will try to boot from the ISO first before falling back to hard disk. ' tags: - Server Actions 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: type: object properties: iso: description: ID or name of ISO to attach to the Server as listed in GET `/isos`. type: string example: FreeBSD-11.0-RELEASE-amd64-dvd1 required: - iso responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: attach_iso status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.AttachISO(ctx, &hcloud.Server{ID: 123}, &hcloud.ISO{\n\ \t\tName: \"FreeBSD-11.0-RELEASE-amd64-dvd1\",\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.isos\ \ import Iso\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.servers.attach_iso(\n server=Server(id=123), iso=Iso(name=\"FreeBSD-11.0-RELEASE-amd64-dvd1\"\ )\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server attach-iso $SERVER "FreeBSD-11.0-RELEASE-amd64-dvd1" /servers/{id}/actions/attach_to_network: post: operationId: attach_server_to_network summary: Attach a Server to a Network description: 'Attaches a Server to a network. This will complement the fixed public Server interface by adding an additional ethernet interface to the Server which is connected to the specified network. The Server will get an IP auto assigned from a subnet of type `server` in the same `network_zone`. Using the `alias_ips` attribute you can also define one or more additional IPs to the Servers. Please note that you will have to configure these IPs by hand on your Server since only the primary IP will be given out by DHCP. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `server_already_attached` | The server is already attached to the network | | `422` | `ip_not_available` | The provided Network IP is not available | | `422` | `no_subnet_available` | No Subnet or IP is available for the Server within the network | | `422` | `networks_overlap` | The network IP range overlaps with one of the server networks | ' tags: - Server Actions 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: AttachToNetworkRequest type: object properties: network: description: ID of an existing network to attach the Server to. type: integer format: int64 example: 4711 ip: description: IP to request to be assigned to this Server; if you do not provide this then you will be auto assigned an IP address. type: string example: 10.0.1.1 alias_ips: description: Additional IPs to be assigned to this Server. type: array items: type: string example: - 10.0.1.2 ip_range: description: 'IP range in CIDR block notation of the subnet to attach to. This allows for auto assigning an IP address for a specific subnet. Providing `ip` that is not part of `ip_range` will result in an error. ' type: string example: 10.0.1.0/24 required: - network responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: attach_to_network status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 4711 type: network error: code: action_failed message: Action failed 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\"net\"\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\taction, _, err := client.Server.AttachToNetwork(ctx, &hcloud.Server{ID: 123}, hcloud.ServerAttachToNetworkOpts{\n\ \t\tAliasIPs: []net.IP{\n\t\t\tnet.ParseIP(\"10.0.1.2\"),\n\t\t},\n\t\tIP: net.ParseIP(\"10.0.1.1\"),\n\t\tNetwork:\ \ &hcloud.Network{\n\t\t\tID: 4711,\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.servers.attach_to_network(\n server=Server(id=123),\n alias_ips=[\"10.0.1.2\"],\n ip=\"\ 10.0.1.1\",\n network=Network(id=4711),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud server attach-to-network $SERVER \\\n --alias-ips 10.0.1.2 \\\n --ip 10.0.1.1 \\\n --network\ \ 4711" /servers/{id}/actions/change_alias_ips: post: operationId: change_server_alias_ips summary: Change alias IPs of a Network description: 'Changes the alias IPs of an already attached Network. Note that the existing aliases for the specified Network will be replaced with these provided in the request body. So if you want to add an alias IP, you have to provide the existing ones from the Network plus the new alias IP in the request body. ' tags: - Server Actions 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: type: object properties: network: description: ID of an existing Network already attached to the Server. type: integer format: int64 example: 4711 alias_ips: description: New alias IPs to set for this Server. type: array items: type: string example: - 10.0.1.2 required: - network - alias_ips responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_alias_ips status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 4711 type: network error: code: action_failed message: Action failed 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\"net\"\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\taction, _, err := client.Server.ChangeAliasIPs(ctx, &hcloud.Server{ID: 123}, hcloud.ServerChangeAliasIPsOpts{\n\ \t\tAliasIPs: []net.IP{\n\t\t\tnet.ParseIP(\"10.0.1.2\"),\n\t\t},\n\t\tNetwork: &hcloud.Network{\n\t\t\tID: 4711,\n\ \t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.servers.change_alias_ips(\n server=Server(id=123),\n alias_ips=[\"10.0.1.2\"],\n network=Network(id=4711),\n\ )\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud server change-alias-ips $SERVER \\\n --alias-ips 10.0.1.2 \\\n --network 4711" /servers/{id}/actions/change_dns_ptr: post: operationId: change_server_dns_ptr summary: Change reverse DNS entry for this Server description: 'Changes the hostname that will appear when getting the hostname belonging to the primary IPs (IPv4 and IPv6) of this Server. Floating IPs assigned to the Server are not affected by this. ' tags: - Server Actions 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: description: Select the IP address for which to change the DNS entry by passing `ip`. It can be either IPv4 or IPv6. The target hostname is set by passing `dns_ptr`, which must be a fully qualified domain name (FQDN) without trailing dot. required: true content: application/json: schema: type: object properties: ip: description: 'Single IPv4 or IPv6 address to create pointer for. ' type: string example: 2001:db8::1 dns_ptr: description: 'Domain Name to point to. PTR record content used for reverse DNS. Set to null to reset (IPv4) to the default value or remove (IPv6) the record. ' type: string nullable: true example: server.example.com required: - ip responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_dns_ptr status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.ChangeDNSPtr(ctx, &hcloud.Server{ID: 123}, \"1.2.3.4\"\ , hcloud.Ptr(\"server01.example.com\"))\n\n\terr = client.Action.WaitFor(ctx, 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.change_dns_ptr(\n\ \ server=Server(id=123), dns_ptr=\"server01.example.com\", ip=\"1.2.3.4\"\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud server set-rdns $SERVER \\\n --ip 1.2.3.4 \\\n --hostname server01.example.com" /servers/{id}/actions/change_protection: post: operationId: change_server_protection summary: Change Server Protection description: 'Changes the protection configuration of the Server. ' tags: - Server Actions 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: type: object properties: delete: description: If true, prevents the Server from being deleted (currently delete and rebuild attribute needs to have the same value). type: boolean example: true rebuild: description: If true, prevents the Server from being rebuilt (currently delete and rebuild attribute needs to have the same value). type: boolean example: true responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.ChangeProtection(ctx, &hcloud.Server{ID: 123}, hcloud.ServerChangeProtectionOpts{\n\ \t\tDelete: hcloud.Ptr(true),\n\t\tRebuild: hcloud.Ptr(true),\n\t})\n\n\terr = client.Action.WaitFor(ctx, 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.change_dns_ptr(\n\ \ server=Server(id=123), dns_ptr=\"server01.example.com\", ip=\"1.2.3.4\"\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud server enable-protection $SERVER delete rebuild hcloud server disable-protection $SERVER delete rebuild' /servers/{id}/actions/change_type: post: operationId: change_server_type summary: Change the Type of a Server description: 'Changes the type (Cores, RAM and disk sizes) of a Server. Server must be powered off for this command to succeed. This copies the content of its disk, and starts it again. You can only migrate to Server types with the same `storage_type` and equal or bigger disks. Shrinking disks is not possible as it might destroy data. If the disk gets upgraded, the Server type can not be downgraded any more. If you plan to downgrade the Server type, set `upgrade_disk` to `false`. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `invalid_server_type` | The server type does not fit for the given server or is deprecated | | `422` | `server_not_stopped` | The action requires a stopped server | ' tags: - Server Actions 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: type: object properties: upgrade_disk: description: If false, do not upgrade the disk (this allows downgrading the Server type later). type: boolean example: true server_type: description: ID or name of Server type the Server should migrate to. type: string example: cpx22 required: - upgrade_disk - server_type responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_server_type status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.ChangeType(ctx, &hcloud.Server{ID: 123}, hcloud.ServerChangeTypeOpts{\n\ \t\tServerType: &hcloud.ServerType{Name: \"cpx22\"},\n\t\tUpgradeDisk: true,\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.server_types\ \ import ServerType\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.servers.change_type(\n server=Server(id=123),\n server_type=ServerType(name=\"cpx22\"),\n\ \ upgrade_disk=True,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server change-type --keep-disk $SERVER cpx32 /servers/{id}/actions/create_image: post: operationId: create_server_image summary: Create Image from a Server description: 'Creates an Image (snapshot) from a Server by copying the contents of its disks. This creates a snapshot of the current state of the disk and copies it into an Image. If the Server is currently running you must make sure that its disk content is consistent. Otherwise, the created Image may not be readable. To make sure disk content is consistent, we recommend to shut down the Server prior to creating an Image. You can either create a `backup` Image that is bound to the Server and therefore will be deleted when the Server is deleted, or you can create a `snapshot` Image which is completely independent of the Server it was created from and will survive Server deletion. Backup Images are only available when the backup option is enabled for the Server. Snapshot Images are billed on a per GB basis. ' tags: - Server Actions 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: CreateImageRequest type: object properties: description: description: Description of the Image, will be auto-generated if not set. type: string example: my image type: description: Type of Image to create. type: string enum: - snapshot - backup default: snapshot example: snapshot 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: '' responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: image: 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 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 examples: default: value: image: id: 4711 type: snapshot status: creating name: null description: my image 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: '20.04' rapid_deploy: false protection: delete: false deprecated: '2018-02-28T00:00:00Z' deleted: null labels: key: value architecture: x86 action: id: 13 command: create_image status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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.CreateImage(ctx, &hcloud.Server{ID: 123}, &hcloud.ServerCreateImageOpts{\n\ \t\tDescription: hcloud.Ptr(\"my image\"),\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\tType: hcloud.ImageTypeSnapshot,\n\ \t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\timage := result.Image\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.create_image(\n\ \ server=Server(id=123),\n description=\"my image\",\n labels={\n \"environment\": \"prod\",\n \ \ \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n type=\"snapshot\",\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud server create-image $SERVER \\\n --description \"my image\" \\\n --label \"environment=prod\"\ \ \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\" \\\n --type snapshot" /servers/{id}/actions/detach_from_network: post: operationId: detach_server_from_network summary: Detach a Server from a Network description: 'Detaches a Server from a network. The interface for this network will vanish. ' tags: - Server Actions 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: DetachFromNetworkRequest type: object properties: network: description: ID of an existing network to detach the Server from. type: integer format: int64 example: 4711 required: - network responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: detach_from_network status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 4711 type: network error: code: action_failed message: Action failed 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\taction, _, err := client.Server.DetachFromNetwork(ctx, &hcloud.Server{ID: 123}, hcloud.ServerDetachFromNetworkOpts{\n\ \t\tNetwork: &hcloud.Network{ID: 4711},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.networks\ \ import Network\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.servers.detach_from_network(\n server=Server(id=123), network=Network(id=4711)\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server detach-from-network --network 4711 $SERVER /servers/{id}/actions/detach_iso: post: operationId: detach_server_iso summary: Detach an ISO from a Server description: 'Detaches an ISO from a Server. In case no ISO Image is attached to the Server, the status of the returned Action is immediately set to `success`. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: detach_iso status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.DetachISO(ctx, &hcloud.Server{ID: 123})\n\n\terr =\ \ client.Action.WaitFor(ctx, 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.detach_iso(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server detach-iso $SERVER /servers/{id}/actions/disable_backup: post: operationId: disable_server_backup summary: Disable Backups for a Server description: 'Disables the automatic backup option and deletes all existing Backups for a Server. No more additional charges for backups will be made. Caution: This immediately removes all existing backups for the Server! ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: disable_backup status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.DisableBackup(ctx, &hcloud.Server{ID: 123})\n\n\terr\ \ = client.Action.WaitFor(ctx, 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.disable_backup(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server disable-backup $SERVER /servers/{id}/actions/disable_rescue: post: operationId: disable_server_rescue summary: Disable Rescue Mode for a Server description: 'Disables the Hetzner Rescue System for a Server. This makes a Server start from its disks on next reboot. Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes. Disabling rescue mode will not reboot your Server — you will have to do this yourself. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: disable_rescue status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.DisableRescue(ctx, &hcloud.Server{ID: 123})\n\n\terr\ \ = client.Action.WaitFor(ctx, 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.disable_rescue(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server disable-rescue $SERVER /servers/{id}/actions/enable_backup: post: operationId: enable_server_backup summary: Enable and Configure Backups for a Server description: 'Enables and configures the automatic daily backup option for the Server. Enabling automatic backups will increase the price of the Server by 20%. In return, you will get seven slots where Images of type backup can be stored. Backups are automatically created daily. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: enable_backup status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.EnableBackup(ctx, &hcloud.Server{ID: 123}, \"\")\n\n\ \terr = client.Action.WaitFor(ctx, 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.enable_backup(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server enable-backup $SERVER /servers/{id}/actions/enable_rescue: post: operationId: enable_server_rescue summary: Enable Rescue Mode for a Server description: 'Enable the Hetzner Rescue System for this Server. The next time a Server with enabled rescue mode boots it will start a special minimal Linux distribution designed for repair and reinstall. In case a Server cannot boot on its own you can use this to access a Server’s disks. Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes. Enabling rescue mode will not [reboot](https://docs.hetzner.cloud/#server-actions-soft-reboot-a-server) your Server — you will have to do this yourself. ' tags: - Server Actions 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: type: object properties: type: description: Type of rescue system to boot. type: string enum: - linux64 default: linux64 ssh_keys: description: Array of SSH key IDs which should be injected into the rescue system. type: array items: type: integer format: int64 example: - 2323 responses: '201': description: Request succeeded. content: application/json: schema: description: 'The `root_password` key in the reply contains the root password that can be used to access the booted rescue system. ' type: object properties: root_password: description: Password that will be set for this Server once the Action succeeds. type: string example: zCWbFhnu950dUTko5f40 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 examples: default: value: root_password: zCWbFhnu950dUTko5f40 action: id: 13 command: enable_rescue status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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.EnableRescue(ctx, &hcloud.Server{ID: 123}, hcloud.ServerEnableRescueOpts{\n\ \t\tSSHKeys: []*hcloud.SSHKey{{\n\t\t\tID: 2323,\n\t\t}},\n\t\tType: hcloud.ServerRescueTypeLinux64,\n\t})\n\n\t\ err = client.Action.WaitFor(ctx, result.Action)\n\n\trootPassword := result.RootPassword\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\nfrom hcloud.ssh_keys import SSHKey\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.servers.enable_rescue(\n server=Server(id=123),\n ssh_keys=[SSHKey(id=2323)],\n type=\"\ linux64\",\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server enable-rescue $SERVER /servers/{id}/actions/poweroff: post: operationId: poweroff_server summary: Power off a Server description: 'Cuts power to the Server. This forcefully stops it without giving the Server operating system time to gracefully stop. May lead to data loss, equivalent to pulling the power cord. Power off should only be used when shutdown does not work. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: stop_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 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\taction, _, err := client.Server.Poweroff(ctx, &hcloud.Server{ID: 123})\n\n\terr = client.Action.WaitFor(ctx,\ \ 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.power_off(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server poweroff $SERVER /servers/{id}/actions/poweron: post: operationId: poweron_server summary: Power on a Server description: 'Starts a Server by turning its power on. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: 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 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\taction, _, err := client.Server.Poweron(ctx, &hcloud.Server{ID: 123})\n\n\terr = client.Action.WaitFor(ctx,\ \ 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.power_on(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server poweron $SERVER /servers/{id}/actions/reboot: post: operationId: reboot_server summary: Soft-reboot a Server description: 'Reboots a Server gracefully by sending an ACPI request. The Server operating system must support ACPI and react to the request, otherwise the Server will not reboot. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: reboot_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 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\taction, _, err := client.Server.Reboot(ctx, &hcloud.Server{ID: 123})\n\n\terr = client.Action.WaitFor(ctx,\ \ 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.reboot(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server reboot $SERVER /servers/{id}/actions/rebuild: post: operationId: rebuild_server summary: Rebuild a Server from an Image description: 'Rebuilds a Server overwriting its disk with the content of an Image, thereby **destroying all data** on the target Server The Image can either be one you have created earlier (`backup` or `snapshot` Image) or it can be a completely fresh `system` Image provided by us. You can get a list of all available Images with `GET /images`. Your Server will automatically be powered off before the rebuild command executes. ' tags: - Server Actions 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: description: To select which Image to rebuild from you can either pass an ID or a name as the `image` argument. Passing a name only works for `system` Images since the other Image types do not have a name set. required: true content: application/json: schema: title: RebuildServerRequest type: object properties: image: description: ID or name of Image to rebuilt from. type: string example: ubuntu-24.04 user_data: description: Cloud-Init user data to use during Server rebuild. This field is limited to 32KiB. If not specified, the Server's previous user_data value will be re-used (if any was set). type: string example: '#cloud-config runcmd: - [touch, /root/cloud-init-worked] ' required: - image responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: root_password: description: New root password when not using SSH keys. type: string nullable: true 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 examples: default: value: action: id: 13 command: rebuild_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: null 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.RebuildWithResult(ctx, &hcloud.Server{ID: 123}, hcloud.ServerRebuildOpts{\n\ \t\tImage: &hcloud.Image{Name: \"ubuntu-24.04\"},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\ \trootPassword := result.RootPassword\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.images import Image from hcloud.servers import Server token = environ["HCLOUD_TOKEN"] client = Client(token=token) action = client.servers.rebuild(server=Server(id=123), image=Image(name="ubuntu-24.04")) action.wait_until_finished()' - lang: Shell label: CLI source: hcloud server rebuild --image ubuntu-24.04 $SERVER /servers/{id}/actions/remove_from_placement_group: post: operationId: remove_server_from_placement_group summary: Remove from Placement Group description: 'Removes a Server from a Placement Group. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: remove_from_placement_group status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Server.RemoveFromPlacementGroup(ctx, &hcloud.Server{ID: 123})\n\ \n\terr = client.Action.WaitFor(ctx, 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.remove_from_placement_group(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server remove-from-placement-group $SERVER /servers/{id}/actions/request_console: post: operationId: request_server_console summary: Request Console for a Server description: 'Requests credentials for remote access via VNC over websocket to keyboard, monitor, and mouse for a Server. The provided URL is valid for 1 minute, after this period a new url needs to be created to connect to the Server. How long the connection is open after the initial connect is not subject to this timeout. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: type: object properties: wss_url: description: URL of websocket proxy to use; this includes a token which is valid for a limited time only. type: string example: wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c password: description: VNC password to use for this connection (this password only works in combination with a wss_url with valid token). type: string example: 9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x 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 required: - wss_url - password - action examples: default: value: wss_url: wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c password: 9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x action: id: 13 command: request_console status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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.RequestConsole(ctx, &hcloud.Server{ID: 123})\n\n\t\ err = client.Action.WaitFor(ctx, result.Action)\n\n\twssUrl, password := result.WSSURL, result.Password\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\nresponse = client.servers.request_console(\n\ \ server=Server(id=123),\n)\n\nresponse.action.wait_until_finished()\n\nwss_url, password = response.wss_url,\ \ response.password" - lang: Shell label: CLI source: hcloud server request-console $SERVER /servers/{id}/actions/reset: post: operationId: reset_server summary: Reset a Server description: 'Cuts power to a Server and starts it again. This forcefully stops it without giving the Server operating system time to gracefully stop. This may lead to data loss, it’s equivalent to pulling the power cord and plugging it in again. Reset should only be used when reboot does not work. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: reset_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 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\taction, _, err := client.Server.Reset(ctx, &hcloud.Server{ID: 123})\n\n\terr = client.Action.WaitFor(ctx,\ \ 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.reset(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server reset $SERVER /servers/{id}/actions/reset_password: post: operationId: reset_server_password summary: Reset root Password of a Server description: 'Resets the root password. Only works for Linux systems that are running the qemu guest agent. Server must be powered on (status `running`) in order for this operation to succeed. This will generate a new password for this Server and return it. If this does not succeed you can use the rescue system to netboot the Server and manually change your Server password by hand. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: description: 'The `root_password` key in the reply contains the new root password that will be active if the Action succeeds. ' type: object properties: root_password: description: Password that will be set for this Server once the Action succeeds. type: string example: zCWbFhnu950dUTko5f40 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 examples: default: value: root_password: zCWbFhnu950dUTko5f40 action: id: 13 command: reset_password status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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.ResetPassword(ctx, &hcloud.Server{ID: 123})\n\n\terr\ \ = client.Action.WaitFor(ctx, result.Action)\n\n\trootPassword := result.RootPassword\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\nresponse = client.servers.reset_password(\n\ \ server=Server(id=123),\n)\n\nresponse.action.wait_until_finished()\n\nroot_password = response.root_password" - lang: Shell label: CLI source: hcloud server reset-password $SERVER /servers/{id}/actions/shutdown: post: operationId: shutdown_server summary: Shutdown a Server description: 'Shuts down a Server gracefully by sending an ACPI shutdown request. The Server operating system must support ACPI and react to the request, otherwise the Server will not shut down. Please note that the `action` status in this case only reflects whether the action was sent to the server. It does not mean that the server actually shut down successfully. If you need to ensure that the server is off, use the `poweroff` action. ' tags: - Server Actions 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: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: shutdown_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 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\taction, _, err := client.Server.Shutdown(ctx, &hcloud.Server{ID: 123})\n\n\terr = client.Action.WaitFor(ctx,\ \ 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.shutdown(\n\ \ server=Server(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud server shutdown $SERVER /servers/{id}/actions/{action_id}: get: deprecated: true operationId: get_server_action summary: Get an Action for a Server description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific Action object for a Server. ' tags: - Server Actions 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: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 13 command: start_server status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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: [] /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\n\ from 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" /ssh_keys: get: operationId: list_ssh_keys summary: List SSH keys description: 'Returns all SSH key objects. ' tags: - SSH Keys parameters: - 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 - 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: May be used to filter SSH keys by their fingerprint. The response will only contain the SSH key matching the specified fingerprint. name: fingerprint 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: 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. content: application/json: schema: type: object properties: ssh_keys: type: array items: type: object properties: id: description: ID of the [SSH Key](#tag/ssh-keys). 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 fingerprint: description: MD5 fingerprint of the SSH public key. type: string example: b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f public_key: description: Public key. type: string example: ssh-rsa AAAjjk76kgf...Xt 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: '' 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' required: - id - name - fingerprint - public_key - labels - created 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: - ssh_keys - 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\tsshKeys, err := client.SSHKey.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) ssh_keys = client.ssh_keys.get_all()' - lang: Shell label: CLI source: hcloud ssh-key list post: operationId: create_ssh_key summary: Create an SSH key description: 'Creates a new SSH key with the given `name` and `public_key`. Once an SSH key is created, it can be used in other calls such as creating Servers. ' tags: - SSH Keys requestBody: required: true content: application/json: schema: type: object properties: name: description: Name of the SSH key. type: string example: My ssh key public_key: description: Public key. type: string example: ssh-rsa AAAjjk76kgf...Xt 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: '' required: - name - public_key responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: ssh_key: type: object properties: id: description: ID of the [SSH Key](#tag/ssh-keys). 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 fingerprint: description: MD5 fingerprint of the SSH public key. type: string example: b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f public_key: description: Public key. type: string example: ssh-rsa AAAjjk76kgf...Xt 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: '' 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' required: - id - name - fingerprint - public_key - labels - created required: - ssh_key 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\tsshKey, _, err := client.SSHKey.Create(ctx, hcloud.SSHKeyCreateOpts{\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 ssh key\",\n\t\tPublicKey: \"ssh-rsa AAAjjk76kgf...Xt\",\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"\ HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nssh_key = client.ssh_keys.create(\n labels={\n \"environment\"\ : \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"My ssh key\"\ ,\n public_key=\"ssh-rsa AAAjjk76kgf...Xt\",\n)" - lang: Shell label: CLI source: "hcloud ssh-key create \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n\ \ --label \"just-a-key=\" \\\n --name \"My ssh key\" \\\n --public-key \"ssh-rsa AAAjjk76kgf...Xt\"\n#\ \ --public-key-from-file ~/.ssh/id_rsa.pub" /ssh_keys/{id}: get: operationId: get_ssh_key summary: Get a SSH key description: 'Returns a specific SSH key object. ' tags: - SSH Keys parameters: - description: ID of the SSH Key. name: id in: path required: true schema: description: ID of the [SSH Key](#tag/ssh-keys). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: ssh_key: type: object properties: id: description: ID of the [SSH Key](#tag/ssh-keys). 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 fingerprint: description: MD5 fingerprint of the SSH public key. type: string example: b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f public_key: description: Public key. type: string example: ssh-rsa AAAjjk76kgf...Xt 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: '' 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' required: - id - name - fingerprint - public_key - labels - created required: - ssh_key 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\tsshKey, _, err := client.SSHKey.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) ssh_key = client.ssh_keys.get_by_id(123)' - lang: Shell label: CLI source: hcloud ssh-key describe $SSHKEY put: operationId: update_ssh_key summary: Update an SSH key description: 'Updates an SSH key. You can update an SSH key name and an SSH key labels. ' tags: - SSH Keys parameters: - description: ID of the SSH Key. name: id in: path required: true schema: description: ID of the [SSH Key](#tag/ssh-keys). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: name: description: New name Name to set. type: string example: My ssh key 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: ssh_key: type: object properties: id: description: ID of the [SSH Key](#tag/ssh-keys). 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 fingerprint: description: MD5 fingerprint of the SSH public key. type: string example: b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f public_key: description: Public key. type: string example: ssh-rsa AAAjjk76kgf...Xt 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: '' 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' required: - id - name - fingerprint - public_key - labels - created required: - ssh_key examples: default: value: ssh_key: id: 2323 name: My ssh key fingerprint: b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f public_key: ssh-rsa AAAjjk76kgf...Xt labels: key: value created: '2016-01-30T23:50:00Z' 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\tsshKey, _, err := client.SSHKey.Update(ctx, &hcloud.SSHKey{ID: 123}, hcloud.SSHKeyUpdateOpts{\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 ssh key\",\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.ssh_keys\ \ import SSHKey\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nssh_key = client.ssh_keys.update(\n\ \ ssh_key=SSHKey(id=123),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\"\ ,\n \"just-a-key\": \"\",\n },\n name=\"My ssh key\",\n)" - lang: Shell label: CLI source: "hcloud ssh-key update $SSHKEY --name \"My ssh key\"\nhcloud ssh-key add-label --overwrite $SSHKEY \\\n \ \ \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud ssh-key remove-label $SSHKEY \\\n \"\ environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_ssh_key summary: Delete an SSH key description: 'Deletes an SSH key. It cannot be used anymore. ' tags: - SSH Keys parameters: - description: ID of the SSH Key. name: id in: path required: true schema: description: ID of the [SSH Key](#tag/ssh-keys). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.SSHKey.Delete(ctx, &hcloud.SSHKey{ID: 123})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.ssh_keys\ \ import SSHKey\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nclient.ssh_keys.delete(\n\ \ ssh_key=SSHKey(id=123),\n)" - lang: Shell label: CLI source: hcloud ssh-key delete $SSHKEY /volumes: get: operationId: list_volumes summary: List Volumes description: 'Gets all existing Volumes that you have available. ' tags: - Volumes parameters: - 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 Volume. type: string enum: - available - creating example: available - 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 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: 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. content: application/json: schema: type: object properties: volumes: type: array items: type: object properties: id: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 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' name: description: Name of the Resource. Must be unique per Project. type: string example: my-resource server: description: ID of the Server the Volume is attached to, null if it is not attached at all. type: integer format: int64 nullable: true example: 12 location: description: Location of the Volume. Volume can only be attached to Servers in the same Location. 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 size: description: Size in GB of the Volume. type: number example: 42 linux_device: description: Device path on the file system for the Volume. type: string example: /dev/disk/by-id/scsi-0HC_Volume_4711 protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' status: description: Status of the Volume. type: string enum: - available - creating example: available format: description: Filesystem of the Volume if formatted on creation, null if not formatted on creation. type: string nullable: true example: xfs required: - id - created - name - server - location - size - linux_device - protection - labels - status - format 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: - volumes - 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\tvolumes, err := client.Volume.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) volumes = client.volumes.get_all()' - lang: Shell label: CLI source: hcloud volume list post: operationId: create_volume summary: Create a Volume description: 'Creates a new Volume attached to a Server. If you want to create a Volume that is not attached to a Server, you need to provide the `location` key instead of `server`. This can be either the ID or the name of the Location this Volume will be created in. Note that a Volume can be attached to a Server only in the same Location as the Volume itself. Specifying the Server during Volume creation will automatically attach the Volume to that Server after it has been initialized. In that case, the `next_actions` key in the response is an array which contains a single `attach_volume` action. The minimum Volume size is 10GB and the maximum size is 10TB (10240GB). A volume’s name can consist of alphanumeric characters, dashes, underscores, and dots, but has to start and end with an alphanumeric character. The total length is limited to 64 characters. Volume names must be unique per Project. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `no_space_left_in_location` | There is no volume space left in the given location | ' tags: - Volumes requestBody: required: true content: application/json: schema: title: CreateVolumeRequest type: object properties: size: description: Size of the Volume in GB. type: integer example: 42 name: description: Name of the volume. type: string example: databases-storage 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 Volume after attach. `server` must be provided. type: boolean example: false format: description: 'Format Volume after creation. One of: `xfs`, `ext4`.' type: string example: xfs location: description: Location to create the Volume in (can be omitted if Server is specified). type: string example: nbg1 server: description: Server to which to attach the Volume once it's created (Volume will be created in the same Location as the server). type: integer format: int64 required: - size - name examples: default: value: size: 42 name: test-database labels: key: value location: nbg1 automount: false format: xfs responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: volume: type: object properties: id: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 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' name: description: Name of the Resource. Must be unique per Project. type: string example: my-resource server: description: ID of the Server the Volume is attached to, null if it is not attached at all. type: integer format: int64 nullable: true example: 12 location: description: Location of the Volume. Volume can only be attached to Servers in the same Location. 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 size: description: Size in GB of the Volume. type: number example: 42 linux_device: description: Device path on the file system for the Volume. type: string example: /dev/disk/by-id/scsi-0HC_Volume_4711 protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' status: description: Status of the Volume. type: string enum: - available - creating example: available format: description: Filesystem of the Volume if formatted on creation, null if not formatted on creation. type: string nullable: true example: xfs required: - id - created - name - server - location - size - linux_device - protection - labels - status - format 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 required: - volume - action - next_actions examples: default: value: volume: id: 4711 created: '2016-01-30T23:50:11Z' name: database-storage server: 12 location: id: 1 name: fsn1 description: Falkenstein DC Park 1 country: DE city: Falkenstein latitude: 50.47612 longitude: 12.370071 network_zone: eu-central size: 42 linux_device: /dev/disk/by-id/scsi-0HC_Volume_4711 protection: delete: false labels: key: value status: available format: xfs action: id: 13 command: create_volume status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 554 type: volume error: code: action_failed message: Action failed next_actions: - id: 13 command: attach_volume status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server - id: 554 type: volume error: code: action_failed message: Action failed 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.Volume.Create(ctx, hcloud.VolumeCreateOpts{\n\t\tAutomount:\ \ hcloud.Ptr(false),\n\t\tFormat: hcloud.Ptr(hcloud.VolumeFormatXFS),\n\t\tLabels: map[string]string{\n\t\t\t\ \"key\": \"value\",\n\t\t},\n\t\tLocation: &hcloud.Location{Name: \"nbg1\"},\n\t\tName: \"test-database\",\n\ \t\tSize: 42,\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tvolume := result.Volume\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.locations\ \ import Location\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.volumes.create(\n\ \ automount=False,\n format=\"xfs\",\n labels={\"key\": \"value\"},\n location=Location(name=\"nbg1\"\ ),\n name=\"test-database\",\n size=42,\n)\n\nresponse.action.wait_until_finished()\n\nvolume = response.volume" - lang: Shell label: CLI source: "hcloud volume create \\\n --automount=false \\\n --format xfs \\\n --label \"key=value\" \\\n \ \ --location nbg1 \\\n --name test-database \\\n --size 42" /volumes/actions: get: operationId: list_volumes_actions summary: List Actions description: 'Returns all Action objects. You can `sort` the results by using the sort URI parameter, and filter them with the `status` and `id` parameter. ' tags: - Volume Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.Volume.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.volumes.actions.get_all()' /volumes/actions/{id}: get: operationId: get_volumes_action summary: Get an Action description: 'Returns a specific Action object. ' tags: - Volume Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.Volume.Action.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) action = client.volumes.actions.get_by_id(123)' /volumes/{id}: get: operationId: get_volume summary: Get a Volume description: 'Gets a specific Volume object. ' tags: - Volumes parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: volume: type: object properties: id: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 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' name: description: Name of the Resource. Must be unique per Project. type: string example: my-resource server: description: ID of the Server the Volume is attached to, null if it is not attached at all. type: integer format: int64 nullable: true example: 12 location: description: Location of the Volume. Volume can only be attached to Servers in the same Location. 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 size: description: Size in GB of the Volume. type: number example: 42 linux_device: description: Device path on the file system for the Volume. type: string example: /dev/disk/by-id/scsi-0HC_Volume_4711 protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' status: description: Status of the Volume. type: string enum: - available - creating example: available format: description: Filesystem of the Volume if formatted on creation, null if not formatted on creation. type: string nullable: true example: xfs required: - id - created - name - server - location - size - linux_device - protection - labels - status - format required: - volume 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\tvolume, _, err := client.Volume.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) volume = client.volumes.get_by_id(123)' - lang: Shell label: CLI source: hcloud volume describe $VOLUME put: operationId: update_volume summary: Update a Volume description: 'Updates the Volume properties. ' tags: - Volumes parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: UpdateVolumeRequest type: object properties: name: description: New Volume name. type: string example: database-storage 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: volume: type: object properties: id: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 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' name: description: Name of the Resource. Must be unique per Project. type: string example: my-resource server: description: ID of the Server the Volume is attached to, null if it is not attached at all. type: integer format: int64 nullable: true example: 12 location: description: Location of the Volume. Volume can only be attached to Servers in the same Location. 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 size: description: Size in GB of the Volume. type: number example: 42 linux_device: description: Device path on the file system for the Volume. type: string example: /dev/disk/by-id/scsi-0HC_Volume_4711 protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete 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: '' status: description: Status of the Volume. type: string enum: - available - creating example: available format: description: Filesystem of the Volume if formatted on creation, null if not formatted on creation. type: string nullable: true example: xfs required: - id - created - name - server - location - size - linux_device - protection - labels - status - format required: - volume examples: default: value: volume: id: 4711 created: '2016-01-30T23:50:11Z' name: database-storage server: 12 location: id: 1 name: fsn1 description: Falkenstein DC Park 1 country: DE city: Falkenstein latitude: 50.47612 longitude: 12.370071 network_zone: eu-central size: 42 linux_device: /dev/disk/by-id/scsi-0HC_Volume_4711 protection: delete: false labels: key: value status: available format: xfs 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\tvolume, _, err := client.Volume.Update(ctx, &hcloud.Volume{ID: 123}, hcloud.VolumeUpdateOpts{\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: \"database-storage\",\n\t})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.volumes\ \ import Volume\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nvolume = client.volumes.update(\n\ \ volume=Volume(id=123),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\"\ ,\n \"just-a-key\": \"\",\n },\n name=\"database-storage\",\n)" - lang: Shell label: CLI source: "hcloud volume update $VOLUME --name \"database-storage\"\nhcloud volume add-label --overwrite $VOLUME \\\n\ \ \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud volume remove-label $VOLUME \\\n \"\ environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_volume summary: Delete a Volume description: 'Deletes a volume. All Volume data is irreversibly destroyed. The Volume must not be attached to a Server and it must not have delete protection enabled. ' tags: - Volumes parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '204': description: Request succeeded. 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\t_, err := client.Volume.Delete(ctx, &hcloud.Volume{ID: 123})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.volumes\ \ import Volume\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nclient.volumes.delete(\n \ \ volume=Volume(id=123),\n)" - lang: Shell label: CLI source: hcloud volume delete $VOLUME /volumes/{id}/actions: get: operationId: list_volume_actions summary: List Actions for a Volume description: 'Returns all Action objects for a Volume. You can `sort` the results by using the sort URI parameter, and filter them with the `status` parameter. ' tags: - Volume Actions parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - meta examples: default: value: actions: - id: 13 command: attach_volume status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server - id: 13 type: volume error: code: action_failed message: Action failed meta: pagination: page: 1 per_page: 25 previous_page: null next_page: null last_page: 1 total_entries: 21 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: [] /volumes/{id}/actions/attach: post: operationId: attach_volume summary: Attach Volume to a Server description: 'Attaches a Volume to a Server. Works only if the Server is in the same Location as the Volume. ' tags: - Volume Actions parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: title: AttachVolumeRequest type: object properties: server: description: ID of the Server the Volume will be attached to. type: integer format: int64 example: 43 automount: description: Auto-mount the Volume after attaching it. type: boolean example: false required: - server responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: attach_volume status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 43 type: server - id: 554 type: volume error: code: action_failed message: Action failed 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\taction, _, err := client.Volume.AttachWithOpts(ctx, &hcloud.Volume{ID: 123}, hcloud.VolumeAttachOpts{\n\ \t\tAutomount: hcloud.Ptr(false),\n\t\tServer: &hcloud.Server{ID: 43},\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ 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\nfrom hcloud.volumes import Volume\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ \naction = client.volumes.attach(\n volume=Volume(id=123),\n automount=False,\n server=Server(id=43),\n\ )\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud volume attach $VOLUME \\\n --automount=false \\\n --server 43" /volumes/{id}/actions/change_protection: post: operationId: change_volume_protection summary: Change Volume Protection description: 'Changes the protection configuration of a Volume. ' tags: - Volume Actions parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: delete: description: If true, prevents the Volume from being deleted. type: boolean example: true responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: change_protection status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server - id: 554 type: volume error: code: action_failed message: Action failed 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\taction, _, err := client.Volume.ChangeProtection(ctx, &hcloud.Volume{ID: 123}, hcloud.VolumeChangeProtectionOpts{\n\ \t\tDelete: hcloud.Ptr(true),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.volumes\ \ import Volume\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.volumes.change_protection(\n\ \ volume=Volume(id=123),\n delete=True,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud volume enable-protection $VOLUME delete hcloud volume disable-protection $VOLUME delete' /volumes/{id}/actions/detach: post: operationId: detach_volume summary: Detach Volume description: 'Detaches a Volume from the Server it’s attached to. You may attach it to a Server again at a later time. ' tags: - Volume Actions parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: detach_volume status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: server error: code: action_failed message: Action failed 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\taction, _, err := client.Volume.Detach(ctx, &hcloud.Volume{ID: 123})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.volumes\ \ import Volume\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.volumes.detach(\n\ \ volume=Volume(id=123),\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud volume detach $VOLUME /volumes/{id}/actions/resize: post: operationId: resize_volume summary: Resize Volume description: 'Changes the size of a Volume. Note that downsizing a Volume is not possible. ' tags: - Volume Actions parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 requestBody: required: true content: application/json: schema: type: object properties: size: description: New Volume size in GB (must be greater than current size). type: number example: 50 required: - size responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 13 command: resize_volume status: running progress: 0 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 554 type: volume error: code: action_failed message: Action failed 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\taction, _, err := client.Volume.Resize(ctx, &hcloud.Volume{ID: 123}, 50)\n\n\terr =\ \ client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.volumes\ \ import Volume\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.volumes.resize(\n\ \ volume=Volume(id=123),\n size=50,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud volume resize --size 50 $VOLUME /volumes/{id}/actions/{action_id}: get: deprecated: true operationId: get_volume_action summary: Get an Action for a Volume description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific Action for a Volume. ' tags: - Volume Actions parameters: - description: ID of the Volume. name: id in: path required: true schema: description: ID of the [Volume](#tag/volumes). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 13 command: attach_volume status: success progress: 100 started: '2016-01-30T23:55:00Z' finished: '2016-01-30T23:56:00Z' resources: - id: 42 type: server error: code: action_failed message: Action failed 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: [] /zones: get: operationId: list_zones summary: List Zones description: 'Returns all [Zones](#tag/zones). Use the provided URI parameters to modify the result. ' tags: - Zones 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 their mode. The response will only contain the resources matching exactly the specified mode. ' name: mode in: query required: false schema: description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string enum: - primary - secondary example: primary - 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: 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. content: application/json: schema: type: object properties: zones: type: array items: title: Zone oneOf: - title: Primary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - primary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string example: primary required: - mode - title: Secondary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - secondary example: secondary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string required: - mode discriminator: propertyName: mode mapping: primary: '#/components/schemas/ZonePrimary' secondary: '#/components/schemas/ZoneSecondary' 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: - zones - 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\tzones, err := client.Zone.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) zones = client.zones.get_all()' - lang: Shell label: CLI source: hcloud zone list post: operationId: create_zone summary: Create a Zone description: 'Creates a [Zone](#tag/zones). A default `SOA` and three `NS` resource records with the assigned Hetzner nameservers are created automatically. ' tags: - Zones requestBody: required: true content: application/json: schema: type: object properties: name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com mode: description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string enum: - primary - secondary example: primary ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 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: '' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in secondary mode. Ignored for [Zones](#tag/zones) in primary mode. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 rrsets: description: '[RRSets](#tag/zone-rrsets) to be added to the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. Ignored for [Zones](#tag/zones) in secondary mode. ' type: array items: type: object properties: name: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www type: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A ttl: description: 'Time To Live (TTL) of the [RRSet](#tag/zone-rrsets). Must be in between 60s and 2147483647s. If not set, the [Zone''s](#tag/zones) Default TTL is used. ' type: integer nullable: true minimum: 60 maximum: 2147483647 example: 3600 records: description: 'Records of the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. The order of records returned in responses is not guaranteed to be consistent. ' type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value 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: '' required: - name - type - records zonefile: description: 'Zone file to import. Only applicable for [Zones](#tag/zones) in primary mode. Ignored for [Zones](#tag/zones) in secondary mode. If provided, `rrsets` must be empty. See [Zone file import](#tag/zones/zone-file-import) for more details. ' type: string example: "$ORIGIN\texample.com.\n$TTL\t3600\n\n@\tIN\tSOA\thydrogen.ns.hetzner.com. dns.hetzner.com. 2024010100\ \ 86400 10800 3600000 3600\n\n@\tIN\t10800\tNS\thydrogen.ns.hetzner.com. ; Some comment.\n@\tIN\t10800\t\ NS\toxygen.ns.hetzner.com.\n@\tIN\t10800\tNS\thelium.ns.hetzner.de.\n" required: - name - mode examples: primary: value: name: example.com mode: primary ttl: 10800 labels: key: value rrsets: - name: www type: A records: - value: 198.51.100.1 comment: My web server at Hetzner Cloud. primary from zone file: value: name: example.com mode: primary ttl: 10800 labels: key: value zonefile: "$ORIGIN\texample.com.\n$TTL\t10800\n\n@\tIN\tA\t198.51.100.1 ; My web server at Hetzner Cloud.\n" secondary: value: name: example.com mode: secondary ttl: 10800 labels: key: value primary_nameservers: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: zone: title: Zone oneOf: - title: Primary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - primary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string example: primary required: - mode - title: Secondary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - secondary example: secondary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string required: - mode discriminator: propertyName: mode mapping: primary: '#/components/schemas/ZonePrimary' secondary: '#/components/schemas/ZoneSecondary' 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 required: - zone - action examples: default: value: zone: id: 42 name: example.com mode: primary status: ok ttl: 3600 record_count: 4 protection: delete: false labels: key: value created: '2016-01-30T23:50:00Z' registrar: hetzner authoritative_nameservers: assigned: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: '2016-01-30T23:50:00Z' delegation_status: valid action: id: 1 command: create_zone status: running progress: 50 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: zone error: null 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 (primary from zone file) 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.Zone.Create(ctx, hcloud.ZoneCreateOpts{\n\t\tName: \"example.com\"\ ,\n\t\tMode: hcloud.ZoneModePrimary,\n\t\tTTL: hcloud.Ptr(10800),\n\t\tLabels: map[string]string{\n\t\t\t\"key\"\ : \"value\",\n\t\t},\n\t\tZonefile: `$ORIGIN\texample.com.\n$TTL\t10800\n\n@\tIN\tA\t198.51.100.1 ; My web server\ \ at Hetzner Cloud.\n`,\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tzone := result.Zone\n}" - lang: Go label: Go (primary) 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.Zone.Create(ctx, hcloud.ZoneCreateOpts{\n\t\tName: \"example.com\"\ ,\n\t\tMode: hcloud.ZoneModePrimary,\n\t\tTTL: hcloud.Ptr(10800),\n\t\tLabels: map[string]string{\n\t\t\t\"key\"\ : \"value\",\n\t\t},\n\t\tRRSets: []hcloud.ZoneCreateOptsRRSet{\n\t\t\t{\n\t\t\t\tName: \"www\",\n\t\t\t\tType:\ \ hcloud.ZoneRRSetTypeA,\n\t\t\t\tRecords: []hcloud.ZoneRRSetRecord{\n\t\t\t\t\t{\n\t\t\t\t\t\tValue: \"198.51.100.1\"\ ,\n\t\t\t\t\t\tComment: \"My web server at Hetzner Cloud.\",\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t})\n\ \n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tzone := result.Zone\n}" - lang: Go label: Go (secondary) 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.Zone.Create(ctx, hcloud.ZoneCreateOpts{\n\t\tName: \"example.com\"\ ,\n\t\tMode: hcloud.ZoneModeSecondary,\n\t\tTTL: hcloud.Ptr(10800),\n\t\tLabels: map[string]string{\n\t\t\t\"key\"\ : \"value\",\n\t\t},\n\t\tPrimaryNameservers: []hcloud.ZoneCreateOptsPrimaryNameserver{\n\t\t\t{Address: \"198.51.100.1\"\ , Port: 53},\n\t\t\t{Address: \"203.0.113.1\", Port: 53},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\ \n\tzone := result.Zone\n}" - lang: Python label: Python (primary from zone file) source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"\ HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.zones.create(\n name=\"example.com\",\n \ \ mode=\"primary\",\n ttl=10800,\n labels={\n \"key\": \"value\",\n },\n zonefile=\"\"\"$ORIGIN\ \ example.com.\n$TTL 10800\n\n@ IN A 198.51.100.1 ; My web server at Hetzner Cloud.\n\"\"\",\n)\n\nresponse.action.wait_until_finished()\n\ \nzone = response.zone" - lang: Python label: Python (primary) source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import ZoneRecord, ZoneRRSet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse =\ \ client.zones.create(\n name=\"example.com\",\n mode=\"primary\",\n ttl=10800,\n labels={\n \ \ \"key\": \"value\",\n },\n rrsets=[\n ZoneRRSet(\n name=\"www\",\n type=\"\ A\",\n records=[\n ZoneRecord(\n value=\"198.51.100.1\",\n \ \ comment=\"My web server at Hetzner Cloud.\",\n )\n ],\n )\n ],\n\ )\n\nresponse.action.wait_until_finished()\n\nzone = response.zone" - lang: Python label: Python (secondary) source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import ZonePrimaryNameserver\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse =\ \ client.zones.create(\n name=\"example.com\",\n mode=\"secondary\",\n ttl=10800,\n labels={\n \ \ \"key\": \"value\",\n },\n primary_nameservers=[\n ZonePrimaryNameserver(address=\"198.51.100.1\"\ , port=53),\n ZonePrimaryNameserver(address=\"203.0.113.1\", port=53),\n ],\n)\n\nresponse.action.wait_until_finished()\n\ \nzone = response.zone" - lang: Shell label: CLI (primary from zone file) source: "hcloud zone create \\\n --name example.com \\\n --mode primary \\\n --ttl 10800 \\\n --label\ \ \"key=value\" \\\n --zonefile <(echo '$ORIGIN\texample.com.\n$TTL\t10800\n\n@\tIN\tA\t198.51.100.1 ; My web\ \ server at Hetzner Cloud.\n')" - lang: Shell label: CLI (primary) source: "hcloud zone create \\\n --name example.com \\\n --mode primary \\\n --ttl 10800 \\\n --label\ \ \"key=value\"\nhcloud zone rrset create example.com \\\n --name www \\\n --type A \\\n --record \"198.51.100.1\"" - lang: Shell label: CLI (secondary) source: "hcloud zone create \\\n --name example.com \\\n --mode secondary \\\n --ttl 10800 \\\n --label\ \ \"key=value\" \\\n --primary-nameservers-file <(echo '[\n {\"address\": \"198.51.100.1\", \"port\":\ \ 53},\n {\"address\": \"203.0.113.1\", \"port\": 53}\n ]')" /zones/{id_or_name}: get: operationId: get_zone summary: Get a Zone description: 'Returns a single [Zone](#tag/zones). ' tags: - Zones parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: zone: title: Zone oneOf: - title: Primary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - primary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string example: primary required: - mode - title: Secondary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - secondary example: secondary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string required: - mode discriminator: propertyName: mode mapping: primary: '#/components/schemas/ZonePrimary' secondary: '#/components/schemas/ZoneSecondary' required: - zone 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\tzone, _, err := client.Zone.Get(ctx, \"example.com\")\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) zone = client.zones.get("example.com")' - lang: Shell label: CLI source: hcloud zone describe $ZONE put: operationId: update_zone summary: Update a Zone description: 'Updates a [Zone](#tag/zones). To modify resource record sets ([RRSets](#tag/zone-rrsets)), use the [RRSet Actions endpoints](#tag/zone-rrset-actions). ' tags: - Zones parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string requestBody: required: true content: application/json: schema: title: ZoneUpdateRequest type: object properties: 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: zone: title: Zone oneOf: - title: Primary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - primary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string example: primary required: - mode - title: Secondary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - secondary example: secondary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string required: - mode discriminator: propertyName: mode mapping: primary: '#/components/schemas/ZonePrimary' secondary: '#/components/schemas/ZoneSecondary' required: - zone examples: default: value: zone: id: 42 name: example.com mode: primary status: ok ttl: 3600 record_count: 4 protection: delete: false labels: key: value created: '2016-01-30T23:50:00Z' registrar: hetzner authoritative_nameservers: assigned: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: '2016-01-30T23:50:00Z' delegation_status: valid 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\tzone, _, err := client.Zone.Update(ctx, &hcloud.Zone{Name: \"example.com\"}, hcloud.ZoneUpdateOpts{\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})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nzone = client.zones.update(\n\ \ zone=Zone(name=\"example.com\"),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\"\ : \"label\",\n \"just-a-key\": \"\",\n },\n)" - lang: Shell label: CLI source: "hcloud zone add-label --overwrite $ZONE \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\ \nhcloud zone remove-label $ZONE \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_zone summary: Delete a Zone description: 'Deletes a [Zone](#tag/zones). ' tags: - Zones parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 1 command: delete_zone status: running progress: 50 started: '2016-01-30T23:50:00Z' finished: null resources: - id: 42 type: zone error: null 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.Zone.Delete(ctx, &hcloud.Zone{Name: \"example.com\"})\n\n\t\ err = 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.zones\ \ import Zone\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.zones.delete(\n\ \ zone=Zone(name=\"example.com\"),\n)\n\nresponse.action.wait_until_finished()" - lang: Shell label: CLI source: hcloud zone delete $ZONE /zones/{id_or_name}/zonefile: get: operationId: get_zone_zonefile summary: Export a Zone file description: 'Returns a generated [Zone](#tag/zones) file in BIND (RFC [1034](https://datatracker.ietf.org/doc/html/rfc1034)/[1035](https://datatracker.ietf.org/doc/html/rfc1035)) format. Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zones parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: zonefile: description: "Generated zone file.\n\nExample:\n\n```dns\n$ORIGIN\texample.com.\n$TTL\t3600\n\n@\tIN\t\ SOA\thydrogen.ns.hetzner.com. dns.hetzner.com. 2024010100 86400 10800 3600000 3600\n\n@\tIN\t10800\t\ NS\thydrogen.ns.hetzner.com. ; Some comment.\n@\tIN\t10800\tNS\toxygen.ns.hetzner.com.\n@\tIN\t10800\t\ NS\thelium.ns.hetzner.de.\n```\n" type: string example: "$ORIGIN\texample.com.\n$TTL\t3600\n\n@\tIN\tSOA\thydrogen.ns.hetzner.com. dns.hetzner.com. 2024010100\ \ 86400 10800 3600000 3600\n\n@\tIN\t10800\tNS\thydrogen.ns.hetzner.com. ; Some comment.\n@\tIN\t10800\t\ NS\toxygen.ns.hetzner.com.\n@\tIN\t10800\tNS\thelium.ns.hetzner.de.\n" required: - zonefile 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.Zone.ExportZonefile(ctx, &hcloud.Zone{Name: \"example.com\"\ })\n\n\tzonefile := result.Zonefile\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.zones.export_zonefile(\n\ \ zone=Zone(name=\"example.com\"),\n)\n\nzonefile = response.zonefile" - lang: Shell label: CLI source: hcloud zone export-zonefile $ZONE /zones/actions: get: operationId: list_zones_actions summary: List Actions description: 'Returns all [Zone](#tag/zones) [Actions](#tag/actions). Use the provided URI parameters to modify the result. ' tags: - Zone Actions parameters: - description: 'Filter the actions by ID. May be used multiple times. The response will only contain actions matching the specified IDs. ' name: id in: query required: false schema: type: array items: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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\tactions, err := client.Zone.Action.All(ctx, hcloud.ActionListOpts{})\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) actions = client.zones.actions.get_all()' /zones/actions/{id}: get: operationId: get_zones_action summary: Get an Action description: 'Returns a specific [Action](#tag/actions). ' tags: - Zone Actions parameters: - description: ID of the Action. name: id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action 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\taction, _, err := client.Zone.Action.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) action = client.zones.actions.get_by_id(123)' /zones/{id_or_name}/actions: get: operationId: list_zone_actions summary: List Actions for a Zone description: 'Returns all [Actions](#tag/actions) for a [Zone](#tag/zones). Use the provided URI parameters to modify the result. ' tags: - Zone Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - description: 'Sort actions 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 - command - command:asc - command:desc - status - status:asc - status:desc - started - started:asc - started:desc - finished - finished:asc - finished:desc - description: 'Filter the actions by status. May be used multiple times. The response will only contain actions matching the specified statuses. ' name: status in: query required: false schema: type: array items: description: Status of the Action. type: string enum: - running - success - error - 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. content: application/json: schema: title: ActionListResponseWithMeta type: object properties: 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 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: - actions - 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: [] /zones/{id_or_name}/actions/{action_id}: get: deprecated: true operationId: get_zone_action summary: Get an Action for a Zone description: '**Deprecated**: This operation is deprecated, see our [changelog](https://docs.hetzner.cloud/changelog#2026-04-30-deprecate-get-resource-action-endpoints) for more details. Returns a specific [Action](#tag/actions) for a [Zone](#tag/zones). ' tags: - Zone Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - description: ID of the Action. name: action_id in: path required: true schema: description: ID of the [Action](#description/actions). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 1 command: import_zonefile status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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: [] /zones/{id_or_name}/actions/change_primary_nameservers: post: operationId: change_zone_primary_nameservers summary: Change a Zone's Primary Nameservers description: 'Overwrites the primary nameservers of a [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in secondary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string requestBody: required: true content: application/json: schema: type: object properties: primary_nameservers: description: Primary nameservers of the [Zone](#tag/zones). type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 required: - primary_nameservers responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: change_primary_nameservers status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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\taction, _, err := client.Zone.ChangePrimaryNameservers(ctx, &hcloud.Zone{Name: \"example.com\"\ }, hcloud.ZoneChangePrimaryNameserversOpts{\n\t\tPrimaryNameservers: []hcloud.ZoneChangePrimaryNameserversOptsPrimaryNameserver{\n\ \t\t\t{Address: \"198.51.100.1\", Port: 53},\n\t\t\t{Address: \"203.0.113.1\", Port: 53},\n\t\t},\n\t})\n\n\terr\ \ = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone, ZonePrimaryNameserver\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction\ \ = client.zones.change_primary_nameservers(\n zone=Zone(name=\"example.com\"),\n primary_nameservers=[\n\ \ ZonePrimaryNameserver(address=\"198.51.100.1\", port=53),\n ZonePrimaryNameserver(address=\"203.0.113.1\"\ , port=53),\n ],\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud zone change-primary-nameservers $ZONE --primary-nameservers-file <(echo '[\n {\"address\": \"198.51.100.1\"\ , \"port\": 53},\n {\"address\": \"203.0.113.1\", \"port\": 53}\n]')" /zones/{id_or_name}/actions/change_protection: post: operationId: change_zone_protection summary: Change a Zone's Protection description: 'Changes the protection configuration of a [Zone](#tag/zones). ' tags: - Zone Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string requestBody: required: true content: application/json: schema: type: object properties: delete: description: Prevents the [Zone](#tag/zones) from being deleted. type: boolean example: false responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: change_protection status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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\taction, _, err := client.Zone.ChangeProtection(ctx, &hcloud.Zone{Name: \"example.com\"\ }, hcloud.ZoneChangeProtectionOpts{\n\t\tDelete: hcloud.Ptr(true),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n\ }" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.zones.change_protection(\n\ \ zone=Zone(name=\"example.com\"),\n delete=True,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud zone enable-protection $ZONE delete hcloud zone disable-protection $ZONE delete' /zones/{id_or_name}/actions/change_ttl: post: operationId: change_zone_ttl summary: Change a Zone's Default TTL description: 'Changes the default Time To Live (TTL) of a [Zone](#tag/zones). This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string requestBody: required: true content: application/json: schema: type: object properties: ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 required: - ttl responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: change_ttl status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 1 type: zone error: null 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\taction, _, err := client.Zone.ChangeTTL(ctx, &hcloud.Zone{Name: \"example.com\"}, hcloud.ZoneChangeTTLOpts{\n\ \t\tTTL: 10800,\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.zones.change_ttl(\n\ \ zone=Zone(name=\"example.com\"),\n ttl=10800,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud zone change-ttl $ZONE --ttl 10800 /zones/{id_or_name}/actions/import_zonefile: post: operationId: import_zone_zonefile summary: Import a Zone file description: 'Imports a zone file, replacing all resource record sets ([RRSets](#tag/zone-rrsets)). The import will fail if existing [RRSet](#tag/zone-rrsets) are `change` protected. See [Zone file import](#tag/zones/zone-file-import) for more details. Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string requestBody: required: true content: application/json: schema: type: object properties: zonefile: description: 'Zone file to import. See [Zone file import](#tag/zones/zone-file-import) for more details. ' type: string example: "$ORIGIN\texample.com.\n$TTL\t3600\n\n@\tIN\tSOA\thydrogen.ns.hetzner.com. dns.hetzner.com. 2024010100\ \ 86400 10800 3600000 3600\n\n@\tIN\t10800\tNS\thydrogen.ns.hetzner.com. ; Some comment.\n@\tIN\t10800\t\ NS\toxygen.ns.hetzner.com.\n@\tIN\t10800\tNS\thelium.ns.hetzner.de.\n" required: - zonefile responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: import_zonefile status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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\taction, _, err := client.Zone.ImportZonefile(ctx, &hcloud.Zone{Name: \"example.com\"\ }, hcloud.ZoneImportZonefileOpts{\n\t\tZonefile: `$ORIGIN\texample.com.\n$TTL\t3600\n\n@\tIN\tSOA\thydrogen.ns.hetzner.com.\ \ dns.hetzner.com. 2024010100 86400 10800 3600000 3600\n\n@\tIN\t10800\tNS\thydrogen.ns.hetzner.com. ; Some comment.\n\ @\tIN\t10800\tNS\toxygen.ns.hetzner.com.\n@\tIN\t10800\tNS\thelium.ns.hetzner.de.\n`,\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.zones.import_zonefile(\n\ \ zone=Zone(name=\"example.com\"),\n zonefile=\"\"\"$ORIGIN\texample.com.\n$TTL\t3600\n\n@\tIN\tSOA\thydrogen.ns.hetzner.com.\ \ dns.hetzner.com. 2024010100 86400 10800 3600000 3600\n\n@\tIN\t10800\tNS\thydrogen.ns.hetzner.com. ; Some comment.\n\ @\tIN\t10800\tNS\toxygen.ns.hetzner.com.\n@\tIN\t10800\tNS\thelium.ns.hetzner.de.\n\"\"\",\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud zone import-zonefile $ZONE --zonefile <(echo '$ORIGIN\texample.com.\n$TTL\t3600\n\n@\tIN\tSOA\thydrogen.ns.hetzner.com.\ \ dns.hetzner.com. 2024010100 86400 10800 3600000 3600\n\n@\tIN\t10800\tNS\thydrogen.ns.hetzner.com. ; Some comment.\n\ @\tIN\t10800\tNS\toxygen.ns.hetzner.com.\n@\tIN\t10800\tNS\thelium.ns.hetzner.de.\n')" /zones/{id_or_name}/rrsets: get: operationId: list_zone_rrsets summary: List RRSets description: 'Returns all [RRSets](#tag/zone-rrsets) in the [Zone](#tag/zones). Use the provided URI parameters to modify the result. The maximum value for `per_page` on this endpoint is `100` instead of `50`. Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSets parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - 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 their type. May be used multiple times. The response will only contain resources matching the specified types. ' name: type in: query required: false schema: type: array items: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A - 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: 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. content: application/json: schema: type: object properties: rrsets: type: array items: title: RRSet type: object properties: id: description: 'ID of the RRSet. The ID is composed of the name and type, joined with a slash (e.g. `www/AAAA`). ' type: string name: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www type: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A ttl: description: 'Time To Live (TTL) of the [RRSet](#tag/zone-rrsets). Must be in between 60s and 2147483647s. If not set, the [Zone''s](#tag/zones) Default TTL is used. ' type: integer nullable: true minimum: 60 maximum: 2147483647 example: 3600 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: '' protection: description: 'Protection of the [RRSet](#tag/zone-rrsets). ' type: object properties: change: description: Prevent the Resource from being changed. type: boolean example: false required: - change records: description: 'Records of the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. The order of records returned in responses is not guaranteed to be consistent. ' type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value zone: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id - name - type - ttl - labels - protection - records - zone 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: - rrsets - 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\trrSets, _, err := client.Zone.ListRRSets(ctx, &hcloud.Zone{Name: \"example.com\"},\ \ hcloud.ZoneRRSetListOpts{})\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.zones import Zone token = environ["HCLOUD_TOKEN"] client = Client(token=token) zones = client.zones.get_rrset_all(zone=Zone(name="example.com"))' - lang: Shell label: CLI source: hcloud zone rrset list $ZONE post: operationId: create_zone_rrset summary: Create an RRSet description: 'Create an [RRSet](#tag/zone-rrsets) in the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSets parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string requestBody: required: true content: application/json: schema: type: object properties: name: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www type: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A ttl: description: 'Time To Live (TTL) of the [RRSet](#tag/zone-rrsets). Must be in between 60s and 2147483647s. If not set, the [Zone''s](#tag/zones) Default TTL is used. ' type: integer nullable: true minimum: 60 maximum: 2147483647 example: 3600 records: description: 'Records of the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. The order of records returned in responses is not guaranteed to be consistent. ' type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value 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: '' required: - name - type - records responses: '201': description: Request succeeded. content: application/json: schema: type: object properties: rrset: title: RRSet type: object properties: id: description: 'ID of the RRSet. The ID is composed of the name and type, joined with a slash (e.g. `www/AAAA`). ' type: string name: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www type: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A ttl: description: 'Time To Live (TTL) of the [RRSet](#tag/zone-rrsets). Must be in between 60s and 2147483647s. If not set, the [Zone''s](#tag/zones) Default TTL is used. ' type: integer nullable: true minimum: 60 maximum: 2147483647 example: 3600 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: '' protection: description: 'Protection of the [RRSet](#tag/zone-rrsets). ' type: object properties: change: description: Prevent the Resource from being changed. type: boolean example: false required: - change records: description: 'Records of the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. The order of records returned in responses is not guaranteed to be consistent. ' type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value zone: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id - name - type - ttl - labels - protection - records - zone 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 required: - rrset - action examples: default: value: rrset: id: www/A name: www type: A ttl: 3600 labels: key: value protection: change: false records: - value: 198.51.100.1 comment: My web server at Hetzner Cloud. zone: 42 action: id: 1 command: create_rrset status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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.Zone.CreateRRSet(ctx, &hcloud.Zone{Name: \"example.com\"},\ \ hcloud.ZoneRRSetCreateOpts{\n\t\tName: \"www\",\n\t\tType: hcloud.ZoneRRSetTypeA,\n\t\tTTL: hcloud.Ptr(3600),\n\ \t\tRecords: []hcloud.ZoneRRSetRecord{\n\t\t\t{\n\t\t\t\tValue: \"198.51.100.1\",\n\t\t\t\tComment: \"My web server\ \ at Hetzner Cloud.\",\n\t\t\t},\n\t\t},\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})\n\n\terr = client.Action.WaitFor(ctx,\ \ result.Action)\n\n\trrSet := result.RRSet\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone, ZoneRecord\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.zones.create_rrset(\n\ \ zone=Zone(name=\"example.com\"),\n name=\"www\",\n type=\"A\",\n ttl=3600,\n records=[\n \ \ ZoneRecord(\n value=\"198.51.100.1\",\n comment=\"My web server at Hetzner Cloud.\",\n\ \ )\n ],\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \ \ \"just-a-key\": \"\",\n },\n)\n\nresponse.action.wait_until_finished()\n\nrrset = response.rrset" - lang: Shell label: CLI source: "hcloud zone rrset create $ZONE \\\n --name www \\\n --type A \\\n --ttl 3600 \\\n --record \"\ 198.51.100.1\" \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"\ just-a-key=\"" /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}: get: operationId: get_zone_rrset summary: Get an RRSet description: 'Returns a single [RRSet](#tag/zone-rrsets) from the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSets parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A responses: '200': description: Request succeeded. content: application/json: schema: type: object properties: rrset: title: RRSet type: object properties: id: description: 'ID of the RRSet. The ID is composed of the name and type, joined with a slash (e.g. `www/AAAA`). ' type: string name: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www type: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A ttl: description: 'Time To Live (TTL) of the [RRSet](#tag/zone-rrsets). Must be in between 60s and 2147483647s. If not set, the [Zone''s](#tag/zones) Default TTL is used. ' type: integer nullable: true minimum: 60 maximum: 2147483647 example: 3600 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: '' protection: description: 'Protection of the [RRSet](#tag/zone-rrsets). ' type: object properties: change: description: Prevent the Resource from being changed. type: boolean example: false required: - change records: description: 'Records of the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. The order of records returned in responses is not guaranteed to be consistent. ' type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value zone: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id - name - type - ttl - labels - protection - records - zone required: - rrset 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\trrSet, _, err := client.Zone.GetRRSetByNameAndType(ctx, &hcloud.Zone{Name: \"example.com\"\ }, \"www\", hcloud.ZoneRRSetTypeA)\n}" - lang: Python label: Python source: 'from __future__ import annotations from os import environ from hcloud import Client from hcloud.zones import Zone token = environ["HCLOUD_TOKEN"] client = Client(token=token) rrset = client.zones.get_rrset(zone=Zone(name="example.com"), name="www", type="A")' - lang: Shell label: CLI source: hcloud zone rrset describe $ZONE $RR_NAME $RR_TYPE put: operationId: update_zone_rrset summary: Update an RRSet description: 'Updates an [RRSet](#tag/zone-rrsets) in the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSets parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A requestBody: required: true content: application/json: schema: type: object properties: 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: rrset: title: RRSet type: object properties: id: description: 'ID of the RRSet. The ID is composed of the name and type, joined with a slash (e.g. `www/AAAA`). ' type: string name: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www type: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A ttl: description: 'Time To Live (TTL) of the [RRSet](#tag/zone-rrsets). Must be in between 60s and 2147483647s. If not set, the [Zone''s](#tag/zones) Default TTL is used. ' type: integer nullable: true minimum: 60 maximum: 2147483647 example: 3600 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: '' protection: description: 'Protection of the [RRSet](#tag/zone-rrsets). ' type: object properties: change: description: Prevent the Resource from being changed. type: boolean example: false required: - change records: description: 'Records of the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. The order of records returned in responses is not guaranteed to be consistent. ' type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value zone: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 required: - id - name - type - ttl - labels - protection - records - zone required: - rrset examples: default: value: rrset: id: www/A name: www type: A ttl: null records: - value: 198.51.100.1 comment: My web server at Hetzner Cloud. labels: environment: prod example.com/my: label just-a-key: '' protection: change: false zone: 42 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\trrSet, _, err := client.Zone.UpdateRRSet(ctx, &hcloud.ZoneRRSet{\n\t\tZone: &hcloud.Zone{Name:\ \ \"example.com\"},\n\t\tName: \"www\",\n\t\tType: hcloud.ZoneRRSetTypeA,\n\t}, hcloud.ZoneRRSetUpdateOpts{\n\t\t\ Labels: 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})\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone, ZoneRRSet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nrrset = client.zones.update_rrset(\n\ \ rrset=ZoneRRSet(\n zone=Zone(name=\"example.com\"),\n name=\"www\",\n type=\"A\",\n \ \ ),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\"\ : \"\",\n },\n)" - lang: Shell label: CLI source: "hcloud zone rrset add-label --overwrite $ZONE $RR_NAME $RR_TYPE \\\n \"environment=prod\" \"example.com/my=label\"\ \ \"just-a-key=\"\nhcloud zone remove-label $ZONE $RR_NAME $RR_TYPE \\\n \"environment\" \"example.com\" \"just-a-key\"" delete: operationId: delete_zone_rrset summary: Delete an RRSet description: 'Deletes an [RRSet](#tag/zone-rrsets) from the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSets parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse 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 required: - action examples: default: value: action: id: 1 command: delete_rrset status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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.Zone.DeleteRRSet(ctx, &hcloud.ZoneRRSet{\n\t\tZone: &hcloud.Zone{Name:\ \ \"example.com\"},\n\t\tName: \"www\",\n\t\tType: hcloud.ZoneRRSetTypeA,\n\t})\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.zones\ \ import Zone, ZoneRRSet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.zones.delete_rrset(\n\ \ rrset=ZoneRRSet(\n zone=Zone(name=\"example.com\"),\n name=\"www\",\n type=\"A\",\n \ \ ),\n)\n\nresponse.action.wait_until_finished()" - lang: Shell label: CLI source: hcloud zone rrset delete $ZONE $RR_NAME $RR_TYPE /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_protection: post: operationId: change_zone_rrset_protection summary: Change an RRSet's Protection description: 'Changes the protection of an [RRSet](#tag/zone-rrsets) in the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSet Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A requestBody: required: true content: application/json: schema: description: 'Protection of the [RRSet](#tag/zone-rrsets). ' type: object properties: change: description: Prevent the Resource from being changed. type: boolean example: false required: - change responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: change_rrset_protection status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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\taction, _, err := client.Zone.ChangeRRSetProtection(ctx, &hcloud.ZoneRRSet{\n\t\tZone:\ \ &hcloud.Zone{Name: \"example.com\"},\n\t\tName: \"www\",\n\t\tType: hcloud.ZoneRRSetTypeA,\n\t}, hcloud.ZoneRRSetChangeProtectionOpts{\n\ \t\tChange: hcloud.Ptr(false),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone, ZoneRRSet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.zones.change_rrset_protection(\n\ \ rrset=ZoneRRSet(\n zone=Zone(name=\"example.com\"),\n name=\"www\",\n type=\"A\",\n \ \ ),\n change=False,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: 'hcloud zone rrset enable-protection $ZONE $RR_NAME $RR_TYPE change hcloud zone rrset disable-protection $ZONE $RR_NAME $RR_TYPE change' /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_ttl: post: operationId: change_zone_rrset_ttl summary: Change an RRSet's TTL description: 'Changes the Time To Live (TTL) of an [RRSet](#tag/zone-rrsets) in the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSet Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A requestBody: required: true content: application/json: schema: type: object properties: ttl: description: 'Time To Live (TTL) of the [RRSet](#tag/zone-rrsets). Must be in between 60s and 2147483647s. If not set, the [Zone''s](#tag/zones) Default TTL is used. ' type: integer nullable: true minimum: 60 maximum: 2147483647 example: 3600 required: - ttl responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: change_rrset_ttl status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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\taction, _, err := client.Zone.ChangeRRSetTTL(ctx, &hcloud.ZoneRRSet{\n\t\tZone: &hcloud.Zone{Name:\ \ \"example.com\"},\n\t\tName: \"www\",\n\t\tType: hcloud.ZoneRRSetTypeA,\n\t}, hcloud.ZoneRRSetChangeTTLOpts{\n\ \t\tTTL: hcloud.Ptr(3600),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone, ZoneRRSet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.zones.change_rrset_ttl(\n\ \ rrset=ZoneRRSet(\n zone=Zone(name=\"example.com\"),\n name=\"www\",\n type=\"A\",\n \ \ ),\n ttl=3600,\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud zone rrset change-ttl $ZONE $RR_NAME $RR_TYPE --ttl 3600 /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/set_records: post: operationId: set_zone_rrset_records summary: Set Records of an RRSet description: 'Overwrites the resource records (RRs) of an existing [RRSet](#tag/zone-rrsets) in the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSet Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A requestBody: required: true content: application/json: schema: type: object properties: records: description: 'Records to set in the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. ' minItems: 1 maxItems: 50 type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value required: - records responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: set_rrset_records status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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\taction, _, err := client.Zone.SetRRSetRecords(ctx, &hcloud.ZoneRRSet{\n\t\tZone: &hcloud.Zone{Name:\ \ \"example.com\"},\n\t\tName: \"www\",\n\t\tType: hcloud.ZoneRRSetTypeA,\n\t}, hcloud.ZoneRRSetSetRecordsOpts{\n\ \t\tRecords: []hcloud.ZoneRRSetRecord{\n\t\t\t{\n\t\t\t\tValue: \"198.51.100.1\",\n\t\t\t\tComment: \"My web server\ \ at Hetzner Cloud.\",\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone, ZoneRecord, ZoneRRSet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction\ \ = client.zones.set_rrset_records(\n rrset=ZoneRRSet(\n zone=Zone(name=\"example.com\"),\n name=\"\ www\",\n type=\"A\",\n ),\n records=[\n ZoneRecord(value=\"198.51.100.1\", comment=\"My web\ \ server at Hetzner Cloud.\")\n ],\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud zone rrset set-records $ZONE $RR_NAME $RR_TYPE --records-file <(echo '[\n {\n \"value\": \"198.51.100.1\"\ ,\n \"comment\": \"My web server at Hetzner Cloud.\"\n }\n]')" /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/add_records: post: operationId: add_zone_rrset_records summary: Add Records to an RRSet description: 'Adds resource records (RRs) to an [RRSet](#tag/zone-rrsets) in the [Zone](#tag/zones). For convenience, the [RRSet](#tag/zone-rrsets) will be automatically created if it doesn''t exist. Otherwise, the new records are appended to the existing [RRSet](#tag/zone-rrsets). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSet Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A requestBody: required: true content: application/json: schema: type: object properties: ttl: description: 'Time To Live (TTL) of the [RRSet](#tag/zone-rrsets). If not set, the [Zone''s](#tag/zones) Default TTL is used. If set, and the RRSet being updated already has a TTL, the values must be the same. ' type: integer nullable: true minimum: 60 maximum: 2147483647 example: 3600 records: description: 'Records to add to the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. ' minItems: 1 maxItems: 50 type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value required: - records responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: add_rrset_records status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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\taction, _, err := client.Zone.AddRRSetRecords(ctx, &hcloud.ZoneRRSet{\n\t\tZone: &hcloud.Zone{Name:\ \ \"example.com\"},\n\t\tName: \"www\",\n\t\tType: hcloud.ZoneRRSetTypeA,\n\t}, hcloud.ZoneRRSetAddRecordsOpts{\n\ \t\tTTL: hcloud.Ptr(3600),\n\t\tRecords: []hcloud.ZoneRRSetRecord{\n\t\t\t{\n\t\t\t\tValue: \"198.51.100.1\",\n\ \t\t\t\tComment: \"My web server at Hetzner Cloud.\",\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx,\ \ action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone, ZoneRecord, ZoneRRSet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction\ \ = client.zones.add_rrset_records(\n rrset=ZoneRRSet(\n zone=Zone(name=\"example.com\"),\n name=\"\ www\",\n type=\"A\",\n ),\n ttl=3600,\n records=[\n ZoneRecord(value=\"198.51.100.1\", comment=\"\ My web server at Hetzner Cloud.\")\n ],\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: "hcloud zone rrset add-records $ZONE $RR_NAME $RR_TYPE \\\n --ttl 3600 \\\n --records-file <(echo '[\n\ \ {\n \"value\": \"198.51.100.1\",\n \"comment\": \"My web server at Hetzner Cloud.\"\n }\n]')" /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/remove_records: post: operationId: remove_zone_rrset_records summary: Remove Records from an RRSet description: 'Removes resource records (RRs) from an existing [RRSet](#tag/zone-rrsets) in the [Zone](#tag/zones). For convenience, the [RRSet](#tag/zone-rrsets) will be automatically deleted if it doesn''t contain any RRs afterwards. Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSet Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A requestBody: required: true content: application/json: schema: type: object properties: records: description: 'Records to remove from the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. ' minItems: 1 maxItems: 50 type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record. For details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/). ' type: string example: 198.51.100.1 comment: description: Comment of the record. type: string example: My web server at Hetzner Cloud. required: - value required: - records responses: '201': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: remove_rrset_records status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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\taction, _, err := client.Zone.RemoveRRSetRecords(ctx, &hcloud.ZoneRRSet{\n\t\tZone:\ \ &hcloud.Zone{Name: \"example.com\"},\n\t\tName: \"www\",\n\t\tType: hcloud.ZoneRRSetTypeA,\n\t}, hcloud.ZoneRRSetRemoveRecordsOpts{\n\ \t\tRecords: []hcloud.ZoneRRSetRecord{\n\t\t\t{\n\t\t\t\tValue: \"198.51.100.1\",\n\t\t\t\tComment: \"My web server\ \ at Hetzner Cloud.\",\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" - lang: Python label: Python source: "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.zones\ \ import Zone, ZoneRecord, ZoneRRSet\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction\ \ = client.zones.remove_rrset_records(\n rrset=ZoneRRSet(\n zone=Zone(name=\"example.com\"),\n \ \ name=\"www\",\n type=\"A\",\n ),\n records=[\n ZoneRecord(value=\"198.51.100.1\", comment=\"\ My web server at Hetzner Cloud.\")\n ],\n)\n\naction.wait_until_finished()" - lang: Shell label: CLI source: hcloud zone rrset remove-records $ZONE $RR_NAME $RR_TYPE --record 198.51.100.1 /zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/update_records: post: operationId: update_zone_rrset_records summary: Update Records of an RRSet description: 'Updates resource records'' (RRs) comments of an existing [RRSet](#tag/zone-rrsets) in the [Zone](#tag/zones). Only applicable for [Zones](#tag/zones) in primary mode. #### Operation specific errors | Status | Code | Description | | --- | --- | --- | | `422` | `incorrect_zone_mode` | This operation is not supported for this Zone''s `mode`. | ' tags: - Zone RRSet Actions parameters: - description: ID or Name of the Zone. name: id_or_name in: path required: true schema: description: ID or Name of the [Zone](#tag/zones). type: string - name: rr_name in: path required: true schema: description: 'Name of the [RRSet](#tag/zone-rrsets). The name must be in lower case, and must not end with a dot or the [Zone](#tag/zones) name. Names containing non-ASCII characters must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--4bi` (✉️). For the [Zone](#tag/zones) apex, use `@`. ' type: string example: www - name: rr_type in: path required: true schema: description: 'Type of the [RRSet](#tag/zone-rrsets). ' type: string enum: - A - AAAA - CAA - CNAME - DS - HINFO - HTTPS - MX - NS - PTR - RP - SOA - SRV - SVCB - TLSA - TXT example: A requestBody: required: true content: application/json: schema: type: object properties: records: description: 'Records to update in the [RRSet](#tag/zone-rrsets). Must not be empty and must only contain distinct record values. ' minItems: 1 maxItems: 50 type: array items: title: Record description: 'Record of a [RRSet](#tag/zone-rrsets). The `value` is used to identify the record in an [RRSet](#tag/zone-rrsets). ' type: object properties: value: description: 'Value of the record to update. ' type: string example: 198.51.100.1 comment: description: 'New comment for the record. ' type: string example: My web server at Hetzner Cloud. required: - value - comment required: - records responses: '200': description: Request succeeded. content: application/json: schema: title: ActionResponse description: 'Response for a created [Action](#description/actions). Make sure to wait for the [Action](#description/actions) completion to ensure your changes are applied. ' 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 required: - action examples: default: value: action: id: 1 command: update_rrset_records status: running progress: 50 started: '2016-01-30T23:55:00Z' finished: null resources: - id: 42 type: zone error: null 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: [] components: securitySchemes: APIToken: type: http scheme: bearer schemas: ServiceTCP: title: LoadBalancerServiceTCP allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - tcp example: tcp ServiceHTTPProtocol: title: LoadBalancerServiceHTTPProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - http example: http http: title: LoadBalancerServiceHTTPConfig description: Configuration option for protocol http. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - sticky_sessions required: - http ServiceHTTPSProtocol: title: LoadBalancerServiceHTTPSProtocol allOf: - type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false required: - domain - path additionalProperties: false required: - protocol - port - interval - timeout - retries required: - protocol - listen_port - destination_port - proxyprotocol - health_check - type: object properties: protocol: type: string enum: - https example: https http: title: LoadBalancerServiceHTTPSConfig description: Configuration option for protocol https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer default: 50 example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. type: boolean default: false example: true required: - cookie_name - cookie_lifetime - timeout_idle - certificates - redirect_http - sticky_sessions required: - http TargetTypeServer: title: LoadBalancerTargetTypeServer allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - server example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - server - health_status - use_private_ip TargetTypeLabelSelector: title: LoadBalancerTargetTypeLabelSelector allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - label_selector example: label_selector label_selector: title: LoadBalancerTargetLabelSelector description: Label selector used to determine targets. Only present for target type "label_selector". type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector targets: description: List of resolved label selector target Servers. type: array items: title: LoadBalancerTargetTarget type: object properties: type: description: Type of the resource. Here always "server". type: string example: server server: title: LoadBalancerTargetServer description: Server where the traffic should be routed to. Only present for target type "server". type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 required: - id health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - type - server - health_status - use_private_ip use_private_ip: title: LoadBalancerTargetUsePrivateIP description: Use the private network IP instead of the public IP. Only present for target types "server" and "label_selector". type: boolean default: false required: - label_selector - targets - use_private_ip TargetTypeIP: title: LoadBalancerTargetTypeIP allOf: - type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip required: - type - type: object properties: type: type: string enum: - ip example: ip ip: title: LoadBalancerTargetIP description: IP target where the traffic should be routed to. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only present for target type `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip health_status: title: LoadBalancerTargetHealthStatus description: List of health statuses of the services on this target. Only present for target types "server" and "ip". type: array items: type: object properties: listen_port: type: integer example: 443 status: type: string enum: - healthy - unhealthy - unknown example: healthy required: - listen_port - status required: - ip - health_status LoadBalancerTargetAddRequest: allOf: - title: LoadBalancerTarget description: Configuration of a Load Balancer target. type: object properties: type: description: Type of the resource. type: string enum: - server - label_selector - ip server: title: LoadBalancerTargetServer description: Configuration for type Server, only valid and required if type is `server`. type: object properties: id: description: ID of the Server. type: integer format: int64 example: 80 additionalProperties: false required: - id label_selector: title: LoadBalancerTargetLabelSelector description: Configuration for label selector targets, only valid and required if type is `label_selector`. type: object properties: selector: description: Label selector. type: string minLength: 1 maxLength: 1000 example: env=prod required: - selector ip: title: LoadBalancerTargetIP description: Configuration for an IP target. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only valid and required if type is `ip`. type: object properties: ip: description: IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch. type: string example: 203.0.113.1 required: - ip required: - type - type: object properties: use_private_ip: description: Use the private network IP instead of the public IP of the Server, requires the Server and Load Balancer to be in the same network. Only valid for target types `server` and `label_selector`. type: boolean default: false example: true LoadBalancerHealthCheckRequest: allOf: - title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false additionalProperties: false - type: object required: - protocol - port - interval - timeout - retries LoadBalancerServiceRequest: allOf: - title: LoadBalancerService type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https example: https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: allOf: - title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false additionalProperties: false - type: object required: - protocol - port - interval - timeout - retries - type: object properties: http: title: LoadBalancerServiceHTTP description: Configuration option for protocols http and https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string default: HCLBSTICKY minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer default: 300 minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough or if `protocol` is `http`. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. Only available if `protocol` is `https`. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. Only available if `protocol` is `http` or `https`. type: boolean default: false example: true required: - protocol - listen_port - destination_port - proxyprotocol - health_check LoadBalancerServiceUpdateRequest: title: UpdateLoadBalancerService allOf: - title: LoadBalancerService type: object properties: protocol: description: Protocol of the Load Balancer. type: string enum: - tcp - http - https example: https listen_port: description: Port the Load Balancer listens on. type: integer example: 443 destination_port: description: Port the Load Balancer will balance to. type: integer example: 80 proxyprotocol: description: Is Proxyprotocol enabled or not. type: boolean example: false health_check: allOf: - title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false additionalProperties: false - type: object required: - protocol - port - interval - timeout - retries - type: object properties: health_check: title: LoadBalancerServiceHealthCheck description: Service health check. type: object properties: protocol: description: Type of the health check. type: string enum: - tcp - http example: http port: description: Port the health check will be performed on. type: integer example: 4711 interval: description: Time interval in seconds health checks are performed. type: integer minimum: 3 maximum: 60 example: 15 timeout: description: Time in seconds after an attempt is considered a timeout. type: integer minimum: 1 maximum: 60 example: 10 retries: description: Unsuccessful retries needed until a target is considered unhealthy; an unhealthy target needs the same number of successful retries to become healthy again. type: integer minimum: 1 maximum: 5 example: 3 http: description: Additional configuration for protocol http. type: object properties: domain: description: Host header to send in the HTTP request. May not contain spaces, percent or backslash symbols. Can be null, in that case no host header is sent. type: string nullable: true maxLength: 128 example: example.com path: description: HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead. type: string minLength: 1 maxLength: 256 example: / response: description: String that must be contained in HTTP response in order to pass the health check. type: string maxLength: 256 example: '{"status": "ok"}' status_codes: description: List of returned HTTP status codes in order to pass the health check. Supports the wildcards `?` for exactly one character and `*` for multiple ones. type: array items: type: string default: - 2?? - 3?? maxItems: 20 example: - 2?? - 3?? tls: description: Use HTTPS for health check. type: boolean example: false additionalProperties: false additionalProperties: false http: title: LoadBalancerServiceHTTP description: Configuration option for protocols http and https. type: object properties: cookie_name: description: Name of the cookie used for sticky sessions. type: string minLength: 1 maxLength: 100 example: HCLBSTICKY cookie_lifetime: description: Lifetime of the cookie used for sticky sessions (in seconds). type: integer minimum: 30 maximum: 86400 example: 300 timeout_idle: description: Idle timeout in seconds for the client and server side. type: integer example: 50 certificates: description: IDs of the Certificates to use for TLS/SSL termination by the Load Balancer; empty for TLS/SSL passthrough or if `protocol` is `http`. type: array items: type: integer format: int64 example: - 897 redirect_http: description: Redirect HTTP requests to HTTPS. Only available if `protocol` is `https`. type: boolean default: false example: true sticky_sessions: description: Use sticky sessions. Only available if `protocol` is `http` or `https`. type: boolean default: false example: true required: - listen_port ZonePrimary: title: Primary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - primary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string example: primary required: - mode ZoneSecondary: title: Secondary Zone allOf: - type: object properties: id: description: ID of the [Zone](#tag/zones). type: integer format: int64 minimum: 1 maximum: 9007199254740991 example: 42 name: description: 'Name of the [Zone](#tag/zones). All names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`, `.com`, `.co.uk`) are supported. Subdomains are not supported. The name must be in lower case and must not end with a dot. [Internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be transcribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`). ' type: string maxLength: 255 example: example.com 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' primary_nameservers: description: 'Primary nameservers of the [Zone](#tag/zones). Only set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty. ' type: array items: description: 'Primary nameserver that returns [Zones](#tag/zones) via `AXFR`. Must allow queries from and may send `NOTIFY` queries to [Hetzner''s secondary nameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers). ' type: object properties: address: description: Public IPv4 or IPv6 address of the primary nameserver. type: string example: 198.51.100.1 port: description: Port of the primary nameserver. type: integer default: 53 example: 5353 tsig_key: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) key to use for the zone transfer. Must be base64 encoded. ' type: string tsig_algorithm: description: '[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm used to generate the TSIG key. ' type: string enum: - hmac-md5 - hmac-sha1 - hmac-sha256 required: - address example: - address: 198.51.100.1 port: 53 - address: 203.0.113.1 port: 53 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: '' protection: description: Protection configuration for the Resource. type: object properties: delete: description: Prevent the Resource from being deleted. type: boolean example: false required: - delete ttl: description: 'Default Time To Live (TTL) of the [Zone](#tag/zones). Must be in between 60s and 2147483647s. This TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL. ' type: integer default: 3600 minimum: 60 maximum: 2147483647 example: 10800 status: description: 'Status of the [Zone](#tag/zones). ' type: string enum: - ok - updating - error x-enumDescriptions: ok: The Zone is pushed to the authoritative nameservers. updating: The Zone is currently being published to the authoritative nameservers. error: The Zone could not be published to the authoritative nameservers. record_count: description: Number of resource records (RR) within the [Zone](#tag/zones). type: integer authoritative_nameservers: type: object properties: assigned: description: 'Authoritative Hetzner nameservers assigned to this [Zone](#tag/zones). ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegated: description: 'Authoritative nameservers currently delegated to by the parent DNS zone. If these don''t match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner. ' type: array items: type: string example: - hydrogen.ns.hetzner.com. - oxygen.ns.hetzner.com. - helium.ns.hetzner.de. delegation_last_check: description: 'Point in time (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format) when the DNS zone delegation was last checked. ' type: string format: date-time example: '2016-01-30T23:55:00Z' nullable: true delegation_status: description: 'Status of the delegation. ' type: string enum: - valid - partially-valid - invalid - lame - unregistered - unknown x-enumDescriptions: valid: Parent zone correctly delegates to assigned nameservers. partially-valid: Parent zone delegates to additional Hetzner nameservers not assigned to this zone. invalid: Parent zone does not delegate to the assigned nameservers. lame: Parent zone delegates to nameservers that don't know the zone. unregistered: Domain is not registered. unknown: Not yet known. required: - assigned - delegated - delegation_last_check registrar: description: Registrar of the domain. type: string enum: - hetzner - other - unknown required: - id - name - labels - created - status - ttl - record_count - protection - authoritative_nameservers - registrar - type: object properties: mode: enum: - secondary example: secondary description: 'Mode of the [Zone](#tag/zones). For more information, see [Zone Modes](#tag/zones/zone-modes). ' type: string required: - mode 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