{ "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.\n", "description": "# Overview\n\nThis is the official documentation for the Hetzner Cloud API.\n\n## Introduction\n\nThe Hetzner Cloud API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.\n\nAs an alternative to working directly with our API you may also consider to use:\n\n- Our CLI program [hcloud](https://github.com/hetznercloud/cli)\n- Our [library for Go](https://github.com/hetznercloud/hcloud-go)\n- Our [library for Python](https://github.com/hetznercloud/hcloud-python)\n\nYou can find even more libraries, tools and integrations on our [Awesome List on GitHub](https://github.com/hetznercloud/awesome-hcloud).\n\n### Open source credits\n\nIf you are developing an open-source project that supports or intends to add support for Hetzner APIs, you may be eligible for a free one-time credit of up to € 50 / $ 50 on your account. Please contact us via the support page on your [Hetzner Console](https://console.hetzner.cloud/support) and let us know the following:\n\n- The name of the project you are working on\n- A short description of the project\n- Link to the project website or repo where the project is hosted\n- Affiliation with / role in the project (e.g. project maintainer)\n- Link to some other open-source work you have already done (if you have done so)\n\n**Note:** We only consider rewards for projects that provide Hetzner-specific functionality or integrations. For example, our Object Storage exposes a standard S3 API without any Hetzner-specific extensions. Projects that focus solely on generic S3 capabilities (e.g., general S3 clients or SDKs) are not Hetzner-specific and are therefore not eligible for Hetzner Rewards.\n\n## Getting Started\n\nTo get started using the API you first need an API token. Sign in into the [Hetzner Console](https://console.hetzner.com/) choose a Project, go to `Security` → `API Tokens`, and generate a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is `LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj`.\n\nYou’re now ready to do your first request against the API. To get a list of all Servers in your Project, issue the example request on the right side using [curl](https://curl.se/).\n\nMake sure to replace the token in the example command with the token you have just created. Since your Project probably does not contain any Servers yet, the example response will look like the response on the right side. We will almost always provide a resource root like `servers` inside the example response. A response can also contain a `meta` object with information like [Pagination](#description/pagination).\n\n**Example Request**\n\n```shell\ncurl -H \"Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj\" \\\n https://api.hetzner.cloud/v1/servers\n```\n\n**Example Response**\n\n```json\n{\n \"servers\": [],\n \"meta\": {\n \"pagination\": {\n \"page\": 1,\n \"per_page\": 25,\n \"previous_page\": null,\n \"next_page\": null,\n \"last_page\": 1,\n \"total_entries\": 0\n }\n }\n}\n```\n\n## Authentication\n\nAll requests to the Hetzner Cloud API must be authenticated via a API token. Include your secret API token in every request you send to the API with the `Authorization` HTTP header.\n\nTo create a new API token for your Project, switch into the [Hetzner Console](https://console.hetzner.com/) choose a Project, go to `Security` → `API Tokens`, and generate a new token.\n\n**Example Authorization header**\n\n```http\nAuthorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj\n```\n\n## Query Parameters\n\nThe API makes use of query parameters to sort and filter responses. The parameter names and values must be URI encoded according to [RFC2396](https://datatracker.ietf.org/doc/html/rfc2396). Query parameters of type `array` can be used multiple times:\n\n**Example query parameters for pagination**\n\n```\nhttps://api.hetzner.cloud/v1/certificates?page=1&page_size=12\n```\n\n**Example use of multiple values for a parameter**\n\n```\nhttps://api.hetzner.cloud/v1/certificates?type=uploaded&type=managed\n```\n\n**Example use of an encoded parameter**\n\n```\nhttps://api.hetzner.cloud/v1/certificates?label_selector=key%3Dvalue\n```\n\n## Errors\n\nErrors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code.\n\nThe error response contains the following keys:\n\n| Keys | Meaning |\n| --------- | --------------------------------------------------------------------- |\n| `code` | Short string indicating the type of error (machine-parsable) |\n| `message` | Textual description on what has gone wrong |\n| `details` | An object providing for details on the error (schema depends on code) |\n\n**Example response**\n\n```json\n{\n \"error\": {\n \"code\": \"invalid_input\",\n \"message\": \"invalid input in field 'broken_field': is too long\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"broken_field\",\n \"messages\": [\"is too long\"]\n }\n ]\n }\n }\n}\n```\n\n### Error Codes\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `400` | `json_error` | Invalid JSON input in your request. |\n| `401` | `unauthorized` | Request was made with an invalid or unknown token. |\n| `401` | `token_readonly` | The token is only allowed to perform GET requests. |\n| `403` | `forbidden` | Insufficient permissions for this request. |\n| `403` | `maintenance` | Cannot perform operation due to maintenance. |\n| `403` | `resource_limit_exceeded` | Error when exceeding the maximum quantity of a resource for an account. |\n| `404` | `not_found` | Entity not found. |\n| `405` | `method_not_allowed` | The request method is not allowed |\n| `409` | `uniqueness_error` | One or more of the objects fields must be unique. |\n| `409` | `conflict` | The resource has changed during the request, please retry. |\n| `410` | `deprecated_api_endpoint` | The API endpoint functionality was removed. |\n| `412` | `resource_unavailable` | The requested resource is currently unavailable (e.g. not available for order). |\n| `422` | `invalid_input` | Error while parsing or processing the input. |\n| `422` | `service_error` | Error within a service. |\n| `422` | `unsupported_error` | The corresponding resource does not support the Action. |\n| `423` | `locked` | The item you are trying to access is locked (there is already an Action running). |\n| `423` | `protected` | The Action you are trying to start is protected for this resource. |\n| `429` | `rate_limit_exceeded` | Error when sending too many requests. |\n| `500` | `server_error` | Error within the API backend. |\n| `503` | `unavailable` | A service or product is currently not available. |\n| `504` | `timeout` | The request could not be answered in time, please retry. |\n\n**invalid_input**\n\n```json\n{\n \"error\": {\n \"code\": \"invalid_input\",\n \"message\": \"invalid input in field 'broken_field': is too long\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"broken_field\",\n \"messages\": [\"is too long\"]\n }\n ]\n }\n }\n}\n```\n\n**uniqueness_error**\n\n```json\n{\n \"error\": {\n \"code\": \"uniqueness_error\",\n \"message\": \"SSH key with the same fingerprint already exists\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"public_key\"\n }\n ]\n }\n }\n}\n```\n\n**resource_limit_exceeded**\n\n```json\n{\n \"error\": {\n \"code\": \"resource_limit_exceeded\",\n \"message\": \"project limit exceeded\",\n \"details\": {\n \"limits\": [\n {\n \"name\": \"project_limit\"\n }\n ]\n }\n }\n}\n```\n\n**deprecated_api_endpoint**\n\n```json\n{\n \"error\": {\n \"code\": \"deprecated_api_endpoint\",\n \"message\": \"API functionality was removed\",\n \"details\": {\n \"announcement\": \"https://docs.hetzner.cloud/changelog#2023-07-20-foo-endpoint-is-deprecated\"\n }\n }\n}\n```\n\n## Actions\n\nActions represent asynchronous tasks within the API, targeting one or more resources. Triggering changes in the API may return a `running` action.\n\nAn action should be waited upon, until it reaches either the `success` or `error` state. Avoid polling the action's state too frequently to reduce the risk of exhausting your API requests and hitting the [rate limit](#description/rate-limiting).\n\nIf an action fails, it will contain details about the underlying error.\n\nOnce the asynchronous tasks have completed and the targeted resources are in a consistent state, the action is marked as succeeded.\n\nIn some cases, you may trigger multiple changes at once, and only wait for the returned actions at a later stage.\n\n## Labels\n\nLabels are `key/value` pairs that can be attached to all resources.\n\nValid label keys have two segments: an optional prefix and name, separated by a slash (`/`). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (`.`), not longer than 253 characters in total, followed by a slash (`/`).\n\nValid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.\n\nThe `hetzner.cloud/` prefix is reserved and cannot be used.\n\n**Example Labels**\n\n```json\n{\n \"labels\": {\n \"environment\": \"development\",\n \"service\": \"backend\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\"\n }\n}\n```\n\n## Label Selector\n\nFor resources with labels, you can filter resources by their labels using the label selector query language.\n\n| Expression | Meaning |\n| -------------------- | ---------------------------------------------------- |\n| `k==v` / `k=v` | Value of key `k` does equal value `v` |\n| `k!=v` | Value of key `k` does not equal value `v` |\n| `k` | Key `k` is present |\n| `!k` | Key `k` is not present |\n| `k in (v1,v2,v3)` | Value of key `k` is `v1`, `v2`, or `v3` |\n| `k notin (v1,v2,v3)` | Value of key `k` is neither `v1`, nor `v2`, nor `v3` |\n| `k1==v,!k2` | Value of key `k1` is `v` and key `k2` is not present |\n\n### Examples\n\n- Returns all resources that have a `env=production` label and that don't have a `type=database` label:\n\n `env=production,type!=database`\n\n- Returns all resources that have a `env=testing` or `env=staging` label:\n\n `env in (testing,staging)`\n\n- Returns all resources that don't have a `type` label:\n\n `!type`\n\n## Pagination\n\nResponses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:\n\n- A `page` parameter specifies the page to fetch. The number of the first page is 1.\n- A `per_page` parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation.\n\nResponses contain a `Link` header with pagination information.\n\nAdditionally, if the response body is JSON and the root object is an object, that object has a `pagination` object inside the `meta` object with pagination information:\n\n**Example Pagination**\n\n```json\n{\n \"servers\": [...],\n \"meta\": {\n \"pagination\": {\n \"page\": 2,\n \"per_page\": 25,\n \"previous_page\": 1,\n \"next_page\": 3,\n \"last_page\": 4,\n \"total_entries\": 100\n }\n }\n}\n```\n\nThe keys `previous_page`, `next_page`, `last_page`, and `total_entries` may be `null` when on the first page, last page, or when the total number of entries is unknown.\n\n**Example Pagination Link header**\n\n```http\nLink: ; rel=\"prev\",\n ; rel=\"next\",\n ; rel=\"last\"\n```\n\nLine breaks have been added for display purposes only and responses may only contain some of the above `rel` values.\n\n## Rate Limiting\n\nAll requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a `429 Too Many Requests` error. Burst requests are allowed. Responses contain several headers which provide information about your current rate limit status.\n\n- The `RateLimit-Limit` header contains the total number of requests you can perform per hour.\n- The `RateLimit-Remaining` header contains the number of requests remaining in the current rate limit time frame.\n- The `RateLimit-Reset` header contains a UNIX timestamp of the point in time when your rate limit will have recovered, and you will have the full number of requests available again.\n\nThe default limit is 3600 requests per hour and per Project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second.\n\n## Server Metadata\n\nYour Server can discover metadata about itself by doing a HTTP request to specific URLs. The following data is available:\n\n| Data | Format | Contents |\n| ----------------- | ------ | ------------------------------------------------------------ |\n| hostname | text | Name of the Server as set in the api |\n| instance-id | number | ID of the server |\n| public-ipv4 | text | Primary public IPv4 address |\n| private-networks | yaml | Details about the private networks the Server is attached to |\n| availability-zone | text | Name of the availability zone that Server runs in |\n| region | text | Network zone, e.g. eu-central |\n\n**Example: Summary**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata\n```\n\n```yaml\navailability-zone: hel1-dc2\nhostname: my-server\ninstance-id: 42\npublic-ipv4: 1.2.3.4\nregion: eu-central\n```\n\n**Example: Hostname**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/hostname\nmy-server\n```\n\n**Example: Instance ID**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/instance-id\n42\n```\n\n**Example: Public IPv4**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/public-ipv4\n1.2.3.4\n```\n\n**Example: Private Networks**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/private-networks\n```\n\n```yaml\n- ip: 10.0.0.2\n alias_ips: [10.0.0.3, 10.0.0.4]\n interface_num: 1\n mac_address: 86:00:00:2a:7d:e0\n network_id: 1234\n network_name: nw-test1\n network: 10.0.0.0/8\n subnet: 10.0.0.0/24\n gateway: 10.0.0.1\n- ip: 192.168.0.2\n alias_ips: []\n interface_num: 2\n mac_address: 86:00:00:2a:7d:e1\n network_id: 4321\n network_name: nw-test2\n network: 192.168.0.0/16\n subnet: 192.168.0.0/24\n gateway: 192.168.0.1\n```\n\n**Example: Availability Zone**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/availability-zone\nhel1-dc2\n```\n\n**Example: Region**\n\n```shell\n$ curl http://169.254.169.254/hetzner/v1/metadata/region\neu-central\n```\n\n## Sorting\n\nSome responses which return multiple items support sorting. If they do support sorting the documentation states which fields can be used for sorting. You specify sorting with the `sort` query string parameter. You can sort by multiple fields. You can set the sort direction by appending `:asc` or `:desc` to the field name. By default, ascending sorting is used.\n\n**Example: Sorting**\n\n```\nhttps://api.hetzner.cloud/v1/actions?sort=status\nhttps://api.hetzner.cloud/v1/actions?sort=status:asc\nhttps://api.hetzner.cloud/v1/actions?sort=status:desc\nhttps://api.hetzner.cloud/v1/actions?sort=status:asc&sort=command:desc\n```\n\n## Deprecation Notices\n\nYou can find all announced deprecations in our [Changelog](/changelog).\n" }, "servers": [ { "url": "https://api.hetzner.cloud/v1" } ], "security": [ { "APIToken": [] } ], "tags": [ { "name": "Actions", "description": "Actions represent asynchronous tasks within the API, targeting one or more resources.\n\nSee [Actions](#description/actions) for more details.\n" }, { "name": "Certificates", "description": "TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic.\n" }, { "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.\n\nSee the [Hetzner Locations Docs](https://docs.hetzner.com/cloud/general/locations/#what-datacenters-are-there) for more details about Datacenters.\n" }, { "name": "Firewalls", "description": "Firewalls can limit the network access to or from your resources.\n\n- When applying a firewall with no `in` rule all inbound traffic will be dropped. The default for `in` is `DROP`.\n- When applying a firewall with no `out` rule all outbound traffic will be accepted. The default for `out` is `ACCEPT`.\n" }, { "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.\n\nFloating 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.\n\nFor Floating IPs to work with your Server, you must configure them inside your operation system.\n\nFloating 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.\n\nFloating IPs are billed on a monthly basis.\n" }, { "name": "Floating IP Actions" }, { "name": "Images", "description": "Images are blueprints for your VM disks. They can be of different types:\n\n### System Images\n\nDistribution Images maintained by us, e.g. “Ubuntu 20.04”\n\n### Snapshot Images\n\nMaintained by you, for example “Ubuntu 20.04 with my own settings”. These are billed per GB per month.\n\n### Backup Images\n\nDaily Backups of your Server. Will automatically be created for Servers which have backups enabled (`POST /servers/{id}/actions/enable_backup`)\n\nBound 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.\n\nThese are billed at 20% of your server price for 7 backup slots.\n\n### App Images\n\nPrebuild images with specific software configurations, e.g. “Wordpress”. All app images are created by us.\n" }, { "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.\n\nOn request our support uploads a private ISO just for you. These are marked with type `private` and only visible in your Project.\n\nTo attach an ISO to your Server use `POST /servers/{id}/actions/attach_iso`.\n" }, { "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.\n\nAll prices are displayed in the currency of the project owner's account.\n" }, { "name": "Locations", "description": "Datacenters are organized by Locations. Datacenters in the same Location are connected with very low latency links.\n" }, { "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.\n\nThey allow Servers to talk to each other over a dedicated network interface using private IP addresses not available publicly.\n\nThe 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.\n\nEach network has a user selected `ip_range` which defines all available IP addresses which can be used for Subnets within the Network.\n\nTo assign individual IPs to Servers you will need to create Network Subnets, described below.\n\nCurrently Networks support IPv4 only.\n\n### Subnets\n\nSubnets divide the `ip_range` from the parent Network object into multiple Subnetworks that you can use for different specific purposes.\n\nFor 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.\n\nCurrently there are three types of subnet:\n\n- type `cloud` is used to connect cloud Resources into your Network.\n- type `server` was used to connect only cloud Servers into your Network. This type is deprecated and is replaced by type cloud.\n- 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\n\nSubnets of type `vswitch` must set a `vswitch_id` which is the ID of the existing vSwitch in Hetzner Robot that should be coupled.\n\n### Network Zones\n\nNetwork 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:\n\n| Network Zone | Contains Locations |\n| ------------ | ------------------ |\n| eu-central | nbg1, fsn1, hel1 |\n| us-east | ash |\n| us-west | hil |\n| ap-southeast | sin |\n\n### IP address management\n\nWhen 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.\n\nA 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).\n\nThe following IP addresses are reserved in networks and can not be used:\n\n- the first IP of the network `ip_range` as it will be used as a default gateway for the private Network interface.\n- `172.31.1.1` as it is being used as default gateway for our public Network interfaces.\n\n### Coupling Dedicated Servers\n\nBy 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\ntalk to each other over the Network.\nIn 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.\n\n### Routes\n\nNetworks 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`.\n" }, { "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.\n\nIn `spread` placement groups, all virtual servers will run on different physical servers. This decreases the probability that some servers might fail together.\n" }, { "name": "Pricing", "description": "Returns prices for resources.\n" }, { "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.\n\nYou 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.\n\nPrimary 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.\n\nIf your Server's operating system supports cloud-init there is no further configuration needed to make Primary IPs work.\n\nPrimary 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.\n\nPrimary IPs are billed on an hourly basis.\n" }, { "name": "Primary IP Actions" }, { "name": "Servers", "description": "Servers are virtual machines that can be provisioned.\n" }, { "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.\n\nAll prices are displayed in the currency of the project owner's account.\n" }, { "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.\n" }, { "name": "Volumes", "description": "A Volume is a highly-available, scalable, and SSD-based block storage for Servers.\n\nPricing for Volumes depends on the Volume size and Location, not the actual used storage.\n\nPlease see [Hetzner Docs](https://docs.hetzner.com/cloud/#Volumes) for more details about Volumes.\n" }, { "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\nThis 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).\nAn RRSet is identified by a name and type. For example, the two RRs\n\n- (name: `@`, type: `MX`, value: `10 smtp.example.com.`) and\n- (name: `@`, type: `MX`, value: `20 smtp-backup.example.com.`)\n\nare part of the RRSet identified by (name: `@`, type: `MX`).\n\nPlease see [Hetzner Docs](https://docs.hetzner.com/networking/dns/record-types/overview) for more information on types.\n" }, { "name": "Zone RRSet Actions" } ], "paths": { "/actions": { "get": { "operationId": "get_actions", "summary": "Get multiple Actions", "description": "Returns multiple Action objects specified by the `id` parameter.\n\n**Note**: This endpoint previously allowed listing all actions in the project. This functionality was deprecated in July 2023 and removed on 30 January 2025.\n\n- Announcement: https://docs.hetzner.cloud/changelog#2023-07-20-actions-list-endpoint-is-deprecated\n- Removal: https://docs.hetzner.cloud/changelog#2025-01-30-listing-arbitrary-actions-in-the-actions-list-endpoint-is-removed\n", "tags": [ "Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.actions.get_by_id(123)" } ] } }, "/certificates": { "get": { "operationId": "list_certificates", "summary": "List Certificates", "description": "Returns all Certificate objects.\n", "tags": [ "Certificates" ], "parameters": [ { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by type. May be used multiple times.\n\nThe response will only contain the resources with the specified type.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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-----\n..." }, "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).\n", "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-----\n...", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ncertificates = 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.\n\nThe 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.\n\nIn 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.\n\nFor 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.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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-----\n..." }, "private_key": { "description": "Certificate key in PEM format. Required for type `uploaded` Certificates.", "type": "string", "example": "-----BEGIN PRIVATE KEY-----\n..." }, "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-----\n...", "private_key": "-----BEGIN PRIVATE KEY-----\n..." } }, "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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-----\n..." }, "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).\n", "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-----\n...", "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.\n", "tags": [ "Certificate Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = client.certificates.actions.get_all()" } ] } }, "/certificates/actions/{id}": { "get": { "operationId": "get_certificates_action", "summary": "Get an Action", "description": "Returns a specific Action object.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.certificates.actions.get_by_id(123)" } ] } }, "/certificates/{id}": { "get": { "operationId": "get_certificate", "summary": "Get a Certificate", "description": "Gets a specific Certificate object.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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-----\n..." }, "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).\n", "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-----\n...", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ncertificate = 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.\n\nNote: if the Certificate object changes during the request, the response will be a “conflict” error.\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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-----\n..." }, "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).\n", "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-----\n...", "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.\n", "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\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\nclient.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.\n\nOnly type `managed` Certificates can have Actions. For type `uploaded` Certificates the `actions` key will always contain an empty array.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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.\n\nOnly applicable if the type of the Certificate is `managed` and the issuance or renewal status is `failed`.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| | `caa_record_does_not_allow_ca` | CAA record does not allow certificate authority |\n| | `ca_dns_validation_failed` | Certificate Authority: DNS validation failed |\n| | `ca_too_many_authorizations_failed_recently` | Certificate Authority: Too many authorizations failed recently |\n| | `ca_too_many_certificates_issued_for_registered_domain` | Certificate Authority: Too many certificates issued for registered domain |\n| | `ca_too_many_duplicate_certificates` | Certificate Authority: Too many duplicate certificates |\n| | `could_not_verify_domain_delegated_to_zone` | Could not verify domain delegated to zone |\n| | `dns_zone_not_found` | DNS zone not found |\n| | `dns_zone_is_secondary_zone` | DNS zone is a secondary zone |\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\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\naction = client.certificates.retry_issuance(certificate=Certificate(id=123))\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud certificate retry $CERTIFICATE" } ] } }, "/certificates/{id}/actions/{action_id}": { "get": { "operationId": "get_certificate_action", "summary": "Get an Action for a Certificate", "description": "Returns a specific Action for a Certificate. Only type `managed` Certificates have Actions.\n", "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).\n", "tags": [ "Data Centers" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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`).\n\nRecommended [Data Center](#tag/data-centers) for creating new resources.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ndatacenters = 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).\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\ndatacenter = 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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Firewalls" ], "parameters": [ { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "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).\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n", "type": "string", "example": "new-name" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nUse `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs.\n", "type": "string", "enum": [ "in", "out" ], "example": "in" }, "source_ips": { "description": "List of permitted IPv4/IPv6 addresses for incoming traffic.\n\nThe `direction` must be set to `in`.\n\nIPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nThe `direction` must be set to `out`.\n\nIPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nOnly applicable for protocols `tcp` and `udp`.\n\nA port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include\nall ports starting from 1024 up to port 5000.\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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.\n\nOnly set for `type` `label_selector`, otherwise `null`.\n", "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).\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nfirewalls = 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).\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `server_already_added` | The [Server](#tag/servers) was applied more than once. |\n| `422` | `incompatible_network_type` | The resources network type is not supported by [Firewalls](#tag/firewalls). |\n| `422` | `firewall_resource_not_found` | The resource the [Firewall](#tag/firewalls) should be attached to was not found. |\n", "tags": [ "Firewalls" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "CreateFirewallRequest", "type": "object", "properties": { "name": { "description": "Name of the [Firewall](#tag/firewalls).\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n", "type": "string", "example": "new-name" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "rules": { "description": "Array of rules.\n\nRules are limited to 50 entries per [Firewall](#tag/firewalls) and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits).\n", "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.\n\nUse `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs.\n", "type": "string", "enum": [ "in", "out" ], "example": "in" }, "source_ips": { "description": "List of permitted IPv4/IPv6 addresses for incoming traffic.\n\nThe `direction` must be set to `in`.\n\nIPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nThe `direction` must be set to `out`.\n\nIPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nOnly applicable for protocols `tcp` and `udp`.\n\nA port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include\nall ports starting from 1024 up to port 5000.\n", "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.\n\nResources added directly are taking precedence over those added via a [Label Selector](#description/label-selector).\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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.\n\nOnly set for `type` `label_selector`, otherwise `null`.\n", "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).\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n", "type": "string", "example": "new-name" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nUse `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs.\n", "type": "string", "enum": [ "in", "out" ], "example": "in" }, "source_ips": { "description": "List of permitted IPv4/IPv6 addresses for incoming traffic.\n\nThe `direction` must be set to `in`.\n\nIPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nThe `direction` must be set to `out`.\n\nIPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nOnly applicable for protocols `tcp` and `udp`.\n\nA port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include\nall ports starting from 1024 up to port 5000.\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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.\n\nOnly set for `type` `label_selector`, otherwise `null`.\n", "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).\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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\tfirewall := 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\"]\nclient = 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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Firewall Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = client.firewalls.actions.get_all()" } ] } }, "/firewalls/actions/{id}": { "get": { "operationId": "get_firewalls_action", "summary": "Get an Action", "description": "Returns the specific [Action](#tag/actions).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.firewalls.actions.get_by_id(123)" } ] } }, "/firewalls/{id}": { "get": { "operationId": "get_firewall", "summary": "Get a Firewall", "description": "Returns a single [Firewall](#tag/firewalls).\n", "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).\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n", "type": "string", "example": "new-name" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nUse `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs.\n", "type": "string", "enum": [ "in", "out" ], "example": "in" }, "source_ips": { "description": "List of permitted IPv4/IPv6 addresses for incoming traffic.\n\nThe `direction` must be set to `in`.\n\nIPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nThe `direction` must be set to `out`.\n\nIPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nOnly applicable for protocols `tcp` and `udp`.\n\nA port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include\nall ports starting from 1024 up to port 5000.\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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.\n\nOnly set for `type` `label_selector`, otherwise `null`.\n", "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).\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nfirewall = 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).\n\nIn case of a parallel running change on the [Firewall](#tag/firewalls) a `conflict` error will be returned.\n", "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).\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n", "type": "string", "example": "new-name" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n", "type": "string", "example": "new-name" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nUse `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs.\n", "type": "string", "enum": [ "in", "out" ], "example": "in" }, "source_ips": { "description": "List of permitted IPv4/IPv6 addresses for incoming traffic.\n\nThe `direction` must be set to `in`.\n\nIPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nThe `direction` must be set to `out`.\n\nIPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nOnly applicable for protocols `tcp` and `udp`.\n\nA port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include\nall ports starting from 1024 up to port 5000.\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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.\n\nOnly set for `type` `label_selector`, otherwise `null`.\n", "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).\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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).\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `resource_in_use` | [Firewall](#tag/firewalls) still applied to a resource |\n", "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\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.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).\n\nUse the provided URI parameters to modify the result.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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.\n\nSupported resources:\n- [Servers](#tag/servers) (with a public network interface)\n- [Label Selectors](#description/label-selector)\n\nA [Server](#tag/servers) can be applied to [a maximum of 5 Firewalls](https://docs.hetzner.com/cloud/firewalls/overview#limits). This limit\napplies to [Servers](#tag/servers) applied via a matching [Label Selector](#description/label-selector) as well.\n\nUpdates to resources matching or no longer matching a [Label Selector](#description/label-selector) can take up to a few seconds\nto be processed.\n\nA [Firewall](#tag/firewalls) is applied to a resource once the related [Action](#tag/actions) with command `apply_firewall` successfully finished.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `404` | `firewall_resource_not_found` | The resource the [Firewall](#tag/firewalls) should be applied to was not found |\n| `422` | `firewall_already_applied` | [Firewall](#tag/firewalls) is already applied to resource |\n| `422` | `incompatible_network_type` | The network type of the resource is not supported by [Firewalls](#tag/firewalls) |\n| `422` | `private_net_only_server` | The [Server](#tag/servers) the [Firewall](#tag/firewalls) should be applied to has no public interface |\n", "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.\n\nExtends existing resources.\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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.\n\nOnly set for `type` `label_selector`, otherwise `null`.\n", "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.\n\nSupported resources:\n- [Servers](#tag/servers) (with a public network interface)\n\nA [Firewall](#tag/firewalls) is removed from a resource once the related [Action](#tag/actions) with command `remove_firewall` successfully finished.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `404` | `firewall_resource_not_found` | The resource the [Firewall](#tag/firewalls) should be removed from was not found |\n| `422` | `firewall_managed_by_label_selector` | [Firewall](#tag/firewall) is applied via a [Label Selector](#description/label-selector) and cannot be removed manually |\n", "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.\n\nOnly set for `type` `server`, otherwise `null`.\n", "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.\n\nOnly set for `type` `label_selector`, otherwise `null`.\n", "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).\n\nOverwrites the existing rules with the given ones. Pass an empty array to remove all rules.\n\nRules are limited to 50 entries per [Firewall](#tag/firewalls) and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits).\n", "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.\n\nRules are limited to 50 entries per [Firewall](#tag/firewalls) and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits).\n\nExisting rules will be replaced.\n", "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.\n\nUse `source_ips` for direction `in` and `destination_ips` for direction `out` to specify IPs.\n", "type": "string", "enum": [ "in", "out" ], "example": "in" }, "source_ips": { "description": "List of permitted IPv4/IPv6 addresses for incoming traffic.\n\nThe `direction` must be set to `in`.\n\nIPs must be provided in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nThe `direction` must be set to `out`.\n\nIPs must be in [CIDR block notation](https://wikipedia.org/wiki/CIDR). You can specify 100 CIDR\nblocks at most.\n\nThe CIDR blocks may refer to networks (with empty host bits) or single hosts.\nFor example, a network could be defined with `10.0.1.0/24` or `2001:db8:ff00:42::/64`,\nand a single host with `10.0.1.1/32` or `2001:db8:ff00:42::8329/128`.\n\nUse `0.0.0.0/0` to allow any IPv4 addresses and `::/0` to allow any IPv6 addresses.\n\nIPv6 CIDRs will be transformed to their canonical form according to [RFC5952](https://datatracker.ietf.org/doc/html/rfc5952#section-4).\n", "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.\n\nOnly applicable for protocols `tcp` and `udp`.\n\nA port range can be specified by separating lower and upper bounds with a dash. `1024-5000` will include\nall ports starting from 1024 up to port 5000.\n", "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": { "operationId": "get_firewall_action", "summary": "Get an Action for a Firewall", "description": "Returns a specific [Action](#tag/actions) for a [Firewall](#tag/firewalls).\n", "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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Floating IPs" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\n`null` if not assigned.\n", "type": "integer", "format": "int64", "nullable": true, "example": 42 }, "dns_ptr": { "description": "List of reverse DNS entries for the [Floating IP](#tag/floating-ips).\n", "type": "array", "items": { "type": "object", "properties": { "ip": { "description": "Single IPv4 or IPv6 address to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nfloating_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).\n\nProvide 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.\n", "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.\n\n`null` if not assigned.\n", "type": "integer", "format": "int64", "nullable": true, "example": 42 }, "home_location": { "description": "Home [Location](#tag/locations) for the [Floating IP](#tag/floating-ips).\n\nEither the ID or the name of the [Location](#tag/locations).\n\nOnly optional if no [Server](#tag/servers) is provided. Routing is optimized for this [Locations](#tag/locations).\n", "oneOf": [ { "description": "Home [Location](#tag/locations) for the [Floating IP](#tag/floating-ips).\n\nEither the ID or the name of the [Location](#tag/locations).\n\nOnly optional if no [Server](#tag/servers) is provided. Routing is optimized for this [Locations](#tag/locations).\n", "type": "string", "example": "fsn1" }, { "description": "Home [Location](#tag/locations) for the [Floating IP](#tag/floating-ips).\n\nEither the ID or the name of the [Location](#tag/locations).\n\nOnly optional if no [Server](#tag/servers) is provided. Routing is optimized for this [Locations](#tag/locations).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\n`null` if not assigned.\n", "type": "integer", "format": "int64", "nullable": true, "example": 42 }, "dns_ptr": { "description": "List of reverse DNS entries for the [Floating IP](#tag/floating-ips).\n", "type": "array", "items": { "type": "object", "properties": { "ip": { "description": "Single IPv4 or IPv6 address to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\tDescription: 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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Floating IP Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = 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).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = 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).\n", "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.\n\n`null` if not assigned.\n", "type": "integer", "format": "int64", "nullable": true, "example": 42 }, "dns_ptr": { "description": "List of reverse DNS entries for the [Floating IP](#tag/floating-ips).\n", "type": "array", "items": { "type": "object", "properties": { "ip": { "description": "Single IPv4 or IPv6 address to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nfloating_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).\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\n`null` if not assigned.\n", "type": "integer", "format": "int64", "nullable": true, "example": 42 }, "dns_ptr": { "description": "List of reverse DNS entries for the [Floating IP](#tag/floating-ips).\n", "type": "array", "items": { "type": "object", "properties": { "ip": { "description": "Single IPv4 or IPv6 address to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nIf 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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `must_be_unassigned` | Error when IP is still assigned to a Resource. This error will appear as of 1 May 2026. |\n", "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\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.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).\n\nUse the provided URI parameters to modify the result.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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).\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `floating_ip_assigned` | The [Floating IP](#tag/floating-ips) is already assigned |\n", "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.\n\n`null` if not assigned.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nAllows to modify the PTR records set for the IP address.\n", "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).\n\nThe `dns_ptr` attribute specifies the hostname used for the IP address. Must be a fully qualified domain name (FQDN) without trailing dot.\n\nFor IPv6 [Floating IPs](#tag/floating-ips) up to 100 entries can be created.\n", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "description": "Single IPv4 or IPv6 address to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "type": "string", "example": "server.example.com" } }, "required": [ "ip", "dns_ptr" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud 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).\n\nResults in the IP being unreachable. Can be assigned to another resource again.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\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.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": { "operationId": "get_floating_ip_action", "summary": "Get an Action for a Floating IP", "description": "Returns a specific [Action](#tag/actions) for a [Floating IP](#tag/floating-ips).\n", "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.\n", "tags": [ "Images" ], "parameters": [ { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources with the specified type.\n", "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.\n\nThe response will only contain the resources with the specified status.\n", "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.\n\nOnly available for Images of type `backup`.\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by cpu architecture.\n\nThe response will only contain the resources with the specified cpu architecture.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "architecture": { "description": "CPU architecture compatible with the Image.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nimages = 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.\n", "tags": [ "Image Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = client.images.actions.get_all()" } ] } }, "/images/actions/{id}": { "get": { "operationId": "get_images_action", "summary": "Get an Action", "description": "Returns a specific Action object.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.images.actions.get_by_id(123)" } ] } }, "/images/{id}": { "get": { "operationId": "get_image", "summary": "Get an Image", "description": "Returns a specific Image object.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "architecture": { "description": "CPU architecture compatible with the Image.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nimage = 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.\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "architecture": { "description": "CPU architecture compatible with the Image.\n", "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.\n", "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\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.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.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\thcloud.ImageChangeProtectionOpts{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.images import Image\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.images.change_protection(image=Image(id=123), delete=True)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud image enable-protection $IMAGE delete\nhcloud image disable-protection $IMAGE delete" } ] } }, "/images/{id}/actions/{action_id}": { "get": { "operationId": "get_image_action", "summary": "Get an Action for an Image", "description": "Returns a specific Action for an Image.\n", "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.\n", "tags": [ "ISOs" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by cpu architecture.\n\nThe response will only contain the resources with the specified cpu architecture.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "architecture": { "description": "CPU architecture compatible with the ISO.\n\nNull indicates no restriction on the architecture (wildcard).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nisos = 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.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "architecture": { "description": "CPU architecture compatible with the ISO.\n\nNull indicates no restriction on the architecture (wildcard).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\niso = 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.\n", "tags": [ "Load Balancer Types" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nload_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.\n", "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" ] } } } } } }, "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nload_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.\n", "tags": [ "Load Balancers" ], "parameters": [ { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "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" } } }, "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": [ "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" } } } }, "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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", "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": { "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", "example": 15 }, "timeout": { "description": "Time in seconds after an attempt is considered a timeout.", "type": "integer", "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", "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, "example": "example.com" }, "path": { "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.", "type": "string", "example": "/" }, "response": { "description": "String that must be contained in HTTP response in order to pass the health check.", "type": "string", "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??" ], "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" ] }, "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", "example": "HCLBSTICKY" }, "cookie_lifetime": { "description": "Lifetime of the cookie used for sticky sessions (in seconds).", "type": "integer", "default": 300, "example": 300 }, "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" ] } }, "targets": { "description": "List of targets that belong to this Load Balancer.", "type": "array", "items": { "title": "LoadBalancerTarget", "type": "object", "properties": { "type": { "description": "Type of the resource.", "type": "string", "enum": [ "server", "label_selector", "ip" ] }, "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" ] }, "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", "example": "env=prod" } }, "required": [ "selector" ] }, "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" } } } }, "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 }, "targets": { "description": "List of resolved label selector target Servers. Only present for type \"label_selector\".", "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" } } } }, "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" ] } }, "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nload_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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `412` | `source_port_already_used` | The source port you are trying to add is already in use |\n| `422` | `ip_not_owned` | The IP is not owned by the owner of the project of the Load Balancer |\n| `422` | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network |\n| `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 |\n| `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 |\n| `422` | `target_already_defined` | The Load Balancer target you are trying to define is already defined |\n", "tags": [ "Load Balancers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "CreateLoadBalancerRequest", "type": "object", "properties": { "name": { "description": "Name of the Load Balancer.", "type": "string", "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" ], "default": "round_robin" } }, "required": [ "type" ], "default": { "type": "round_robin" } }, "services": { "description": "Array of services.", "type": "array", "items": { "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": { "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", "example": 15 }, "timeout": { "description": "Time in seconds after an attempt is considered a timeout.", "type": "integer", "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", "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, "example": "example.com" }, "path": { "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.", "type": "string", "example": "/" }, "response": { "description": "String that must be contained in HTTP response in order to pass the health check.", "type": "string", "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??" ], "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" ] }, "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", "example": "HCLBSTICKY" }, "cookie_lifetime": { "description": "Lifetime of the cookie used for sticky sessions (in seconds).", "type": "integer", "default": 300, "example": 300 }, "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" ] } }, "targets": { "description": "Array of targets.", "type": "array", "items": { "title": "LoadBalancerTarget", "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" ] }, "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 }, "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", "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" ] } }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "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" } } }, "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": [ "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" } } } }, "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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", "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": { "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", "example": 15 }, "timeout": { "description": "Time in seconds after an attempt is considered a timeout.", "type": "integer", "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", "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, "example": "example.com" }, "path": { "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.", "type": "string", "example": "/" }, "response": { "description": "String that must be contained in HTTP response in order to pass the health check.", "type": "string", "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??" ], "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" ] }, "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", "example": "HCLBSTICKY" }, "cookie_lifetime": { "description": "Lifetime of the cookie used for sticky sessions (in seconds).", "type": "integer", "default": 300, "example": 300 }, "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" ] } }, "targets": { "description": "List of targets that belong to this Load Balancer.", "type": "array", "items": { "title": "LoadBalancerTarget", "type": "object", "properties": { "type": { "description": "Type of the resource.", "type": "string", "enum": [ "server", "label_selector", "ip" ] }, "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" ] }, "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", "example": "env=prod" } }, "required": [ "selector" ] }, "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" } } } }, "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 }, "targets": { "description": "List of resolved label selector target Servers. Only present for type \"label_selector\".", "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" } } } }, "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" ] } }, "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" }, "ipv6": { "ip": "2001:db8::1" } }, "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": "http", "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 } } ], "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\tResponse: 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\tPort: 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\tLabelSelector: 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.\n", "tags": [ "Load Balancer Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = 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.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = 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.\n", "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" } } }, "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": [ "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" } } } }, "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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", "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": { "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", "example": 15 }, "timeout": { "description": "Time in seconds after an attempt is considered a timeout.", "type": "integer", "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", "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, "example": "example.com" }, "path": { "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.", "type": "string", "example": "/" }, "response": { "description": "String that must be contained in HTTP response in order to pass the health check.", "type": "string", "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??" ], "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" ] }, "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", "example": "HCLBSTICKY" }, "cookie_lifetime": { "description": "Lifetime of the cookie used for sticky sessions (in seconds).", "type": "integer", "default": 300, "example": 300 }, "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" ] } }, "targets": { "description": "List of targets that belong to this Load Balancer.", "type": "array", "items": { "title": "LoadBalancerTarget", "type": "object", "properties": { "type": { "description": "Type of the resource.", "type": "string", "enum": [ "server", "label_selector", "ip" ] }, "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" ] }, "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", "example": "env=prod" } }, "required": [ "selector" ] }, "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" } } } }, "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 }, "targets": { "description": "List of resolved label selector target Servers. Only present for type \"label_selector\".", "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" } } } }, "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" ] } }, "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nload_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.\n\nNote: if the Load Balancer object changes during the request, the response will be a “conflict” error.\n", "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", "example": "new-name" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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" } } }, "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": [ "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" } } } }, "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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", "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": { "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", "example": 15 }, "timeout": { "description": "Time in seconds after an attempt is considered a timeout.", "type": "integer", "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", "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, "example": "example.com" }, "path": { "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.", "type": "string", "example": "/" }, "response": { "description": "String that must be contained in HTTP response in order to pass the health check.", "type": "string", "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??" ], "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" ] }, "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", "example": "HCLBSTICKY" }, "cookie_lifetime": { "description": "Lifetime of the cookie used for sticky sessions (in seconds).", "type": "integer", "default": 300, "example": 300 }, "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" ] } }, "targets": { "description": "List of targets that belong to this Load Balancer.", "type": "array", "items": { "title": "LoadBalancerTarget", "type": "object", "properties": { "type": { "description": "Type of the resource.", "type": "string", "enum": [ "server", "label_selector", "ip" ] }, "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" ] }, "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", "example": "env=prod" } }, "required": [ "selector" ] }, "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" } } } }, "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 }, "targets": { "description": "List of resolved label selector target Servers. Only present for type \"label_selector\".", "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" } } } }, "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" ] } }, "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" }, "ipv6": { "ip": "2001:db8::1" } }, "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": "http", "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 } } ], "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.\n", "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\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\nclient.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.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `412` | `source_port_already_used` | The source port you are trying to add is already in use |\n", "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": "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": { "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", "example": 15 }, "timeout": { "description": "Time in seconds after an attempt is considered a timeout.", "type": "integer", "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", "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, "example": "example.com" }, "path": { "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.", "type": "string", "example": "/" }, "response": { "description": "String that must be contained in HTTP response in order to pass the health check.", "type": "string", "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??" ], "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" ] }, "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", "example": "HCLBSTICKY" }, "cookie_lifetime": { "description": "Lifetime of the cookie used for sticky sessions (in seconds).", "type": "integer", "default": 300, "example": 300 }, "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\tStatusCodes: []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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `ip_not_in_vswitch_subnet` | The IP you are trying to add does not belong to the vswitch subnet of the attached network |\n| `422` | `ip_not_owned` | The IP you are trying to add as a target is not owned by the Project owner |\n| `422` | `load_balancer_public_interface_disabled` | The Load Balancer's public network interface is disabled |\n| `422` | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network |\n| `422` | `network_has_no_vswitch_subnet` | The given IP is private but attached network does not have a vswitch subnet |\n| `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 |\n| `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 |\n| `422` | `target_already_defined` | The Load Balancer target you are trying to define is already defined |\n", "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", "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" ] }, "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 }, "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", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud load-balancer add-target $LOADBALANCER --label-selector \"env=prod\"\nhcloud 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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `load_balancer_already_attached` | The Load Balancer is already attached to a network |\n| `422` | `ip_not_available` | The provided Network IP is not available |\n| `422` | `no_subnet_available` | No Subnet or IP is available for the Load Balancer within the network |\n", "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": 4711 }, "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.\n\nThis allows for auto assigning an IP address for a specific subnet.\nProviding `ip` that is not part of `ip_range` will result in an error.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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": { "type": { "description": "Algorithm of the Load Balancer.", "type": "string", "enum": [ "round_robin", "least_connections" ] } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nFloating IPs assigned to the Server are not affected by this.\n", "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": { "title": "ChangeLoadbalancerDnsPtrRequest", "type": "object", "properties": { "ip": { "description": "Public IP address for which the reverse DNS entry should be set.", "type": "string", "example": "1.2.3.4" }, "dns_ptr": { "description": "Hostname to set as a reverse DNS PTR entry.", "type": "string", "nullable": true, "example": "lb1.example.com" } }, "required": [ "ip", "dns_ptr" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud 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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `invalid_load_balancer_type` | The Load Balancer type does not fit for the given Load Balancer |\n", "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": "lb21" } }, "required": [ "load_balancer_type" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\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_balancer_types import LoadBalancerType\nfrom hcloud.load_balancers import LoadBalancer\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = 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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\naction = 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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network |\n| `422` | `targets_without_use_private_ip` | The Load Balancer has targets that use the public IP instead of the private IP |\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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": "RemoveTargetRequest", "type": "object", "properties": { "type": { "description": "Type of the resource.", "type": "string", "enum": [ "server", "label_selector", "ip" ] }, "server": { "description": "Configuration for type Server, 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": { "description": "Configuration for label selector targets, required if type is `label_selector`.", "type": "object", "properties": { "selector": { "description": "Label selector.", "type": "string", "example": "env=prod" } }, "required": [ "selector" ] }, "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" ] } }, "required": [ "type" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud load-balancer remove-target $LOADBALANCER --label-selector \"env=prod\"\nhcloud 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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `source_port_already_used` | The source port you are trying to add is already in use |\n", "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", "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": { "title": "UpdateLoadBalancerServiceHealthCheck", "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", "example": 15 }, "timeout": { "description": "Time in seconds after an attempt is considered a timeout.", "type": "integer", "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", "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, "example": "example.com" }, "path": { "description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.", "type": "string", "example": "/" }, "response": { "description": "String that must be contained in HTTP response in order to pass the health check.", "type": "string", "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??" ], "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", "example": "HCLBSTICKY" }, "cookie_lifetime": { "description": "Lifetime of the cookie used for sticky sessions (in seconds).", "type": "integer", "example": 300 }, "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\tStatusCodes: []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": { "operationId": "get_load_balancer_action", "summary": "Get an Action for a Load Balancer", "description": "Returns a specific Action for a Load Balancer.\n", "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`.\n\nDepending on the type you will get different time series data:\n\n|Type | Timeseries | Unit | Description |\n|---- |------------|------|-------------|\n| open_connections | open_connections | number | Open connections |\n| connections_per_second | connections_per_second | connections/s | Connections per second |\n| requests_per_second | requests_per_second | requests/s | Requests per second |\n| bandwidth | bandwidth.in | bytes/s | Ingress bandwidth |\n|| bandwidth.out | bytes/s | Egress bandwidth |\n\nMetrics are available for the last 30 days only.\n\nIf you do not provide the step argument we will automatically adjust it so that 200 samples are returned.\n\nWe limit the number of samples to a maximum of 500 and will adjust the step parameter accordingly.\n", "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\nfrom 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).\n", "tags": [ "Locations" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nlocations = 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).\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nlocation = 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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Networks" ], "parameters": [ { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "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).\n\nUses CIDR notation.\n", "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.\n", "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.\n\nUses CIDR notation.\n", "type": "string", "example": "10.0.1.0/24" }, "network_zone": { "description": "Name of the [Network Zone](#tag/network-zones).\n\nThe [Location](#tag/locations) contains the `network_zone` property it belongs to.\n", "type": "string", "example": "eu-central" }, "gateway": { "description": "Gateway for [Servers](#tag/servers) attached to this subnet.\n\nFor subnets of type `server` this is always the first IP of the subnets IP range.\n", "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.\n\nPackages addressed for IPs matching the destination IP prefix will be send to the specified gateway.\n\nMust be one of\n* private IPv4 ranges of RFC1918\n* or `0.0.0.0/0`.\n\nMust not overlap with\n* an existing ip_range in any subnets\n* or with any destinations in other routes\n* or with `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "type": "string", "example": "10.100.1.0/24" }, "gateway": { "description": "Gateway of the route.\n\nPackages addressed for the specified destination will be send to this IP address.\n\nCannot be\n* the first IP of the networks ip_range,\n* an IP behind a vSwitch or\n* `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nnetworks = 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).\n\nThe provided `ip_range` can only be extended later on, but not reduced.\n\nSubnets 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.\n\nRoutes can be added now or later by using the [add route action](#tag/network-actions/add_network_route).\n", "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).\n\nUses CIDR notation.\n\nMust span all included subnets. Must be one of the private IPv4 ranges of RFC1918.\n\nMinimum network size is /24. We highly recommend that you pick a larger [Network](#tag/networks) with a /16 netmask.\n", "type": "string" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n", "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.\n\nUses CIDR notation.\n\nMust be a subnet of the parent [Networks](#tag/networks) `ip_range`.\n\nMust not overlap with any other subnets or with any destinations in routes.\n\nMinimum network size is /30. We highly recommend that you pick a larger subnet with a /24 netmask.\n", "type": "string", "example": "10.0.1.0/24" }, "network_zone": { "description": "Name of the [Network Zone](#tag/network-zones).\n\nThe [Location](#tag/locations) contains the `network_zone` property it belongs to.\n", "type": "string", "example": "eu-central" }, "vswitch_id": { "description": "ID of the robot vSwitch.\n\nMust only be supplied for subnets of type `vswitch`.\n", "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.\n\nPackages addressed for IPs matching the destination IP prefix will be send to the specified gateway.\n\nMust be one of\n* private IPv4 ranges of RFC1918\n* or `0.0.0.0/0`.\n\nMust not overlap with\n* an existing ip_range in any subnets\n* or with any destinations in other routes\n* or with `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "type": "string", "example": "10.100.1.0/24" }, "gateway": { "description": "Gateway of the route.\n\nPackages addressed for the specified destination will be send to this IP address.\n\nCannot be\n* the first IP of the networks ip_range,\n* an IP behind a vSwitch or\n* `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "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.\n\nIndicates 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).\n", "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).\n\nUses CIDR notation.\n", "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.\n", "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.\n\nUses CIDR notation.\n", "type": "string", "example": "10.0.1.0/24" }, "network_zone": { "description": "Name of the [Network Zone](#tag/network-zones).\n\nThe [Location](#tag/locations) contains the `network_zone` property it belongs to.\n", "type": "string", "example": "eu-central" }, "gateway": { "description": "Gateway for [Servers](#tag/servers) attached to this subnet.\n\nFor subnets of type `server` this is always the first IP of the subnets IP range.\n", "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.\n\nPackages addressed for IPs matching the destination IP prefix will be send to the specified gateway.\n\nMust be one of\n* private IPv4 ranges of RFC1918\n* or `0.0.0.0/0`.\n\nMust not overlap with\n* an existing ip_range in any subnets\n* or with any destinations in other routes\n* or with `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "type": "string", "example": "10.100.1.0/24" }, "gateway": { "description": "Gateway of the route.\n\nPackages addressed for the specified destination will be send to this IP address.\n\nCannot be\n* the first IP of the networks ip_range,\n* an IP behind a vSwitch or\n* `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Network Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = client.networks.actions.get_all()" } ] } }, "/networks/actions/{id}": { "get": { "operationId": "get_networks_action", "summary": "Get an Action", "description": "Returns a single [Action](#tag/actions).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.networks.actions.get_by_id(123)" } ] } }, "/networks/{id}": { "get": { "operationId": "get_network", "summary": "Get a Network", "description": "Get a specific [Network](#tag/networks).\n", "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).\n\nUses CIDR notation.\n", "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.\n", "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.\n\nUses CIDR notation.\n", "type": "string", "example": "10.0.1.0/24" }, "network_zone": { "description": "Name of the [Network Zone](#tag/network-zones).\n\nThe [Location](#tag/locations) contains the `network_zone` property it belongs to.\n", "type": "string", "example": "eu-central" }, "gateway": { "description": "Gateway for [Servers](#tag/servers) attached to this subnet.\n\nFor subnets of type `server` this is always the first IP of the subnets IP range.\n", "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.\n\nPackages addressed for IPs matching the destination IP prefix will be send to the specified gateway.\n\nMust be one of\n* private IPv4 ranges of RFC1918\n* or `0.0.0.0/0`.\n\nMust not overlap with\n* an existing ip_range in any subnets\n* or with any destinations in other routes\n* or with `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "type": "string", "example": "10.100.1.0/24" }, "gateway": { "description": "Gateway of the route.\n\nPackages addressed for the specified destination will be send to this IP address.\n\nCannot be\n* the first IP of the networks ip_range,\n* an IP behind a vSwitch or\n* `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nnetwork = 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).\n\nIf a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned.\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nIndicates 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).\n", "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).\n\nUses CIDR notation.\n", "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.\n", "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.\n\nUses CIDR notation.\n", "type": "string", "example": "10.0.1.0/24" }, "network_zone": { "description": "Name of the [Network Zone](#tag/network-zones).\n\nThe [Location](#tag/locations) contains the `network_zone` property it belongs to.\n", "type": "string", "example": "eu-central" }, "gateway": { "description": "Gateway for [Servers](#tag/servers) attached to this subnet.\n\nFor subnets of type `server` this is always the first IP of the subnets IP range.\n", "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.\n\nPackages addressed for IPs matching the destination IP prefix will be send to the specified gateway.\n\nMust be one of\n* private IPv4 ranges of RFC1918\n* or `0.0.0.0/0`.\n\nMust not overlap with\n* an existing ip_range in any subnets\n* or with any destinations in other routes\n* or with `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "type": "string", "example": "10.100.1.0/24" }, "gateway": { "description": "Gateway of the route.\n\nPackages addressed for the specified destination will be send to this IP address.\n\nCannot be\n* the first IP of the networks ip_range,\n* an IP behind a vSwitch or\n* `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\nhcloud 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).\n\nAttached resources will be detached automatically.\n", "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).\n\nUse the provided URI parameters to modify the result.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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).\n\nIf a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned.\n", "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.\n\nPackages addressed for IPs matching the destination IP prefix will be send to the specified gateway.\n\nMust be one of\n* private IPv4 ranges of RFC1918\n* or `0.0.0.0/0`.\n\nMust not overlap with\n* an existing ip_range in any subnets\n* or with any destinations in other routes\n* or with `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "type": "string", "example": "10.100.1.0/24" }, "gateway": { "description": "Gateway of the route.\n\nPackages addressed for the specified destination will be send to this IP address.\n\nCannot be\n* the first IP of the networks ip_range,\n* an IP behind a vSwitch or\n* `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nIf the subnet `ip_range` is not provided, the first available `/24` IP range will be used.\n\nIf a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned.\n", "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.\n", "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.\n\nUses CIDR notation.\n\nMust be a subnet of the parent [Networks](#tag/networks) `ip_range`.\n\nMust not overlap with any other subnets or with any destinations in routes.\n\nMinimum network size is /30. We highly recommend that you pick a larger subnet with a /24 netmask.\n", "type": "string", "example": "10.0.1.0/24" }, "network_zone": { "description": "Name of the [Network Zone](#tag/network-zones).\n\nThe [Location](#tag/locations) contains the `network_zone` it belongs to.\n", "type": "string", "example": "eu-central" }, "vswitch_id": { "description": "ID of the robot vSwitch.\n\nMust be supplied if the subnet is of type `vswitch`.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\tMask: 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).\n\nThe following restrictions apply to changing the IP range:\n- IP ranges can only be extended and never shrunk.\n- IPs can only be added to the end of the existing range, therefore only the netmask is allowed to be changed.\n\nTo update the routes on the connected [Servers](#tag/servers), they need to be rebooted or the routes to be updated manually.\n\nFor 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.\n\nIf a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned.\n", "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).\n\nUses CIDR notation.\n\nMust span all included subnets. Must be one of the private IPv4 ranges of RFC1918.\n\nMinimum network size is /24. We highly recommend that you pick a larger [Network](#tag/networks) with a /16 netmask.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nIf a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned.\n", "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.\n\nIf true, prevents the [Network](#tag/networks) from being deleted.\n", "type": "boolean", "example": true } } } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud 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).\n\nIf a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned.\n", "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.\n\nPackages addressed for IPs matching the destination IP prefix will be send to the specified gateway.\n\nMust be one of\n* private IPv4 ranges of RFC1918\n* or `0.0.0.0/0`.\n\nMust not overlap with\n* an existing ip_range in any subnets\n* or with any destinations in other routes\n* or with `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "type": "string", "example": "10.100.1.0/24" }, "gateway": { "description": "Gateway of the route.\n\nPackages addressed for the specified destination will be send to this IP address.\n\nCannot be\n* the first IP of the networks ip_range,\n* an IP behind a vSwitch or\n* `172.31.1.1`.\n\n`172.31.1.1` is being used as a gateway for the public network interface of [Servers](#tag/servers).\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nSubnets containing attached resources can not be deleted, they must be detached beforehand.\n\nIf a change is currently being performed on this [Network](#tag/networks), a error response with code `conflict` will be returned.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\tMask: 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": { "operationId": "get_network_action", "summary": "Get an Action for a Network", "description": "Returns a specific [Action](#tag/actions) for a [Network](#tag/networks).\n", "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.\n", "tags": [ "Placement Groups" ], "parameters": [ { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by type. May be used multiple times.\n\nThe response will only contain the resources with the specified type.\n", "name": "type", "in": "query", "required": false, "schema": { "type": "array", "items": { "description": "Type of Placement Group.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "type": { "description": "Type of Placement Group.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nplacement_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.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "type": { "description": "Type of Placement Group.\n", "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.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "type": { "description": "Type of Placement Group.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nplacement_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.\n\nNote: if the Placement Group object changes during the request, the response will be a “conflict” error.\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "type": { "description": "Type of Placement Group.\n", "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.\n", "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.\n\nBoth net and gross prices are included in the response.\n", "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).\n\n**Deprecated**: This field is deprecated, please refer to the `floating_ips` field instead.\n\nSee the [Changelog](https://docs.hetzner.cloud/changelog#2024-08-29-field-floating_ip-in-pricing-response-is-now-deprecated) for more details.\n", "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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Primary IPs" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nUse the `location` property instead.\n\n[Data Center](#tag/data-centers) of the [Primary IP](#tag/primary-ips).\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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).\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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 to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "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.\n\nIf enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted.\n", "type": "boolean", "default": false, "example": true }, "assignee_type": { "description": "Type of resource the [Primary IP](#tag/primary-ips) can get assigned to.\n", "type": "string", "enum": [ "server" ], "example": "server" }, "assignee_id": { "description": "ID of resource the [Primary IP](#tag/primary-ips) is assigned to.\n\n`null` if the [Primary IP](#tag/primary-ips) is not assigned.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nprimary_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).\n\nCan optionally be assigned to a resource by providing an `assignee_id` and `assignee_type`.\n\nIf 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.\n\nA [Primary IP](#tag/primary-ips) can only be assigned to resource in the same [Location](#tag/locations) later on.\n\nThe `datacenter` key is deprecated in favor of `location` and will be removed after 01 July 2026.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `server_not_stopped` | The specified [Server](#tag/servers) is running, but needs to be powered off |\n| `422` | `server_has_ipv4` | The [Server](#tag/servers) already has an ipv4 address |\n| `422` | `server_has_ipv6` | The [Server](#tag/servers) already has an ipv6 address |\n", "tags": [ "Primary IPs" ], "requestBody": { "description": "Request Body for creating a new [Primary IP](#tag/primary-ips).\n\nThe `location`, `datacenter` and `assignee_id`/`assignee_type` attributes are mutually exclusive.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nUse the `location` key instead.\n\n[Data Center](#tag/data-centers) ID or name.\n\nThe [Primary IP](#tag/primary-ips) will be bound to this [Data Center](#tag/data-centers).\nOmit if `assignee_id`/`assignee_type` or `location` are provided.\n", "oneOf": [ { "description": "**Deprecated**: This property is deprecated and will be removed after 1 July 2026.\nUse the `location` key instead.\n\n[Data Center](#tag/data-centers) ID or name.\n\nThe [Primary IP](#tag/primary-ips) will be bound to this [Data Center](#tag/data-centers).\nOmit if `assignee_id`/`assignee_type` or `location` are provided.\n", "type": "string", "example": "fsn1-dc8" }, { "description": "**Deprecated**: This property is deprecated and will be removed after 1 July 2026.\nUse the `location` key instead.\n\n[Data Center](#tag/data-centers) ID or name.\n\nThe [Primary IP](#tag/primary-ips) will be bound to this [Data Center](#tag/data-centers).\nOmit if `assignee_id`/`assignee_type` or `location` are provided.\n", "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.\n\nOmit if `assignee_id`/`assignee_type` or `datacenter` are provided.\n", "oneOf": [ { "description": "[Location](#tag/locations) ID or name the [Primary IP](#tag/primary-ips) will be bound to.\n\nOmit if `assignee_id`/`assignee_type` or `datacenter` are provided.\n", "type": "string", "example": "fsn1" }, { "description": "[Location](#tag/locations) ID or name the [Primary IP](#tag/primary-ips) will be bound to.\n\nOmit if `assignee_id`/`assignee_type` or `datacenter` are provided.\n", "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.\n\nCurrently [Primary IPs](#tag/primary-ips) can only be assigned to [Servers](#tag/servers),\ntherefore this field must be set to `server`.\n", "type": "string", "enum": [ "server" ], "example": "server" }, "assignee_id": { "description": "ID of resource to assign the [Primary IP](#tag/primary-ips) to.\n\nOmitted if the [Primary IP](#tag/primary-ips) should not get assigned.\n", "type": "integer", "format": "int64", "nullable": true, "example": 17 }, "auto_delete": { "example": false, "description": "Auto deletion state.\n\nIf enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nUse the `location` property instead.\n\n[Data Center](#tag/data-centers) of the [Primary IP](#tag/primary-ips).\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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).\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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 to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "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.\n\nIf enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted.\n", "type": "boolean", "default": false, "example": true }, "assignee_type": { "description": "Type of resource the [Primary IP](#tag/primary-ips) can get assigned to.\n", "type": "string", "enum": [ "server" ], "example": "server" }, "assignee_id": { "description": "ID of resource the [Primary IP](#tag/primary-ips) is assigned to.\n\n`null` if the [Primary IP](#tag/primary-ips) is not assigned.\n", "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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Primary IP Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = 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).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = 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).\n\nUse the provided URI parameters to modify the result.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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": { "operationId": "get_primary_ip_action", "summary": "Get an Action for a Primary IP", "description": "Returns a specific [Action](#tag/actions) for a [Primary IP](#tag/primary-ips).\n", "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).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nUse the `location` property instead.\n\n[Data Center](#tag/data-centers) of the [Primary IP](#tag/primary-ips).\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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).\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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 to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "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.\n\nIf enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted.\n", "type": "boolean", "default": false, "example": true }, "assignee_type": { "description": "Type of resource the [Primary IP](#tag/primary-ips) can get assigned to.\n", "type": "string", "enum": [ "server" ], "example": "server" }, "assignee_id": { "description": "ID of resource the [Primary IP](#tag/primary-ips) is assigned to.\n\n`null` if the [Primary IP](#tag/primary-ips) is not assigned.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nprimary_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).\n\nIf another change is concurrently performed on this [Primary IP](#tag/primary-ips), a error response with code `conflict` will be returned.\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "auto_delete": { "description": "Auto deletion state.\n\nIf enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nUse the `location` property instead.\n\n[Data Center](#tag/data-centers) of the [Primary IP](#tag/primary-ips).\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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).\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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 to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "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.\n\nIf enabled the [Primary IP](#tag/primary-ips) will be deleted once the assigned resource gets deleted.\n", "type": "boolean", "default": false, "example": true }, "assignee_type": { "description": "Type of resource the [Primary IP](#tag/primary-ips) can get assigned to.\n", "type": "string", "enum": [ "server" ], "example": "server" }, "assignee_id": { "description": "ID of resource the [Primary IP](#tag/primary-ips) is assigned to.\n\n`null` if the [Primary IP](#tag/primary-ips) is not assigned.\n", "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).\n\nThe [Server](#tag/servers) must be powered off (status `off`) in order for this operation to succeed.\nIf 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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `must_be_unassigned` | Error when IP is still assigned to a Resource. This error will appear as of 1 May 2026. |\n", "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.\n\nA [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).\n\nA [Server](#tag/servers) must be powered off (status `off`) in order for this operation to succeed.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `server_not_stopped` | The [Server](#tag/servers) is running, but needs to be powered off |\n| `422` | `primary_ip_already_assigned` | [Primary IP](#tag/primary-ips) is already assigned to a different [Server](#tag/servers) |\n| `422` | `server_has_ipv4` | The [Server](#tag/servers) already has an IPv4 address |\n| `422` | `server_has_ipv6` | The [Server](#tag/servers) already has an IPv6 address |\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nAllows to modify the PTR records set for the IP address.\n", "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).\n\nThe `dns_ptr` attribute specifies the hostname used for the IP address. Must be a fully qualified domain name (FQDN) without trailing dot.\n\nFor IPv6 [Primary IPs](#tag/primary-ips) up to 100 entries can be created.\n", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "description": "Single IPv4 or IPv6 address to create pointer for.\n", "type": "string", "example": "2001:db8::1" }, "dns_ptr": { "description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n", "type": "string", "example": "server.example.com" } }, "required": [ "ip", "dns_ptr" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nA [Primary IPs](#tag/primary-ips) deletion protection can only be enabled if its `auto_delete` property is set to `false`.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud 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.\n\nA [Server](#tag/servers) must be powered off (status `off`) in order for this operation to succeed.\n\nA [Server](#tag/servers) requires at least one network interface (public or private) to be powered on.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `server_not_stopped` | The [Server](#tag/servers) is running, but needs to be powered off |\n| `422` | `server_is_load_balancer_target` | The [Server](#tag/servers) IPv4 address is a loadbalancer target |\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "tags": [ "Server Types" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "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.\n", "type": "string", "enum": [ "x86", "arm" ], "example": "x86" }, "deprecation": { "deprecated": true, "description": "This field is deprecated.\n\nUse the `deprecation` object in the `locations` field instead (`.locations[].deprecation`).\n", "title": "DeprecationInfo", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "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.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "recommended": { "type": "boolean", "example": false }, "available": { "type": "boolean", "example": true } }, "required": [ "id", "name", "deprecation" ] } } }, "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nserver_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.\n", "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.\n", "type": "string", "enum": [ "x86", "arm" ], "example": "x86" }, "deprecation": { "deprecated": true, "description": "This field is deprecated.\n\nUse the `deprecation` object in the `locations` field instead (`.locations[].deprecation`).\n", "title": "DeprecationInfo", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "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.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "recommended": { "type": "boolean", "example": false }, "available": { "type": "boolean", "example": true } }, "required": [ "id", "name", "deprecation" ] } } }, "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nserver_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.\n", "tags": [ "Servers" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources with the specified status.\n", "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.\n", "type": "string", "enum": [ "x86", "arm" ], "example": "x86" }, "deprecation": { "deprecated": true, "description": "This field is deprecated.\n\nUse the `deprecation` object in the `locations` field instead (`.locations[].deprecation`).\n", "title": "DeprecationInfo", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "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.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "recommended": { "type": "boolean", "example": false }, "available": { "type": "boolean", "example": true } }, "required": [ "id", "name", "deprecation" ] } } }, "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.\nUse the `location` property instead.\n\nData Center this Resource is located at.\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "architecture": { "description": "CPU architecture compatible with the Image.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "architecture": { "description": "CPU architecture compatible with the ISO.\n\nNull indicates no restriction on the architecture (wildcard).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "type": { "description": "Type of Placement Group.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nservers = 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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `412` | `primary_ip_version_mismatch` | The specified Primary IP has the wrong IP Version |\n| `422` | `placement_error` | An error during the placement occurred |\n| `422` | `primary_ip_assigned` | The specified Primary IP is already assigned to a server |\n| `422` | `primary_ip_datacenter_mismatch` | he specified Primary IP is in a different datacenter |\n", "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).\n\nFor `server_type` you can either use the ID as listed in `/server_types` or its name.\n\nFor `image` you can either use the ID as listed in `/images` or its name.\n\nIf you want to create the Server in a Location, you must set `location` to the ID or name as listed in `/locations`.\n\nSome 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.\n\nFor 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.\n\nPlease 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.\n", "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.\nUse the `location` property instead.\n\nID or name of the Data Center to create Server in (must not be used together with `location`).\n", "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\nruncmd:\n- [touch, /root/cloud-init-worked]\n" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n", "type": "string", "enum": [ "x86", "arm" ], "example": "x86" }, "deprecation": { "deprecated": true, "description": "This field is deprecated.\n\nUse the `deprecation` object in the `locations` field instead (`.locations[].deprecation`).\n", "title": "DeprecationInfo", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "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.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "recommended": { "type": "boolean", "example": false }, "available": { "type": "boolean", "example": true } }, "required": [ "id", "name", "deprecation" ] } } }, "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.\nUse the `location` property instead.\n\nData Center this Resource is located at.\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "architecture": { "description": "CPU architecture compatible with the Image.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "architecture": { "description": "CPU architecture compatible with the ISO.\n\nNull indicates no restriction on the architecture (wildcard).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "type": { "description": "Type of Placement Group.\n", "type": "string", "enum": [ "spread" ], "example": "spread" }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "servers": { "description": "Array of IDs of Servers that are part of this Placement Group.", "type": "array", "items": { "type": "integer", "format": "int64" }, "example": [ 42 ] } }, "required": [ "id", "name", "labels", "type", "created", "servers" ], "nullable": true } }, "required": [ "id", "name", "status", "created", "public_net", "private_net", "server_type", "location", "datacenter", "image", "iso", "rescue_enabled", "locked", "backup_window", "outgoing_traffic", "ingoing_traffic", "included_traffic", "protection", "labels", "primary_disk_size" ] }, "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] }, "next_actions": { "type": "array", "items": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "root_password": { "description": "Root password when no SSH keys have been specified.", "type": "string", "nullable": true, "example": "YItygq1v3GYjjMomLaKc" } }, "required": [ "server", "action", "next_actions", "root_password" ] }, "examples": { "default": { "value": { "server": { "id": 42, "name": "my-server", "status": "initializing", "created": "2016-01-30T23:50:00Z", "public_net": { "ipv4": { "ip": "1.2.3.4", "blocked": false, "dns_ptr": "server01.example.com" }, "ipv6": { "ip": "2001:db8::/64", "blocked": false, "dns_ptr": [ { "ip": "2001:db8::1", "dns_ptr": "server.example.com" } ] }, "floating_ips": [ 478 ], "firewalls": [ { "id": 38, "status": "applied" } ] }, "private_net": [ { "network": 4711, "ip": "10.0.0.2", "alias_ips": [], "mac_address": "86:00:ff:2a:7d:e1" } ], "server_type": { "id": 1, "name": "cpx22", "description": "CPX22", "cores": 2, "memory": 4, "disk": 80, "deprecated": true, "prices": [ { "location": "fsn1", "price_hourly": { "net": "1.0000000000", "gross": "1.1900000000000000" }, "price_monthly": { "net": "1.0000000000", "gross": "1.1900000000000000" }, "included_traffic": 21990232555520, "price_per_tb_traffic": { "net": "1.0000000000", "gross": "1.1900000000000000" } } ], "storage_type": "local", "cpu_type": "shared", "architecture": "x86", "locations": [ { "id": 1, "name": "fsn1", "deprecation": null, "available": true, "recommended": true }, { "id": 2, "name": "nbg1", "deprecation": { "announced": "2018-02-28T00:00:00Z", "unavailable_after": "2018-05-31T00:00:00Z" }, "available": false, "recommended": false } ] }, "location": { "id": 1, "name": "fsn1", "description": "Falkenstein DC Park 1", "country": "DE", "city": "Falkenstein", "latitude": 50.47612, "longitude": 12.370071, "network_zone": "eu-central" }, "datacenter": { "id": 1, "name": "fsn1-dc8", "description": "Falkenstein 1 DC 8", "location": { "id": 1, "name": "fsn1", "description": "Falkenstein DC Park 1", "country": "DE", "city": "Falkenstein", "latitude": 50.47612, "longitude": 12.370071, "network_zone": "eu-central" }, "server_types": { "supported": [ 1, 2, 3 ], "available": [ 1, 2, 3 ], "available_for_migration": [ 1, 2, 3 ] } }, "image": { "id": 4711, "type": "snapshot", "status": "available", "name": "ubuntu-24.04", "description": "Ubuntu 24.04 Standard 64 bit", "image_size": 2.3, "disk_size": 10, "created": "2016-01-30T23:50:00Z", "created_from": { "id": 1, "name": "Server" }, "bound_to": null, "os_flavor": "ubuntu", "os_version": "24.04", "rapid_deploy": false, "protection": { "delete": false }, "deprecated": "2018-02-28T00:00:00Z", "deleted": null, "labels": { "key": "value" }, "architecture": "x86" }, "iso": { "id": 4711, "name": "FreeBSD-11.0-RELEASE-amd64-dvd1", "description": "FreeBSD 11.0 x64", "type": "public", "deprecation": { "announced": "2018-02-28T00:00:00Z", "unavailable_after": "2018-05-31T00:00:00Z" }, "architecture": "x86" }, "rescue_enabled": false, "locked": false, "backup_window": "22-02", "outgoing_traffic": 123456, "ingoing_traffic": 123456, "included_traffic": 654321, "protection": { "delete": false, "rebuild": false }, "labels": { "key": "value" }, "volumes": [], "load_balancers": [], "primary_disk_size": 50 }, "action": { "id": 1, "command": "create_server", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "server" } ], "error": { "code": "action_failed", "message": "Action failed" } }, "next_actions": [ { "id": 13, "command": "start_server", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "server" } ], "error": { "code": "action_failed", "message": "Action failed" } } ], "root_password": "YItygq1v3GYjjMomLaKc" } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.Server.Create(ctx, hcloud.ServerCreateOpts{\n\t\tAutomount: hcloud.Ptr(false),\n\t\tFirewalls: []*hcloud.ServerCreateFirewall{\n\t\t\t{\n\t\t\t\tFirewall: hcloud.Firewall{ID: 38},\n\t\t\t},\n\t\t},\n\t\tImage: &hcloud.Image{Name: \"ubuntu-24.04\"},\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t\tLocation: &hcloud.Location{Name: \"nbg1\"},\n\t\tName: \"my-server\",\n\t\tNetworks: []*hcloud.Network{\n\t\t\t{\n\t\t\t\tID: 456,\n\t\t\t},\n\t\t},\n\t\tPlacementGroup: &hcloud.PlacementGroup{ID: 1},\n\t\tPublicNet: &hcloud.ServerCreatePublicNet{\n\t\t\tEnableIPv4: false,\n\t\t\tEnableIPv6: false,\n\t\t\tIPv4: nil,\n\t\t\tIPv6: nil,\n\t\t},\n\t\tServerType: &hcloud.ServerType{Name: \"cx23\"},\n\t\tSSHKeys: []*hcloud.SSHKey{\n\t\t\t{\n\t\t\t\tName: \"my-ssh-key\",\n\t\t\t},\n\t\t},\n\t\tStartAfterCreate: hcloud.Ptr(true),\n\t\tUserData: \"#cloud-config\\nruncmd:\\n- [touch, /root/cloud-init-worked]\\n\",\n\t\tVolumes: []*hcloud.Volume{\n\t\t\t{\n\t\t\t\tID: 123,\n\t\t\t},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tserver := result.Server\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.firewalls import Firewall\nfrom hcloud.images import Image\nfrom hcloud.locations import Location\nfrom hcloud.networks import Network\nfrom hcloud.placement_groups import PlacementGroup\nfrom hcloud.server_types import ServerType\nfrom hcloud.servers import ServerCreatePublicNetwork\nfrom hcloud.ssh_keys import SSHKey\nfrom hcloud.volumes import Volume\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.servers.create(\n automount=False,\n firewalls=[Firewall(id=38)],\n image=Image(name=\"ubuntu-24.04\"),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n location=Location(name=\"hel1\"),\n name=\"my-server\",\n networks=[Network(id=456)],\n placement_group=PlacementGroup(id=1),\n public_net=ServerCreatePublicNetwork(\n enable_ipv4=False,\n enable_ipv6=False,\n ipv4=None,\n ipv6=None,\n ),\n server_type=ServerType(name=\"cpx22\"),\n ssh_keys=[SSHKey(name=\"my-ssh-key\")],\n start_after_create=True,\n user_data=\"#cloud-config\\nruncmd:\\n- [touch, /root/cloud-init-worked]\\n\",\n volumes=[Volume(id=123)],\n)\n\nresponse.action.wait_until_finished()\n\nserver = response.server" }, { "lang": "Shell", "label": "CLI", "source": "hcloud server create \\\n --automount=false \\\n --firewall 38 \\\n --image ubuntu-24.04 \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\" \\\n --location hel1 \\\n --name my-server \\\n --network 456 \\\n --placement-group 1 \\\n --without-ipv4 \\\n --without-ipv6 \\\n --type cpx22 \\\n --ssh-key my-ssh-key \\\n --start-after-create \\\n --volume 123 \\\n --user-data-from-file <(printf '#cloud-config\\nruncmd:\\n- [touch, /root/cloud-init-worked]\\n')" } ] } }, "/servers/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.\n", "tags": [ "Server Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = client.servers.actions.get_all()" } ] } }, "/servers/actions/{id}": { "get": { "operationId": "get_servers_action", "summary": "Get an Action", "description": "Returns a specific Action object.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = 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.\n", "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.\n", "type": "string", "enum": [ "x86", "arm" ], "example": "x86" }, "deprecation": { "deprecated": true, "description": "This field is deprecated.\n\nUse the `deprecation` object in the `locations` field instead (`.locations[].deprecation`).\n", "title": "DeprecationInfo", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "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.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "recommended": { "type": "boolean", "example": false }, "available": { "type": "boolean", "example": true } }, "required": [ "id", "name", "deprecation" ] } } }, "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.\nUse the `location` property instead.\n\nData Center this Resource is located at.\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "architecture": { "description": "CPU architecture compatible with the Image.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "architecture": { "description": "CPU architecture compatible with the ISO.\n\nNull indicates no restriction on the architecture (wildcard).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "type": { "description": "Type of Placement Group.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nserver = 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.\n\nPlease 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).\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n", "type": "string", "enum": [ "x86", "arm" ], "example": "x86" }, "deprecation": { "deprecated": true, "description": "This field is deprecated.\n\nUse the `deprecation` object in the `locations` field instead (`.locations[].deprecation`).\n", "title": "DeprecationInfo", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "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.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "recommended": { "type": "boolean", "example": false }, "available": { "type": "boolean", "example": true } }, "required": [ "id", "name", "deprecation" ] } } }, "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.\nUse the `location` property instead.\n\nData Center this Resource is located at.\n", "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).\n\nMay be used as a more descriptive identifier.\n", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1-dc8" }, "description": { "description": "Descriptive name for the [Data Center](#tag/data-centers).\n\nDesired to be easy to understand for humans. May change for cosmetic reasons. Must not be used as an identifier.\n", "type": "string", "example": "Falkenstein DC Park 8" }, "location": { "description": "[Location](#tag/locations) the [Data Center](#tag/data-centers) is located at.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\n\n[Server Types](#tag/server-types) supported and available in this [Data Center](#tag/data-centers).\n", "type": "object", "properties": { "supported": { "deprecated": true, "description": "This field is deprecated. Use the [Server Type](#tag/server-types) `locations` field instead.\n\nList of [Server Types](#tag/server-types) supported in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) are generally available in this Data Center, but may be\ntemporarily out of stock.\n", "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`).\n\n[Server Types](#tag/server-types) currently available in this [Data Center](#tag/data-centers).\n\nThese [Server Types](#tag/server-types) can currently be purchased. Types that are temporarily unavailable\nbut are supported in this [Data Center](#tag/data-centers) are listed as `supported`.\n", "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`).\n\n[Server Types](#tag/server-types) available to migrate to in this [Data Center](#tag/data-centers).\n\nExisting [Servers](#tag/servers) can be migrated to these [Server Types](#tag/server-types).\n", "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.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "architecture": { "description": "CPU architecture compatible with the Image.\n", "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\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] }, "architecture": { "description": "CPU architecture compatible with the ISO.\n\nNull indicates no restriction on the architecture (wildcard).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "type": { "description": "Type of Placement Group.\n", "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.\n\nThis immediately removes the Server from your account, and it is no longer\naccessible. Any resources attached to the server (like Volumes, Primary IPs,\nFloating IPs, Firewalls, Placement Groups) are detached while the server is deleted.\n", "tags": [ "Servers" ], "parameters": [ { "description": "ID of the Server.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Server](#tag/servers).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.Server.DeleteWithResult(ctx, &hcloud.Server{ID: 123})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.servers.delete(\n server=Server(id=123),\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud server delete $SERVER" } ] } }, "/servers/{id}/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.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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.\n\nServer must be powered off for this command to succeed.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `server_not_stopped` | The action requires a stopped server |\n| `422` | `already_in_placement_group` | The server is already part of a placement group |\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nServers with attached ISOs have a modified boot order: They will try to boot from the ISO first before falling back to hard disk.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nThe Server will get an IP auto assigned from a subnet of type `server` in the same `network_zone`.\n\nUsing 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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `server_already_attached` | The server is already attached to the network |\n| `422` | `ip_not_available` | The provided Network IP is not available |\n| `422` | `no_subnet_available` | No Subnet or IP is available for the Server within the network |\n| `422` | `networks_overlap` | The network IP range overlaps with one of the server networks |\n", "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.\n\nThis allows for auto assigning an IP address for a specific subnet.\nProviding `ip` that is not part of `ip_range` will result in an error.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nFloating IPs assigned to the Server are not affected by this.\n", "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": "Primary IP address for which the reverse DNS entry should be set.", "type": "string", "example": "1.2.3.4" }, "dns_ptr": { "description": "Hostname to set as a reverse DNS PTR entry, reset to original value if `null`.", "type": "string", "nullable": true, "example": "server01.example.com" } }, "required": [ "ip", "dns_ptr" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud 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.\n\nServer must be powered off for this command to succeed.\n\nThis copies the content of its disk, and starts it again.\n\nYou 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.\n\nIf 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`.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `invalid_server_type` | The server type does not fit for the given server or is deprecated |\n| `422` | `server_not_stopped` | The action requires a stopped server |\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nTo make sure disk content is consistent, we recommend to shut down the Server prior to creating an Image.\n\nYou 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.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "architecture": { "description": "CPU architecture compatible with the Image.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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`.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nCaution: This immediately removes all existing backups for the Server!\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nRescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.\n\nDisabling rescue mode will not reboot your Server — you will have to do this yourself.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nBackups are automatically created daily.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nIn case a Server cannot boot on its own you can use this to access a Server’s disks.\n\nRescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.\n\nEnabling rescue mode will not [reboot](https://docs.hetzner.cloud/#server-actions-soft-reboot-a-server) your Server — you will have to do this yourself.\n", "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.\n", "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\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\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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\n\nThe 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`.\n\nYour Server will automatically be powered off before the rebuild command executes.\n", "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\nruncmd:\n- [touch, /root/cloud-init-worked]\n" } }, "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\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.images import Image\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.servers.rebuild(server=Server(id=123), image=Image(name=\"ubuntu-24.04\"))\n\naction.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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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\terr = 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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n\nThis will generate a new password for this Server and return it.\n\nIf this does not succeed you can use the rescue system to netboot the Server and manually change your Server password by hand.\n", "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.\n", "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\nand react to the request, otherwise the Server will not shut down. Please note that the `action` status in this case\nonly reflects whether the action was sent to the server. It does not mean that the server actually shut down\nsuccessfully. If you need to ensure that the server is off, use the `poweroff` action.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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": { "operationId": "get_server_action", "summary": "Get an Action for a Server", "description": "Returns a specific Action object for a Server.\n", "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.\n\nYou 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.\n\nDepending on the type you will get different time series data\n\n| Type | Timeseries | Unit | Description |\n|---------|-------------------------|-----------|------------------------------------------------------|\n| cpu | cpu | percent | Percent CPU usage |\n| disk | disk.0.iops.read | iop/s | Number of read IO operations per second |\n| | disk.0.iops.write | iop/s | Number of write IO operations per second |\n| | disk.0.bandwidth.read | bytes/s | Bytes read per second |\n| | disk.0.bandwidth.write | bytes/s | Bytes written per second |\n| network | network.0.pps.in | packets/s | Public Network interface packets per second received |\n| | network.0.pps.out | packets/s | Public Network interface packets per second sent |\n| | network.0.bandwidth.in | bytes/s | Public Network interface bytes/s received |\n| | network.0.bandwidth.out | bytes/s | Public Network interface bytes/s sent |\n\nMetrics are available for the last 30 days only.\n\nIf you do not provide the step argument we will automatically adjust it so that a maximum of 200 samples are returned.\n\nWe limit the number of samples returned to a maximum of 500 and will adjust the step parameter accordingly.\n", "tags": [ "Servers" ], "parameters": [ { "description": "ID of the Server.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Server](#tag/servers).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "Type of metrics to get.", "name": "type", "in": "query", "required": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "cpu", "disk", "network" ] } } }, { "description": "Start of period to get Metrics for (must be in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "name": "start", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "End of period to get Metrics for (must be in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "name": "end", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "Resolution of results in seconds.", "name": "step", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "metrics": { "type": "object", "properties": { "start": { "description": "Start of period of metrics reported (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2017-01-01T00:00:00Z" }, "end": { "description": "End of period of metrics reported (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2017-01-01T23:00:00Z" }, "step": { "description": "Resolution of results in seconds.", "type": "number", "example": 60 }, "time_series": { "description": "Hash with timeseries information, containing the name of timeseries as key.", "type": "object", "additionalProperties": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "array", "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, "description": "Metrics Timestamps with values." } }, "required": [ "values" ] }, "example": { "name_of_timeseries": { "values": [ [ 1435781470.622, "42" ], [ 1435781471.622, "43" ] ] } } } }, "required": [ "start", "end", "step", "time_series" ] } }, "required": [ "metrics" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\t\"time\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tmetrics, _, err := client.Server.GetMetrics(ctx, &hcloud.Server{ID: 123}, hcloud.ServerGetMetricsOpts{\n\t\tStart: time.Date(2017, 1, 1, 0, 0, 0, 0, time.UTC),\n\t\tEnd: time.Date(2017, 1, 1, 23, 0, 0, 0, time.UTC),\n\t\tStep: 60,\n\t\tTypes: []hcloud.ServerMetricType{\n\t\t\thcloud.ServerMetricCPU,\n\t\t\thcloud.ServerMetricNetwork,\n\t\t\thcloud.ServerMetricDisk,\n\t\t},\n\t})\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nimport datetime\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.servers import Server\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.servers.get_metrics(\n server=Server(id=123),\n start=datetime.datetime(2017, 1, 1, 0, 0, 0, 0, datetime.UTC),\n end=datetime.datetime(2017, 1, 1, 23, 0, 0, 0, datetime.UTC),\n step=60,\n type=[\n \"cpu\",\n \"network\",\n \"disk\",\n ],\n)\n\nresponse.action.wait_until_finished()\n\nmetrics = response.metrics" }, { "lang": "Shell", "label": "CLI", "source": "hcloud server metrics $SERVER \\\n --type cpu,network,disk \\\n --start 2017-01-01T00:00:00Z \\\n --end 2017-01-01T23:00:00Z" } ] } }, "/ssh_keys": { "get": { "operationId": "list_ssh_keys", "summary": "List SSH keys", "description": "Returns all SSH key objects.\n", "tags": [ "SSH Keys" ], "parameters": [ { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "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.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nssh_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.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\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.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.\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n", "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.\n", "tags": [ "Volumes" ], "parameters": [ { "description": "Filter resources by status. May be used multiple times.\n\nThe response will only contain the resources with the specified status.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nvolumes = 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.\n\nSpecifying 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.\n\nThe minimum Volume size is 10GB and the maximum size is 10TB (10240GB).\n\nA 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.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `no_space_left_in_location` | There is no volume space left in the given location |\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n", "tags": [ "Volume Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = client.volumes.actions.get_all()" } ] } }, "/volumes/actions/{id}": { "get": { "operationId": "get_volumes_action", "summary": "Get an Action", "description": "Returns a specific Action object.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.volumes.actions.get_by_id(123)" } ] } }, "/volumes/{id}": { "get": { "operationId": "get_volume", "summary": "Get a Volume", "description": "Gets a specific Volume object.\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nvolume = 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.\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n", "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.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud 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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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": { "operationId": "get_volume_action", "summary": "Get an Action for a Volume", "description": "Returns a specific Action for a Volume.\n", "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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Zones" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by their mode.\n\nThe response will only contain the resources matching exactly the specified mode.\n", "name": "mode", "in": "query", "required": false, "schema": { "description": "Mode of the [Zone](#tag/zones).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "type": "string", "enum": [ "primary", "secondary" ], "example": "primary" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nzones = 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).\n\nA default `SOA` and three `NS` resource records with the assigned Hetzner\nnameservers are created automatically.\n", "tags": [ "Zones" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Name of the [Zone](#tag/zones).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "type": "string", "maxLength": 255, "example": "example.com" }, "mode": { "description": "Mode of the [Zone](#tag/zones).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "type": "string", "enum": [ "primary", "secondary" ], "example": "primary" }, "ttl": { "description": "Default Time To Live (TTL) of the [Zone](#tag/zones).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nOnly applicable for [Zones](#tag/zones) in secondary mode.\nIgnored for [Zones](#tag/zones) in primary mode.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\nIgnored for [Zones](#tag/zones) in secondary mode.\n", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "Name of the [RRSet](#tag/zone-rrsets).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" }, "type": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the [Zone's](#tag/zones) Default TTL is used.\n", "type": "integer", "nullable": true, "minimum": 60, "maximum": 2147483647, "example": 3600 }, "records": { "description": "Records of the [RRSet](#tag/zone-rrsets).\n\nMust not be empty and must only contain distinct record values.\nThe order of records returned in responses is not guaranteed to be consistent.\n", "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\nIgnored for [Zones](#tag/zones) in secondary mode.\n\nIf provided, `rrsets` must be empty.\n\nSee [Zone file import](#tag/zones/zone-file-import) for more details.\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\tNS\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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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).\n", "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nzone = 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).\n\nTo modify resource record sets ([RRSets](#tag/zone-rrsets)), use the [RRSet Actions\nendpoints](#tag/zone-rrset-actions).\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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).\n", "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\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\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.\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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\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", "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\tNS\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).\n\nUse the provided URI parameters to modify the result.\n", "tags": [ "Zone Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = client.zones.actions.get_all()" } ] } }, "/zones/actions/{id}": { "get": { "operationId": "get_zones_action", "summary": "Get an Action", "description": "Returns a specific [Action](#tag/actions).\n", "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\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = 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).\n\nUse the provided URI parameters to modify the result.\n", "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.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe response will only contain actions matching the specified statuses.\n", "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": { "operationId": "get_zone_action", "summary": "Get an Action for a Zone", "description": "Returns a specific [Action](#tag/actions) for a [Zone](#tag/zones).\n", "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).\n\nOnly applicable for [Zones](#tag/zones) in secondary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud 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).\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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)).\n\nThe import will fail if existing [RRSet](#tag/zone-rrsets) are `change` protected.\n\nSee [Zone file import](#tag/zones/zone-file-import) for more details.\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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.\n\nSee [Zone file import](#tag/zones/zone-file-import) for more details.\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\tNS\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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nUse the provided URI parameters to modify the result.\n\nThe maximum value for `per_page` on this endpoint is `100` instead of `50`.\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by their type. May be used multiple times.\n\nThe response will only contain resources matching the specified types.\n", "name": "type", "in": "query", "required": false, "schema": { "type": "array", "items": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "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.\n\nThe ID is composed of the name and type, joined with a slash (e.g. `www/AAAA`).\n", "type": "string" }, "name": { "description": "Name of the [RRSet](#tag/zone-rrsets).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" }, "type": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the [Zone's](#tag/zones) Default TTL is used.\n", "type": "integer", "nullable": true, "minimum": 60, "maximum": 2147483647, "example": 3600 }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "protection": { "description": "Protection of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust not be empty and must only contain distinct record values.\nThe order of records returned in responses is not guaranteed to be consistent.\n", "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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\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\nzones = 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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" }, "type": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the [Zone's](#tag/zones) Default TTL is used.\n", "type": "integer", "nullable": true, "minimum": 60, "maximum": 2147483647, "example": 3600 }, "records": { "description": "Records of the [RRSet](#tag/zone-rrsets).\n\nMust not be empty and must only contain distinct record values.\nThe order of records returned in responses is not guaranteed to be consistent.\n", "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nThe ID is composed of the name and type, joined with a slash (e.g. `www/AAAA`).\n", "type": "string" }, "name": { "description": "Name of the [RRSet](#tag/zone-rrsets).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" }, "type": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the [Zone's](#tag/zones) Default TTL is used.\n", "type": "integer", "nullable": true, "minimum": 60, "maximum": 2147483647, "example": 3600 }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "protection": { "description": "Protection of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust not be empty and must only contain distinct record values.\nThe order of records returned in responses is not guaranteed to be consistent.\n", "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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.\n\nThe ID is composed of the name and type, joined with a slash (e.g. `www/AAAA`).\n", "type": "string" }, "name": { "description": "Name of the [RRSet](#tag/zone-rrsets).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" }, "type": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the [Zone's](#tag/zones) Default TTL is used.\n", "type": "integer", "nullable": true, "minimum": 60, "maximum": 2147483647, "example": 3600 }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "protection": { "description": "Protection of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust not be empty and must only contain distinct record values.\nThe order of records returned in responses is not guaranteed to be consistent.\n", "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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\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\nrrset = 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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "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.\n\nThe ID is composed of the name and type, joined with a slash (e.g. `www/AAAA`).\n", "type": "string" }, "name": { "description": "Name of the [RRSet](#tag/zone-rrsets).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" }, "type": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the [Zone's](#tag/zones) Default TTL is used.\n", "type": "integer", "nullable": true, "minimum": 60, "maximum": 2147483647, "example": 3600 }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "protection": { "description": "Protection of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust not be empty and must only contain distinct record values.\nThe order of records returned in responses is not guaranteed to be consistent.\n", "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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\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, 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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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\nhcloud 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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the [Zone's](#tag/zones) Default TTL is used.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust not be empty and must only contain distinct record values.\n", "minItems": 1, "maxItems": 50, "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nFor convenience, the [RRSet](#tag/zone-rrsets) will be automatically created if it doesn't exist. Otherwise, the new\nrecords are appended to the existing [RRSet](#tag/zone-rrsets).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nIf not set, the [Zone's](#tag/zones) Default TTL is used.\nIf set, and the RRSet being updated already has a TTL, the values must be the same.\n", "type": "integer", "nullable": true, "minimum": 60, "maximum": 2147483647, "example": 3600 }, "records": { "description": "Records to add to the [RRSet](#tag/zone-rrsets).\n\nMust not be empty and must only contain distinct record values.\n", "minItems": 1, "maxItems": 50, "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nFor convenience, the [RRSet](#tag/zone-rrsets) will be automatically deleted if it doesn't contain any RRs afterwards.\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust not be empty and must only contain distinct record values.\n", "minItems": 1, "maxItems": 50, "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record.\n\nFor details about accepted values, see the [DNS record types documentation](https://docs.hetzner.com/networking/dns/record-types/overview/).\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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).\n\nOnly applicable for [Zones](#tag/zones) in primary mode.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `incorrect_zone_mode` | This operation is not supported for this Zone's `mode`. |\n", "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).\n\nThe name must be in lower case, and must not end with a dot or the [Zone](#tag/zones)\nname. Names containing non-ASCII characters must be transcribed to\n[Punycode](https://wikipedia.org/wiki/Punycode) representation with ACE prefix, e.g.\n`xn--4bi` (✉️).\n\nFor the [Zone](#tag/zones) apex, use `@`.\n", "type": "string", "example": "www" } }, { "name": "rr_type", "in": "path", "required": true, "schema": { "description": "Type of the [RRSet](#tag/zone-rrsets).\n", "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).\n\nMust not be empty and must only contain distinct record values.\n", "minItems": 1, "maxItems": 50, "type": "array", "items": { "title": "Record", "description": "Record of a [RRSet](#tag/zone-rrsets).\n\nThe `value` is used to identify the record in an [RRSet](#tag/zone-rrsets).\n", "type": "object", "properties": { "value": { "description": "Value of the record to update.\n", "type": "string", "example": "198.51.100.1" }, "comment": { "description": "New comment for the record.\n", "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).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "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": { "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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).\n\nAll names with [well-known public suffixes](https://publicsuffix.org/) (e.g. `.de`,\n`.com`, `.co.uk`) are supported. Subdomains are not supported.\n\nThe name must be in lower case and must not end with a dot.\n[Internationalized domain\nnames](https://en.wikipedia.org/wiki/Internationalized_domain_name) must be\ntranscribed to [Punycode](https://wikipedia.org/wiki/Punycode) representation with\nACE prefix, e.g. `xn--mnchen-3ya.de` (`münchen.de`).\n", "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).\n\nOnly set if [Zone](#tag/zones) is in [secondary mode](#tag/zones/zone-modes), otherwise empty.\n", "type": "array", "items": { "description": "Primary nameserver that returns [Zones](#tag/zones) via `AXFR`.\n\nMust allow queries from and may send `NOTIFY` queries to [Hetzner's secondary\nnameservers](https://docs.hetzner.com/dns-console/dns/general/authoritative-name-servers#secondary-dns-servers-old-name-servers-for-robot-customers).\n", "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\nfor the zone transfer. Must be base64 encoded.\n", "type": "string" }, "tsig_algorithm": { "description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n", "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.\nFor more information, see \"[Labels](#description/labels)\".\n", "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).\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for [RRSets](#tag/zone-rrsets) that do not explicitly define a TTL.\n", "type": "integer", "default": 3600, "minimum": 60, "maximum": 2147483647, "example": 10800 }, "status": { "description": "Status of the [Zone](#tag/zones).\n", "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).\n", "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.\n\nIf these don't match the assigned authoritative nameservers, the DNS zone is currently not being served by Hetzner.\n", "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.\n", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "delegation_status": { "description": "Status of the delegation.\n", "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).\n\nFor more information, see [Zone Modes](#tag/zones/zone-modes).\n", "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" ] } ] }