{
"openapi": "3.0.3",
"info": {
"contact": {
"url": "https://docs.hetzner.cloud/"
},
"description": "Copied from the official API documentation for the Public Hetzner Cloud.",
"title": "Hetzner Cloud API",
"version": "5134cbc"
},
"servers": [
{
"description": "Hetzner Cloud API",
"url": "https://api.hetzner.cloud/v1"
},
{
"description": "Hetzner API",
"url": "https://api.hetzner.com/v1"
}
],
"tags": [
{
"description": "Actions represent asynchronous tasks within the API, targeting one or more resources.\n\nSee Actions for more details.\n",
"name": "actions"
},
{
"description": "TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic.\n",
"name": "certificates"
},
{
"description": "Each Datacenter represents a _virtual_ Datacenter which is made up of possible many physical Datacenters where 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": "datacenters"
},
{
"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": "firewalls"
},
{
"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_ips"
},
{
"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": "images"
},
{
"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": "isos"
},
{
"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": "load_balancer_types"
},
{
"name": "load_balancers"
},
{
"description": "Datacenters are organized by Locations. Datacenters in the same Location are connected with very low latency links.\n",
"name": "locations"
},
{
"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": "networks"
},
{
"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": "placement_groups"
},
{
"description": "Returns prices for resources.\n",
"name": "pricing"
},
{
"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 Datacenter. You can not assign a Primary IP from one Datacenter to a Server in a different Datacenter. 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_ips"
},
{
"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": "server_types"
},
{
"description": "Servers are virtual machines that can be provisioned.\n",
"name": "servers"
},
{
"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": "ssh_keys"
},
{
"description": "Storage Box Types define storage products of different sizes. Each type has an hourly and a monthly cost. You will pay whichever cost is lower for your usage of this specific Storage Box. Costs may differ between Locations.\n\nAll prices are displayed in the currency of the project owner's account.\n",
"name": "storage_box_types"
},
{
"description": "Storage Boxes offer storage capacity for both small and large amounts of data. Any data you save in your Storage Box is saved on several disks configured in a RAID array, increasing redundancy and fault tolerance.\n\nPlease see [Hetzner Docs](https://docs.hetzner.com/storage/storage-box) for more details about Storage Boxes.\n\nPassword policy
\n\nThis policy applies to both Storage Boxes and Storage Box Subaccounts.\n\n- The password must be between 12 and 128 characters long\n- The password can only contain these characters: `a-z A-Z Ä Ö Ü ä ö ü ß 0-9 ^ ° ! § $ % / ( ) = ? + # - . , ; : ~ * @ { } _ &`\n- The password must contain at least one upper case letter, one lower case letter, one number, and a special character\n- The password must not have appeared in any known data breach\n",
"name": "storage_boxes"
},
{
"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": "volumes"
},
{
"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\nZone Modes
\n\nThis API supports two types of zone modes.\n\n- In _primary_ mode, resource record sets (RRSets) and resource records (RRs) are managed via the Cloud API or Hetzner Console.\n- In _secondary_ mode, Hetzner's nameservers query 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\nZone 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 in primary mode.\n\nDuring an import:\n\n- An `$ORIGIN` directive may be present, it must match the Zone's name with an ending dot\n- A `$TTL` directive may be present, it is used as new default Zone 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": "zones"
}
],
"components": {
"schemas": {
"action": {
"description": "Actions show the results and progress of asynchronous requests to the API.",
"properties": {
"command": {
"description": "Command executed in the Action.",
"example": "start_resource",
"type": "string"
},
"error": {
"allOf": [
{
"$ref": "#/components/schemas/error"
}
],
"description": "Error message for the Action if an error occurred, otherwise null.",
"nullable": true
},
"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.",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"nullable": true,
"type": "string"
},
"id": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"progress": {
"description": "Progress of the Action in percent.",
"example": 100,
"format": "int32",
"type": "integer"
},
"resources": {
"description": "Resources the Action relates to.",
"items": {
"$ref": "#/components/schemas/resource"
},
"type": "array"
},
"started": {
"description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"status": {
"description": "Status of the Action.",
"enum": [
"error",
"running",
"success"
],
"type": "string"
}
},
"required": [
"command",
"error",
"finished",
"id",
"progress",
"resources",
"started",
"status"
],
"title": "Action",
"type": "object"
},
"add_records_to_rrset_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/add_records",
"properties": {
"records": {
"description": "Records to add to the RRSet.\n\nMust not be empty and must only contain distinct record values.\n",
"items": {
"$ref": "#/components/schemas/resource_record"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
},
"ttl": {
"description": "Time To Live (TTL) of the RRSet.\n\nIf not set, the Zone's Default TTL is used.\nIf set, and the RRSet being updated already has a TTL, the values must be the same.\n",
"example": 3600,
"maximum": 2147483647,
"minimum": 60,
"nullable": true,
"type": "integer"
}
},
"required": [
"records"
],
"type": "object"
},
"add_records_to_rrset_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/add_records",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"add_route_to_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/add_route",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"add_server_to_placement_group_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/add_to_placement_group",
"properties": {
"placement_group": {
"description": "ID of Placement Group the Server should be added to.",
"example": 1,
"format": "int64",
"type": "integer"
}
},
"required": [
"placement_group"
],
"title": "AddToPlacementGroupRequest",
"type": "object"
},
"add_server_to_placement_group_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/add_to_placement_group",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"add_service_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_service",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"add_subnet_to_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/add_subnet",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"add_target_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_target",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"apply_to_resources_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/apply_to_resources",
"properties": {
"apply_to": {
"description": "Resources to apply the Firewall to.\n\nExtends existing resources.\n",
"items": {
"$ref": "#/components/schemas/firewall_resource"
},
"type": "array"
}
},
"required": [
"apply_to"
],
"title": "ApplyToResourcesRequest",
"type": "object"
},
"apply_to_resources_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/apply_to_resources",
"properties": {
"actions": {
"items": {
"$ref": "#/components/schemas/action"
},
"type": "array"
}
},
"required": [
"actions"
],
"title": "ActionListResponse",
"type": "object"
},
"architecture": {
"description": "CPU architecture compatible with the Image.\n | CPU architecture compatible with the ISO.\n\nNull indicates no restriction on the architecture (wildcard).\n | CPU architecture of the Server Type.\n",
"enum": [
"arm",
"x86"
],
"example": "x86",
"type": "string"
},
"assign_floating_ip_to_server_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/assign",
"properties": {
"server": {
"description": "Server the Floating IP is assigned to.\n\n`null` if not assigned.\n",
"example": 42,
"format": "int64",
"nullable": true,
"type": "integer"
}
},
"required": [
"server"
],
"title": "FloatingIPActionsAssignRequest",
"type": "object"
},
"assign_floating_ip_to_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/assign",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"assign_primary_ip_to_resource_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/assign",
"properties": {
"assignee_id": {
"description": "ID of a resource of type `assignee_type`.",
"example": 4711,
"format": "int64",
"type": "integer"
},
"assignee_type": {
"description": "Type of resource assigning the Primary IP to.",
"enum": [
"server"
],
"example": "server",
"type": "string"
}
},
"required": [
"assignee_id",
"assignee_type"
],
"title": "PrimaryIPActionsAssignRequest",
"type": "object"
},
"assign_primary_ip_to_resource_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/assign",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"attach_iso_to_server_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/attach_iso",
"properties": {
"iso": {
"description": "ID or name of ISO to attach to the Server as listed in GET `/isos`.",
"example": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"type": "string"
}
},
"required": [
"iso"
],
"type": "object"
},
"attach_iso_to_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/attach_iso",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"attach_load_balancer_to_network_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/attach_to_network",
"properties": {
"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.",
"example": "10.0.1.1",
"type": "string"
},
"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",
"example": "10.0.1.0/24",
"type": "string"
},
"network": {
"description": "ID of an existing network to attach the Load Balancer to.",
"example": 4711,
"format": "int64",
"type": "integer"
}
},
"required": [
"network"
],
"type": "object"
},
"attach_load_balancer_to_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/attach_to_network",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"attach_server_to_network_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/attach_to_network",
"properties": {
"alias_ips": {
"description": "Additional IPs to be assigned to this Server.",
"example": [
"10.0.1.2"
],
"items": {
"type": "string"
},
"type": "array"
},
"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.",
"example": "10.0.1.1",
"type": "string"
},
"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",
"example": "10.0.1.0/24",
"type": "string"
},
"network": {
"description": "ID of an existing network to attach the Server to.",
"example": 4711,
"format": "int64",
"type": "integer"
}
},
"required": [
"network"
],
"title": "AttachToNetworkRequest",
"type": "object"
},
"attach_server_to_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/attach_to_network",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"attach_volume_to_server_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/volumes/{id}/actions/attach",
"properties": {
"automount": {
"description": "Auto-mount the Volume after attaching it.",
"example": false,
"type": "boolean"
},
"server": {
"description": "ID of the Server the Volume will be attached to.",
"example": 43,
"format": "int64",
"type": "integer"
}
},
"required": [
"server"
],
"title": "AttachVolumeRequest",
"type": "object"
},
"attach_volume_to_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/volumes/{id}/actions/attach",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"certificate": {
"description": "TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic.",
"properties": {
"certificate": {
"description": "Certificate and chain in PEM format, in order so that each record directly certifies the one preceding.",
"example": "-----BEGIN CERTIFICATE-----\n...",
"nullable": true,
"type": "string"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"domain_names": {
"description": "Domains and subdomains covered by the Certificate.",
"example": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"items": {
"type": "string"
},
"type": "array"
},
"fingerprint": {
"description": "SHA256 fingerprint of the Certificate.",
"example": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
"nullable": true,
"type": "string"
},
"id": {
"description": "ID of the Certificate.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"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",
"example": "2019-07-08T09:59:59Z",
"format": "date-time",
"nullable": true,
"type": "string"
},
"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).",
"example": "2019-01-08T10:00:00Z",
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"description": "Current status of a type `managed` Certificate, always *null* for type `uploaded` Certificates.",
"nullable": true,
"properties": {
"error": {
"description": "If issuance or renewal reports `failed`, this property contains information about what happened.",
"example": null,
"nullable": true,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"type": "object"
},
"issuance": {
"description": "Status of the issuance process of the Certificate.",
"enum": [
"completed",
"failed",
"pending"
],
"example": "completed",
"type": "string"
},
"renewal": {
"description": "Status of the renewal process of the Certificate.",
"enum": [
"failed",
"pending",
"scheduled",
"unavailable"
],
"example": "scheduled",
"type": "string"
}
},
"type": "object"
},
"type": {
"description": "Type of the Certificate.",
"enum": [
"managed",
"uploaded"
],
"example": "uploaded",
"type": "string"
},
"used_by": {
"description": "Resources currently using the Certificate.",
"items": {
"$ref": "#/components/schemas/resource"
},
"type": "array"
}
},
"required": [
"certificate",
"created",
"domain_names",
"fingerprint",
"id",
"labels",
"name",
"not_valid_after",
"not_valid_before",
"used_by"
],
"title": "Certificate",
"type": "object"
},
"change_algorithm_request": {
"$ref": "#/components/schemas/load_balancer_algorithm"
},
"change_algorithm_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_algorithm",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_alias_ips_of_network_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_alias_ips",
"properties": {
"alias_ips": {
"description": "New alias IPs to set for this Server.",
"example": [
"10.0.1.2"
],
"items": {
"type": "string"
},
"type": "array"
},
"network": {
"description": "ID of an existing Network already attached to the Server.",
"example": 4711,
"format": "int64",
"type": "integer"
}
},
"required": [
"alias_ips",
"network"
],
"type": "object"
},
"change_alias_ips_of_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_alias_ips",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_floating_ip_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_home_directory_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory",
"properties": {
"home_directory": {
"description": "Home directory of the Storage Box Subaccount.\n\nThe directory will be created if it doesn't exist yet.\n",
"example": "my-backup/server01",
"maxLength": 999,
"minLength": 1,
"pattern": "^[a-zA-Z0-9 ./_-]+$",
"type": "string"
}
},
"required": [
"home_directory"
],
"type": "object"
},
"change_home_directory_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_image_protection_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/images/{id}/actions/change_protection",
"properties": {
"delete": {
"description": "If true, prevents the snapshot from being deleted.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"change_image_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/images/{id}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_ip_range_of_network_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/networks/{id}/actions/change_ip_range",
"properties": {
"ip_range": {
"description": "IP range of the Network.\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 with a /16 netmask.\n",
"example": "10.0.0.0/16",
"type": "string"
}
},
"required": [
"ip_range"
],
"title": "ChangeIPRangeRequest",
"type": "object"
},
"change_ip_range_of_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/change_ip_range",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_load_balancer_protection_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_protection",
"properties": {
"delete": {
"description": "If true, prevents the Load Balancer from being deleted.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"change_load_balancer_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_network_protection_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/networks/{id}/actions/change_protection",
"properties": {
"delete": {
"description": "Delete protection setting.\n\nIf true, prevents the Network from being deleted.\n",
"example": true,
"type": "boolean"
}
},
"title": "ChangeProtectionRequest",
"type": "object"
},
"change_network_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_primary_ip_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_protection_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/change_protection",
"properties": {
"delete": {
"description": "Prevent the Resource from being deleted.",
"example": false,
"type": "boolean"
}
},
"type": "object"
},
"change_protection_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_reverse_dns_entry_for_this_load_balancer_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_dns_ptr",
"properties": {
"dns_ptr": {
"description": "Hostname to set as a reverse DNS PTR entry.",
"example": "lb1.example.com",
"nullable": true,
"type": "string"
},
"ip": {
"description": "Public IP address for which the reverse DNS entry should be set.",
"example": "1.2.3.4",
"type": "string"
}
},
"required": [
"dns_ptr",
"ip"
],
"title": "ChangeLoadbalancerDnsPtrRequest",
"type": "object"
},
"change_reverse_dns_entry_for_this_load_balancer_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_dns_ptr",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_reverse_dns_entry_for_this_server_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_dns_ptr",
"properties": {
"dns_ptr": {
"description": "Hostname to set as a reverse DNS PTR entry, reset to original value if `null`.",
"example": "server01.example.com",
"nullable": true,
"type": "string"
},
"ip": {
"description": "Primary IP address for which the reverse DNS entry should be set.",
"example": "1.2.3.4",
"type": "string"
}
},
"required": [
"dns_ptr",
"ip"
],
"type": "object"
},
"change_reverse_dns_entry_for_this_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_dns_ptr",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_reverse_dns_records_for_floating_ip_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_dns_ptr",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_reverse_dns_records_for_primary_ip_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/change_dns_ptr",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_rrsets_protection_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_protection",
"properties": {
"change": {
"description": "Prevent the Resource from being changed.",
"example": false,
"type": "boolean"
}
},
"required": [
"change"
],
"type": "object"
},
"change_rrsets_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_rrsets_ttl_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_ttl",
"properties": {
"ttl": {
"description": "Time To Live (TTL) of the RRSet.\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the Zone's Default TTL is used.\n",
"example": 3600,
"maximum": 2147483647,
"minimum": 60,
"nullable": true,
"type": "integer"
}
},
"required": [
"ttl"
],
"type": "object"
},
"change_rrsets_ttl_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_ttl",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_server_protection_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_protection",
"properties": {
"delete": {
"description": "If true, prevents the Server from being deleted (currently delete and rebuild attribute needs to have the same value).",
"example": true,
"type": "boolean"
},
"rebuild": {
"description": "If true, prevents the Server from being rebuilt (currently delete and rebuild attribute needs to have the same value).",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"change_server_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_type_of_load_balancer_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_type",
"properties": {
"load_balancer_type": {
"description": "ID or name of Load Balancer type the Load Balancer should migrate to.",
"example": "lb21",
"type": "string"
}
},
"required": [
"load_balancer_type"
],
"title": "ChangeTypeRequest",
"type": "object"
},
"change_type_of_load_balancer_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_type",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_type_of_server_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_type",
"properties": {
"server_type": {
"description": "ID or name of Server type the Server should migrate to.",
"example": "cpx22",
"type": "string"
},
"upgrade_disk": {
"description": "If false, do not upgrade the disk (this allows downgrading the Server type later).",
"example": true,
"type": "boolean"
}
},
"required": [
"server_type",
"upgrade_disk"
],
"type": "object"
},
"change_type_of_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_type",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_type_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/change_type",
"properties": {
"storage_box_type": {
"description": "ID or Name of the Storage Box Type.",
"example": "bx20",
"type": "string"
}
},
"required": [
"storage_box_type"
],
"type": "object"
},
"change_type_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/change_type",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_volume_protection_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/volumes/{id}/actions/change_protection",
"properties": {
"delete": {
"description": "If true, prevents the Volume from being deleted.",
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"change_volume_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/volumes/{id}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_zones_default_ttl_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_ttl",
"properties": {
"ttl": {
"default": 3600,
"description": "Default Time To Live (TTL) of the Zone.\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for RRSets that do not explicitly define a TTL.\n",
"example": 10800,
"maximum": 2147483647,
"minimum": 60,
"type": "integer"
}
},
"required": [
"ttl"
],
"type": "object"
},
"change_zones_default_ttl_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_ttl",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_zones_primary_nameservers_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_primary_nameservers",
"properties": {
"primary_nameservers": {
"description": "Primary nameservers of the Zone.",
"example": [
{
"address": "198.51.100.1",
"port": 53
},
{
"address": "203.0.113.1",
"port": 53
}
],
"items": {
"$ref": "#/components/schemas/nameserver"
},
"type": "array"
}
},
"required": [
"primary_nameservers"
],
"type": "object"
},
"change_zones_primary_nameservers_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_primary_nameservers",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"change_zones_protection_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_protection",
"properties": {
"delete": {
"description": "Prevents the Zone from being deleted.",
"example": false,
"type": "boolean"
}
},
"type": "object"
},
"change_zones_protection_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_protection",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"create_certificate_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/certificates",
"properties": {
"certificate": {
"description": "Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. Required for type `uploaded` Certificates.",
"example": "-----BEGIN CERTIFICATE-----\n...",
"type": "string"
},
"domain_names": {
"description": "Domains and subdomains that should be contained in the Certificate issued by *Let's Encrypt*. Required for type `managed` Certificates.",
"example": [
"example.com",
"www.example.com"
],
"items": {
"type": "string"
},
"type": "array"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Certificate.",
"example": "my website cert",
"type": "string"
},
"private_key": {
"description": "Certificate key in PEM format. Required for type `uploaded` Certificates.",
"example": "-----BEGIN PRIVATE KEY-----\n...",
"type": "string"
},
"type": {
"default": "uploaded",
"description": "Choose between uploading a Certificate in PEM format or requesting a managed *Let's Encrypt* Certificate.",
"enum": [
"managed",
"uploaded"
],
"example": "uploaded",
"type": "string"
}
},
"required": [
"name"
],
"title": "CreateCertificateRequest",
"type": "object"
},
"create_certificate_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/certificates",
"properties": {
"action": {
"allOf": [
{
"$ref": "#/components/schemas/action"
}
],
"nullable": true
},
"certificate": {
"$ref": "#/components/schemas/certificate"
}
},
"required": [
"certificate"
],
"title": "CreateCertificateResponse",
"type": "object"
},
"create_firewall_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/firewalls",
"properties": {
"apply_to": {
"description": "Resources to apply the Firewall to.\n\nResources added directly are taking precedence over those added via a Label Selector.\n",
"items": {
"$ref": "#/components/schemas/firewall_resource"
},
"type": "array"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Firewall.\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n",
"example": "new-name",
"type": "string"
},
"rules": {
"description": "Array of rules.\n\nRules are limited to 50 entries per Firewall and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits).\n",
"example": [
{
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"192.0.2.2/32",
"192.0.2.0/24",
"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
],
"items": {
"$ref": "#/components/schemas/rule"
},
"type": "array"
}
},
"required": [
"name"
],
"title": "CreateFirewallRequest",
"type": "object"
},
"create_firewall_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/firewalls",
"properties": {
"actions": {
"example": [
{
"command": "set_firewall_rules",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
},
{
"command": "apply_firewall",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 14,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
],
"items": {
"$ref": "#/components/schemas/action"
},
"type": "array"
},
"firewall": {
"$ref": "#/components/schemas/firewall"
}
},
"title": "CreateFirewallResponse",
"type": "object"
},
"create_floating_ip_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/floating_ips",
"properties": {
"description": {
"description": "Description of the Resource.",
"example": "This describes my resource",
"nullable": true,
"type": "string"
},
"home_location": {
"description": "Home Location for the Floating IP.\n\nEither the ID or the name of the Location.\n\nOnly optional if no Server is provided. Routing is optimized for this Locations.\n",
"example": "fsn1",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"server": {
"description": "Server the Floating IP is assigned to.\n\n`null` if not assigned.\n",
"example": 42,
"format": "int64",
"nullable": true,
"type": "integer"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"type"
],
"title": "FloatingIPCreateRequest",
"type": "object"
},
"create_floating_ip_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/floating_ips",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"floating_ip": {
"$ref": "#/components/schemas/floating_ip"
}
},
"required": [
"floating_ip"
],
"type": "object"
},
"create_image_from_server_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/create_image",
"properties": {
"description": {
"description": "Description of the Image, will be auto-generated if not set.",
"example": "my image",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"type": {
"default": "snapshot",
"description": "Type of Image to create.",
"enum": [
"backup",
"snapshot"
],
"example": "snapshot",
"type": "string"
}
},
"title": "CreateImageRequest",
"type": "object"
},
"create_image_from_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/create_image",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"image": {
"$ref": "#/components/schemas/image"
}
},
"type": "object"
},
"create_load_balancer_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/load_balancers",
"properties": {
"algorithm": {
"$ref": "#/components/schemas/load_balancer_algorithm"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"load_balancer_type": {
"description": "ID or name of the Load Balancer type this Load Balancer should be created with.",
"example": "lb11",
"type": "string"
},
"location": {
"description": "ID or name of Location to create Load Balancer in.",
"example": "fsn1",
"type": "string"
},
"name": {
"description": "Name of the Load Balancer.",
"example": "Web Frontend",
"type": "string"
},
"network": {
"description": "ID of the network the Load Balancer should be attached to on creation.",
"example": 123,
"format": "int64",
"type": "integer"
},
"network_zone": {
"description": "Name of network zone.",
"example": "eu-central",
"type": "string"
},
"public_interface": {
"description": "Enable or disable the public interface of the Load Balancer.",
"example": true,
"type": "boolean"
},
"services": {
"description": "Array of services.",
"items": {
"$ref": "#/components/schemas/load_balancer_service"
},
"type": "array"
},
"targets": {
"description": "Array of targets.",
"items": {
"$ref": "#/components/schemas/load_balancer_add_target"
},
"type": "array"
}
},
"required": [
"load_balancer_type",
"name"
],
"title": "CreateLoadBalancerRequest",
"type": "object"
},
"create_load_balancer_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"load_balancer": {
"$ref": "#/components/schemas/load_balancer"
}
},
"required": [
"action",
"load_balancer"
],
"type": "object"
},
"create_network_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/networks",
"properties": {
"expose_routes_to_vswitch": {
"description": "Toggle to expose routes to the Networks vSwitch.\n\nIndicates if the routes from this Network should be exposed to the vSwitch in this Network. Only takes effect if a [vSwitch is setup](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch) in this Network.\n",
"example": false,
"type": "boolean"
},
"ip_range": {
"description": "IP range of the Network.\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 with a /16 netmask.\n",
"example": "10.0.0.0/16",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Network.",
"example": "mynet",
"type": "string"
},
"routes": {
"description": "Array of routes set in this Network.",
"items": {
"$ref": "#/components/schemas/route"
},
"type": "array"
},
"subnets": {
"description": "Array of subnets to allocate.",
"items": {
"$ref": "#/components/schemas/subnet"
},
"type": "array"
}
},
"required": [
"ip_range",
"name"
],
"title": "NetworkCreateRequest",
"type": "object"
},
"create_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/networks",
"properties": {
"network": {
"$ref": "#/components/schemas/network"
}
},
"type": "object"
},
"create_placementgroup_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/placement_groups",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Placement Group.",
"example": "my Placement Group",
"type": "string"
},
"type": {
"description": "Define the Placement Group Type.",
"enum": [
"spread"
],
"example": "spread",
"type": "string"
}
},
"required": [
"name",
"type"
],
"title": "CreatePlacementGroupRequest",
"type": "object"
},
"create_placementgroup_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/placement_groups",
"properties": {
"action": {
"allOf": [
{
"$ref": "#/components/schemas/action"
}
],
"nullable": true
},
"placement_group": {
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Placement Group.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"servers": {
"description": "Array of IDs of Servers that are part of this Placement Group.",
"example": [
42
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"type": {
"description": "Type of Placement Group.\n",
"enum": [
"spread"
],
"example": "spread",
"type": "string"
}
},
"required": [
"created",
"id",
"labels",
"name",
"servers",
"type"
],
"title": "PlacementGroup",
"type": "object"
}
},
"required": [
"placement_group"
],
"title": "CreatePlacementGroupResponse",
"type": "object"
},
"create_primary_ip_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/primary_ips",
"properties": {
"assignee_id": {
"description": "ID of resource to assign the Primary IP to.\n\nOmitted if the Primary IP should not get assigned.\n",
"example": 17,
"format": "int64",
"nullable": true,
"type": "integer"
},
"assignee_type": {
"description": "Type of resource the Primary IP can get assigned to.\n\nCurrently Primary IPs can only be assigned to Servers,\ntherefore this field must be set to `server`.\n",
"enum": [
"server"
],
"example": "server",
"type": "string"
},
"auto_delete": {
"default": false,
"description": "Auto deletion state.\n\nIf enabled the Primary IP will be deleted once the assigned resource gets deleted.\n",
"example": false,
"type": "boolean"
},
"datacenter": {
"deprecated": true,
"description": "**Deprecated**: This property is deprecated and will be removed after 1 July 2026.\nUse the `location` key instead.\n\nData Center ID or name.\n\nThe Primary IP will be bound to this Data Center.\nOmit if `assignee_id`/`assignee_type` or `location` are provided.\n",
"example": "fsn1-dc8",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"description": "Location ID or name the Primary IP will be bound to.\n\nOmit if `assignee_id`/`assignee_type` or `datacenter` are provided.\n",
"example": "fsn1",
"type": "string"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"assignee_type",
"name",
"type"
],
"title": "PrimaryIPCreateRequest",
"type": "object"
},
"create_primary_ip_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/primary_ips",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"primary_ip": {
"properties": {
"assignee_id": {
"description": "ID of resource the Primary IP is assigned to.\n\n`null` if the Primary IP is not assigned.\n",
"example": 17,
"format": "int64",
"nullable": true,
"type": "integer"
},
"assignee_type": {
"description": "Type of resource the Primary IP can get assigned to.\n",
"enum": [
"server"
],
"example": "server",
"type": "string"
},
"auto_delete": {
"default": false,
"description": "Auto deletion state.\n\nIf enabled the Primary IP will be deleted once the assigned resource gets deleted.\n",
"example": true,
"type": "boolean"
},
"blocked": {
"description": "Blocked state of the Primary IP.",
"example": false,
"type": "boolean"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"datacenter": {
"allOf": [
{
"$ref": "#/components/schemas/data_center"
}
],
"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 of the Primary IP.\n"
},
"dns_ptr": {
"description": "List of reverse DNS records.",
"items": {
"$ref": "#/components/schemas/dns_ptr"
},
"type": "array"
},
"id": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"ip": {
"description": "IP address.",
"example": "2001:db8::/64",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"$ref": "#/components/schemas/location"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"assignee_id",
"assignee_type",
"auto_delete",
"blocked",
"created",
"datacenter",
"dns_ptr",
"id",
"ip",
"labels",
"location",
"name",
"protection",
"type"
],
"title": "PrimaryIP",
"type": "object"
}
},
"required": [
"primary_ip"
],
"title": "CreatePrimaryIPResponse",
"type": "object"
},
"create_rrset_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"rrset": {
"$ref": "#/components/schemas/resource_record_set"
}
},
"required": [
"action",
"rrset"
],
"type": "object"
},
"create_server_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers",
"properties": {
"automount": {
"description": "Auto-mount Volumes after attach.",
"example": false,
"type": "boolean"
},
"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",
"example": "nbg1-dc3",
"type": "string"
},
"firewalls": {
"description": "Firewalls which should be applied on the Server's public network interface at creation time.",
"example": [
{
"firewall": 38
}
],
"items": {
"properties": {
"firewall": {
"description": "ID of the Firewall.",
"format": "int64",
"type": "integer"
}
},
"required": [
"firewall"
],
"title": "CreateServerRequestFirewalls",
"type": "object"
},
"type": "array"
},
"image": {
"description": "ID or name of the Image the Server is created from.",
"example": "ubuntu-24.04",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"description": "ID or name of the Location to create the Server in (must not be used together with `datacenter`).",
"example": "nbg1",
"type": "string"
},
"name": {
"description": "Name of the Server to create (must be unique per Project and a valid hostname as per RFC 1123).",
"example": "my-server",
"type": "string"
},
"networks": {
"description": "Network IDs which should be attached to the Server private network interface at the creation time.",
"example": [
456
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"placement_group": {
"description": "ID of the Placement Group the Server should be in.",
"example": 1,
"format": "int64",
"type": "integer"
},
"public_net": {
"description": "Public Network options.",
"properties": {
"enable_ipv4": {
"default": true,
"description": "Attach an IPv4 on the public NIC. If false, no IPv4 address will be attached.",
"type": "boolean"
},
"enable_ipv6": {
"default": true,
"description": "Attach an IPv6 on the public NIC. If false, no IPv6 address will be attached.",
"type": "boolean"
},
"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.",
"nullable": true,
"type": "integer"
},
"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.",
"nullable": true,
"type": "integer"
}
},
"type": "object"
},
"server_type": {
"description": "ID or name of the Server type this Server should be created with.",
"example": "cpx22",
"type": "string"
},
"ssh_keys": {
"description": "SSH key IDs (`integer`) or names (`string`) which should be injected into the Server at creation time.",
"example": [
"my-ssh-key"
],
"items": {
"type": "string"
},
"type": "array"
},
"start_after_create": {
"default": true,
"description": "This automatically triggers a Power on a Server-Server Action after the creation is finished and is returned in the `next_actions` response object.",
"example": true,
"type": "boolean"
},
"user_data": {
"description": "Cloud-Init user data to use during Server creation. This field is limited to 32KiB.",
"example": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n",
"type": "string"
},
"volumes": {
"description": "Volume IDs which should be attached to the Server at the creation time. Volumes must be in the same Location.",
"example": [
123
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
}
},
"required": [
"image",
"name",
"server_type"
],
"title": "CreateServerRequest",
"type": "object"
},
"create_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"next_actions": {
"items": {
"$ref": "#/components/schemas/action"
},
"type": "array"
},
"root_password": {
"description": "Root password when no SSH keys have been specified.",
"example": "YItygq1v3GYjjMomLaKc",
"nullable": true,
"type": "string"
},
"server": {
"$ref": "#/components/schemas/server"
}
},
"required": [
"action",
"next_actions",
"root_password",
"server"
],
"title": "CreateServerResponse",
"type": "object"
},
"create_snapshot_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/snapshots",
"properties": {
"description": {
"description": "Description of the Storage Box Snapshot.",
"example": "snapshot-0001",
"maxLength": 1000,
"pattern": "[a-zA-Z0-9-_,:<>+#!\\(\\)\\[\\]\\{\\} ]*",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
}
},
"type": "object"
},
"create_snapshot_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/snapshots",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"snapshot": {
"properties": {
"id": {
"description": "ID of the Storage Box Snapshot.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"storage_box": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id",
"storage_box"
],
"type": "object"
}
},
"required": [
"action",
"snapshot"
],
"type": "object"
},
"create_ssh_key_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/ssh_keys",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the SSH key.",
"example": "My ssh key",
"type": "string"
},
"public_key": {
"description": "Public key.",
"example": "ssh-rsa AAAjjk76kgf...Xt",
"type": "string"
}
},
"required": [
"name",
"public_key"
],
"type": "object"
},
"create_ssh_key_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/ssh_keys",
"properties": {
"ssh_key": {
"$ref": "#/components/schemas/ssh_key"
}
},
"required": [
"ssh_key"
],
"type": "object"
},
"create_storage_box_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes",
"properties": {
"access_settings": {
"description": "Access settings of the Storage Box.",
"properties": {
"reachable_externally": {
"description": "Whether access from outside the Hetzner network is allowed.",
"type": "boolean"
},
"samba_enabled": {
"description": "Whether the Samba subsystem is enabled.",
"type": "boolean"
},
"ssh_enabled": {
"description": "Whether the SSH subsystem is enabled.",
"type": "boolean"
},
"webdav_enabled": {
"description": "Whether the WebDAV subsystem is enabled.",
"type": "boolean"
},
"zfs_enabled": {
"description": "Whether the ZFS snapshot folder is visible.",
"type": "boolean"
}
},
"type": "object"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"description": "ID or Name of Location.",
"example": "fsn1",
"type": "string"
},
"name": {
"description": "Name of the Storage Box.\n",
"type": "string"
},
"password": {
"description": "Password of the Storage Box.\n\nFor more details, see the Storage Boxes password policy.\n",
"type": "string"
},
"ssh_keys": {
"description": "SSH public keys in OpenSSH format to inject into the Storage Box.",
"items": {
"example": "ssh-rsa AAAjjk76kgf...Xt",
"type": "string"
},
"type": "array"
},
"storage_box_type": {
"description": "ID or Name of the Storage Box Type.",
"example": "bx20",
"type": "string"
}
},
"required": [
"location",
"name",
"password",
"storage_box_type"
],
"type": "object"
},
"create_storage_box_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"storage_box": {
"$ref": "#/components/schemas/storage_box"
}
},
"required": [
"action",
"storage_box"
],
"type": "object"
},
"create_subaccount_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts",
"properties": {
"access_settings": {
"properties": {
"reachable_externally": {
"description": "Whether access from outside the Hetzner network is allowed.",
"type": "boolean"
},
"readonly": {
"description": "Whether the Subaccount is read-only.",
"type": "boolean"
},
"samba_enabled": {
"description": "Whether the Samba subsystem is enabled.",
"type": "boolean"
},
"ssh_enabled": {
"description": "Whether the SSH subsystem is enabled.",
"type": "boolean"
},
"webdav_enabled": {
"description": "Whether the WebDAV subsystem is enabled.",
"type": "boolean"
}
},
"type": "object"
},
"description": {
"description": "A description of Storage Box Subaccount.\n",
"example": "my-backup-server01",
"maxLength": 1000,
"type": "string"
},
"home_directory": {
"description": "Home directory of the Storage Box Subaccount.\n\nThe directory will be created if it doesn't exist yet.\n",
"example": "my-backup/server01",
"maxLength": 999,
"minLength": 1,
"pattern": "^[a-zA-Z0-9 ./_-]+$",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Storage Box Subaccount.\n\nDefaults to the Storage Box Subaccount `username`.\n",
"example": "my-name",
"maxLength": 50,
"minLength": 1,
"type": "string"
},
"password": {
"description": "Password of the Storage Box Subaccount.\n\nFor more details, see the Storage Boxes password policy.\n",
"type": "string"
}
},
"required": [
"home_directory",
"password"
],
"type": "object"
},
"create_subaccount_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"subaccount": {
"properties": {
"id": {
"description": "ID of the Storage Box Subaccount.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"storage_box": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id",
"storage_box"
],
"type": "object"
}
},
"required": [
"action",
"subaccount"
],
"type": "object"
},
"create_volume_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/volumes",
"properties": {
"automount": {
"description": "Auto-mount Volume after attach. `server` must be provided.",
"example": false,
"type": "boolean"
},
"format": {
"description": "Format Volume after creation. One of: `xfs`, `ext4`.",
"example": "xfs",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"description": "Location to create the Volume in (can be omitted if Server is specified).",
"example": "nbg1",
"type": "string"
},
"name": {
"description": "Name of the volume.",
"example": "databases-storage",
"type": "string"
},
"server": {
"description": "Server to which to attach the Volume once it's created (Volume will be created in the same Location as the server).",
"format": "int64",
"type": "integer"
},
"size": {
"description": "Size of the Volume in GB.",
"example": 42,
"type": "integer"
}
},
"required": [
"name",
"size"
],
"title": "CreateVolumeRequest",
"type": "object"
},
"create_volume_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/volumes",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"next_actions": {
"items": {
"$ref": "#/components/schemas/action"
},
"type": "array"
},
"volume": {
"$ref": "#/components/schemas/volume"
}
},
"required": [
"action",
"next_actions",
"volume"
],
"type": "object"
},
"create_zone_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"mode": {
"description": "Mode of the Zone.\n\nFor more information, see Zone Modes.\n",
"enum": [
"primary",
"secondary"
],
"example": "primary",
"type": "string"
},
"name": {
"description": "Name of the Zone.\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",
"example": "example.com",
"maxLength": 255,
"type": "string"
},
"primary_nameservers": {
"description": "Primary nameservers of the Zone.\n\nOnly applicable for Zones in secondary mode.\nIgnored for Zones in primary mode.\n",
"example": [
{
"address": "198.51.100.1",
"port": 53
},
{
"address": "203.0.113.1",
"port": 53
}
],
"items": {
"$ref": "#/components/schemas/nameserver"
},
"type": "array"
},
"rrsets": {
"description": "RRSets to be added to the Zone.\n\nOnly applicable for Zones in primary mode.\nIgnored for Zones in secondary mode.\n",
"items": {
"$ref": "#/components/schemas/resource_record_set_to_create"
},
"type": "array"
},
"ttl": {
"default": 3600,
"description": "Default Time To Live (TTL) of the Zone.\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for RRSets that do not explicitly define a TTL.\n",
"example": 10800,
"maximum": 2147483647,
"minimum": 60,
"type": "integer"
},
"zonefile": {
"description": "Zone file to import.\n\nOnly applicable for Zones in primary mode.\nIgnored for Zones in secondary mode.\n\nIf provided, `rrsets` must be empty.\n\nSee Zone file import for more details.\n",
"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",
"type": "string"
}
},
"required": [
"mode",
"name"
],
"type": "object"
},
"create_zone_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"zone": {
"$ref": "#/components/schemas/zone"
}
},
"required": [
"action",
"zone"
],
"type": "object"
},
"created_from": {
"description": "Information about the Server the Image was created from.",
"properties": {
"id": {
"description": "ID of the Server the Image was created from.",
"example": 1,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"name": {
"description": "Server name at the time the Image was created.",
"example": "Server",
"type": "string"
}
},
"required": [
"id",
"name"
],
"type": "object"
},
"data_center": {
"description": "**Deprecated**: This property is deprecated and will be removed after the 1 July 2026.\nUse the `location` property instead.\n\nData Center of the Primary IP.\n | **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",
"properties": {
"description": {
"description": "Descriptive name for the Data Center.\n\nDesired to be easy to understand for humans. Might be changed for cosmetic reasons. Do not use this as an identifier.\n",
"example": "Falkenstein DC Park 8",
"type": "string"
},
"id": {
"description": "ID of the Data Center.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"location": {
"$ref": "#/components/schemas/location"
},
"name": {
"description": "Unique name for the Data Center.\n\nCan be used as a more descriptive identifier.\n",
"example": "fsn1-dc8",
"pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$",
"type": "string"
},
"server_types": {
"description": "Server Types supported and available in this Data Center.\n",
"properties": {
"available": {
"description": "Server Types currently available in this Data Center.\n\nThese Server Types can currently be purchased. Types that are temporarily unavailable\nbut are supported in this Data Center are listed as `supported`.\n",
"example": [
1,
2,
3
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"available_for_migration": {
"description": "Server Types available to migrate to in this Data Center.\n\nExisting Servers can be migrated to these Server Types.\n",
"example": [
1,
2,
3
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"supported": {
"description": "List of Server Types supported in this Data Center.\n\nThese Server Types are generally available in this Data Center, but might be\ntemporarily out of stock.\n",
"example": [
1,
2,
3
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
}
},
"required": [
"available",
"available_for_migration",
"supported"
],
"type": "object"
}
},
"required": [
"description",
"id",
"location",
"name",
"server_types"
],
"type": "object"
},
"delete_route_from_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/delete_route",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"delete_rrset_response": {
"description": "Response to DELETE https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"delete_server_response": {
"description": "Response to DELETE https://api.hetzner.cloud/v1/servers/{id}",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"type": "object"
},
"delete_service_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/delete_service",
"properties": {
"listen_port": {
"description": "The listen port of the service you want to delete.",
"example": 443,
"type": "integer"
}
},
"required": [
"listen_port"
],
"type": "object"
},
"delete_service_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/delete_service",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"delete_snapshot_response": {
"description": "Response to DELETE https://api.hetzner.com/v1/storage_boxes/{id}/snapshots/{snapshot_id}",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"delete_storage_box_response": {
"description": "Response to DELETE https://api.hetzner.com/v1/storage_boxes/{id}",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"delete_subaccount_response": {
"description": "Response to DELETE https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"delete_subnet_from_network_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/networks/{id}/actions/delete_subnet",
"properties": {
"ip_range": {
"description": "IP range in CIDR block notation of the subnet to delete.",
"example": "10.0.1.0/24",
"type": "string"
}
},
"required": [
"ip_range"
],
"title": "DeleteSubnetRequest",
"type": "object"
},
"delete_subnet_from_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/delete_subnet",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"delete_zone_response": {
"description": "Response to DELETE https://api.hetzner.cloud/v1/zones/{id_or_name}",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"deprecation_info": {
"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 | This field is deprecated.\n\nUse the `deprecation` object in the `locations` field instead (`.locations[].deprecation`).\n",
"properties": {
"announced": {
"description": "Date of the deprecation announcement.\n",
"example": "2023-06-01T00:00:00Z",
"format": "date-time",
"type": "string"
},
"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",
"example": "2023-09-01T00:00:00Z",
"format": "date-time",
"type": "string"
}
},
"required": [
"announced",
"unavailable_after"
],
"title": "DeprecationInfo",
"type": "object"
},
"detach_iso_from_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/detach_iso",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"detach_load_balancer_from_network_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/detach_from_network",
"properties": {
"network": {
"description": "ID of an existing network to detach the Load Balancer from.",
"example": 4711,
"format": "int64",
"type": "integer"
}
},
"required": [
"network"
],
"type": "object"
},
"detach_load_balancer_from_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/detach_from_network",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"detach_server_from_network_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/detach_from_network",
"properties": {
"network": {
"description": "ID of an existing network to detach the Server from.",
"example": 4711,
"format": "int64",
"type": "integer"
}
},
"required": [
"network"
],
"title": "DetachFromNetworkRequest",
"type": "object"
},
"detach_server_from_network_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/detach_from_network",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"detach_volume_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/volumes/{id}/actions/detach",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"disable_backups_for_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/disable_backup",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"disable_public_interface_of_load_balancer_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/disable_public_interface",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"disable_rescue_mode_for_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/disable_rescue",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"disable_snapshot_plan_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/disable_snapshot_plan",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"dns_ptr": {
"description": "Request for POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_dns_ptr | Request for POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/change_dns_ptr",
"properties": {
"dns_ptr": {
"description": "Domain Name to point to.\n\nPTR record content used for reverse DNS.\n | DNS pointer for the specific IP address.",
"example": "server.example.com",
"type": "string"
},
"ip": {
"description": "Single IPv4 or IPv6 address to create pointer for.\n | Single IPv6 address of this Server for which the reverse DNS entry has been set up.",
"example": "2001:db8::1",
"type": "string"
}
},
"required": [
"dns_ptr",
"ip"
],
"type": "object"
},
"enable_and_configure_backups_for_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/enable_backup",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"enable_public_interface_of_load_balancer_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/enable_public_interface",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"enable_rescue_mode_for_server_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/enable_rescue",
"properties": {
"ssh_keys": {
"description": "Array of SSH key IDs which should be injected into the rescue system.",
"example": [
2323
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"type": {
"default": "linux64",
"description": "Type of rescue system to boot.",
"enum": [
"linux64"
],
"type": "string"
}
},
"type": "object"
},
"enable_rescue_mode_for_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/enable_rescue",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"root_password": {
"description": "Password that will be set for this Server once the Action succeeds.",
"example": "zCWbFhnu950dUTko5f40",
"type": "string"
}
},
"type": "object"
},
"enable_snapshot_plan_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/enable_snapshot_plan",
"properties": {
"day_of_month": {
"default": null,
"description": "Day of the month when the Snapshot Plan is executed.\n\nNull means every day.\n",
"example": null,
"maximum": 31,
"minimum": 1,
"nullable": true,
"type": "integer"
},
"day_of_week": {
"default": null,
"description": "Day of the week when the Snapshot Plan is executed.\n\nStarts at 1 for Monday til 7 for Sunday. Null means every day.\n",
"example": 7,
"maximum": 7,
"minimum": 1,
"nullable": true,
"type": "integer"
},
"hour": {
"description": "Hour when the Snapshot Plan is executed (UTC).\n",
"example": 3,
"maximum": 23,
"minimum": 0,
"type": "integer"
},
"max_snapshots": {
"description": "Maximum amount of Snapshots that will be created by this Snapshot Plan.\n\nOlder Snapshots will be deleted.\n",
"example": 10,
"minimum": 1,
"type": "integer"
},
"minute": {
"description": "Minute when the Snapshot Plan is executed (UTC).\n",
"example": 30,
"maximum": 59,
"minimum": 0,
"type": "integer"
}
},
"required": [
"hour",
"max_snapshots",
"minute"
],
"type": "object"
},
"enable_snapshot_plan_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/enable_snapshot_plan",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"error": {
"description": "Error message for the Action if an error occurred, otherwise null.",
"properties": {
"code": {
"description": "Fixed error code for machines.",
"example": "action_failed",
"type": "string"
},
"message": {
"description": "Error message for humans.",
"example": "Action failed",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"error_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/actions | Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/actions/{action_id} | Response to GET https://api.hetzner.cloud/v1/certificates | Response to POST https://api.hetzner.cloud/v1/certificates | Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/actions | Response to GET https://api.hetzner.cloud/v1/certificates/{id} | Response to PUT https://api.hetzner.cloud/v1/certificates/{id} | Response to DELETE https://api.hetzner.cloud/v1/certificates/{id} | Response to POST https://api.hetzner.cloud/v1/certificates/{id}/actions/retry | Response to GET https://api.hetzner.cloud/v1/datacenters | Response to GET https://api.hetzner.cloud/v1/datacenters/{id} | Response to GET https://api.hetzner.cloud/v1/firewalls | Response to POST https://api.hetzner.cloud/v1/firewalls | Response to GET https://api.hetzner.cloud/v1/firewalls/{id} | Response to PUT https://api.hetzner.cloud/v1/firewalls/{id} | Response to DELETE https://api.hetzner.cloud/v1/firewalls/{id} | Response to POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/apply_to_resources | Response to POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/remove_from_resources | Response to POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/set_rules | Response to GET https://api.hetzner.cloud/v1/floating_ips | Response to POST https://api.hetzner.cloud/v1/floating_ips | Response to GET https://api.hetzner.cloud/v1/floating_ips/{id} | Response to PUT https://api.hetzner.cloud/v1/floating_ips/{id} | Response to DELETE https://api.hetzner.cloud/v1/floating_ips/{id} | Response to POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/assign | Response to POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_dns_ptr | Response to POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_protection | Response to POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/unassign | Response to GET https://api.hetzner.cloud/v1/images | Response to GET https://api.hetzner.cloud/v1/images/{id} | Response to PUT https://api.hetzner.cloud/v1/images/{id} | Response to DELETE https://api.hetzner.cloud/v1/images/{id} | Response to POST https://api.hetzner.cloud/v1/images/{id}/actions/change_protection | Response to GET https://api.hetzner.cloud/v1/isos | Response to GET https://api.hetzner.cloud/v1/isos/{id} | Response to GET https://api.hetzner.cloud/v1/load_balancer_types | Response to GET https://api.hetzner.cloud/v1/load_balancer_types/{id} | Response to GET https://api.hetzner.cloud/v1/load_balancers | Response to POST https://api.hetzner.cloud/v1/load_balancers | Response to GET https://api.hetzner.cloud/v1/load_balancers/{id} | Response to PUT https://api.hetzner.cloud/v1/load_balancers/{id} | Response to DELETE https://api.hetzner.cloud/v1/load_balancers/{id} | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_service | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_target | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/attach_to_network | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_algorithm | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_dns_ptr | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_protection | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_type | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/delete_service | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/detach_from_network | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/disable_public_interface | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/enable_public_interface | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/remove_target | Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/update_service | Response to GET https://api.hetzner.cloud/v1/load_balancers/{id}/metrics | Response to GET https://api.hetzner.cloud/v1/locations | Response to GET https://api.hetzner.cloud/v1/locations/{id} | Response to GET https://api.hetzner.cloud/v1/networks | Response to POST https://api.hetzner.cloud/v1/networks | Response to GET https://api.hetzner.cloud/v1/networks/{id} | Response to PUT https://api.hetzner.cloud/v1/networks/{id} | Response to DELETE https://api.hetzner.cloud/v1/networks/{id} | Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/add_route | Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/add_subnet | Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/change_ip_range | Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/change_protection | Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/delete_route | Response to POST https://api.hetzner.cloud/v1/networks/{id}/actions/delete_subnet | Response to GET https://api.hetzner.cloud/v1/placement_groups | Response to POST https://api.hetzner.cloud/v1/placement_groups | Response to GET https://api.hetzner.cloud/v1/placement_groups/{id} | Response to PUT https://api.hetzner.cloud/v1/placement_groups/{id} | Response to DELETE https://api.hetzner.cloud/v1/placement_groups/{id} | Response to GET https://api.hetzner.cloud/v1/pricing | Response to GET https://api.hetzner.cloud/v1/primary_ips | Response to POST https://api.hetzner.cloud/v1/primary_ips | Response to GET https://api.hetzner.cloud/v1/primary_ips/{id} | Response to PUT https://api.hetzner.cloud/v1/primary_ips/{id} | Response to DELETE https://api.hetzner.cloud/v1/primary_ips/{id} | Response to POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/assign | Response to POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/change_dns_ptr | Response to POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/change_protection | Response to POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/unassign | Response to GET https://api.hetzner.cloud/v1/server_types | Response to GET https://api.hetzner.cloud/v1/server_types/{id} | Response to GET https://api.hetzner.cloud/v1/servers | Response to POST https://api.hetzner.cloud/v1/servers | Response to GET https://api.hetzner.cloud/v1/servers/{id} | Response to PUT https://api.hetzner.cloud/v1/servers/{id} | Response to DELETE https://api.hetzner.cloud/v1/servers/{id} | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/add_to_placement_group | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/attach_iso | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/attach_to_network | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_alias_ips | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_dns_ptr | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_protection | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_type | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/create_image | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/detach_from_network | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/detach_iso | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/disable_backup | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/disable_rescue | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/enable_backup | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/enable_rescue | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/poweroff | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/poweron | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/reboot | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/rebuild | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/remove_from_placement_group | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/request_console | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/reset | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/reset_password | Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/shutdown | Response to GET https://api.hetzner.cloud/v1/servers/{id}/metrics | Response to GET https://api.hetzner.cloud/v1/ssh_keys | Response to POST https://api.hetzner.cloud/v1/ssh_keys | Response to GET https://api.hetzner.cloud/v1/ssh_keys/{id} | Response to PUT https://api.hetzner.cloud/v1/ssh_keys/{id} | Response to DELETE https://api.hetzner.cloud/v1/ssh_keys/{id} | Response to GET https://api.hetzner.cloud/v1/volumes | Response to POST https://api.hetzner.cloud/v1/volumes | Response to GET https://api.hetzner.cloud/v1/volumes/{id} | Response to PUT https://api.hetzner.cloud/v1/volumes/{id} | Response to DELETE https://api.hetzner.cloud/v1/volumes/{id} | Response to POST https://api.hetzner.cloud/v1/volumes/{id}/actions/attach | Response to POST https://api.hetzner.cloud/v1/volumes/{id}/actions/change_protection | Response to POST https://api.hetzner.cloud/v1/volumes/{id}/actions/detach | Response to POST https://api.hetzner.cloud/v1/volumes/{id}/actions/resize | Response to GET https://api.hetzner.cloud/v1/zones | Response to POST https://api.hetzner.cloud/v1/zones | Response to GET https://api.hetzner.cloud/v1/zones/{id_or_name} | Response to PUT https://api.hetzner.cloud/v1/zones/{id_or_name} | Response to DELETE https://api.hetzner.cloud/v1/zones/{id_or_name} | Response to GET https://api.hetzner.cloud/v1/zones/{id_or_name}/zonefile | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_primary_nameservers | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_protection | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/change_ttl | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/import_zonefile | Response to GET https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets | Response to GET https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type} | Response to PUT https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type} | Response to DELETE https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type} | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_protection | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_ttl | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/set_records | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/add_records | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/remove_records | Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/update_records | Response to GET https://api.hetzner.com/v1/storage_boxes | Response to POST https://api.hetzner.com/v1/storage_boxes | Response to GET https://api.hetzner.com/v1/storage_boxes/{id} | Response to PUT https://api.hetzner.com/v1/storage_boxes/{id} | Response to DELETE https://api.hetzner.com/v1/storage_boxes/{id} | Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/folders | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/change_protection | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/change_type | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/reset_subaccount_password | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/update_access_settings | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/rollback_snapshot | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/disable_snapshot_plan | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/enable_snapshot_plan | Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts | Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id} | Response to PUT https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id} | Response to DELETE https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id} | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory | Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/snapshots | Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/snapshots | Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/snapshots/{snapshot_id} | Response to PUT https://api.hetzner.com/v1/storage_boxes/{id}/snapshots/{snapshot_id} | Response to DELETE https://api.hetzner.com/v1/storage_boxes/{id}/snapshots/{snapshot_id} | Response to GET https://api.hetzner.com/v1/storage_box_types | Response to GET https://api.hetzner.com/v1/storage_box_types/{id}",
"example": {
"error": {
"code": "unauthorized",
"details": null,
"message": "unable to authenticate"
}
},
"properties": {
"error": {
"properties": {
"code": {
"description": "Error code for machines.",
"type": "string"
},
"details": {
"description": "Details about the error.",
"nullable": true,
"type": "object"
},
"message": {
"description": "Error message for humans.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
}
},
"required": [
"error"
],
"type": "object"
},
"export_zone_file_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/zones/{id_or_name}/zonefile",
"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",
"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",
"type": "string"
}
},
"required": [
"zonefile"
],
"type": "object"
},
"firewall": {
"description": "Firewalls can limit the network access to or from your resources.",
"properties": {
"applied_to": {
"items": {
"$ref": "#/components/schemas/firewall_resource_id"
},
"type": "array"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Firewall.\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n",
"example": "new-name",
"type": "string"
},
"rules": {
"items": {
"properties": {
"description": {
"description": "Description of the rule.",
"maxLength": 255,
"nullable": true,
"type": "string"
},
"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",
"example": [],
"items": {
"type": "string"
},
"type": "array"
},
"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",
"enum": [
"in",
"out"
],
"example": "in",
"type": "string"
},
"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",
"example": "80",
"nullable": true,
"type": "string"
},
"protocol": {
"description": "Network protocol to apply the rule for.",
"enum": [
"esp",
"gre",
"icmp",
"tcp",
"udp"
],
"type": "string"
},
"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",
"example": [
"192.0.2.2/32",
"192.0.2.0/24",
"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"destination_ips",
"direction",
"port",
"protocol",
"source_ips"
],
"title": "RuleResponse",
"type": "object"
},
"type": "array"
}
},
"required": [
"applied_to",
"created",
"id",
"name",
"rules"
],
"title": "FirewallResponse",
"type": "object"
},
"firewall_resource": {
"description": "Resource a Firewall should be applied to.",
"properties": {
"label_selector": {
"$ref": "#/components/schemas/label_selector"
},
"server": {
"$ref": "#/components/schemas/resource_id"
},
"type": {
"description": "Type of the resource.",
"enum": [
"label_selector",
"server"
],
"type": "string"
}
},
"required": [
"type"
],
"title": "FirewallResource",
"type": "object"
},
"firewall_resource_id": {
"description": "Resource a Firewall should be applied to.",
"properties": {
"applied_to_resources": {
"description": "Resources applied to via this Label Selector.\n",
"items": {
"properties": {
"server": {
"$ref": "#/components/schemas/resource_id"
},
"type": {
"description": "Type of resource.",
"enum": [
"server"
],
"example": "server",
"type": "string"
}
},
"title": "FirewallResourceIdAppliedToResources",
"type": "object"
},
"type": "array"
},
"label_selector": {
"$ref": "#/components/schemas/label_selector"
},
"server": {
"$ref": "#/components/schemas/resource_id"
},
"type": {
"description": "The type of resource to apply.",
"enum": [
"label_selector",
"server"
],
"example": "server",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"floating_ip": {
"properties": {
"blocked": {
"description": "Indicates whether the Floating IP is blocked.",
"example": false,
"type": "boolean"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"description": {
"description": "Description of the Resource.",
"example": "This describes my resource",
"nullable": true,
"type": "string"
},
"dns_ptr": {
"description": "List of reverse DNS entries for the Floating IP.\n",
"items": {
"$ref": "#/components/schemas/dns_ptr"
},
"type": "array"
},
"home_location": {
"$ref": "#/components/schemas/location"
},
"id": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"ip": {
"description": "IP address.",
"example": "2001:db8::/64",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"server": {
"description": "Server the Floating IP is assigned to.\n\n`null` if not assigned.\n",
"example": 42,
"format": "int64",
"nullable": true,
"type": "integer"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"blocked",
"created",
"description",
"dns_ptr",
"home_location",
"id",
"ip",
"labels",
"name",
"protection",
"server",
"type"
],
"type": "object"
},
"get_action_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/{resource}/actions",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"get_certificate_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/certificates/{id}",
"properties": {
"certificate": {
"$ref": "#/components/schemas/certificate"
}
},
"required": [
"certificate"
],
"title": "CertificateResponse",
"type": "object"
},
"get_data_center_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/datacenters/{id}",
"properties": {
"datacenter": {
"$ref": "#/components/schemas/data_center"
}
},
"required": [
"datacenter"
],
"type": "object"
},
"get_firewall_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/firewalls/{id}",
"properties": {
"firewall": {
"$ref": "#/components/schemas/firewall"
}
},
"required": [
"firewall"
],
"title": "FirewallResponse",
"type": "object"
},
"get_floating_ip_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/floating_ips/{id}",
"properties": {
"floating_ip": {
"$ref": "#/components/schemas/floating_ip"
}
},
"required": [
"floating_ip"
],
"type": "object"
},
"get_image_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/images/{id}",
"properties": {
"image": {
"$ref": "#/components/schemas/image"
}
},
"type": "object"
},
"get_iso_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/isos/{id}",
"properties": {
"iso": {
"$ref": "#/components/schemas/iso"
}
},
"required": [
"iso"
],
"type": "object"
},
"get_load_balancer_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/load_balancers/{id}",
"properties": {
"load_balancer": {
"$ref": "#/components/schemas/load_balancer"
}
},
"required": [
"load_balancer"
],
"type": "object"
},
"get_load_balancer_type_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/load_balancer_types/{id}",
"properties": {
"load_balancer_type": {
"$ref": "#/components/schemas/load_balancer_type"
}
},
"type": "object"
},
"get_location_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/locations/{id}",
"properties": {
"location": {
"$ref": "#/components/schemas/location"
}
},
"required": [
"location"
],
"type": "object"
},
"get_metrics_for_loadbalancer_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/load_balancers/{id}/metrics",
"properties": {
"metrics": {
"$ref": "#/components/schemas/metrics"
}
},
"required": [
"metrics"
],
"type": "object"
},
"get_metrics_for_server_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/servers/{id}/metrics",
"properties": {
"metrics": {
"$ref": "#/components/schemas/metrics"
}
},
"required": [
"metrics"
],
"type": "object"
},
"get_multiple_actions_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/actions",
"properties": {
"actions": {
"items": {
"$ref": "#/components/schemas/action"
},
"type": "array"
}
},
"required": [
"actions"
],
"title": "ActionListResponse",
"type": "object"
},
"get_network_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/networks/{id}",
"properties": {
"network": {
"$ref": "#/components/schemas/network"
}
},
"type": "object"
},
"get_placementgroup_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/placement_groups/{id}",
"properties": {
"placement_group": {
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Placement Group.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"servers": {
"description": "Array of IDs of Servers that are part of this Placement Group.",
"example": [
42
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"type": {
"description": "Type of Placement Group.\n",
"enum": [
"spread"
],
"example": "spread",
"type": "string"
}
},
"required": [
"created",
"id",
"labels",
"name",
"servers",
"type"
],
"title": "PlacementGroup",
"type": "object"
}
},
"required": [
"placement_group"
],
"title": "PlacementGroupResponse",
"type": "object"
},
"get_primary_ip_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/primary_ips/{id}",
"properties": {
"primary_ip": {
"properties": {
"assignee_id": {
"description": "ID of resource the Primary IP is assigned to.\n\n`null` if the Primary IP is not assigned.\n",
"example": 17,
"format": "int64",
"nullable": true,
"type": "integer"
},
"assignee_type": {
"description": "Type of resource the Primary IP can get assigned to.\n",
"enum": [
"server"
],
"example": "server",
"type": "string"
},
"auto_delete": {
"default": false,
"description": "Auto deletion state.\n\nIf enabled the Primary IP will be deleted once the assigned resource gets deleted.\n",
"example": true,
"type": "boolean"
},
"blocked": {
"description": "Blocked state of the Primary IP.",
"example": false,
"type": "boolean"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"datacenter": {
"allOf": [
{
"$ref": "#/components/schemas/data_center"
}
],
"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 of the Primary IP.\n"
},
"dns_ptr": {
"description": "List of reverse DNS records.",
"items": {
"$ref": "#/components/schemas/dns_ptr"
},
"type": "array"
},
"id": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"ip": {
"description": "IP address.",
"example": "2001:db8::/64",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"$ref": "#/components/schemas/location"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"assignee_id",
"assignee_type",
"auto_delete",
"blocked",
"created",
"datacenter",
"dns_ptr",
"id",
"ip",
"labels",
"location",
"name",
"protection",
"type"
],
"title": "PrimaryIP",
"type": "object"
}
},
"required": [
"primary_ip"
],
"title": "PrimaryIPResponse",
"type": "object"
},
"get_rrset_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}",
"properties": {
"rrset": {
"$ref": "#/components/schemas/resource_record_set"
}
},
"required": [
"rrset"
],
"type": "object"
},
"get_server_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/servers/{id}",
"properties": {
"server": {
"$ref": "#/components/schemas/server"
}
},
"type": "object"
},
"get_server_type_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/server_types/{id}",
"properties": {
"server_type": {
"$ref": "#/components/schemas/server_type"
}
},
"required": [
"server_type"
],
"type": "object"
},
"get_snapshot_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/snapshots/{snapshot_id}",
"properties": {
"snapshot": {
"$ref": "#/components/schemas/snapshot"
}
},
"required": [
"snapshot"
],
"type": "object"
},
"get_ssh_key_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/ssh_keys/{id}",
"properties": {
"ssh_key": {
"$ref": "#/components/schemas/ssh_key"
}
},
"required": [
"ssh_key"
],
"type": "object"
},
"get_storage_box_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_boxes/{id}",
"properties": {
"storage_box": {
"$ref": "#/components/schemas/storage_box"
}
},
"required": [
"storage_box"
],
"type": "object"
},
"get_storage_box_type_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_box_types/{id}",
"properties": {
"storage_box_type": {
"$ref": "#/components/schemas/storage_box_type"
}
},
"required": [
"storage_box_type"
],
"type": "object"
},
"get_subaccount_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}",
"properties": {
"subaccount": {
"$ref": "#/components/schemas/subaccount"
}
},
"required": [
"subaccount"
],
"type": "object"
},
"get_volume_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/volumes/{id}",
"properties": {
"volume": {
"$ref": "#/components/schemas/volume"
}
},
"required": [
"volume"
],
"type": "object"
},
"get_zone_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/zones/{id_or_name}",
"properties": {
"zone": {
"$ref": "#/components/schemas/zone"
}
},
"required": [
"zone"
],
"type": "object"
},
"http": {
"description": "Configuration option for protocols http and https.",
"properties": {
"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`.",
"example": [
897
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"cookie_lifetime": {
"default": 300,
"description": "Lifetime of the cookie used for sticky sessions (in seconds).",
"example": 300,
"type": "integer"
},
"cookie_name": {
"default": "HCLBSTICKY",
"description": "Name of the cookie used for sticky sessions.",
"example": "HCLBSTICKY",
"type": "string"
},
"redirect_http": {
"default": false,
"description": "Redirect HTTP requests to HTTPS. Only available if `protocol` is `https`.",
"example": true,
"type": "boolean"
},
"sticky_sessions": {
"default": false,
"description": "Use sticky sessions. Only available if `protocol` is `http` or `https`.",
"example": true,
"type": "boolean"
}
},
"title": "LoadBalancerServiceHTTP",
"type": "object"
},
"image": {
"description": "Image the server is based on.",
"properties": {
"architecture": {
"$ref": "#/components/schemas/architecture"
},
"bound_to": {
"description": "ID of Server the Image is bound to. Only set for Images of type `backup`.",
"example": null,
"format": "int64",
"nullable": true,
"type": "integer"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"created_from": {
"allOf": [
{
"$ref": "#/components/schemas/created_from"
}
],
"description": "Information about the Server the Image was created from.",
"nullable": true
},
"deleted": {
"description": "Point in time where the Image was deleted (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": null,
"nullable": true,
"type": "string"
},
"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).",
"example": "2018-02-28T00:00:00Z",
"format": "date-time",
"nullable": true,
"type": "string"
},
"description": {
"description": "Description of the Image.",
"example": "Ubuntu 24.04 Standard 64 bit",
"type": "string"
},
"disk_size": {
"description": "Size of the disk contained in the Image in GB.",
"example": 10,
"type": "number"
},
"id": {
"description": "ID of the Image.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"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.",
"example": 2.3,
"nullable": true,
"type": "number"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Unique identifier of the Image. This value is only set for system Images.",
"example": "ubuntu-24.04",
"nullable": true,
"type": "string"
},
"os_flavor": {
"description": "Flavor of operating system contained in the Image.",
"enum": [
"alma",
"centos",
"debian",
"fedora",
"opensuse",
"rocky",
"ubuntu",
"unknown"
],
"example": "ubuntu",
"type": "string"
},
"os_version": {
"description": "Operating system version.",
"example": "24.04",
"nullable": true,
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"rapid_deploy": {
"description": "Indicates that rapid deploy of the Image is available.",
"example": false,
"type": "boolean"
},
"status": {
"description": "Whether the Image can be used or if it's still being created or unavailable.",
"enum": [
"available",
"creating",
"unavailable"
],
"type": "string"
},
"type": {
"description": "Type of the Image.",
"enum": [
"app",
"backup",
"snapshot",
"system"
],
"example": "snapshot",
"type": "string"
}
},
"required": [
"architecture",
"bound_to",
"created",
"created_from",
"deleted",
"deprecated",
"description",
"disk_size",
"id",
"image_size",
"labels",
"name",
"os_flavor",
"os_version",
"protection",
"status",
"type"
],
"type": "object"
},
"import_zone_file_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/import_zonefile",
"properties": {
"zonefile": {
"description": "Zone file to import.\n\nSee Zone file import for more details.\n",
"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",
"type": "string"
}
},
"required": [
"zonefile"
],
"type": "object"
},
"import_zone_file_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/actions/import_zonefile",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"ip_type": {
"description": "The Floating IP type. | Type of Primary IP the price is for. | Type of Floating IP the price is for. | Primary IP type.",
"enum": [
"ipv4",
"ipv6"
],
"example": "ipv6",
"type": "string"
},
"ipv4": {
"description": "IP address (v4) and its reverse DNS entry of this Server.",
"properties": {
"blocked": {
"description": "If the IP is blocked by our anti abuse dept.",
"example": false,
"type": "boolean"
},
"dns_ptr": {
"description": "Reverse DNS PTR entry for the IPv4 addresses of this Server.",
"example": "server01.example.com",
"type": "string"
},
"id": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"ip": {
"description": "IP address (v4) of this Server.",
"example": "1.2.3.4",
"type": "string"
}
},
"required": [
"blocked",
"dns_ptr",
"ip"
],
"type": "object"
},
"ipv6": {
"description": "IPv6 network assigned to this Server and its reverse DNS entry.",
"properties": {
"blocked": {
"description": "If the IP is blocked by our anti abuse dept.",
"example": false,
"type": "boolean"
},
"dns_ptr": {
"description": "Reverse DNS PTR entries for the IPv6 addresses of this Server.",
"items": {
"$ref": "#/components/schemas/dns_ptr"
},
"nullable": true,
"type": "array"
},
"id": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"ip": {
"description": "IP address (v6) of this Server.",
"example": "2001:db8::/64",
"type": "string"
}
},
"required": [
"blocked",
"dns_ptr",
"ip"
],
"type": "object"
},
"iso": {
"description": "ISO Image that is attached to this Server. Null if no ISO is attached.",
"properties": {
"architecture": {
"allOf": [
{
"$ref": "#/components/schemas/architecture"
}
],
"description": "CPU architecture compatible with the ISO.\n\nNull indicates no restriction on the architecture (wildcard).\n",
"nullable": true
},
"deprecation": {
"allOf": [
{
"$ref": "#/components/schemas/deprecation_info"
}
],
"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",
"nullable": true
},
"description": {
"description": "Description of the ISO.",
"example": "FreeBSD 11.0 x64",
"type": "string"
},
"id": {
"description": "ID of the ISO.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"name": {
"description": "Unique identifier of the ISO. Only set for public ISOs.",
"example": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"nullable": true,
"type": "string"
},
"type": {
"description": "Type of the ISO.",
"enum": [
"private",
"public"
],
"nullable": true,
"type": "string"
}
},
"required": [
"architecture",
"deprecation",
"description",
"id",
"name",
"type"
],
"type": "object"
},
"label_selector": {
"description": "Configuration for type LabelSelector, required if type is `label_selector`",
"properties": {
"selector": {
"description": "The selector. | Label selector.",
"example": "env=prod",
"type": "string"
}
},
"required": [
"selector"
],
"type": "object"
},
"labels": {
"additionalProperties": {
"pattern": "^(()|[a-z0-9A-Z]|([a-z0-9A-Z][a-z0-9A-Z\\._-]{0,61}[a-z0-9A-Z]))$",
"type": "string"
},
"description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"Labels\".\n | User-defined labels (`key/value` pairs) for the Resource.\n\nNote that the set of Labels provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"Labels\".\n",
"example": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"type": "object"
},
"list_actions_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/{resource}/actions/{id}",
"properties": {
"actions": {
"items": {
"$ref": "#/components/schemas/action"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"actions",
"meta"
],
"title": "ActionListResponseWithMeta",
"type": "object"
},
"list_certificates_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/certificates",
"properties": {
"certificates": {
"items": {
"$ref": "#/components/schemas/certificate"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"certificates",
"meta"
],
"title": "CertificatesResponse",
"type": "object"
},
"list_data_centers_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/datacenters",
"properties": {
"datacenters": {
"description": "List of Data Centers.",
"items": {
"$ref": "#/components/schemas/data_center"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
},
"recommendation": {
"description": "Recommended Data Center for creating new resources.",
"example": 1,
"format": "int64",
"type": "integer"
}
},
"required": [
"datacenters",
"meta",
"recommendation"
],
"type": "object"
},
"list_firewalls_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/firewalls",
"properties": {
"firewalls": {
"items": {
"$ref": "#/components/schemas/firewall"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"firewalls",
"meta"
],
"title": "FirewallsResponse",
"type": "object"
},
"list_floating_ips_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/floating_ips",
"properties": {
"floating_ips": {
"items": {
"$ref": "#/components/schemas/floating_ip"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"floating_ips",
"meta"
],
"type": "object"
},
"list_folders_of_storage_box_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/folders",
"properties": {
"folders": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"folders"
],
"type": "object"
},
"list_images_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/images",
"properties": {
"images": {
"items": {
"$ref": "#/components/schemas/image"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"images",
"meta"
],
"type": "object"
},
"list_isos_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/isos",
"properties": {
"isos": {
"items": {
"$ref": "#/components/schemas/iso"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"isos",
"meta"
],
"type": "object"
},
"list_load_balancer_types_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/load_balancer_types",
"properties": {
"load_balancer_types": {
"items": {
"$ref": "#/components/schemas/load_balancer_type"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"load_balancer_types",
"meta"
],
"type": "object"
},
"list_load_balancers_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/load_balancers",
"properties": {
"load_balancers": {
"items": {
"$ref": "#/components/schemas/load_balancer"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"load_balancers",
"meta"
],
"type": "object"
},
"list_locations_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/locations",
"properties": {
"locations": {
"description": "List of Locations.",
"items": {
"$ref": "#/components/schemas/location"
},
"type": "array"
},
"meta": {
"$ref": "#/components/schemas/meta"
}
},
"required": [
"locations",
"meta"
],
"type": "object"
},
"list_networks_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/networks",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"networks": {
"items": {
"$ref": "#/components/schemas/network"
},
"type": "array"
}
},
"required": [
"meta",
"networks"
],
"type": "object"
},
"list_placement_groups_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/placement_groups",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"placement_groups": {
"items": {
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Placement Group.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"servers": {
"description": "Array of IDs of Servers that are part of this Placement Group.",
"example": [
42
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"type": {
"description": "Type of Placement Group.\n",
"enum": [
"spread"
],
"example": "spread",
"type": "string"
}
},
"required": [
"created",
"id",
"labels",
"name",
"servers",
"type"
],
"title": "PlacementGroup",
"type": "object"
},
"type": "array"
}
},
"required": [
"meta",
"placement_groups"
],
"title": "PlacementGroupsResponse",
"type": "object"
},
"list_prices_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/pricing",
"properties": {
"pricing": {
"properties": {
"currency": {
"description": "Currency the returned prices are expressed in, coded according to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).",
"example": "EUR",
"type": "string"
},
"floating_ip": {
"deprecated": true,
"description": "Price of 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",
"properties": {
"price_monthly": {
"$ref": "#/components/schemas/price"
}
},
"required": [
"price_monthly"
],
"type": "object"
},
"floating_ips": {
"description": "Price of Floating IPs per type and per Location.",
"items": {
"properties": {
"prices": {
"description": "Price of the Floating IP type per Location.",
"items": {
"$ref": "#/components/schemas/price_per_time_monthly"
},
"type": "array"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"prices",
"type"
],
"title": "ListPricesResponsePricingFloatingIps",
"type": "object"
},
"type": "array"
},
"image": {
"description": "Price of Images.",
"properties": {
"price_per_gb_month": {
"$ref": "#/components/schemas/price"
}
},
"required": [
"price_per_gb_month"
],
"type": "object"
},
"load_balancer_types": {
"description": "Price of Load Balancer per type and per Location.",
"items": {
"properties": {
"id": {
"description": "ID of the Load Balancer Types the price is for.",
"example": 1,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"name": {
"description": "Name of the Load Balancer Types the price is for.",
"example": "lb11",
"type": "string"
},
"prices": {
"description": "Price of the Load Balancer Types per Location.",
"items": {
"$ref": "#/components/schemas/price_per_time"
},
"type": "array"
}
},
"required": [
"id",
"name",
"prices"
],
"title": "ListPricesResponsePricingLoadBalancerTypes",
"type": "object"
},
"type": "array"
},
"primary_ips": {
"description": "Price of Primary IPs per type and per Location.",
"items": {
"properties": {
"prices": {
"description": "Price of the Primary IP type per Location.",
"items": {
"$ref": "#/components/schemas/price_per_time_without_traffic"
},
"type": "array"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"prices",
"type"
],
"title": "ListPricesResponsePricingPrimaryIps",
"type": "object"
},
"type": "array"
},
"server_backup": {
"description": "Price of Server backups.",
"properties": {
"percentage": {
"description": "Price increase of the Server base price in percentage.",
"example": "20.00",
"format": "decimal",
"type": "string"
}
},
"required": [
"percentage"
],
"type": "object"
},
"server_types": {
"description": "Price of Server per type and per Location.",
"items": {
"properties": {
"id": {
"description": "ID of the Server Types the price is for.",
"example": 104,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"name": {
"description": "Name of the Server Types the price is for.",
"example": "cpx22",
"type": "string"
},
"prices": {
"description": "Price of the Server Types per Location.",
"items": {
"$ref": "#/components/schemas/price_per_time"
},
"type": "array"
}
},
"required": [
"id",
"name",
"prices"
],
"title": "ListPricesResponsePricingServerTypes",
"type": "object"
},
"type": "array"
},
"vat_rate": {
"description": "VAT rate used for calculating prices with VAT.",
"example": "19.00",
"format": "decimal",
"type": "string"
},
"volume": {
"description": "Price of Volumes.",
"properties": {
"price_per_gb_month": {
"$ref": "#/components/schemas/price"
}
},
"required": [
"price_per_gb_month"
],
"type": "object"
}
},
"required": [
"currency",
"floating_ip",
"floating_ips",
"image",
"load_balancer_types",
"primary_ips",
"server_backup",
"server_types",
"vat_rate",
"volume"
],
"type": "object"
}
},
"required": [
"pricing"
],
"type": "object"
},
"list_primary_ips_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/primary_ips",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"primary_ips": {
"items": {
"properties": {
"assignee_id": {
"description": "ID of resource the Primary IP is assigned to.\n\n`null` if the Primary IP is not assigned.\n",
"example": 17,
"format": "int64",
"nullable": true,
"type": "integer"
},
"assignee_type": {
"description": "Type of resource the Primary IP can get assigned to.\n",
"enum": [
"server"
],
"example": "server",
"type": "string"
},
"auto_delete": {
"default": false,
"description": "Auto deletion state.\n\nIf enabled the Primary IP will be deleted once the assigned resource gets deleted.\n",
"example": true,
"type": "boolean"
},
"blocked": {
"description": "Blocked state of the Primary IP.",
"example": false,
"type": "boolean"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"datacenter": {
"allOf": [
{
"$ref": "#/components/schemas/data_center"
}
],
"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 of the Primary IP.\n"
},
"dns_ptr": {
"description": "List of reverse DNS records.",
"items": {
"$ref": "#/components/schemas/dns_ptr"
},
"type": "array"
},
"id": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"ip": {
"description": "IP address.",
"example": "2001:db8::/64",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"$ref": "#/components/schemas/location"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"assignee_id",
"assignee_type",
"auto_delete",
"blocked",
"created",
"datacenter",
"dns_ptr",
"id",
"ip",
"labels",
"location",
"name",
"protection",
"type"
],
"title": "PrimaryIP",
"type": "object"
},
"type": "array"
}
},
"required": [
"meta",
"primary_ips"
],
"title": "PrimaryIPsResponse",
"type": "object"
},
"list_rrsets_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"rrsets": {
"items": {
"$ref": "#/components/schemas/resource_record_set"
},
"type": "array"
}
},
"required": [
"meta",
"rrsets"
],
"type": "object"
},
"list_server_types_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/server_types",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"server_types": {
"items": {
"$ref": "#/components/schemas/server_type"
},
"type": "array"
}
},
"required": [
"meta",
"server_types"
],
"type": "object"
},
"list_servers_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/servers",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"servers": {
"items": {
"$ref": "#/components/schemas/server"
},
"type": "array"
}
},
"required": [
"meta",
"servers"
],
"type": "object"
},
"list_snapshots_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/snapshots",
"properties": {
"snapshots": {
"items": {
"$ref": "#/components/schemas/snapshot"
},
"type": "array"
}
},
"required": [
"snapshots"
],
"type": "object"
},
"list_ssh_keys_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/ssh_keys",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"ssh_keys": {
"items": {
"$ref": "#/components/schemas/ssh_key"
},
"type": "array"
}
},
"required": [
"meta",
"ssh_keys"
],
"type": "object"
},
"list_storage_box_types_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_box_types",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"storage_box_types": {
"items": {
"$ref": "#/components/schemas/storage_box_type"
},
"type": "array"
}
},
"required": [
"meta",
"storage_box_types"
],
"type": "object"
},
"list_storage_boxes_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_boxes",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"storage_boxes": {
"items": {
"$ref": "#/components/schemas/storage_box"
},
"type": "array"
}
},
"required": [
"meta",
"storage_boxes"
],
"type": "object"
},
"list_subaccounts_response": {
"description": "Response to GET https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts",
"properties": {
"subaccounts": {
"items": {
"$ref": "#/components/schemas/subaccount"
},
"type": "array"
}
},
"required": [
"subaccounts"
],
"type": "object"
},
"list_volumes_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/volumes",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"volumes": {
"items": {
"$ref": "#/components/schemas/volume"
},
"type": "array"
}
},
"required": [
"meta",
"volumes"
],
"type": "object"
},
"list_zones_response": {
"description": "Response to GET https://api.hetzner.cloud/v1/zones",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"zones": {
"items": {
"$ref": "#/components/schemas/zone"
},
"type": "array"
}
},
"required": [
"meta",
"zones"
],
"type": "object"
},
"load_balancer": {
"properties": {
"algorithm": {
"$ref": "#/components/schemas/load_balancer_algorithm"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"included_traffic": {
"description": "Free Traffic for the current billing period in bytes.",
"example": 10000,
"format": "int64",
"type": "integer"
},
"ingoing_traffic": {
"description": "Inbound Traffic for the current billing period in bytes.",
"format": "int64",
"nullable": true,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"load_balancer_type": {
"$ref": "#/components/schemas/load_balancer_type"
},
"location": {
"$ref": "#/components/schemas/location"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"outgoing_traffic": {
"description": "Outbound Traffic for the current billing period in bytes.",
"format": "int64",
"nullable": true,
"type": "integer"
},
"private_net": {
"description": "Private networks information.",
"items": {
"$ref": "#/components/schemas/load_balancer_private_net"
},
"type": "array"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"public_net": {
"$ref": "#/components/schemas/load_balancer_public_net"
},
"services": {
"description": "List of services that belong to this Load Balancer.",
"items": {
"$ref": "#/components/schemas/load_balancer_service"
},
"type": "array"
},
"targets": {
"description": "List of targets that belong to this Load Balancer.",
"items": {
"$ref": "#/components/schemas/load_balancer_target"
},
"type": "array"
}
},
"required": [
"algorithm",
"created",
"id",
"included_traffic",
"ingoing_traffic",
"labels",
"load_balancer_type",
"location",
"name",
"outgoing_traffic",
"private_net",
"protection",
"public_net",
"services",
"targets"
],
"type": "object"
},
"load_balancer_add_target": {
"description": "A target to be added to a load balancer.",
"properties": {
"ip": {
"$ref": "#/components/schemas/load_balancer_target_ip"
},
"label_selector": {
"$ref": "#/components/schemas/label_selector"
},
"server": {
"$ref": "#/components/schemas/resource_id"
},
"type": {
"description": "Type of the resource.",
"enum": [
"ip",
"label_selector",
"server"
],
"type": "string"
},
"use_private_ip": {
"default": false,
"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`.",
"example": true,
"type": "boolean"
}
},
"required": [
"type"
],
"title": "LoadBalancerTarget",
"type": "object"
},
"load_balancer_algorithm": {
"default": {
"type": "round_robin"
},
"description": "Algorithm of the Load Balancer.",
"properties": {
"type": {
"default": "round_robin",
"description": "Type of the algorithm.",
"enum": [
"least_connections",
"round_robin"
],
"type": "string"
}
},
"required": [
"type"
],
"title": "LoadBalancerAlgorithm",
"type": "object"
},
"load_balancer_private_net": {
"properties": {
"ip": {
"description": "IP address (v4) of this Load Balancer in this Network.",
"example": "10.0.0.2",
"type": "string"
},
"network": {
"description": "ID of the Network.",
"example": 4711,
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"load_balancer_public_net": {
"description": "Public network information.",
"properties": {
"enabled": {
"description": "Public Interface enabled or not.",
"type": "boolean"
},
"ipv4": {
"description": "IP address (v4).",
"properties": {
"dns_ptr": {
"description": "Reverse DNS PTR entry for the IPv4 address of this Load Balancer.",
"example": "lb1.example.com",
"nullable": true,
"type": "string"
},
"ip": {
"description": "IP address (v4) of this Load Balancer.",
"example": "1.2.3.4",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ipv6": {
"description": "IP address (v6).",
"properties": {
"dns_ptr": {
"description": "Reverse DNS PTR entry for the IPv6 address of this Load Balancer.",
"example": "lb1.example.com",
"nullable": true,
"type": "string"
},
"ip": {
"description": "IP address (v6) of this Load Balancer.",
"example": "2001:db8::1",
"nullable": true,
"type": "string"
}
},
"type": "object"
}
},
"required": [
"enabled",
"ipv4",
"ipv6"
],
"type": "object"
},
"load_balancer_selected_target": {
"description": "Resolved label selector target Servers. Only present for type \"label_selector\".",
"properties": {
"health_status": {
"description": "List of health statuses of the services on this target. Only present for target types \"server\" and \"ip\".",
"items": {
"$ref": "#/components/schemas/load_balancer_target_health_status"
},
"title": "LoadBalancerTargetHealthStatus",
"type": "array"
},
"server": {
"$ref": "#/components/schemas/resource_id"
},
"type": {
"description": "Type of the resource. Here always \"server\".",
"example": "server",
"type": "string"
},
"use_private_ip": {
"default": false,
"description": "Use the private network IP instead of the public IP. Only present for target types \"server\" and \"label_selector\".",
"title": "LoadBalancerTargetUsePrivateIP",
"type": "boolean"
}
},
"title": "LoadBalancerTargetTarget",
"type": "object"
},
"load_balancer_service": {
"description": "A service for a Load Balancer.",
"properties": {
"destination_port": {
"description": "Port the Load Balancer will balance to.",
"example": 80,
"type": "integer"
},
"health_check": {
"additionalProperties": false,
"description": "Service health check.",
"properties": {
"http": {
"additionalProperties": false,
"description": "Additional configuration for protocol http.",
"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.",
"example": "example.com",
"nullable": true,
"type": "string"
},
"path": {
"description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.",
"example": "/",
"type": "string"
},
"response": {
"description": "String that must be contained in HTTP response in order to pass the health check.",
"example": "{\"status\": \"ok\"}",
"type": "string"
},
"status_codes": {
"default": [
"2??",
"3??"
],
"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.",
"example": [
"2??",
"3??"
],
"items": {
"type": "string"
},
"type": "array"
},
"tls": {
"description": "Use HTTPS for health check.",
"example": false,
"type": "boolean"
}
},
"required": [
"domain",
"path"
],
"type": "object"
},
"interval": {
"description": "Time interval in seconds health checks are performed.",
"example": 15,
"type": "integer"
},
"port": {
"description": "Port the health check will be performed on.",
"example": 4711,
"type": "integer"
},
"protocol": {
"description": "Type of the health check.",
"enum": [
"http",
"tcp"
],
"example": "http",
"type": "string"
},
"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.",
"example": 3,
"type": "integer"
},
"timeout": {
"description": "Time in seconds after an attempt is considered a timeout.",
"example": 10,
"type": "integer"
}
},
"required": [
"interval",
"port",
"protocol",
"retries",
"timeout"
],
"title": "LoadBalancerServiceHealthCheck",
"type": "object"
},
"http": {
"$ref": "#/components/schemas/http"
},
"listen_port": {
"description": "Port the Load Balancer listens on.",
"example": 443,
"type": "integer"
},
"protocol": {
"description": "Protocol of the Load Balancer.",
"enum": [
"http",
"https",
"tcp"
],
"example": "https",
"type": "string"
},
"proxyprotocol": {
"description": "Is Proxyprotocol enabled or not.",
"example": false,
"type": "boolean"
}
},
"required": [
"destination_port",
"health_check",
"listen_port",
"protocol",
"proxyprotocol"
],
"title": "LoadBalancerService",
"type": "object"
},
"load_balancer_target": {
"description": "A target of a Load Balancer.",
"properties": {
"health_status": {
"description": "List of health statuses of the services on this target. Only present for target types \"server\" and \"ip\".",
"items": {
"$ref": "#/components/schemas/load_balancer_target_health_status"
},
"title": "LoadBalancerTargetHealthStatus",
"type": "array"
},
"ip": {
"$ref": "#/components/schemas/load_balancer_target_ip"
},
"label_selector": {
"$ref": "#/components/schemas/label_selector"
},
"server": {
"$ref": "#/components/schemas/resource_id"
},
"targets": {
"description": "List of resolved label selector target Servers. Only present for type \"label_selector\".",
"items": {
"$ref": "#/components/schemas/load_balancer_selected_target"
},
"type": "array"
},
"type": {
"description": "Type of the resource.",
"enum": [
"ip",
"label_selector",
"server"
],
"type": "string"
},
"use_private_ip": {
"default": false,
"description": "Use the private network IP instead of the public IP. Only present for target types \"server\" and \"label_selector\".",
"title": "LoadBalancerTargetUsePrivateIP",
"type": "boolean"
}
},
"required": [
"type"
],
"title": "LoadBalancerTarget",
"type": "object"
},
"load_balancer_target_health_status": {
"description": "Health status of the services on this target. Only present for target types \"server\" and \"ip\".",
"properties": {
"listen_port": {
"example": 443,
"type": "integer"
},
"status": {
"enum": [
"healthy",
"unhealthy",
"unknown"
],
"example": "healthy",
"type": "string"
}
},
"type": "object"
},
"load_balancer_target_ip": {
"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`. | 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`.",
"properties": {
"ip": {
"description": "IP of a server that belongs to the same customer (public IPv4/IPv6) or private IP in a subnet type vswitch.",
"example": "203.0.113.1",
"type": "string"
}
},
"required": [
"ip"
],
"title": "LoadBalancerTargetIP",
"type": "object"
},
"load_balancer_type": {
"properties": {
"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).",
"example": "2016-01-30T23:50:00Z",
"format": "date-time",
"nullable": true,
"type": "string"
},
"description": {
"description": "Description of the Load Balancer type.",
"example": "LB11",
"type": "string"
},
"id": {
"description": "ID of the Load Balancer type.",
"example": 1,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"max_assigned_certificates": {
"description": "Number of SSL Certificates that can be assigned to a single Load Balancer.",
"example": 10,
"format": "int64",
"type": "integer"
},
"max_connections": {
"description": "Number of maximum simultaneous open connections.",
"example": 20000,
"format": "int64",
"type": "integer"
},
"max_services": {
"description": "Number of services a Load Balancer of this type can have.",
"example": 5,
"format": "int64",
"type": "integer"
},
"max_targets": {
"description": "Number of targets a single Load Balancer can have.",
"example": 25,
"format": "int64",
"type": "integer"
},
"name": {
"description": "Unique identifier of the Load Balancer type.",
"example": "lb11",
"type": "string"
},
"prices": {
"description": "Price per Location.",
"items": {
"$ref": "#/components/schemas/price_per_time"
},
"type": "array"
}
},
"required": [
"deprecated",
"description",
"id",
"max_assigned_certificates",
"max_connections",
"max_services",
"max_targets",
"name",
"prices"
],
"type": "object"
},
"location": {
"description": "Location the Data Center is located at.\n | Location of the Primary IP.\n | Location this Resource is located at.\n | Location of the Volume. Volume can only be attached to Servers in the same Location. | Location of the Storage Box.",
"properties": {
"city": {
"description": "Name of the closest city to the Location.\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n",
"example": "Falkenstein",
"type": "string"
},
"country": {
"description": "Country the Location resides in.\n\nISO 3166-1 alpha-2 code of the country.\n",
"example": "DE",
"type": "string"
},
"description": {
"description": "Human readable description of the Location.",
"example": "Falkenstein DC Park 1",
"type": "string"
},
"id": {
"description": "ID of the Location.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"latitude": {
"description": "Latitude of the city closest to the Location.",
"example": 50.47612,
"format": "double",
"type": "number"
},
"longitude": {
"description": "Longitude of the city closest to the Location.",
"example": 12.370071,
"format": "double",
"type": "number"
},
"name": {
"description": "Unique identifier of the Location.",
"example": "fsn1",
"pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$",
"type": "string"
},
"network_zone": {
"description": "Name of the Network Zone this Location resides in.",
"example": "eu-central",
"pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$",
"type": "string"
}
},
"required": [
"city",
"country",
"description",
"id",
"latitude",
"longitude",
"name",
"network_zone"
],
"type": "object"
},
"meta": {
"properties": {
"pagination": {
"$ref": "#/components/schemas/pagination"
}
},
"required": [
"pagination"
],
"title": "ListMeta",
"type": "object"
},
"metrics": {
"description": "You must specify the type of metric to get: open_connections, requests_per_second or bandwidth. You can also specify more than one type by comma separation, e.g. requests_per_second,bandwidth. Depending on the type you will get different time series data.",
"properties": {
"end": {
"description": "End of period of metrics reported (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2017-01-01T23:00:00Z",
"format": "date-time",
"type": "string"
},
"start": {
"description": "Start of period of metrics reported (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2017-01-01T00:00:00Z",
"format": "date-time",
"type": "string"
},
"step": {
"description": "Resolution of results in seconds.",
"example": 60,
"type": "integer"
},
"time_series": {
"additionalProperties": {
"properties": {
"values": {
"description": "Metrics Timestamps with values.",
"items": {
"items": {
"oneOf": [
{
"type": "number"
},
{
"type": "string"
}
],
"title": "MetricsTimeSeriesValue"
},
"type": "array"
},
"type": "array"
}
},
"required": [
"values"
],
"type": "object"
},
"description": "Hash with timeseries information, containing the name of timeseries as key.",
"example": {
"name_of_timeseries": {
"values": [
[
1435781470.622,
"42"
],
[
1435781471.622,
"43"
]
]
}
},
"title": "MetricsTimeSeries",
"type": "object"
}
},
"required": [
"end",
"start",
"step",
"time_series"
],
"type": "object"
},
"nameserver": {
"description": "Primary nameserver that returns 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",
"properties": {
"address": {
"description": "Public IPv4 or IPv6 address of the primary nameserver.",
"example": "198.51.100.1",
"type": "string"
},
"port": {
"default": 53,
"description": "Port of the primary nameserver.",
"example": 5353,
"type": "integer"
},
"tsig_algorithm": {
"description": "[Transaction signature (TSIG)](https://en.wikipedia.org/wiki/TSIG) algorithm\nused to generate the TSIG key.\n",
"enum": [
"hmac-md5",
"hmac-sha1",
"hmac-sha256"
],
"type": "string"
},
"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"
}
},
"required": [
"address"
],
"type": "object"
},
"network": {
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"expose_routes_to_vswitch": {
"description": "Indicates if the routes from this Network should be exposed to the vSwitch connection.",
"example": false,
"type": "boolean"
},
"id": {
"description": "ID of the Network.",
"example": 4711,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"ip_range": {
"description": "IP range of the Network.\n\nUses CIDR notation.\n",
"example": "10.0.0.0/16",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"load_balancers": {
"description": "Array of IDs of Load Balancers attached to this Network.",
"example": [
42
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"name": {
"description": "Name of the Network.",
"example": "mynet",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"routes": {
"description": "Array of routes set in this Network.",
"items": {
"$ref": "#/components/schemas/route"
},
"type": "array"
},
"servers": {
"description": "Array of IDs of Servers attached to this Network.",
"example": [
42
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"subnets": {
"description": "List of subnets allocated in this Network.",
"items": {
"$ref": "#/components/schemas/subnet_with_gateway"
},
"type": "array"
}
},
"required": [
"created",
"expose_routes_to_vswitch",
"id",
"ip_range",
"labels",
"name",
"protection",
"routes",
"servers",
"subnets"
],
"type": "object"
},
"pagination": {
"description": "See \"Pagination\" for more information.",
"properties": {
"last_page": {
"description": "Page number of the last page available. Can be null if the current page is the last one.",
"example": 4,
"format": "int64",
"nullable": true,
"type": "integer"
},
"next_page": {
"description": "Page number of the next page. Can be null if the current page is the last one.",
"example": 4,
"format": "int64",
"nullable": true,
"type": "integer"
},
"page": {
"description": "Current page number.",
"example": 3,
"format": "int64",
"type": "integer"
},
"per_page": {
"description": "Maximum number of entries returned per page.",
"example": 25,
"format": "int64",
"type": "integer"
},
"previous_page": {
"description": "Page number of the previous page. Can be null if the current page is the first one.",
"example": 2,
"format": "int64",
"nullable": true,
"type": "integer"
},
"total_entries": {
"description": "Total number of entries that exist for this query. Can be null if unknown.",
"example": 100,
"format": "int64",
"nullable": true,
"type": "integer"
}
},
"required": [
"last_page",
"next_page",
"page",
"per_page",
"previous_page",
"total_entries"
],
"type": "object"
},
"power_off_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/poweroff",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"power_on_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/poweron",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"price": {
"description": "Hourly price in this Location. | Monthly price in this Location. | Additional traffic price per TB in this Location. | Price of Images per GB/month. | Price of Volumes per GB/month. | Price of one Floating IP per month. | Setup fee in this Location.",
"properties": {
"gross": {
"description": "Price with VAT added.",
"example": "1.1900",
"format": "decimal",
"type": "string"
},
"net": {
"description": "Price without VAT.",
"example": "1.0000",
"format": "decimal",
"type": "string"
}
},
"required": [
"gross",
"net"
],
"type": "object"
},
"price_per_time": {
"properties": {
"included_traffic": {
"description": "Free traffic per month in bytes in this Location.",
"example": 654321,
"format": "int64",
"type": "integer"
},
"location": {
"description": "Name of the Location the price is for.",
"example": "fsn1",
"type": "string"
},
"price_hourly": {
"$ref": "#/components/schemas/price"
},
"price_monthly": {
"$ref": "#/components/schemas/price"
},
"price_per_tb_traffic": {
"$ref": "#/components/schemas/price"
}
},
"required": [
"included_traffic",
"location",
"price_hourly",
"price_monthly",
"price_per_tb_traffic"
],
"type": "object"
},
"price_per_time_monthly": {
"properties": {
"location": {
"description": "Name of the Location the price is for.",
"example": "fsn1",
"type": "string"
},
"price_monthly": {
"$ref": "#/components/schemas/price"
}
},
"required": [
"location",
"price_monthly"
],
"type": "object"
},
"price_per_time_without_traffic": {
"properties": {
"location": {
"description": "Name of the Location the price is for.",
"example": "fsn1",
"type": "string"
},
"price_hourly": {
"$ref": "#/components/schemas/price"
},
"price_monthly": {
"$ref": "#/components/schemas/price"
}
},
"required": [
"location",
"price_hourly",
"price_monthly"
],
"type": "object"
},
"protection": {
"description": "Protection configuration for the Resource",
"properties": {
"delete": {
"description": "Prevent the Resource from being deleted.",
"example": false,
"type": "boolean"
}
},
"required": [
"delete"
],
"type": "object"
},
"rebuild_server_from_image_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/servers/{id}/actions/rebuild",
"properties": {
"image": {
"description": "ID or name of Image to rebuilt from.",
"example": "ubuntu-24.04",
"type": "string"
},
"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).",
"example": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n",
"type": "string"
}
},
"required": [
"image"
],
"title": "RebuildServerRequest",
"type": "object"
},
"rebuild_server_from_image_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/rebuild",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"root_password": {
"description": "New root password when not using SSH keys.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"remove_from_placement_group_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/remove_from_placement_group",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"remove_from_resources_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/remove_from_resources",
"properties": {
"remove_from": {
"description": "Resources to remove the Firewall from.",
"items": {
"$ref": "#/components/schemas/firewall_resource"
},
"type": "array"
}
},
"required": [
"remove_from"
],
"title": "RemoveFromResourcesRequest",
"type": "object"
},
"remove_from_resources_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/remove_from_resources",
"properties": {
"actions": {
"items": {
"$ref": "#/components/schemas/action"
},
"type": "array"
}
},
"required": [
"actions"
],
"title": "ActionListResponse",
"type": "object"
},
"remove_records_from_rrset_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/remove_records",
"properties": {
"records": {
"description": "Records to remove from the RRSet.\n\nMust not be empty and must only contain distinct record values.\n",
"items": {
"$ref": "#/components/schemas/resource_record"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
}
},
"required": [
"records"
],
"type": "object"
},
"remove_records_from_rrset_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/remove_records",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"remove_target_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/remove_target",
"properties": {
"ip": {
"$ref": "#/components/schemas/load_balancer_target_ip"
},
"label_selector": {
"$ref": "#/components/schemas/label_selector"
},
"server": {
"$ref": "#/components/schemas/resource_id"
},
"type": {
"description": "Type of the resource.",
"enum": [
"ip",
"label_selector",
"server"
],
"type": "string"
}
},
"required": [
"type"
],
"title": "RemoveTargetRequest",
"type": "object"
},
"remove_target_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/remove_target",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"replace_certificate_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/certificates/{id}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "New Certificate name.",
"example": "my website cert",
"type": "string"
}
},
"title": "UpdateCertificateRequest",
"type": "object"
},
"replace_certificate_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/certificates/{id}",
"properties": {
"certificate": {
"$ref": "#/components/schemas/certificate"
}
},
"required": [
"certificate"
],
"title": "CertificateResponse",
"type": "object"
},
"replace_firewall_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/firewalls/{id}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Firewall.\n\nLimited to a maximum of 128 characters.\n\nMust be unique per Project.\n",
"example": "new-name",
"type": "string"
}
},
"title": "UpdateFirewallRequest",
"type": "object"
},
"replace_firewall_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/firewalls/{id}",
"properties": {
"firewall": {
"$ref": "#/components/schemas/firewall"
}
},
"required": [
"firewall"
],
"title": "FirewallResponse",
"type": "object"
},
"replace_floating_ip_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/floating_ips/{id}",
"properties": {
"description": {
"description": "Description of the Resource.",
"example": "This describes my resource",
"nullable": true,
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
}
},
"title": "FloatingIPUpdateRequest",
"type": "object"
},
"replace_floating_ip_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/floating_ips/{id}",
"properties": {
"floating_ip": {
"$ref": "#/components/schemas/floating_ip"
}
},
"required": [
"floating_ip"
],
"type": "object"
},
"replace_image_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/images/{id}",
"properties": {
"description": {
"description": "New description of Image.",
"example": "My new Image description",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"type": {
"description": "Destination Image type to convert to.",
"enum": [
"snapshot"
],
"type": "string"
}
},
"title": "UpdateImageRequest",
"type": "object"
},
"replace_image_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/images/{id}",
"properties": {
"image": {
"$ref": "#/components/schemas/image"
}
},
"type": "object"
},
"replace_load_balancer_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/load_balancers/{id}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "New Load Balancer name.",
"example": "new-name",
"type": "string"
}
},
"type": "object"
},
"replace_load_balancer_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/load_balancers/{id}",
"properties": {
"load_balancer": {
"$ref": "#/components/schemas/load_balancer"
}
},
"required": [
"load_balancer"
],
"type": "object"
},
"replace_network_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/networks/{id}",
"properties": {
"expose_routes_to_vswitch": {
"description": "Toggle to expose routes to the Networks vSwitch.\n\nIndicates if the routes from this Network should be exposed to the vSwitch in this Network. Only takes effect if a [vSwitch is setup](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch) in this Network.\n",
"example": false,
"type": "boolean"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "New Network name.",
"example": "new-name",
"type": "string"
}
},
"title": "NetworkUpdateRequest",
"type": "object"
},
"replace_network_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/networks/{id}",
"properties": {
"network": {
"$ref": "#/components/schemas/network"
}
},
"type": "object"
},
"replace_placementgroup_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/placement_groups/{id}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "New Placement Group name.",
"example": "my Placement Group",
"type": "string"
}
},
"title": "UpdatePlacementGroupRequest",
"type": "object"
},
"replace_placementgroup_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/placement_groups/{id}",
"properties": {
"placement_group": {
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Placement Group.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"servers": {
"description": "Array of IDs of Servers that are part of this Placement Group.",
"example": [
42
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"type": {
"description": "Type of Placement Group.\n",
"enum": [
"spread"
],
"example": "spread",
"type": "string"
}
},
"required": [
"created",
"id",
"labels",
"name",
"servers",
"type"
],
"title": "PlacementGroup",
"type": "object"
}
},
"required": [
"placement_group"
],
"title": "PlacementGroupResponse",
"type": "object"
},
"replace_primary_ip_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/primary_ips/{id}",
"properties": {
"auto_delete": {
"default": false,
"description": "Auto deletion state.\n\nIf enabled the Primary IP will be deleted once the assigned resource gets deleted.\n",
"example": true,
"type": "boolean"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
}
},
"title": "PrimaryIPUpdateRequest",
"type": "object"
},
"replace_primary_ip_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/primary_ips/{id}",
"properties": {
"primary_ip": {
"properties": {
"assignee_id": {
"description": "ID of resource the Primary IP is assigned to.\n\n`null` if the Primary IP is not assigned.\n",
"example": 17,
"format": "int64",
"nullable": true,
"type": "integer"
},
"assignee_type": {
"description": "Type of resource the Primary IP can get assigned to.\n",
"enum": [
"server"
],
"example": "server",
"type": "string"
},
"auto_delete": {
"default": false,
"description": "Auto deletion state.\n\nIf enabled the Primary IP will be deleted once the assigned resource gets deleted.\n",
"example": true,
"type": "boolean"
},
"blocked": {
"description": "Blocked state of the Primary IP.",
"example": false,
"type": "boolean"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"datacenter": {
"allOf": [
{
"$ref": "#/components/schemas/data_center"
}
],
"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 of the Primary IP.\n"
},
"dns_ptr": {
"description": "List of reverse DNS records.",
"items": {
"$ref": "#/components/schemas/dns_ptr"
},
"type": "array"
},
"id": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"ip": {
"description": "IP address.",
"example": "2001:db8::/64",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"$ref": "#/components/schemas/location"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"type": {
"$ref": "#/components/schemas/ip_type"
}
},
"required": [
"assignee_id",
"assignee_type",
"auto_delete",
"blocked",
"created",
"datacenter",
"dns_ptr",
"id",
"ip",
"labels",
"location",
"name",
"protection",
"type"
],
"title": "PrimaryIP",
"type": "object"
}
},
"required": [
"primary_ip"
],
"title": "PrimaryIPResponse",
"type": "object"
},
"replace_rrset_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
}
},
"type": "object"
},
"replace_rrset_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}",
"properties": {
"rrset": {
"$ref": "#/components/schemas/resource_record_set"
}
},
"required": [
"rrset"
],
"type": "object"
},
"replace_server_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/servers/{id}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "New name to set.",
"example": "my-server",
"type": "string"
}
},
"title": "UpdateServerRequest",
"type": "object"
},
"replace_server_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/servers/{id}",
"properties": {
"server": {
"$ref": "#/components/schemas/server"
}
},
"type": "object"
},
"replace_snapshot_request": {
"description": "Request for PUT https://api.hetzner.com/v1/storage_boxes/{id}/snapshots/{snapshot_id}",
"properties": {
"description": {
"description": "Description of the Storage Box Snapshot.",
"example": "snapshot-0001",
"maxLength": 1000,
"pattern": "[a-zA-Z0-9-_,:<>+#!\\(\\)\\[\\]\\{\\} ]*",
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
}
},
"type": "object"
},
"replace_snapshot_response": {
"description": "Response to PUT https://api.hetzner.com/v1/storage_boxes/{id}/snapshots/{snapshot_id}",
"properties": {
"snapshot": {
"$ref": "#/components/schemas/snapshot"
}
},
"required": [
"snapshot"
],
"type": "object"
},
"replace_ssh_key_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/ssh_keys/{id}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "New name Name to set.",
"example": "My ssh key",
"type": "string"
}
},
"type": "object"
},
"replace_ssh_key_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/ssh_keys/{id}",
"properties": {
"ssh_key": {
"$ref": "#/components/schemas/ssh_key"
}
},
"required": [
"ssh_key"
],
"type": "object"
},
"replace_storage_box_request": {
"description": "Request for PUT https://api.hetzner.com/v1/storage_boxes/{id}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Storage Box.\n",
"type": "string"
}
},
"type": "object"
},
"replace_storage_box_response": {
"description": "Response to PUT https://api.hetzner.com/v1/storage_boxes/{id}",
"properties": {
"storage_box": {
"$ref": "#/components/schemas/storage_box"
}
},
"required": [
"storage_box"
],
"type": "object"
},
"replace_subaccount_request": {
"description": "Request for PUT https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}",
"properties": {
"description": {
"description": "A description of Storage Box Subaccount.\n",
"example": "my-backup-server01",
"maxLength": 1000,
"type": "string"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Storage Box Subaccount.\n",
"example": "my-name",
"maxLength": 50,
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"replace_subaccount_response": {
"description": "Response to PUT https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}",
"properties": {
"subaccount": {
"$ref": "#/components/schemas/subaccount"
}
},
"required": [
"subaccount"
],
"type": "object"
},
"replace_volume_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/volumes/{id}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "New Volume name.",
"example": "database-storage",
"type": "string"
}
},
"title": "UpdateVolumeRequest",
"type": "object"
},
"replace_volume_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/volumes/{id}",
"properties": {
"volume": {
"$ref": "#/components/schemas/volume"
}
},
"required": [
"volume"
],
"type": "object"
},
"replace_zone_request": {
"description": "Request for PUT https://api.hetzner.cloud/v1/zones/{id_or_name}",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
}
},
"title": "ZoneUpdateRequest",
"type": "object"
},
"replace_zone_response": {
"description": "Response to PUT https://api.hetzner.cloud/v1/zones/{id_or_name}",
"properties": {
"zone": {
"$ref": "#/components/schemas/zone"
}
},
"required": [
"zone"
],
"type": "object"
},
"request_console_for_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/request_console",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"password": {
"description": "VNC password to use for this connection (this password only works in combination with a wss_url with valid token).",
"example": "9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x",
"type": "string"
},
"wss_url": {
"description": "URL of websocket proxy to use; this includes a token which is valid for a limited time only.",
"example": "wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c",
"type": "string"
}
},
"required": [
"action",
"password",
"wss_url"
],
"type": "object"
},
"reset_password_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/reset_subaccount_password",
"properties": {
"password": {
"description": "Password of the Storage Box Subaccount.\n\nFor more details, see the Storage Boxes password policy.\n",
"type": "string"
}
},
"required": [
"password"
],
"type": "object"
},
"reset_password_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/reset_subaccount_password",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"reset_root_password_of_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/reset_password",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
},
"root_password": {
"description": "Password that will be set for this Server once the Action succeeds.",
"example": "zCWbFhnu950dUTko5f40",
"type": "string"
}
},
"type": "object"
},
"reset_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/reset",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"resize_volume_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/volumes/{id}/actions/resize",
"properties": {
"size": {
"description": "New Volume size in GB (must be greater than current size).",
"example": 50,
"type": "number"
}
},
"required": [
"size"
],
"type": "object"
},
"resize_volume_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/volumes/{id}/actions/resize",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"resource": {
"properties": {
"id": {
"description": "ID of the Resource. | ID of resource referenced.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": {
"description": "Type of the Resource. | Type of resource referenced.",
"example": "server",
"type": "string"
}
},
"required": [
"id",
"type"
],
"type": "object"
},
"resource_id": {
"description": "ID of the Resource",
"properties": {
"id": {
"description": "ID of the Server. | ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id"
],
"type": "object"
},
"resource_record": {
"description": "Record of a RRSet.\n\nThe `value` is used to identify the record in an RRSet.\n",
"properties": {
"comment": {
"description": "Comment of the record.",
"example": "My web server at Hetzner Cloud.",
"type": "string"
},
"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",
"example": "198.51.100.1",
"type": "string"
}
},
"required": [
"value"
],
"title": "Record",
"type": "object"
},
"resource_record_set": {
"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"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
},
"protection": {
"description": "Protection of the RRSet.\n",
"properties": {
"change": {
"description": "Prevent the Resource from being changed.",
"example": false,
"type": "boolean"
}
},
"required": [
"change"
],
"type": "object"
},
"records": {
"description": "Records of the RRSet.\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",
"items": {
"$ref": "#/components/schemas/resource_record"
},
"type": "array"
},
"ttl": {
"description": "Time To Live (TTL) of the RRSet.\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the Zone's Default TTL is used.\n",
"example": 3600,
"maximum": 2147483647,
"minimum": 60,
"nullable": true,
"type": "integer"
},
"type": {
"$ref": "#/components/schemas/resource_record_set_type"
},
"zone": {
"description": "ID of the Zone.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id",
"labels",
"name",
"protection",
"records",
"ttl",
"type",
"zone"
],
"title": "RRSet",
"type": "object"
},
"resource_record_set_to_create": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets",
"properties": {
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
},
"records": {
"description": "Records of the RRSet.\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",
"items": {
"$ref": "#/components/schemas/resource_record"
},
"type": "array"
},
"ttl": {
"description": "Time To Live (TTL) of the RRSet.\n\nMust be in between 60s and 2147483647s.\n\nIf not set, the Zone's Default TTL is used.\n",
"example": 3600,
"maximum": 2147483647,
"minimum": 60,
"nullable": true,
"type": "integer"
},
"type": {
"$ref": "#/components/schemas/resource_record_set_type"
}
},
"required": [
"name",
"records",
"type"
],
"type": "object"
},
"resource_record_set_type": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
},
"resource_record_with_comment": {
"description": "Record of a RRSet.\n\nThe `value` is used to identify the record in an RRSet.\n",
"properties": {
"comment": {
"description": "New comment for the record.\n",
"example": "My web server at Hetzner Cloud.",
"type": "string"
},
"value": {
"description": "Value of the record to update.\n",
"example": "198.51.100.1",
"type": "string"
}
},
"required": [
"comment",
"value"
],
"title": "Record",
"type": "object"
},
"retry_issuance_or_renewal_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/certificates/{id}/actions/retry",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"rollback_snapshot_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/rollback_snapshot",
"properties": {
"snapshot": {
"description": "ID or Name of the Storage Box Snapshot.",
"example": "my-snapshot",
"type": "string"
}
},
"required": [
"snapshot"
],
"type": "object"
},
"rollback_snapshot_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/actions/rollback_snapshot",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"route": {
"description": "Request for POST https://api.hetzner.cloud/v1/networks/{id}/actions/add_route | Request for POST https://api.hetzner.cloud/v1/networks/{id}/actions/delete_route",
"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.\n",
"example": "10.100.1.0/24",
"type": "string"
},
"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.\n",
"example": "10.0.1.1",
"type": "string"
}
},
"required": [
"destination",
"gateway"
],
"type": "object"
},
"rule": {
"description": "Rule of a firewall.",
"properties": {
"description": {
"description": "Description of the rule.",
"maxLength": 255,
"nullable": true,
"type": "string"
},
"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",
"example": [],
"items": {
"type": "string"
},
"type": "array"
},
"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",
"enum": [
"in",
"out"
],
"example": "in",
"type": "string"
},
"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",
"example": "80",
"nullable": true,
"type": "string"
},
"protocol": {
"description": "Network protocol to apply the rule for.",
"enum": [
"esp",
"gre",
"icmp",
"tcp",
"udp"
],
"type": "string"
},
"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",
"example": [
"192.0.2.2/32",
"192.0.2.0/24",
"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"direction",
"protocol"
],
"title": "Rule",
"type": "object"
},
"server": {
"description": "Servers are virtual machines that can be provisioned.",
"properties": {
"backup_window": {
"description": "Time window (UTC) in which the backup will run, or null if the backups are not enabled.",
"example": "22-02",
"nullable": true,
"type": "string"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"datacenter": {
"allOf": [
{
"$ref": "#/components/schemas/data_center"
}
],
"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"
},
"id": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"image": {
"allOf": [
{
"$ref": "#/components/schemas/image"
}
],
"description": "Image the server is based on.",
"nullable": true
},
"included_traffic": {
"description": "Free Traffic for the current billing period in bytes.",
"example": 654321,
"format": "int64",
"nullable": true,
"type": "integer"
},
"ingoing_traffic": {
"description": "Inbound Traffic for the current billing period in bytes.",
"example": 123456,
"format": "int64",
"nullable": true,
"type": "integer"
},
"iso": {
"allOf": [
{
"$ref": "#/components/schemas/iso"
}
],
"description": "ISO Image that is attached to this Server. Null if no ISO is attached.",
"nullable": true
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"load_balancers": {
"description": "Load Balancer IDs assigned to the server.",
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"location": {
"$ref": "#/components/schemas/location"
},
"locked": {
"description": "True if Server has been locked and is not available to user.",
"example": false,
"type": "boolean"
},
"name": {
"description": "Name of the Server (must be unique per Project and a valid hostname as per RFC 1123).",
"example": "my-resource",
"type": "string"
},
"outgoing_traffic": {
"description": "Outbound Traffic for the current billing period in bytes.",
"example": 123456,
"format": "int64",
"nullable": true,
"type": "integer"
},
"placement_group": {
"description": "The placement group the server is assigned to.",
"nullable": true,
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Placement Group.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"servers": {
"description": "Array of IDs of Servers that are part of this Placement Group.",
"example": [
42
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"type": {
"description": "Type of Placement Group.\n",
"enum": [
"spread"
],
"example": "spread",
"type": "string"
}
},
"required": [
"created",
"id",
"labels",
"name",
"servers",
"type"
],
"title": "PlacementGroupNullable",
"type": "object"
},
"primary_disk_size": {
"description": "Size of the primary Disk.",
"example": 50,
"type": "integer"
},
"private_net": {
"description": "Private networks information.",
"items": {
"$ref": "#/components/schemas/server_private_net"
},
"type": "array"
},
"protection": {
"$ref": "#/components/schemas/server_protection"
},
"public_net": {
"$ref": "#/components/schemas/server_public_net"
},
"rescue_enabled": {
"description": "True if rescue mode is enabled. Server will then boot into rescue system on next reboot.",
"example": false,
"type": "boolean"
},
"server_type": {
"$ref": "#/components/schemas/server_type"
},
"status": {
"description": "Status of the Server.",
"enum": [
"deleting",
"initializing",
"migrating",
"off",
"rebuilding",
"running",
"starting",
"stopping",
"unknown"
],
"type": "string"
},
"volumes": {
"description": "IDs of Volumes assigned to this Server.",
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
}
},
"required": [
"backup_window",
"created",
"datacenter",
"id",
"image",
"included_traffic",
"ingoing_traffic",
"iso",
"labels",
"location",
"locked",
"name",
"outgoing_traffic",
"primary_disk_size",
"private_net",
"protection",
"public_net",
"rescue_enabled",
"server_type",
"status"
],
"type": "object"
},
"server_private_net": {
"properties": {
"alias_ips": {
"description": "Additional IP addresses of the server on the network.",
"example": [
"10.0.0.3",
"10.0.0.4"
],
"items": {
"type": "string"
},
"type": "array"
},
"ip": {
"description": "The server IP address on the network.",
"example": "10.0.0.2",
"type": "string"
},
"mac_address": {
"description": "The server MAC address on the network.",
"example": "86:00:ff:2a:7d:e1",
"type": "string"
},
"network": {
"description": "The Network ID the server is attached to.",
"example": 4711,
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"server_protection": {
"description": "Protection configuration for the Server.",
"properties": {
"delete": {
"description": "If true, prevents the Server from being deleted.",
"example": false,
"type": "boolean"
},
"rebuild": {
"description": "If true, prevents the Server from being rebuilt.",
"example": false,
"type": "boolean"
}
},
"required": [
"delete",
"rebuild"
],
"type": "object"
},
"server_public_net": {
"description": "Public network information. The Server's IPv4 address can be found in `public_net->ipv4->ip`.",
"properties": {
"firewalls": {
"description": "Firewalls applied to the public network interface of this Server.",
"items": {
"properties": {
"id": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"status": {
"description": "Status of the Firewall on the Server.",
"enum": [
"applied",
"pending"
],
"example": "applied",
"type": "string"
}
},
"title": "ServerPublicNetFirewall",
"type": "object"
},
"type": "array"
},
"floating_ips": {
"description": "IDs of Floating IPs assigned to this Server.",
"example": [
478
],
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"ipv4": {
"allOf": [
{
"$ref": "#/components/schemas/ipv4"
}
],
"description": "IP address (v4) and its reverse DNS entry of this Server.",
"nullable": true
},
"ipv6": {
"allOf": [
{
"$ref": "#/components/schemas/ipv6"
}
],
"description": "IPv6 network assigned to this Server and its reverse DNS entry.",
"nullable": true
}
},
"required": [
"floating_ips",
"ipv4",
"ipv6"
],
"type": "object"
},
"server_type": {
"properties": {
"architecture": {
"$ref": "#/components/schemas/architecture"
},
"category": {
"description": "Category of Server Type.",
"example": "Shared vCPU",
"type": "string"
},
"cores": {
"description": "Number of cpu cores a Server of this type will have.",
"example": 2,
"type": "integer"
},
"cpu_type": {
"description": "Type of cpu.",
"enum": [
"dedicated",
"shared"
],
"example": "shared",
"type": "string"
},
"deprecated": {
"description": "This field is deprecated. Use the deprecation object instead.",
"example": false,
"nullable": true,
"type": "boolean"
},
"deprecation": {
"allOf": [
{
"$ref": "#/components/schemas/deprecation_info"
}
],
"deprecated": true,
"description": "This field is deprecated.\n\nUse the `deprecation` object in the `locations` field instead (`.locations[].deprecation`).\n",
"nullable": true
},
"description": {
"description": "Description of the Server type.",
"example": "CPX22",
"type": "string"
},
"disk": {
"description": "Disk size a Server of this type will have in GB.",
"example": 80,
"type": "number"
},
"id": {
"description": "ID of the Server type.",
"example": 1,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"locations": {
"description": "Supported Location and per Location details for the Server Type.\n\nA Server Type is:\n - only supported in the Location that are listed.\n - deprecated in the Location when the `deprecation` property is set.\n - unavailable in the Location when the `deprecation.unavailable_after` date is in the past.\n",
"items": {
"$ref": "#/components/schemas/server_type_location"
},
"type": "array"
},
"memory": {
"description": "Memory a Server of this type will have in GB.",
"example": 4,
"type": "number"
},
"name": {
"description": "Unique identifier of the Server type.",
"example": "cpx22",
"type": "string"
},
"prices": {
"description": "Price per Location.",
"items": {
"$ref": "#/components/schemas/price_per_time"
},
"type": "array"
},
"storage_type": {
"description": "Type of Server boot drive. Local has higher speed. Network has better availability.",
"enum": [
"local",
"network"
],
"type": "string"
}
},
"required": [
"architecture",
"cores",
"cpu_type",
"deprecated",
"description",
"disk",
"id",
"locations",
"memory",
"name",
"prices",
"storage_type"
],
"type": "object"
},
"server_type_location": {
"description": "A Location (containing only id and name) and Server Type specific metadata.\n",
"properties": {
"deprecation": {
"allOf": [
{
"$ref": "#/components/schemas/deprecation_info"
}
],
"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",
"nullable": true
},
"id": {
"description": "ID of the Location.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"name": {
"description": "Name of the Location.",
"example": "fsn1",
"type": "string"
}
},
"required": [
"deprecation",
"id",
"name"
],
"type": "object"
},
"set_records_of_rrset_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/set_records",
"properties": {
"records": {
"description": "Records to set in the RRSet.\n\nMust not be empty and must only contain distinct record values.\n",
"items": {
"$ref": "#/components/schemas/resource_record"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
}
},
"required": [
"records"
],
"type": "object"
},
"set_records_of_rrset_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/set_records",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"set_rules_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/set_rules",
"properties": {
"rules": {
"description": "Array of rules.\n\nRules are limited to 50 entries per Firewall and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits).\n\nExisting rules will be replaced.\n",
"items": {
"$ref": "#/components/schemas/rule"
},
"maxItems": 50,
"type": "array"
}
},
"required": [
"rules"
],
"title": "SetRulesRequest",
"type": "object"
},
"set_rules_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/firewalls/{id}/actions/set_rules",
"properties": {
"actions": {
"items": {
"$ref": "#/components/schemas/action"
},
"type": "array"
}
},
"required": [
"actions"
],
"title": "ActionListResponse",
"type": "object"
},
"shutdown_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/shutdown",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"snapshot": {
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"description": {
"description": "Description of the Storage Box Snapshot.",
"example": "snapshot-0001",
"maxLength": 1000,
"pattern": "[a-zA-Z0-9-_,:<>+#!\\(\\)\\[\\]\\{\\} ]*",
"type": "string"
},
"id": {
"description": "ID of the Storage Box Snapshot.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"is_automatic": {
"description": "Whether the Storage Box Snapshot was created automatically.",
"type": "boolean"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Storage Box Snapshot.",
"example": "my-snapshot",
"type": "string"
},
"stats": {
"$ref": "#/components/schemas/snapshot_stats"
},
"storage_box": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"created",
"description",
"id",
"is_automatic",
"labels",
"name",
"stats",
"storage_box"
],
"type": "object"
},
"snapshot_plan": {
"description": "Details of the active snapshot plan.\n\nNot available if the `status` is `initializing`.\n",
"properties": {
"day_of_month": {
"default": null,
"description": "Day of the month when the Snapshot Plan is executed.\n\nNull means every day.\n",
"example": null,
"maximum": 31,
"minimum": 1,
"nullable": true,
"type": "integer"
},
"day_of_week": {
"default": null,
"description": "Day of the week when the Snapshot Plan is executed.\n\nStarts at 1 for Monday til 7 for Sunday. Null means every day.\n",
"example": 7,
"maximum": 7,
"minimum": 1,
"nullable": true,
"type": "integer"
},
"hour": {
"description": "Hour when the Snapshot Plan is executed (UTC).\n",
"example": 3,
"maximum": 23,
"minimum": 0,
"type": "integer"
},
"max_snapshots": {
"description": "Maximum amount of Snapshots that will be created by this Snapshot Plan.\n\nOlder Snapshots will be deleted.\n",
"example": 10,
"minimum": 1,
"type": "integer"
},
"minute": {
"description": "Minute when the Snapshot Plan is executed (UTC).\n",
"example": 30,
"maximum": 59,
"minimum": 0,
"type": "integer"
}
},
"required": [
"day_of_month",
"day_of_week",
"hour",
"max_snapshots",
"minute"
],
"type": "object"
},
"snapshot_stats": {
"description": "Statistics of the Storage Box Snapshot.\n",
"properties": {
"size": {
"description": "Current storage requirements of the Snapshot in bytes.",
"format": "int64",
"type": "integer"
},
"size_filesystem": {
"description": "Size of the compressed file system contained in the Snapshot in bytes.",
"format": "int64",
"type": "integer"
}
},
"required": [
"size",
"size_filesystem"
],
"type": "object"
},
"soft_reboot_server_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/servers/{id}/actions/reboot",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"ssh_key": {
"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.",
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"fingerprint": {
"description": "MD5 fingerprint of the SSH public key.",
"example": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"type": "string"
},
"id": {
"description": "ID of the SSH Key.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"public_key": {
"description": "Public key.",
"example": "ssh-rsa AAAjjk76kgf...Xt",
"type": "string"
}
},
"required": [
"created",
"fingerprint",
"id",
"labels",
"name",
"public_key"
],
"type": "object"
},
"storage_box": {
"properties": {
"access_settings": {
"$ref": "#/components/schemas/storage_box_access_setting"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"location": {
"$ref": "#/components/schemas/location"
},
"name": {
"description": "Name of the Storage Box.\n",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"server": {
"description": "FQDN of the Storage Box.\n\nNot available if the `status` is `initializing`.\n",
"example": "u1337.your-storagebox.de",
"nullable": true,
"type": "string"
},
"snapshot_plan": {
"allOf": [
{
"$ref": "#/components/schemas/snapshot_plan"
}
],
"description": "Details of the active snapshot plan.\n\nNot available if the `status` is `initializing`.\n",
"nullable": true
},
"stats": {
"$ref": "#/components/schemas/storage_box_stats"
},
"status": {
"description": "Status of the Storage Box.",
"enum": [
"active",
"initializing",
"locked"
],
"type": "string"
},
"storage_box_type": {
"$ref": "#/components/schemas/storage_box_type"
},
"system": {
"description": "Host system of the Storage Box.\n\nNot available if the `status` is `initializing`.\n",
"example": "FSN1-BX355",
"nullable": true,
"type": "string"
},
"username": {
"description": "Primary username of the Storage Box.\n\nNot available if the `status` is `initializing`.\n",
"example": "u12345",
"nullable": true,
"type": "string"
}
},
"required": [
"access_settings",
"created",
"id",
"labels",
"location",
"name",
"protection",
"server",
"snapshot_plan",
"stats",
"status",
"storage_box_type",
"system",
"username"
],
"type": "object"
},
"storage_box_access_setting": {
"description": "Access settings of the Storage Box.",
"properties": {
"reachable_externally": {
"description": "Whether access from outside the Hetzner network is allowed.",
"type": "boolean"
},
"samba_enabled": {
"description": "Whether the Samba subsystem is enabled.",
"type": "boolean"
},
"ssh_enabled": {
"description": "Whether the SSH subsystem is enabled.",
"type": "boolean"
},
"webdav_enabled": {
"description": "Whether the WebDAV subsystem is enabled.",
"type": "boolean"
},
"zfs_enabled": {
"description": "Whether the ZFS snapshot folder is visible.",
"type": "boolean"
}
},
"required": [
"reachable_externally",
"samba_enabled",
"ssh_enabled",
"webdav_enabled",
"zfs_enabled"
],
"type": "object"
},
"storage_box_stats": {
"description": "Statistics of the Storage Box.\n",
"properties": {
"size": {
"description": "Current disk usage in bytes.",
"format": "int64",
"type": "integer"
},
"size_data": {
"description": "Current disk usage for data in bytes.",
"format": "int64",
"type": "integer"
},
"size_snapshots": {
"description": "Current disk usage for snapshots in bytes.",
"format": "int64",
"type": "integer"
}
},
"required": [
"size",
"size_data",
"size_snapshots"
],
"type": "object"
},
"storage_box_type": {
"description": "Type of the Storage Box.",
"properties": {
"automatic_snapshot_limit": {
"description": "Maximum number of snapshots created automatically by a snapshot plan.",
"example": 10,
"nullable": true,
"type": "integer"
},
"deprecation": {
"allOf": [
{
"$ref": "#/components/schemas/deprecation_info"
}
],
"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",
"nullable": true
},
"description": {
"description": "Description of the Storage Box Type.",
"example": "BX11",
"type": "string"
},
"id": {
"description": "ID of the Storage Box Type.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"name": {
"description": "Name of the Storage Box Type.",
"example": "bx11",
"type": "string"
},
"prices": {
"description": "Price per Location.",
"items": {
"properties": {
"location": {
"description": "Name of the Location the price is for.",
"example": "fsn1",
"type": "string"
},
"price_hourly": {
"$ref": "#/components/schemas/price"
},
"price_monthly": {
"$ref": "#/components/schemas/price"
},
"setup_fee": {
"$ref": "#/components/schemas/price"
}
},
"required": [
"location",
"price_hourly",
"price_monthly",
"setup_fee"
],
"type": "object"
},
"type": "array"
},
"size": {
"description": "Available storage in bytes.",
"example": 1073741824,
"format": "int64",
"type": "integer"
},
"snapshot_limit": {
"description": "Maximum number of allowed manual snapshots.",
"example": 10,
"nullable": true,
"type": "integer"
},
"subaccounts_limit": {
"description": "Maximum number of subaccounts.",
"example": 200,
"type": "integer"
}
},
"required": [
"automatic_snapshot_limit",
"deprecation",
"description",
"id",
"name",
"prices",
"size",
"snapshot_limit",
"subaccounts_limit"
],
"type": "object"
},
"subaccount": {
"properties": {
"access_settings": {
"$ref": "#/components/schemas/subaccount_access_setting"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"description": {
"description": "A description of Storage Box Subaccount.\n",
"example": "my-backup-server01",
"maxLength": 1000,
"type": "string"
},
"home_directory": {
"description": "Home directory of the Storage Box Subaccount.\n",
"example": "my-backup/server01",
"maxLength": 999,
"minLength": 1,
"pattern": "^[a-zA-Z0-9 ./_-]+$",
"type": "string"
},
"id": {
"description": "ID of the Storage Box Subaccount.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"name": {
"description": "Name of the Storage Box Subaccount.\n",
"example": "my-name",
"maxLength": 50,
"minLength": 1,
"type": "string"
},
"server": {
"description": "FQDN of the Storage Box Subaccount.",
"example": "u1337-sub1.your-storagebox.de",
"type": "string"
},
"storage_box": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"username": {
"description": "Username of the Storage Box Subaccount.",
"example": "u1337-sub1",
"type": "string"
}
},
"required": [
"access_settings",
"created",
"description",
"home_directory",
"id",
"labels",
"name",
"server",
"storage_box",
"username"
],
"type": "object"
},
"subaccount_access_setting": {
"description": "Access settings for the Subaccount.\n",
"properties": {
"reachable_externally": {
"description": "Whether access from outside the Hetzner network is allowed.",
"type": "boolean"
},
"readonly": {
"description": "Whether the Subaccount is read-only.",
"type": "boolean"
},
"samba_enabled": {
"description": "Whether the Samba subsystem is enabled.",
"type": "boolean"
},
"ssh_enabled": {
"description": "Whether the SSH subsystem is enabled.",
"type": "boolean"
},
"webdav_enabled": {
"description": "Whether the WebDAV subsystem is enabled.",
"type": "boolean"
}
},
"required": [
"reachable_externally",
"readonly",
"samba_enabled",
"ssh_enabled",
"webdav_enabled"
],
"type": "object"
},
"subnet": {
"description": "Subnets divide the ip_range from the parent Network object into multiple Subnetworks that you can use for different specific purposes.",
"properties": {
"ip_range": {
"description": "IP range of the subnet.\n\nUses CIDR notation.\n\nMust be a subnet of the parent 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",
"example": "10.0.1.0/24",
"type": "string"
},
"network_zone": {
"description": "Name of the Network Zone.\n\nThe Location contains the `network_zone` property it belongs to.\n | Name of the Network Zone.\n\nThe Location contains the `network_zone` it belongs to.\n",
"example": "eu-central",
"type": "string"
},
"type": {
"description": "Type of subnet.\n\n- `cloud` - Used to connect cloud Servers and Load Balancers.\n- `server` - Same as the `cloud` type. **Deprecated**, use the `cloud` type instead.\n- `vswitch` - Used to [connect cloud Servers and Load Balancers with dedicated Servers](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch).\n",
"enum": [
"cloud",
"server",
"vswitch"
],
"type": "string"
},
"vswitch_id": {
"description": "ID of the robot vSwitch.\n\nMust only be supplied for subnets of type `vswitch`.\n | ID of the robot vSwitch.\n\nMust be supplied if the subnet is of type `vswitch`.\n",
"example": 1000,
"format": "int64",
"type": "integer"
}
},
"required": [
"network_zone",
"type"
],
"type": "object"
},
"subnet_with_gateway": {
"properties": {
"gateway": {
"description": "Gateway for Servers attached to this subnet.\n\nFor subnets of type `server` this is always the first IP of the subnets IP range.\n",
"example": "10.0.0.1",
"type": "string"
},
"ip_range": {
"description": "IP range of the subnet.\n\nUses CIDR notation.\n",
"example": "10.0.1.0/24",
"type": "string"
},
"network_zone": {
"description": "Name of the Network Zone.\n\nThe Location contains the `network_zone` property it belongs to.\n",
"example": "eu-central",
"type": "string"
},
"type": {
"description": "Type of subnet.\n\n- `cloud` - Used to connect cloud Servers and Load Balancers.\n- `server` - Same as the `cloud` type. **Deprecated**, use the `cloud` type instead.\n- `vswitch` - Used to [connect cloud Servers and Load Balancers with dedicated Servers](https://docs.hetzner.com/cloud/networks/connect-dedi-vswitch).\n",
"enum": [
"cloud",
"server",
"vswitch"
],
"type": "string"
},
"vswitch_id": {
"description": "ID of the robot vSwitch if the subnet is of type `vswitch`.",
"example": 1000,
"format": "int64",
"nullable": true,
"type": "integer"
}
},
"required": [
"gateway",
"network_zone",
"type"
],
"type": "object"
},
"unassign_floating_ip_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/unassign",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"unassign_primary_ip_from_resource_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/primary_ips/{id}/actions/unassign",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"update_access_settings_request": {
"description": "Request for POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/update_access_settings",
"properties": {
"reachable_externally": {
"description": "Whether access from outside the Hetzner network is allowed.",
"type": "boolean"
},
"readonly": {
"description": "Whether the Subaccount is read-only.",
"type": "boolean"
},
"samba_enabled": {
"description": "Whether the Samba subsystem is enabled.",
"type": "boolean"
},
"ssh_enabled": {
"description": "Whether the SSH subsystem is enabled.",
"type": "boolean"
},
"webdav_enabled": {
"description": "Whether the WebDAV subsystem is enabled.",
"type": "boolean"
}
},
"type": "object"
},
"update_access_settings_response": {
"description": "Response to POST https://api.hetzner.com/v1/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/update_access_settings",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"update_load_balancer_service": {
"description": "An update to a service for a Load Balancer.",
"properties": {
"destination_port": {
"description": "Port the Load Balancer will balance to.",
"example": 80,
"type": "integer"
},
"health_check": {
"additionalProperties": false,
"description": "Service health check.",
"properties": {
"http": {
"additionalProperties": false,
"description": "Additional configuration for protocol http.",
"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.",
"example": "example.com",
"nullable": true,
"type": "string"
},
"path": {
"description": "HTTP path to use for health checks. May not contain literal spaces, use percent-encoding instead.",
"example": "/",
"type": "string"
},
"response": {
"description": "String that must be contained in HTTP response in order to pass the health check.",
"example": "{\"status\": \"ok\"}",
"type": "string"
},
"status_codes": {
"default": [
"2??",
"3??"
],
"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.",
"example": [
"2??",
"3??"
],
"items": {
"type": "string"
},
"type": "array"
},
"tls": {
"description": "Use HTTPS for health check.",
"example": false,
"type": "boolean"
}
},
"type": "object"
},
"interval": {
"description": "Time interval in seconds health checks are performed.",
"example": 15,
"type": "integer"
},
"port": {
"description": "Port the health check will be performed on.",
"example": 4711,
"type": "integer"
},
"protocol": {
"description": "Type of the health check.",
"enum": [
"http",
"tcp"
],
"example": "http",
"type": "string"
},
"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.",
"example": 3,
"type": "integer"
},
"timeout": {
"description": "Time in seconds after an attempt is considered a timeout.",
"example": 10,
"type": "integer"
}
},
"title": "UpdateLoadBalancerServiceHealthCheck",
"type": "object"
},
"http": {
"$ref": "#/components/schemas/http"
},
"listen_port": {
"description": "Port the Load Balancer listens on.",
"example": 443,
"type": "integer"
},
"protocol": {
"description": "Protocol of the Load Balancer.",
"enum": [
"http",
"https",
"tcp"
],
"example": "https",
"type": "string"
},
"proxyprotocol": {
"description": "Is Proxyprotocol enabled or not.",
"example": false,
"type": "boolean"
}
},
"required": [
"listen_port"
],
"title": "UpdateLoadBalancerService",
"type": "object"
},
"update_records_of_rrset_request": {
"description": "Request for POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/update_records",
"properties": {
"records": {
"description": "Records to update in the RRSet.\n\nMust not be empty and must only contain distinct record values.\n",
"items": {
"$ref": "#/components/schemas/resource_record_with_comment"
},
"maxItems": 50,
"minItems": 1,
"type": "array"
}
},
"required": [
"records"
],
"type": "object"
},
"update_records_of_rrset_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/update_records",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"update_service_response": {
"description": "Response to POST https://api.hetzner.cloud/v1/load_balancers/{id}/actions/update_service",
"properties": {
"action": {
"$ref": "#/components/schemas/action"
}
},
"required": [
"action"
],
"title": "ActionResponse",
"type": "object"
},
"volume": {
"description": "A Volume is a highly-available, scalable, and SSD-based block storage for Servers. Pricing for Volumes depends on the Volume size and Location, not the actual used storage. Please see [Hetzner Wiki](https://wiki.hetzner.de/index.php/CloudServer/en#Volumes) for more details about Volumes.",
"properties": {
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"format": {
"description": "Filesystem of the Volume if formatted on creation, null if not formatted on creation.",
"example": "xfs",
"nullable": true,
"type": "string"
},
"id": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"linux_device": {
"description": "Device path on the file system for the Volume.",
"example": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"type": "string"
},
"location": {
"$ref": "#/components/schemas/location"
},
"name": {
"description": "Name of the Resource. Must be unique per Project.",
"example": "my-resource",
"type": "string"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"server": {
"description": "ID of the Server the Volume is attached to, null if it is not attached at all.",
"example": 12,
"format": "int64",
"nullable": true,
"type": "integer"
},
"size": {
"description": "Size in GB of the Volume.",
"example": 42,
"type": "number"
},
"status": {
"description": "Status of the Volume.",
"enum": [
"available",
"creating"
],
"example": "available",
"type": "string"
}
},
"required": [
"created",
"format",
"id",
"labels",
"linux_device",
"location",
"name",
"protection",
"server",
"size",
"status"
],
"type": "object"
},
"zone": {
"properties": {
"authoritative_nameservers": {
"properties": {
"assigned": {
"description": "Authoritative Hetzner nameservers assigned to this Zone.\n",
"example": [
"hydrogen.ns.hetzner.com.",
"oxygen.ns.hetzner.com.",
"helium.ns.hetzner.de."
],
"items": {
"type": "string"
},
"type": "array"
},
"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",
"example": [
"hydrogen.ns.hetzner.com.",
"oxygen.ns.hetzner.com.",
"helium.ns.hetzner.de."
],
"items": {
"type": "string"
},
"type": "array"
},
"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",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"nullable": true,
"type": "string"
},
"delegation_status": {
"description": "Status of the delegation.\n\n- `valid` - Parent zone correctly delegates to assigned nameservers.\n- `partially-valid` - Parent zone delegates to additional Hetzner nameservers not assigned to this zone.\n- `invalid` - Parent zone does not delegate to the assigned nameservers.\n- `lame` - Parent zone delegates to nameservers that don't know the zone.\n- `unregistered` - Domain is not registered.\n- `unknown` - Not yet known.\n",
"enum": [
"invalid",
"lame",
"partially-valid",
"unknown",
"unregistered",
"valid"
],
"type": "string"
}
},
"required": [
"assigned",
"delegated",
"delegation_last_check"
],
"type": "object"
},
"created": {
"description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"example": "2016-01-30T23:55:00Z",
"format": "date-time",
"type": "string"
},
"id": {
"description": "ID of the Zone.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"labels": {
"$ref": "#/components/schemas/labels"
},
"mode": {
"description": "Mode of the Zone.\n\nFor more information, see Zone Modes.\n",
"enum": [
"primary",
"secondary"
],
"example": "primary",
"type": "string"
},
"name": {
"description": "Name of the Zone.\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",
"example": "example.com",
"maxLength": 255,
"type": "string"
},
"primary_nameservers": {
"description": "Primary nameservers of the Zone.\n\nOnly set if Zone is in secondary mode, otherwise empty.\n",
"example": [
{
"address": "198.51.100.1",
"port": 53
},
{
"address": "203.0.113.1",
"port": 53
}
],
"items": {
"$ref": "#/components/schemas/nameserver"
},
"type": "array"
},
"protection": {
"$ref": "#/components/schemas/protection"
},
"record_count": {
"description": "Number of resource records (RR) within the Zone.",
"type": "integer"
},
"registrar": {
"description": "Registrar of the domain.",
"enum": [
"hetzner",
"other",
"unknown"
],
"type": "string"
},
"status": {
"description": "Status of the Zone.\n\n- `ok`: the Zone is pushed to the authoritative nameservers.\n- `updating`: the Zone is currently being published to the authoritative nameservers.\n- `error`: the Zone could not be published to the authoritative nameservers.\n",
"enum": [
"error",
"ok",
"updating"
],
"type": "string"
},
"ttl": {
"default": 3600,
"description": "Default Time To Live (TTL) of the Zone.\n\nMust be in between 60s and 2147483647s.\n\nThis TTL is used for RRSets that do not explicitly define a TTL.\n",
"example": 10800,
"maximum": 2147483647,
"minimum": 60,
"type": "integer"
}
},
"required": [
"authoritative_nameservers",
"created",
"id",
"labels",
"mode",
"name",
"protection",
"record_count",
"registrar",
"status",
"ttl"
],
"title": "Zone",
"type": "object"
}
},
"securitySchemes": {
"APIToken": {
"scheme": "bearer",
"type": "http"
}
}
},
"paths": {
"/actions": {
"get": {
"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",
"operationId": "get_multiple_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": true,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_multiple_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get multiple Actions",
"tags": [
"actions"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/actions/{id}": {
"get": {
"description": "Returns a specific Action object.\n",
"operationId": "get_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"actions"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/certificates": {
"get": {
"description": "Returns all Certificate objects.\n",
"operationId": "list_certificates",
"parameters": [
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by type. Can be used multiple times. The response will only\ncontain the resources with the specified type.\n",
"in": "query",
"name": "type",
"required": false,
"schema": {
"items": {
"description": "Type of the Certificate.",
"enum": [
"uploaded",
"managed"
],
"example": "uploaded",
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"certificates": [
{
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00Z",
"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",
"id": 897,
"labels": {
"key": "value"
},
"name": "my website cert",
"not_valid_after": "2019-07-08T09:59:59Z",
"not_valid_before": "2019-01-08T10:00:00Z",
"status": null,
"type": "uploaded",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_certificates_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Certificates",
"tags": [
"certificates"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud certificate list"
}
]
},
"post": {
"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",
"operationId": "create_certificate",
"requestBody": {
"content": {
"application/json": {
"examples": {
"managed": {
"summary": "Creating a type `managed` Certificate",
"value": {
"domain_names": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"name": "my website cert",
"type": "managed"
}
},
"uploaded": {
"summary": "Creating a type `uploaded` Certificate",
"value": {
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"name": "my website cert",
"private_key": "-----BEGIN PRIVATE KEY-----\n...",
"type": "uploaded"
}
}
},
"schema": {
"$ref": "#/components/schemas/create_certificate_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"managed": {
"summary": "Response when creating a type `managed` Certificate",
"value": {
"action": {
"command": "create_certificate",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 879,
"type": "certificate"
}
],
"started": "2019-01-08T12:10:00Z",
"status": "running"
},
"certificate": {
"certificate": null,
"created": "2019-01-08T12:10:00Z",
"domain_names": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"fingerprint": null,
"id": 897,
"labels": {
"key": "value"
},
"name": "my website cert",
"not_valid_after": null,
"not_valid_before": null,
"status": {
"error": null,
"issuance": "pending",
"renewal": "unavailable"
},
"type": "managed",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}
},
"uploaded": {
"summary": "Response when creating a type `uploaded` Certificate",
"value": {
"action": null,
"certificate": {
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00Z",
"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",
"id": 897,
"labels": {
"key": "value"
},
"name": "my website cert",
"not_valid_after": "2019-07-08T09:59:59Z",
"not_valid_before": "2019-01-08T10:00:00Z",
"status": null,
"type": "uploaded",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_certificate_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Certificate",
"tags": [
"certificates"
],
"x-codeSamples": [
{
"label": "Go (managed)",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Go (uploaded)",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python (managed)",
"lang": "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.create_managed(\n domain_names=[\n \"example.com\",\n \"webmail.example.com\",\n \"www.example.com\",\n ],\n name=\"my website cert\",\n)"
},
{
"label": "Python (uploaded)",
"lang": "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.create(\n certificate=\"-----BEGIN CERTIFICATE-----\\n...\",\n name=\"my website cert\",\n private_key=\"-----BEGIN PRIVATE KEY-----\\n...\",\n)"
},
{
"label": "CLI (managed)",
"lang": "Shell",
"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"
},
{
"label": "CLI (uploaded)",
"lang": "Shell",
"source": "hcloud certificate create \\\n --name \"my website cert\" \\\n --type uploaded \\\n --cert-file my-cert.pem \\\n --key-file my-key.pem"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/certificates/{id}": {
"delete": {
"description": "Deletes a Certificate.\n",
"operationId": "delete_certificate",
"parameters": [
{
"description": "ID of the Certificate.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Certificate.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Certificate",
"tags": [
"certificates"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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))"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud certificate delete $CERTIFICATE"
}
]
},
"get": {
"description": "Gets a specific Certificate object.\n",
"operationId": "get_certificate",
"parameters": [
{
"description": "ID of the Certificate.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Certificate.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"certificate": {
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00Z",
"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",
"id": 897,
"labels": {
"key": "value"
},
"name": "my website cert",
"not_valid_after": "2019-07-08T09:59:59Z",
"not_valid_before": "2019-01-08T10:00:00Z",
"status": null,
"type": "uploaded",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_certificate_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Certificate",
"tags": [
"certificates"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud certificate describe $CERTIFICATE"
}
]
},
"put": {
"description": "Updates the Certificate properties.\n\nNote: if the Certificate object changes during the request, the response will be a “conflict” error.\n",
"operationId": "replace_certificate",
"parameters": [
{
"description": "ID of the Certificate.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Certificate.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_certificate_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"certificate": {
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00Z",
"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",
"id": 897,
"labels": {
"key": "value"
},
"name": "my website cert",
"not_valid_after": "2019-07-08T09:59:59Z",
"not_valid_before": "2019-01-08T10:00:00Z",
"status": null,
"type": "uploaded",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_certificate_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Certificate",
"tags": [
"certificates"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/certificates/{id}/actions": {
"get": {
"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",
"operationId": "list_actions_for_certificate",
"parameters": [
{
"description": "ID of the Certificate.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Certificate.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"title": "Certificate ID",
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "issue_certificate",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2021-01-30T23:57:00Z",
"id": 14,
"progress": 100,
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"started": "2021-01-30T23:55:00Z",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Certificate",
"tags": [
"certificates"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/certificates/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for a Certificate. Only type `managed` Certificates have Actions.\n",
"operationId": "get_action_for_certificate",
"parameters": [
{
"description": "ID of the Certificate.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Certificate.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "issue_certificate",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2021-01-30T23:57:00Z",
"id": 14,
"progress": 100,
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"started": "2021-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Certificate",
"tags": [
"certificates"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/certificates/{id}/actions/retry": {
"post": {
"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",
"operationId": "retry_issuance_or_renewal",
"parameters": [
{
"description": "ID of the Certificate.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Certificate.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "issue_certificate",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2021-01-30T23:57:00Z",
"id": 14,
"progress": 100,
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"started": "2021-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/retry_issuance_or_renewal_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Retry Issuance or Renewal",
"tags": [
"certificates"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud certificate retry $CERTIFICATE"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/certificates/actions": {
"get": {
"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",
"operationId": "list_certificate_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"certificates"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/certificates/actions/{id}": {
"get": {
"description": "Returns a specific Action object.\n",
"operationId": "get_certificate_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"certificates"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/datacenters": {
"get": {
"description": "Returns all Data Centers.\n",
"operationId": "list_data_centers",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_data_centers_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Data Centers",
"tags": [
"datacenters"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud datacenter list"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/datacenters/{id}": {
"get": {
"description": "Returns a single Data Center.\n",
"operationId": "get_data_center",
"parameters": [
{
"description": "ID of the Data Center.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Data Center.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_data_center_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Data Center",
"tags": [
"datacenters"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud datacenter describe $DATACENTER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls": {
"get": {
"description": "Returns all Firewalls.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_firewalls",
"parameters": [
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_firewalls_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Firewalls",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud firewall list"
}
]
},
"post": {
"description": "Create a Firewall.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `server_already_added` | The Server was applied more than once. |\n| `422` | `incompatible_network_type` | The resources network type is not supported by Firewalls. |\n| `422` | `firewall_resource_not_found` | The resource the Firewall should be attached to was not found. |\n",
"operationId": "create_firewall",
"requestBody": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"apply_to": [
{
"server": {
"id": 42
},
"type": "server"
}
],
"labels": {
"key": "value"
},
"name": "Corporate Intranet Protection",
"rules": [
{
"description": "Allow port 80",
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"192.0.2.2/32",
"192.0.2.0/24",
"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/create_firewall_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_firewall_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Firewall",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"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]')"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls/{id}": {
"delete": {
"description": "Deletes the Firewall.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `resource_in_use` | Firewall still applied to a resource |\n",
"operationId": "delete_firewall",
"parameters": [
{
"description": "ID of the Firewall.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Firewall",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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))"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud firewall delete $FIREWALL"
}
]
},
"get": {
"description": "Returns a single Firewall.\n",
"operationId": "get_firewall",
"parameters": [
{
"description": "ID of the Firewall.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_firewall_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Firewall",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud firewall describe $FIREWALL"
}
]
},
"put": {
"description": "Update a Firewall.\n\nIn case of a parallel running change on the Firewall a `conflict` error will be returned.\n",
"operationId": "replace_firewall",
"parameters": [
{
"description": "ID of the Firewall.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_firewall_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_firewall_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Firewall",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls/{id}/actions": {
"get": {
"description": "Returns all Actions for the Firewall.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_actions_for_firewall",
"parameters": [
{
"description": "ID of the Firewall.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"title": "Firewall ID",
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "set_firewall_rules",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Firewall",
"tags": [
"firewalls"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for a Firewall.\n",
"operationId": "get_action_for_firewall",
"parameters": [
{
"description": "ID of the Firewall.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "set_firewall_rules",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Firewall",
"tags": [
"firewalls"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls/{id}/actions/apply_to_resources": {
"post": {
"description": "Applies a Firewall to multiple resources.\n\nSupported resources:\n- Servers (with a public network interface)\n- Label Selectors\n\nA Server can be applied to [a maximum of 5 Firewalls](https://docs.hetzner.com/cloud/firewalls/overview#limits). This limit\napplies to Servers applied via a matching Label Selector as well.\n\nUpdates to resources matching or no longer matching a Label Selector can take up to a few seconds\nto be processed.\n\nA Firewall is applied to a resource once the related Action 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 should be applied to was not found |\n| `422` | `firewall_already_applied` | Firewall is already applied to resource |\n| `422` | `incompatible_network_type` | The network type of the resource is not supported by Firewalls |\n| `422` | `private_net_only_server` | The Server the Firewall should be applied to has no public interface |\n",
"operationId": "apply_to_resources",
"parameters": [
{
"description": "ID of the Firewall.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"apply_to": [
{
"server": {
"id": 42
},
"type": "server"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/apply_to_resources_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "apply_firewall",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 14,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/apply_to_resources_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Apply to Resources",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud firewall apply-to-resource $FIREWALL \\\n --type server \\\n --server $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls/{id}/actions/remove_from_resources": {
"post": {
"description": "Removes a Firewall from multiple resources.\n\nSupported resources:\n- Servers (with a public network interface)\n\nA Firewall is removed from a resource once the related Action 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 should be removed from was not found |\n| `422` | `firewall_managed_by_label_selector` | Firewall is applied via a Label Selector and cannot be removed manually |\n",
"operationId": "remove_from_resources",
"parameters": [
{
"description": "ID of the Firewall.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"remove_from": [
{
"server": {
"id": 42
},
"type": "server"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/remove_from_resources_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "remove_firewall",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 14,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/remove_from_resources_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Remove from Resources",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud firewall remove-from-resource $FIREWALL \\\n --type server \\\n --server $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls/{id}/actions/set_rules": {
"post": {
"description": "Set the rules of a Firewall.\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 and [500 effective rules](https://docs.hetzner.com/cloud/firewalls/overview#limits).\n",
"operationId": "set_rules",
"parameters": [
{
"description": "ID of the Firewall.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Firewall.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"rules": [
{
"description": "Allow port 80",
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"192.0.2.2/32",
"192.0.2.0/24",
"2001:0db8:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/set_rules_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "set_firewall_rules",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
},
{
"command": "apply_firewall",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 14,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
},
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/set_rules_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Set Rules",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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]')"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls/actions": {
"get": {
"description": "Returns all Actions for Firewalls.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_firewall_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/firewalls/actions/{id}": {
"get": {
"description": "Returns the specific Action.\n",
"operationId": "get_firewall_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"firewalls"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips": {
"get": {
"description": "List multiple Floating IPs.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_floating_ips",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_floating_ips_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Floating IPs",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud floating-ip list"
}
]
},
"post": {
"description": "Create a Floating IP.\n\nProvide the `server` attribute to assign the Floating IP to that server or provide a `home_location` to locate the Floating IP at. Note that the Floating IP can be assigned to a Server in any Location later on. For optimal routing it is advised to use the Floating IP in the same Location it was created in.\n",
"operationId": "create_floating_ip",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_floating_ip_request"
}
}
},
"description": "The `type` argument is required while `home_location` and `server` are mutually exclusive.",
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "assign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"floating_ip": {
"blocked": false,
"created": "2016-01-30T23:50:00Z",
"description": "Web Frontend",
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"home_location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"id": 4711,
"ip": "2001:db8::/64",
"labels": {
"key": "value"
},
"name": "Web Frontend",
"protection": {
"delete": false
},
"server": 42,
"type": "ipv6"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_floating_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Floating IP",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/{id}": {
"delete": {
"description": "Deletes a Floating IP.\n\nIf assigned to a Server the Floating IP will be unassigned automatically until 1 May 2026. After this date, the Floating IP 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",
"operationId": "delete_floating_ip",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Floating IP",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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))"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud floating-ip delete $FLOATINGIP"
}
]
},
"get": {
"description": "Returns a single Floating IP.\n",
"operationId": "get_floating_ip",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_floating_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Floating IP",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud floating-ip describe $FLOATINGIP"
}
]
},
"put": {
"description": "Update a Floating IP.\n",
"operationId": "replace_floating_ip",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_floating_ip_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"floating_ip": {
"blocked": false,
"created": "2016-01-30T23:50:00Z",
"description": "Web Frontend",
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"home_location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"id": 4711,
"ip": "2001:db8::/64",
"labels": {
"key": "value"
},
"name": "Web Frontend",
"protection": {
"delete": false
},
"server": 42,
"type": "ipv6"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_floating_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Floating IP",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/{id}/actions": {
"get": {
"description": "Lists Actions for a Floating IP.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_actions_for_floating_ip",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "assign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "server"
},
{
"id": 4712,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Floating IP",
"tags": [
"floating_ips"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for a Floating IP.\n",
"operationId": "get_action_for_floating_ip",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "assign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Floating IP",
"tags": [
"floating_ips"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/{id}/actions/assign": {
"post": {
"description": "Assigns a Floating IP to a Server.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `422` | `floating_ip_assigned` | The Floating IP is already assigned |\n",
"operationId": "assign_floating_ip_to_server",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/assign_floating_ip_to_server_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "assign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/assign_floating_ip_to_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Assign a Floating IP to a Server",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud floating-ip assign $FLOATINGIP $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/{id}/actions/change_dns_ptr": {
"post": {
"description": "Change the reverse DNS records for this Floating IP.\n\nAllows to modify the PTR records set for the IP address.\n",
"operationId": "change_reverse_dns_records_for_floating_ip",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dns_ptr"
}
}
},
"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. For IPv6 addresses this must be a single address within the `/64` subnet of the Floating IP.\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 up to 100 entries can be created.\n",
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_dns_ptr",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_reverse_dns_records_for_floating_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change reverse DNS records for a Floating IP",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud floating-ip set-rdns $FLOATINGIP \\\n --ip 2001:db8::1 \\\n --hostname server.example.com"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/{id}/actions/change_protection": {
"post": {
"description": "Changes the protection settings configured for the Floating IP.\n",
"operationId": "change_floating_ip_protection",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/protection"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_floating_ip_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Floating IP Protection",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud floating-ip enable-protection $FLOATINGIP delete\nhcloud floating-ip disable-protection $FLOATINGIP delete"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/{id}/actions/unassign": {
"post": {
"description": "Unassigns a Floating IP.\n\nResults in the IP being unreachable. Can be assigned to another resource again.\n",
"operationId": "unassign_floating_ip",
"parameters": [
{
"description": "ID of the Floating IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Floating IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "unassign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/unassign_floating_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Unassign a Floating IP",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud floating-ip unassign $FLOATINGIP"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/actions": {
"get": {
"description": "Lists multiple Actions.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_floating_ip_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/floating_ips/actions/{id}": {
"get": {
"description": "Returns a single Action.\n",
"operationId": "get_floating_ip_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"floating_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/images": {
"get": {
"description": "Returns all Image objects. You can select specific Image types only and sort the results by using URI parameters.\n",
"operationId": "list_images",
"parameters": [
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by type. Can be used multiple times. The response will only\ncontain the resources with the specified type.\n",
"in": "query",
"name": "type",
"required": false,
"schema": {
"items": {
"description": "Type of the Image.",
"enum": [
"system",
"app",
"snapshot",
"backup"
],
"example": "snapshot",
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by status. Can be used multiple times. The response will only\ncontain the resources with the specified status.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Image.",
"enum": [
"available",
"creating",
"unavailable"
],
"example": "available",
"type": "string"
},
"type": "array"
}
},
{
"description": "Can be used multiple times. Server ID linked to the Image. Only available for Images of type `backup`.",
"in": "query",
"name": "bound_to",
"required": false,
"schema": {
"items": {
"type": "string"
},
"type": "array"
}
},
{
"description": "Can be used multiple times.",
"in": "query",
"name": "include_deprecated",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by cpu architecture. The response will only contain the resources\nwith the specified cpu architecture.\n",
"in": "query",
"name": "architecture",
"required": false,
"schema": {
"description": "CPU architecture of the Resource.",
"enum": [
"x86",
"arm"
],
"example": "x86",
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_images_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Images",
"tags": [
"images"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud image list"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/images/{id}": {
"delete": {
"description": "Deletes an Image. Only Images of type `snapshot` and `backup` can be deleted.\n",
"operationId": "delete_image",
"parameters": [
{
"description": "ID of the Image.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Image.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete an Image",
"tags": [
"images"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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))"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud image delete $IMAGE"
}
]
},
"get": {
"description": "Returns a specific Image object.\n",
"operationId": "get_image",
"parameters": [
{
"description": "ID of the Image.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Image.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_image_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Image",
"tags": [
"images"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud image describe $IMAGE"
}
]
},
"put": {
"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",
"operationId": "replace_image",
"parameters": [
{
"description": "ID of the Image.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Image.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_image_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"image": {
"architecture": "x86",
"bound_to": null,
"created": "2016-01-30T23:50:00Z",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00Z",
"description": "My new Image description",
"disk_size": 10,
"id": 4711,
"image_size": 2.3,
"labels": {
"key": "value"
},
"name": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_image_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update an Image",
"tags": [
"images"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/images/{id}/actions": {
"get": {
"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",
"operationId": "list_actions_for_image",
"parameters": [
{
"description": "ID of the Image.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Image.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "image"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for an Image",
"tags": [
"images"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/images/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for an Image.\n",
"operationId": "get_action_for_image",
"parameters": [
{
"description": "ID of the Image.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Image.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "image"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for an Image",
"tags": [
"images"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/images/{id}/actions/change_protection": {
"post": {
"description": "Changes the protection configuration of the Image. Can only be used on snapshots.\n",
"operationId": "change_image_protection",
"parameters": [
{
"description": "ID of the Image.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Image.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_image_protection_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "image"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_image_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Image Protection",
"tags": [
"images"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud image enable-protection $IMAGE delete\nhcloud image disable-protection $IMAGE delete"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/images/actions": {
"get": {
"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",
"operationId": "list_image_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"images"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/images/actions/{id}": {
"get": {
"description": "Returns a specific Action object.\n",
"operationId": "get_image_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"images"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/isos": {
"get": {
"description": "Returns all available ISO objects.\n",
"operationId": "list_isos",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by cpu architecture. The response will only contain the resources\nwith the specified cpu architecture.\n",
"in": "query",
"name": "architecture",
"required": false,
"schema": {
"description": "CPU architecture of the Resource.",
"enum": [
"x86",
"arm"
],
"example": "x86",
"type": "string"
}
},
{
"description": "Include Images with wildcard architecture (architecture is null). Works only if architecture filter is specified.",
"in": "query",
"name": "include_architecture_wildcard",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_isos_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List ISOs",
"tags": [
"isos"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud iso list"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/isos/{id}": {
"get": {
"description": "Returns a specific ISO object.\n",
"operationId": "get_iso",
"parameters": [
{
"description": "ID of the ISO.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the ISO.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_iso_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an ISO",
"tags": [
"isos"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud iso describe $ISO"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancer_types": {
"get": {
"description": "Gets all Load Balancer type objects.\n",
"operationId": "list_load_balancer_types",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_load_balancer_types_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Load Balancer Types",
"tags": [
"load_balancer_types"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer-type list"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancer_types/{id}": {
"get": {
"description": "Gets a specific Load Balancer type object.\n",
"operationId": "get_load_balancer_type",
"parameters": [
{
"description": "ID of the Load Balancer Type.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer Type.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_load_balancer_type_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Load Balancer Type",
"tags": [
"load_balancer_types"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer-type describe $LOADBALANCERTYPE"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers": {
"get": {
"description": "Gets all existing Load Balancers that you have available.\n",
"operationId": "list_load_balancers",
"parameters": [
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_load_balancers_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Load Balancers",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer list"
}
]
},
"post": {
"description": "Creates a Load Balancer.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| | `cloud_resource_ip_not_allowed` | The IP you are trying to add as a target belongs to a Hetzner Cloud resource |\n| | `ip_not_owned` | The IP is not owned by the owner of the project of the Load Balancer |\n| | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network |\n| | `robot_unavailable` | Robot was not available. The caller may retry the operation after a short delay. |\n| | `server_not_attached_to_network` | The server you are trying to add as a target is not attached to the same network as the Load Balancer |\n| | `source_port_already_used` | The source port you are trying to add is already in use |\n| | `missing_ipv4` | The server that you are trying to add as a public target does not have a public IPv4 address |\n| | `target_already_defined` | The Load Balancer target you are trying to define is already defined |\n",
"operationId": "create_load_balancer",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_load_balancer_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "create_load_balancer",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
},
"load_balancer": {
"algorithm": {
"type": "round_robin"
},
"created": "2016-01-30T23:50:00Z",
"id": 4711,
"included_traffic": 654321,
"ingoing_traffic": 123456,
"labels": {
"key": "value"
},
"load_balancer_type": {
"deprecated": "2016-01-30T23:50:00Z",
"description": "LB11",
"id": 1,
"max_assigned_certificates": 10,
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"name": "lb11",
"prices": [
{
"included_traffic": 654321,
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_per_tb_traffic": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
},
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "Web Frontend",
"outgoing_traffic": 123456,
"private_net": [
{
"ip": "10.0.0.2",
"network": 4711
}
],
"protection": {
"delete": false
},
"public_net": {
"enabled": false,
"ipv4": {
"ip": "1.2.3.4"
},
"ipv6": {
"ip": "2001:db8::1"
}
},
"services": [
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??,3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "http",
"proxyprotocol": false
}
],
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"server": {
"id": 80
},
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"server": {
"id": 80
},
"type": "server",
"use_private_ip": true
}
],
"type": "server",
"use_private_ip": true
}
]
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_load_balancer_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Load Balancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}": {
"delete": {
"description": "Deletes a Load Balancer.\n",
"operationId": "delete_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Load Balancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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))"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer delete $LOADBALANCER"
}
]
},
"get": {
"description": "Gets a specific Load Balancer object.\n",
"operationId": "get_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_load_balancer_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Load Balancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer describe $LOADBALANCER"
}
]
},
"put": {
"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",
"operationId": "replace_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_load_balancer_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"load_balancer": {
"algorithm": {
"type": "round_robin"
},
"created": "2016-01-30T23:50:00Z",
"id": 4711,
"included_traffic": 654321,
"ingoing_traffic": 123456,
"labels": {
"key": "value"
},
"load_balancer_type": {
"deprecated": "2016-01-30T23:50:00Z",
"description": "LB11",
"id": 1,
"max_assigned_certificates": 10,
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"name": "lb11",
"prices": [
{
"included_traffic": 654321,
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_per_tb_traffic": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
},
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "new-name",
"outgoing_traffic": 123456,
"private_net": [
{
"ip": "10.0.0.2",
"network": 4711
}
],
"protection": {
"delete": false
},
"public_net": {
"enabled": false,
"ipv4": {
"ip": "1.2.3.4"
},
"ipv6": {
"ip": "2001:db8::1"
}
},
"services": [
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??,3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "http",
"proxyprotocol": false
}
],
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"ip": {
"ip": "203.0.113.1"
},
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 80
},
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"server": {
"id": 80
},
"type": "server",
"use_private_ip": true
}
],
"type": "server",
"use_private_ip": true
}
]
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_load_balancer_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Load Balancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions": {
"get": {
"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",
"operationId": "list_actions_for_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "add_service",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Load Balancer",
"tags": [
"load_balancers"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for a Load Balancer.\n",
"operationId": "get_action_for_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Load Balancer",
"tags": [
"load_balancers"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/add_service": {
"post": {
"description": "Adds a service to a Load Balancer.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| | `source_port_already_used` | The source port you are trying to add is already in use |\n",
"operationId": "add_service",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/load_balancer_service"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "add_service",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/add_service_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Add Service",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/add_target": {
"post": {
"description": "Adds a target to a Load Balancer.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| | `cloud_resource_ip_not_allowed` | The IP you are trying to add as a target belongs to a Hetzner Cloud resource |\n| | `ip_not_owned` | The IP you are trying to add as a target is not owned by the Project owner |\n| | `load_balancer_public_interface_disabled` | The Load Balancer's public network interface is disabled |\n| | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network |\n| | `robot_unavailable` | Robot was not available. The caller may retry the operation after a short delay. |\n| | `server_not_attached_to_network` | The server you are trying to add as a target is not attached to the same network as the Load Balancer |\n| | `missing_ipv4` | The server that you are trying to add as a public target does not have a public IPv4 address |\n| | `target_already_defined` | The Load Balancer target you are trying to define is already defined |\n",
"operationId": "add_target",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/load_balancer_add_target"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "add_target",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/add_target_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Add Target",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/attach_to_network": {
"post": {
"description": "Attach a Load Balancer to a Network.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| | `load_balancer_already_attached` | The Load Balancer is already attached to a network |\n| | `ip_not_available` | The provided Network IP is not available |\n| | `no_subnet_available` | No Subnet or IP is available for the Load Balancer within the network |\n",
"operationId": "attach_load_balancer_to_network",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/attach_load_balancer_to_network_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "attach_to_network",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/attach_load_balancer_to_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Attach a Load Balancer to a Network",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer attach-to-network $LOADBALANCER \\\n --ip 10.0.1.1 \\\n --network 4711"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/change_algorithm": {
"post": {
"description": "Change the algorithm that determines to which target new requests are sent.\n",
"operationId": "change_algorithm",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_algorithm_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_algorithm",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_algorithm_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Algorithm",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer change-algorithm $LOADBALANCER \\\n --algorithm-type round_robin"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/change_dns_ptr": {
"post": {
"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",
"operationId": "change_reverse_dns_entry_for_this_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_reverse_dns_entry_for_this_load_balancer_request"
}
}
},
"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
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_dns_ptr",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_reverse_dns_entry_for_this_load_balancer_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change reverse DNS entry for this Load Balancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer set-rdns $LOADBALANCER \\\n --ip 1.2.3.4 \\\n --hostname lb1.example.com"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/change_protection": {
"post": {
"description": "Changes the protection configuration of a Load Balancer.\n",
"operationId": "change_load_balancer_protection",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_load_balancer_protection_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_load_balancer_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Load Balancer Protection",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer enable-protection $LOADBALANCER delete\nhcloud load-balancer disable-protection $LOADBALANCER delete"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/change_type": {
"post": {
"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| | `invalid_load_balancer_type` | The Load Balancer type does not fit for the given Load Balancer |\n",
"operationId": "change_type_of_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_type_of_load_balancer_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_load_balancer_type",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_type_of_load_balancer_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change the Type of a Load Balancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer change-type $LOADBALANCER lb21"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/delete_service": {
"post": {
"description": "Delete a service of a Load Balancer.\n",
"operationId": "delete_service",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_service_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "delete_service",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/delete_service_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete Service",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer delete-service $LOADBALANCER \\\n --listen-port 443"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/detach_from_network": {
"post": {
"description": "Detaches a Load Balancer from a network.\n",
"operationId": "detach_load_balancer_from_network",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/detach_load_balancer_from_network_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "detach_from_network",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/detach_load_balancer_from_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Detach a Load Balancer from a Network",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer detach-from-network $LOADBALANCER \\\n --network $NETWORK"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/disable_public_interface": {
"post": {
"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| | `load_balancer_not_attached_to_network` | The Load Balancer is not attached to a network |\n| | `targets_without_use_private_ip` | The Load Balancer has targets that use the public IP instead of the private IP |\n",
"operationId": "disable_public_interface_of_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "disable_public_interface",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/disable_public_interface_of_load_balancer_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Disable the public interface of a Load Balancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer disable-public-interface $LOADBALANCER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/enable_public_interface": {
"post": {
"description": "Enable the public interface of a Load Balancer. The Load Balancer will be accessible from the internet via its public IPs.\n",
"operationId": "enable_public_interface_of_load_balancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "enable_public_interface",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/enable_public_interface_of_load_balancer_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Enable the public interface of a Load Balancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud load-balancer enable-public-interface $LOADBALANCER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/remove_target": {
"post": {
"description": "Removes a target from a Load Balancer.\n",
"operationId": "remove_target",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/remove_target_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "remove_target",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/remove_target_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Remove Target",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/actions/update_service": {
"post": {
"description": "Updates a Load Balancer Service.\n\n#### Operation specific errors\n\n| Status | Code | Description |\n| --- | --- | --- |\n| | `source_port_already_used` | The source port you are trying to add is already in use |\n",
"operationId": "update_service",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update_load_balancer_service"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "update_service",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/update_service_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update Service",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/{id}/metrics": {
"get": {
"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",
"operationId": "get_metrics_for_loadbalancer",
"parameters": [
{
"description": "ID of the Load Balancer.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Load Balancer.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Type of metrics to get.",
"in": "query",
"name": "type",
"required": true,
"schema": {
"items": {
"enum": [
"open_connections",
"connections_per_second",
"requests_per_second",
"bandwidth"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Start of period to get Metrics for (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"in": "query",
"name": "start",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "End of period to get Metrics for (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"in": "query",
"name": "end",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Resolution of results in seconds.",
"in": "query",
"name": "step",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_metrics_for_loadbalancer_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get Metrics for a LoadBalancer",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/actions": {
"get": {
"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",
"operationId": "list_load_balancer_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/load_balancers/actions/{id}": {
"get": {
"description": "Returns a specific Action object.\n",
"operationId": "get_load_balancer_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"load_balancers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/locations": {
"get": {
"description": "Returns all Locations.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_locations",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_locations_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Locations",
"tags": [
"locations"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud location list"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/locations/{id}": {
"get": {
"description": "Returns a Location.\n",
"operationId": "get_location",
"parameters": [
{
"description": "ID of the Location.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Location.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_location_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Location",
"tags": [
"locations"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud location describe $LOCATION"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks": {
"get": {
"description": "List multiple Networks.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_networks",
"parameters": [
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_networks_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Networks",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud network list"
}
]
},
"post": {
"description": "Creates a Network.\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. 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.\n",
"operationId": "create_network",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_network_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}": {
"delete": {
"description": "Deletes a Network.\n\nAttached resources will be detached automatically.\n",
"operationId": "delete_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud network delete $NETWORK"
}
]
},
"get": {
"description": "Get a specific Network.\n",
"operationId": "get_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud network describe $NETWORK"
}
]
},
"put": {
"description": "Update a Network.\n\nIf a change is currently being performed on this Network, a error response with code `conflict` will be returned.\n",
"operationId": "replace_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_network_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"network": {
"created": "2016-01-30T23:50:00Z",
"expose_routes_to_vswitch": true,
"id": 4711,
"ip_range": "10.0.0.0/16",
"labels": {
"key": "value"
},
"load_balancers": [
42
],
"name": "new-name",
"protection": {
"delete": false
},
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"subnets": [
{
"gateway": "10.0.0.1",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"type": "cloud"
}
]
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}/actions": {
"get": {
"description": "Lists Actions for a Network.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_actions_for_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "add_subnet",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Network",
"tags": [
"networks"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for a Network.\n",
"operationId": "get_action_for_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "add_subnet",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Network",
"tags": [
"networks"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}/actions/add_route": {
"post": {
"description": "Adds a route entry to a Network.\n\nIf a change is currently being performed on this Network, a error response with code `conflict` will be returned.\n",
"operationId": "add_route_to_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/route"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "add_route",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/add_route_to_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Add a route to a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud network add-route $NETWORK \\\n --destination 10.100.1.0/24 \\\n --gateway 10.0.1.1"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}/actions/add_subnet": {
"post": {
"description": "Adds a new subnet to the Network.\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, a error response with code `conflict` will be returned.\n",
"operationId": "add_subnet_to_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subnet"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "add_subnet",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/add_subnet_to_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Add a subnet to a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}/actions/change_ip_range": {
"post": {
"description": "Changes the IP range of a Network.\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, they need to be rebooted or the routes to be updated manually.\n\nFor example if the Network 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, a error response with code `conflict` will be returned.\n",
"operationId": "change_ip_range_of_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_ip_range_of_network_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_ip_range",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_ip_range_of_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change IP range of a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud network change-ip-range $NETWORK \\\n --ip-range 10.0.0.0/16"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}/actions/change_protection": {
"post": {
"description": "Changes the protection settings of a Network.\n\nIf a change is currently being performed on this Network, a error response with code `conflict` will be returned.\n",
"operationId": "change_network_protection",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_network_protection_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_network_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Network Protection",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud network enable-protection $NETWORK delete\nhcloud network disable-protection $NETWORK delete"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}/actions/delete_route": {
"post": {
"description": "Delete a route entry from a Network.\n\nIf a change is currently being performed on this Network, a error response with code `conflict` will be returned.\n",
"operationId": "delete_route_from_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/route"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "delete_route",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/delete_route_from_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a route from a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud network remove-route $NETWORK \\\n --destination 10.100.1.0/24 \\\n --gateway 10.0.1.1"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/{id}/actions/delete_subnet": {
"post": {
"description": "Deletes a single subnet entry from a Network.\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, a error response with code `conflict` will be returned.\n",
"operationId": "delete_subnet_from_network",
"parameters": [
{
"description": "ID of the Network.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Network.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_subnet_from_network_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "delete_subnet",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/delete_subnet_from_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a subnet from a Network",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud network remove-subnet $NETWORK \\\n --ip-range 10.0.1.0/24"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/actions": {
"get": {
"description": "Lists multiple Actions.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_network_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/networks/actions/{id}": {
"get": {
"description": "Returns a single Action.\n",
"operationId": "get_network_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"networks"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/placement_groups": {
"get": {
"description": "Returns all Placement Group objects.\n",
"operationId": "list_placement_groups",
"parameters": [
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by type. Can be used multiple times. The response will only\ncontain the resources with the specified type.\n",
"in": "query",
"name": "type",
"required": false,
"schema": {
"items": {
"description": "Type of Placement Group.\n",
"enum": [
"spread"
],
"example": "spread",
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
},
"placement_groups": [
{
"created": "2019-01-08T12:10:00Z",
"id": 897,
"labels": {
"key": "value"
},
"name": "my Placement Group",
"servers": [
4711,
4712
],
"type": "spread"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/list_placement_groups_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Placement Groups",
"tags": [
"placement_groups"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud placement-group list"
}
]
},
"post": {
"description": "Creates a new Placement Group.\n",
"operationId": "create_placementgroup",
"requestBody": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"name": "my Placement Group",
"type": "spread"
}
}
},
"schema": {
"$ref": "#/components/schemas/create_placementgroup_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"placement_group": {
"created": "2019-01-08T12:10:00Z",
"id": 897,
"labels": {
"key": "value"
},
"name": "my Placement Group",
"servers": [],
"type": "spread"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_placementgroup_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a PlacementGroup",
"tags": [
"placement_groups"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud placement-group create \\\n --name \"my Placement Group\" \\\n --type spread"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/placement_groups/{id}": {
"delete": {
"description": "Deletes a Placement Group.\n",
"operationId": "delete_placementgroup",
"parameters": [
{
"description": "ID of the Placement Group.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Placement Group.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a PlacementGroup",
"tags": [
"placement_groups"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud placement-group delete $PLACEMENTGROUP"
}
]
},
"get": {
"description": "Gets a specific Placement Group object.\n",
"operationId": "get_placementgroup",
"parameters": [
{
"description": "ID of the Placement Group.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Placement Group.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"placement_group": {
"created": "2019-01-08T12:10:00Z",
"id": 897,
"labels": {
"key": "value"
},
"name": "my Placement Group",
"servers": [
4711,
4712
],
"type": "spread"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_placementgroup_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a PlacementGroup",
"tags": [
"placement_groups"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud placement-group describe $PLACEMENTGROUP"
}
]
},
"put": {
"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",
"operationId": "replace_placementgroup",
"parameters": [
{
"description": "ID of the Placement Group.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Placement Group.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_placementgroup_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"placement_group": {
"created": "2019-01-08T12:10:00Z",
"id": 897,
"labels": {
"key": "value"
},
"name": "my Placement Group",
"servers": [
4711,
4712
],
"type": "spread"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_placementgroup_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a PlacementGroup",
"tags": [
"placement_groups"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/pricing": {
"get": {
"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",
"operationId": "list_prices",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_prices_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get all prices",
"tags": [
"pricing"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips": {
"get": {
"description": "List multiple Primary IPs.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_primary_ips",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter results by IP address.",
"example": "127.0.0.1",
"in": "query",
"name": "ip",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_primary_ips_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Primary IPs",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud primary-ip list"
}
]
},
"post": {
"description": "Create a new Primary IP.\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 this Primary IP shall be created in.\n\nA Primary IP can only be assigned to resource in the same Location 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 is running, but needs to be powered off |\n| `422` | `server_has_ipv4` | The Server already has an ipv4 address |\n| `422` | `server_has_ipv6` | The Server already has an ipv6 address |\n",
"operationId": "create_primary_ip",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_primary_ip_request"
}
}
},
"description": "Request Body for creating a new Primary IP.\n\nThe `location`, `datacenter` and `assignee_id`/`assignee_type` attributes are mutually exclusive.\n",
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "assign_primary_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 17,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"primary_ip": {
"assignee_id": 17,
"assignee_type": "server",
"auto_delete": true,
"blocked": false,
"created": "2016-01-30T23:50:00Z",
"datacenter": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"id": 42,
"ip": "2001:db8::/64",
"labels": {
"key": "value"
},
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "my-ip",
"protection": {
"delete": false
},
"type": "ipv6"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_primary_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Primary IP",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/{id}": {
"delete": {
"description": "Deletes a Primary IP.\n\nThe Server must be powered off (status `off`) in order for this operation to succeed.\nIf assigned to a Server the Primary IP will be unassigned automatically until 1 May 2026. After this date, the Primary IP 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",
"operationId": "delete_primary_ip",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Primary IP",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud primary-ip delete $PRIMARYIP"
}
]
},
"get": {
"description": "Returns a Primary IP.\n",
"operationId": "get_primary_ip",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_primary_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Primary IP",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud primary-ip describe $PRIMARYIP"
}
]
},
"put": {
"description": "Update a Primary IP.\n\nIf another change is concurrently performed on this Primary IP, a error response with code `conflict` will be returned.\n",
"operationId": "replace_primary_ip",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_primary_ip_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_primary_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Primary IP",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/{id}/actions": {
"get": {
"description": "Returns all Actions for a Primary IP.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_actions_for_primary_ip",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Primary IP",
"tags": [
"primary_ips"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for a Primary IP.\n",
"operationId": "get_action_for_primary_ip",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Primary IP",
"tags": [
"primary_ips"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/{id}/actions/assign": {
"post": {
"description": "Assign a Primary IP to a resource.\n\nA Server can only have one Primary IP of type `ipv4` and one of type `ipv6` assigned. If you need more IPs use Floating IPs.\n\nA Server 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 is running, but needs to be powered off |\n| `422` | `primary_ip_already_assigned` | Primary IP is already assigned to a different Server |\n| `422` | `server_has_ipv4` | The Server already has an IPv4 address |\n| `422` | `server_has_ipv6` | The Server already has an IPv6 address |\n",
"operationId": "assign_primary_ip_to_resource",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/assign_primary_ip_to_resource_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "assign_primary_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "primary_ip"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/assign_primary_ip_to_resource_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Assign a Primary IP to a resource",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud primary-ip assign --server 4711 $PRIMARYIP"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/{id}/actions/change_dns_ptr": {
"post": {
"description": "Change the reverse DNS records for this Primary IP.\n\nAllows to modify the PTR records set for the IP address.\n",
"operationId": "change_reverse_dns_records_for_primary_ip",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dns_ptr"
}
}
},
"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. For IPv6 addresses this must be a single address within the `/64` subnet of the Primary IP.\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 up to 100 entries can be created.\n",
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_dns_ptr",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "primary_ip"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_reverse_dns_records_for_primary_ip_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change reverse DNS records for a Primary IP",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud primary-ip set-rdns $PRIMARYIP \\\n --ip 1.2.3.4 \\\n --hostname server02.example.com"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/{id}/actions/change_protection": {
"post": {
"description": "Changes the protection configuration of a Primary IP.\n\nA Primary IPs deletion protection can only be enabled if its `auto_delete` property is set to `false`.\n",
"operationId": "change_primary_ip_protection",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/protection"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "primary_ip"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_primary_ip_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Primary IP Protection",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud primary-ip enable-protection $PRIMARYIP delete\nhcloud primary-ip disable-protection $PRIMARYIP delete"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/{id}/actions/unassign": {
"post": {
"description": "Unassign a Primary IP from a resource.\n\nA Server must be powered off (status `off`) in order for this operation to succeed.\n\nA Server 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 is running, but needs to be powered off |\n| `422` | `server_is_load_balancer_target` | The Server IPv4 address is a loadbalancer target |\n",
"operationId": "unassign_primary_ip_from_resource",
"parameters": [
{
"description": "ID of the Primary IP.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Primary IP.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "unassign_primary_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "primary_ip"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/unassign_primary_ip_from_resource_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Unassign a Primary IP from a resource",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud primary-ip unassign $PRIMARYIP"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/actions": {
"get": {
"description": "Lists multiple Actions.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_primary_ip_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/primary_ips/actions/{id}": {
"get": {
"description": "Returns a single Action.\n",
"operationId": "get_primary_ip_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"primary_ips"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/server_types": {
"get": {
"description": "Gets all Server type objects.\n",
"operationId": "list_server_types",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_server_types_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Server Types",
"tags": [
"server_types"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server-type list"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/server_types/{id}": {
"get": {
"description": "Gets a specific Server type object.\n",
"operationId": "get_server_type",
"parameters": [
{
"description": "ID of the Server Type.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server Type.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_server_type_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Server Type",
"tags": [
"server_types"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server-type describe $SERVERTYPE"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers": {
"get": {
"description": "Returns all existing Server objects.\n",
"operationId": "list_servers",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by status. Can be used multiple times. The response will only\ncontain the resources with the specified status.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Server.",
"enum": [
"running",
"initializing",
"starting",
"stopping",
"off",
"deleting",
"migrating",
"rebuilding",
"unknown"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_servers_response"
}
}
},
"description": "Request succeeded.",
"headers": {
"x-next": {
"description": "A link to the next page of responses.",
"schema": {
"type": "string"
}
}
}
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Servers",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server list"
}
]
},
"post": {
"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| | `placement_error` | An error during the placement occurred |\n| | `primary_ip_assigned` | The specified Primary IP is already assigned to a server |\n| | `primary_ip_datacenter_mismatch` | he specified Primary IP is in a different datacenter |\n| | `primary_ip_version_mismatch` | The specified Primary IP has the wrong IP Version |\n",
"operationId": "create_server",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_server_request"
}
}
},
"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
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "create_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 1,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"next_actions": [
{
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
],
"root_password": "YItygq1v3GYjjMomLaKc",
"server": {
"backup_window": "22-02",
"created": "2016-01-30T23:50:00Z",
"datacenter": {
"description": "Falkenstein 1 DC 8",
"id": 1,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"id": 42,
"image": {
"architecture": "x86",
"bound_to": null,
"created": "2016-01-30T23:50:00Z",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00Z",
"description": "Ubuntu 24.04 Standard 64 bit",
"disk_size": 10,
"id": 4711,
"image_size": 2.3,
"labels": {
"key": "value"
},
"name": "ubuntu-24.04",
"os_flavor": "ubuntu",
"os_version": "24.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
},
"included_traffic": 654321,
"ingoing_traffic": 123456,
"iso": {
"architecture": "x86",
"deprecation": {
"announced": "2018-02-28T00:00:00Z",
"unavailable_after": "2018-05-31T00:00:00Z"
},
"description": "FreeBSD 11.0 x64",
"id": 4711,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"type": "public"
},
"labels": {
"key": "value"
},
"load_balancers": [],
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"locked": false,
"name": "my-server",
"outgoing_traffic": 123456,
"primary_disk_size": 50,
"private_net": [
{
"alias_ips": [],
"ip": "10.0.0.2",
"mac_address": "86:00:ff:2a:7d:e1",
"network": 4711
}
],
"protection": {
"delete": false,
"rebuild": false
},
"public_net": {
"firewalls": [
{
"id": 38,
"status": "applied"
}
],
"floating_ips": [
478
],
"ipv4": {
"blocked": false,
"dns_ptr": "server01.example.com",
"ip": "1.2.3.4"
},
"ipv6": {
"blocked": false,
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"ip": "2001:db8::/64"
}
},
"rescue_enabled": false,
"server_type": {
"architecture": "x86",
"cores": 2,
"cpu_type": "shared",
"deprecated": true,
"description": "CPX22",
"disk": 80,
"id": 1,
"locations": [
{
"deprecation": null,
"id": 1,
"name": "fsn1"
},
{
"deprecation": {
"announced": "2018-02-28T00:00:00Z",
"unavailable_after": "2018-05-31T00:00:00Z"
},
"id": 2,
"name": "nbg1"
}
],
"memory": 4,
"name": "cpx22",
"prices": [
{
"included_traffic": 21990232555520,
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_per_tb_traffic": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"storage_type": "local"
},
"status": "initializing",
"volumes": []
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"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": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}": {
"delete": {
"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",
"operationId": "delete_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/delete_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server delete $SERVER"
}
]
},
"get": {
"description": "Returns a specific Server object. The Server must exist inside the Project.\n",
"operationId": "get_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server describe $SERVER"
}
]
},
"put": {
"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",
"operationId": "replace_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_server_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions": {
"get": {
"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",
"operationId": "list_actions_for_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"title": "Server ID",
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Server",
"tags": [
"servers"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action object for a Server.\n",
"operationId": "get_action_for_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Server",
"tags": [
"servers"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/add_to_placement_group": {
"post": {
"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| | `server_not_stopped` | The action requires a stopped server |\n",
"operationId": "add_server_to_placement_group",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/add_server_to_placement_group_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "add_to_placement_group",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/add_server_to_placement_group_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Add a Server to a Placement Group",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server add-to-placement-group --placement-group 1 $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/attach_iso": {
"post": {
"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",
"operationId": "attach_iso_to_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/attach_iso_to_server_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "attach_iso",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/attach_iso_to_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Attach an ISO to a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server attach-iso $SERVER \"FreeBSD-11.0-RELEASE-amd64-dvd1\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/attach_to_network": {
"post": {
"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",
"operationId": "attach_server_to_network",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/attach_server_to_network_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "attach_to_network",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/attach_server_to_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Attach a Server to a Network",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server attach-to-network $SERVER \\\n --alias-ips 10.0.1.2 \\\n --ip 10.0.1.1 \\\n --network 4711"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/change_alias_ips": {
"post": {
"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",
"operationId": "change_alias_ips_of_network",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_alias_ips_of_network_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_alias_ips",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_alias_ips_of_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change alias IPs of a Network",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server change-alias-ips $SERVER \\\n --alias-ips 10.0.1.2 \\\n --network 4711"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/change_dns_ptr": {
"post": {
"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",
"operationId": "change_reverse_dns_entry_for_this_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_reverse_dns_entry_for_this_server_request"
}
}
},
"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
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_dns_ptr",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_reverse_dns_entry_for_this_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change reverse DNS entry for this Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server set-rdns $SERVER \\\n --ip 1.2.3.4 \\\n --hostname server01.example.com"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/change_protection": {
"post": {
"description": "Changes the protection configuration of the Server.\n",
"operationId": "change_server_protection",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_server_protection_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_server_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Server Protection",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server enable-protection $SERVER delete rebuild\nhcloud server disable-protection $SERVER delete rebuild"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/change_type": {
"post": {
"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| | `invalid_server_type` | The server type does not fit for the given server or is deprecated |\n| | `server_not_stopped` | The action requires a stopped server |\n",
"operationId": "change_type_of_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_type_of_server_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_server_type",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_type_of_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change the Type of a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server change-type --keep-disk $SERVER cpx32"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/create_image": {
"post": {
"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",
"operationId": "create_image_from_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_image_from_server_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "create_image",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
},
"image": {
"architecture": "x86",
"bound_to": null,
"created": "2016-01-30T23:50:00Z",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00Z",
"description": "my image",
"disk_size": 10,
"id": 4711,
"image_size": 2.3,
"labels": {
"key": "value"
},
"name": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "creating",
"type": "snapshot"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_image_from_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create Image from a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/detach_from_network": {
"post": {
"description": "Detaches a Server from a network. The interface for this network will vanish.\n",
"operationId": "detach_server_from_network",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/detach_server_from_network_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "detach_from_network",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/detach_server_from_network_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Detach a Server from a Network",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server detach-from-network --network 4711 $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/detach_iso": {
"post": {
"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",
"operationId": "detach_iso_from_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "detach_iso",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/detach_iso_from_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Detach an ISO from a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server detach-iso $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/disable_backup": {
"post": {
"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",
"operationId": "disable_backups_for_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "disable_backup",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/disable_backups_for_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Disable Backups for a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server disable-backup $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/disable_rescue": {
"post": {
"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",
"operationId": "disable_rescue_mode_for_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "disable_rescue",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/disable_rescue_mode_for_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Disable Rescue Mode for a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server disable-rescue $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/enable_backup": {
"post": {
"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",
"operationId": "enable_and_configure_backups_for_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "enable_backup",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/enable_and_configure_backups_for_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Enable and Configure Backups for a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server enable-backup $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/enable_rescue": {
"post": {
"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",
"operationId": "enable_rescue_mode_for_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/enable_rescue_mode_for_server_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "enable_rescue",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
},
"root_password": "zCWbFhnu950dUTko5f40"
}
}
},
"schema": {
"$ref": "#/components/schemas/enable_rescue_mode_for_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Enable Rescue Mode for a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server enable-rescue $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/poweroff": {
"post": {
"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",
"operationId": "power_off_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "stop_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/power_off_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Power off a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server poweroff $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/poweron": {
"post": {
"description": "Starts a Server by turning its power on.\n",
"operationId": "power_on_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/power_on_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Power on a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server poweron $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/reboot": {
"post": {
"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",
"operationId": "soft_reboot_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "reboot_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/soft_reboot_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Soft-reboot a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server reboot $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/rebuild": {
"post": {
"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",
"operationId": "rebuild_server_from_image",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rebuild_server_from_image_request"
}
}
},
"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
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "rebuild_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"root_password": null
}
}
},
"schema": {
"$ref": "#/components/schemas/rebuild_server_from_image_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Rebuild a Server from an Image",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server rebuild --image ubuntu-24.04 $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/remove_from_placement_group": {
"post": {
"description": "Removes a Server from a Placement Group.\n",
"operationId": "remove_from_placement_group",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "remove_from_placement_group",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/remove_from_placement_group_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Remove from Placement Group",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server remove-from-placement-group $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/request_console": {
"post": {
"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",
"operationId": "request_console_for_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "request_console",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
},
"password": "9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x",
"wss_url": "wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c"
}
}
},
"schema": {
"$ref": "#/components/schemas/request_console_for_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Request Console for a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server request-console $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/reset": {
"post": {
"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",
"operationId": "reset_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "reset_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/reset_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Reset a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server reset $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/reset_password": {
"post": {
"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",
"operationId": "reset_root_password_of_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "reset_password",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"root_password": "zCWbFhnu950dUTko5f40"
}
}
},
"schema": {
"$ref": "#/components/schemas/reset_root_password_of_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Reset root Password of a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server reset-password $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/actions/shutdown": {
"post": {
"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",
"operationId": "shutdown_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "shutdown_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/shutdown_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Shutdown a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server shutdown $SERVER"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/{id}/metrics": {
"get": {
"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",
"operationId": "get_metrics_for_server",
"parameters": [
{
"description": "ID of the Server.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Server.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Type of metrics to get.",
"in": "query",
"name": "type",
"required": true,
"schema": {
"items": {
"enum": [
"cpu",
"disk",
"network"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Start of period to get Metrics for (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"in": "query",
"name": "start",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "End of period to get Metrics for (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).",
"in": "query",
"name": "end",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Resolution of results in seconds.",
"in": "query",
"name": "step",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_metrics_for_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get Metrics for a Server",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud server metrics $SERVER \\\n --type cpu,network,disk \\\n --start 2017-01-01T00:00:00Z \\\n --end 2017-01-01T23:00:00Z"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/actions": {
"get": {
"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",
"operationId": "list_server_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/servers/actions/{id}": {
"get": {
"description": "Returns a specific Action object.\n",
"operationId": "get_server_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"servers"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/ssh_keys": {
"get": {
"description": "Returns all SSH key objects.\n",
"operationId": "list_ssh_keys",
"parameters": [
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Can be used to filter SSH keys by their fingerprint. The response will only contain the SSH key matching the specified fingerprint.",
"in": "query",
"name": "fingerprint",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_ssh_keys_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List SSH keys",
"tags": [
"ssh_keys"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud ssh-key list"
}
]
},
"post": {
"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",
"operationId": "create_ssh_key",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_ssh_key_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_ssh_key_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create an SSH key",
"tags": [
"ssh_keys"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/ssh_keys/{id}": {
"delete": {
"description": "Deletes an SSH key. It cannot be used anymore.\n",
"operationId": "delete_ssh_key",
"parameters": [
{
"description": "ID of the SSH Key.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the SSH Key.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete an SSH key",
"tags": [
"ssh_keys"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud ssh-key delete $SSHKEY"
}
]
},
"get": {
"description": "Returns a specific SSH key object.\n",
"operationId": "get_ssh_key",
"parameters": [
{
"description": "ID of the SSH Key.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the SSH Key.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_ssh_key_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a SSH key",
"tags": [
"ssh_keys"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud ssh-key describe $SSHKEY"
}
]
},
"put": {
"description": "Updates an SSH key. You can update an SSH key name and an SSH key labels.\n",
"operationId": "replace_ssh_key",
"parameters": [
{
"description": "ID of the SSH Key.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the SSH Key.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_ssh_key_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"ssh_key": {
"created": "2016-01-30T23:50:00Z",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"id": 2323,
"labels": {
"key": "value"
},
"name": "My ssh key",
"public_key": "ssh-rsa AAAjjk76kgf...Xt"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_ssh_key_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update an SSH key",
"tags": [
"ssh_keys"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes": {
"get": {
"description": "Gets all existing Volumes that you have available.\n",
"operationId": "list_volumes",
"parameters": [
{
"description": "Filter resources by status. Can be used multiple times. The response will only\ncontain the resources with the specified status.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Volume.",
"enum": [
"available",
"creating"
],
"example": "available",
"type": "string"
},
"type": "array"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_volumes_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Volumes",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud volume list"
}
]
},
"post": {
"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| | `no_space_left_in_location` | There is no volume space left in the given location |\n",
"operationId": "create_volume",
"requestBody": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"automount": false,
"format": "xfs",
"labels": {
"key": "value"
},
"location": "nbg1",
"name": "test-database",
"size": 42
}
}
},
"schema": {
"$ref": "#/components/schemas/create_volume_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "create_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"next_actions": [
{
"command": "attach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
],
"volume": {
"created": "2016-01-30T23:50:11Z",
"format": "xfs",
"id": 4711,
"labels": {
"key": "value"
},
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "database-storage",
"protection": {
"delete": false
},
"server": 12,
"size": 42,
"status": "available"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_volume_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Volume",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud volume create \\\n --automount=false \\\n --format xfs \\\n --label \"key=value\" \\\n --location nbg1 \\\n --name test-database \\\n --size 42"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/{id}": {
"delete": {
"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",
"operationId": "delete_volume",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Volume",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud volume delete $VOLUME"
}
]
},
"get": {
"description": "Gets a specific Volume object.\n",
"operationId": "get_volume",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_volume_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Volume",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud volume describe $VOLUME"
}
]
},
"put": {
"description": "Updates the Volume properties.\n",
"operationId": "replace_volume",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_volume_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"volume": {
"created": "2016-01-30T23:50:11Z",
"format": "xfs",
"id": 4711,
"labels": {
"key": "value"
},
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "database-storage",
"protection": {
"delete": false
},
"server": 12,
"size": 42,
"status": "available"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_volume_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Volume",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/{id}/actions": {
"get": {
"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",
"operationId": "list_actions_for_volume",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"actions": [
{
"command": "attach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 13,
"type": "volume"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 1,
"next_page": null,
"page": 1,
"per_page": 25,
"previous_page": null,
"total_entries": 21
}
}
}
}
},
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Volume",
"tags": [
"volumes"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for a Volume.\n",
"operationId": "get_action_for_volume",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "attach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Volume",
"tags": [
"volumes"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/{id}/actions/attach": {
"post": {
"description": "Attaches a Volume to a Server. Works only if the Server is in the same Location as the Volume.\n",
"operationId": "attach_volume_to_server",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/attach_volume_to_server_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "attach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 43,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/attach_volume_to_server_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Attach Volume to a Server",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud volume attach $VOLUME \\\n --automount=false \\\n --server 43"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/{id}/actions/change_protection": {
"post": {
"description": "Changes the protection configuration of a Volume.\n",
"operationId": "change_volume_protection",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_volume_protection_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00Z",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_volume_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Volume Protection",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud volume enable-protection $VOLUME delete\nhcloud volume disable-protection $VOLUME delete"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/{id}/actions/detach": {
"post": {
"description": "Detaches a Volume from the Server it’s attached to. You may attach it to a Server again at a later time.\n",
"operationId": "detach_volume",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "detach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/detach_volume_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Detach Volume",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud volume detach $VOLUME"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/{id}/actions/resize": {
"post": {
"description": "Changes the size of a Volume. Note that downsizing a Volume is not possible.\n",
"operationId": "resize_volume",
"parameters": [
{
"description": "ID of the Volume.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Volume.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/resize_volume_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "resize_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/resize_volume_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Resize Volume",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud volume resize --size 50 $VOLUME"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/actions": {
"get": {
"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",
"operationId": "list_volume_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/volumes/actions/{id}": {
"get": {
"description": "Returns a specific Action object.\n",
"operationId": "get_volume_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"volumes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/storage_box_types": {
"get": {
"description": "Returns a paginated list of Storage Box Types.\n",
"operationId": "list_storage_box_types",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_storage_box_types_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Storage Box Types",
"tags": [
"storage_box_types"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBoxTypes, err := client.StorageBoxType.All(ctx)\n}"
},
{
"label": "Python",
"lang": "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\nstorage_box_types = client.storage_box_types.get_all()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box-type list"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_box_types/{id}": {
"get": {
"description": "Returns a specific Storage Box Type.\n",
"operationId": "get_storage_box_type",
"parameters": [
{
"description": "ID of the Storage Box Type.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box Type.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_storage_box_type_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Storage Box Type",
"tags": [
"storage_box_types"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBoxType, _, err := client.StorageBoxType.GetByID(ctx, 123)\n}"
},
{
"label": "Python",
"lang": "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\nstorage_box_type = client.storage_box_types.get_by_id(123)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box-type describe $STORAGEBOXTYPE"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes": {
"get": {
"description": "Returns a paginated list of Storage Boxes.\n",
"operationId": "list_storage_boxes",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc",
"stats.size",
"stats.size:asc",
"stats.size:desc",
"stats.size_filesystem",
"stats.size_filesystem:asc",
"stats.size_filesystem:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_storage_boxes_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Storage Boxes",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBoxes, err := client.StorageBox.All(ctx)\n}"
},
{
"label": "Python",
"lang": "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\nstorage_boxes = client.storage_boxes.get_all()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box list"
}
]
},
"post": {
"description": "Creates a Storage Box.\n",
"operationId": "create_storage_box",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_storage_box_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "create",
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"storage_box": {
"access_settings": {
"reachable_externally": false,
"samba_enabled": false,
"ssh_enabled": false,
"webdav_enabled": false,
"zfs_enabled": false
},
"created": "2016-01-30T23:50:00Z",
"id": 42,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.476119,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "my-resource",
"protection": {
"delete": false
},
"server": null,
"snapshot_plan": null,
"stats": null,
"status": "initializing",
"storage_box_type": {
"automatic_snapshot_limit": 10,
"description": "BX20",
"id": 1,
"name": "bx20",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "0.0061",
"net": "0.0051"
},
"price_monthly": {
"gross": "3.8080",
"net": "3.2000"
},
"setup_fee": {
"gross": "0.0000",
"net": "0.0000"
}
}
],
"size": 1073741824,
"snapshot_limit": 10,
"subaccounts_limit": 100
},
"system": null
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_storage_box_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Storage Box",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.Create(ctx, hcloud.StorageBoxCreateOpts{\n\t\tName: \"string\",\n\t\tLocation: &hcloud.Location{Name: \"fsn1\"},\n\t\tStorageBoxType: &hcloud.StorageBoxType{\n\t\t\tName: \"bx11\",\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\tPassword: \"my-password\",\n\t\tAccessSettings: &hcloud.StorageBoxCreateOptsAccessSettings{\n\t\t\tReachableExternally: hcloud.Ptr(false),\n\t\t\tSambaEnabled: hcloud.Ptr(false),\n\t\t\tSSHEnabled: hcloud.Ptr(false),\n\t\t\tWebDAVEnabled: hcloud.Ptr(false),\n\t\t\tZFSEnabled: hcloud.Ptr(false),\n\t\t},\n\t\tSSHKeys: []*hcloud.SSHKey{\n\t\t\t{PublicKey: \"ssh-rsa AAAjjk76kgf...Xt\"},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tstorageBox := result.StorageBox\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.locations import Location\nfrom hcloud.ssh_keys import SSHKey\nfrom hcloud.storage_box_types import StorageBoxType\nfrom hcloud.storage_boxes import StorageBoxAccessSettings\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.create(\n name=\"string\",\n location=Location(name=\"fsn1\"),\n storage_box_type=StorageBoxType(name=\"bx11\"),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n password=\"my-password\",\n access_settings=StorageBoxAccessSettings(\n reachable_externally=False,\n samba_enabled=False,\n ssh_enabled=False,\n webdav_enabled=False,\n zfs_enabled=False,\n ),\n ssh_keys=[SSHKey(public_key=\"ssh-rsa AAAjjk76kgf...Xt\")],\n)\n\nresponse.action.wait_until_finished()\n\nstorage_box = response.storage_box"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box create \\\n --name \"string\" \\\n --location \"fsn1\" \\\n --type \"bx21\" \\\n --password \"string\" \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\" \\\n --ssh-key \"some-ssh-key\" \\\n --ssh-key \"ssh-rsa AAAjjk76kgf...Xt\" \\\n --reachable-externally \\\n --enable-samba=false \\\n --enable-ssh=true \\\n --enable-webdav \\\n --enable-zfs"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/actions": {
"get": {
"description": "Returns all Action objects.\n",
"operationId": "list_storage_box_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.Action.All(ctx, hcloud.ActionListOpts{})\n}"
},
{
"label": "Python",
"lang": "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.storage_boxes.actions.get_all()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/actions/{id}": {
"get": {
"description": "Returns a specific Action object.\n",
"operationId": "get_storage_box_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.Action.GetByID(ctx, 123)\n}"
},
{
"label": "Python",
"lang": "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.storage_boxes.actions.get_by_id(123)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}": {
"delete": {
"description": "Deletes a Storage Box.\n",
"operationId": "delete_storage_box",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "delete",
"error": null,
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/delete_storage_box_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Storage Box",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.Delete(ctx, &hcloud.StorageBox{ID: 123})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.delete(\n storage_box=StorageBox(id=123),\n)\n\nresponse.action.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box delete $STORAGEBOX"
}
]
},
"get": {
"description": "Returns a specific Storage Box.\n",
"operationId": "get_storage_box",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_storage_box_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Storage Box",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBox, _, err := client.StorageBox.GetByID(ctx, 123)\n}"
},
{
"label": "Python",
"lang": "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\nstorage_box = client.storage_boxes.get_by_id(123)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box describe $STORAGEBOX"
}
]
},
"put": {
"description": "Updates a Storage Box.\n",
"operationId": "replace_storage_box",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_storage_box_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_storage_box_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Storage Box",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBox, _, err := client.StorageBox.Update(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxUpdateOpts{\n\t\tName: \"string\",\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}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box = client.storage_boxes.update(\n storage_box=StorageBox(id=123),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"string\",\n)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box update $STORAGEBOX --name \"My Storage Box\"\nhcloud storage-box add-label --overwrite $STORAGEBOX \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud storage-box remove-label $STORAGEBOX \\\n \"environment\" \"example.com\" \"just-a-key\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions": {
"get": {
"description": "List all Actions related to a specific Storage Box.\n",
"operationId": "list_actions_for_storage_box",
"parameters": [
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Storage Box",
"tags": [
"storage_boxes"
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions/change_protection": {
"post": {
"description": "Changes the protection configuration of a Storage Box.\n",
"operationId": "change_protection",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_protection_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "change_protection",
"error": null,
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "success"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Protection",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.ChangeProtection(ctx, &hcloud.StorageBox{ID: 123},\n\t\thcloud.StorageBoxChangeProtectionOpts{Delete: hcloud.Ptr(true)})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.change_protection(\n storage_box=StorageBox(id=123),\n delete=True,\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box enable-protection $STORAGEBOX delete\nhcloud storage-box disable-protection $STORAGEBOX delete"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions/change_type": {
"post": {
"description": "Changes the type of a Storage Box.\n\nUpgrades or downgrades a Storage Box to another Storage Box Type.\n\nIt is not possible to downgrade to a Storage Box Type that offers less disk space\nthan you are currently using.\n",
"operationId": "change_type",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_type_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "change_type",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_type_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Type",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.ChangeType(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxChangeTypeOpts{\n\t\tStorageBoxType: &hcloud.StorageBoxType{Name: \"bx21\"},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_box_types import StorageBoxType\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.change_type(\n storage_box=StorageBox(id=123), storage_box_type=StorageBoxType(name=\"bx21\")\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box change-type $STORAGEBOX bx21"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions/disable_snapshot_plan": {
"post": {
"description": "Disables the active Snapshot Plan of a Storage Box.\n\nExisting Storage Box Snapshots created by the Snapshot\nPlan will not be delete, they must be removed manually.\n",
"operationId": "disable_snapshot_plan",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "disable_snapshot_plan",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/disable_snapshot_plan_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Disable Snapshot Plan",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.DisableSnapshotPlan(ctx, &hcloud.StorageBox{ID: 123})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.disable_snapshot_plan(\n storage_box=StorageBox(id=123),\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box disable-snapshot-plan $STORAGEBOX"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions/enable_snapshot_plan": {
"post": {
"description": "Enables a Snapshot Plan for a Storage Box.\n\nOnce enabled, a Snapshot Plan will create Snapshots at predefined intervals.\nThere can only ever be one Snapshot Plan. The existing Snapshot Plan will be deleted before a new one is set up.\n\nAutomatic Snapshots are retained until explicitly deleted by the user or the maximum snapshot count for the plan (\"max_snapshots\") is exceeded.\n\nYou can choose the specific time (UTC timezone), day of the week, and day of the month. The time-related options are cron like. Some typical use cases include:\n\n| Interval | Request body |\n| ------------------------------------------ | ------------------------------------------------------------- |\n| Every day at 3 o'clock | `{\"max_snapshots\":10,\"minute\":0,\"hour\":3}` |\n| Every Friday at 3 o'clock | `{\"max_snapshots\":10,\"minute\":0,\"hour\":3,\"day_of_week\": 5}` |\n| On the first of every month at half past 6 | `{\"max_snapshots\":10,\"minute\":30,\"hour\":6,\"day_of_month\": 1}` |\n",
"operationId": "enable_snapshot_plan",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/enable_snapshot_plan_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "enable_snapshot_plan",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/enable_snapshot_plan_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Enable Snapshot Plan",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "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.StorageBox.EnableSnapshotPlan(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxEnableSnapshotPlanOpts{\n\t\tMaxSnapshots: 10,\n\t\tMinute: 30,\n\t\tHour: 3,\n\t\tDayOfWeek: hcloud.Ptr(time.Sunday),\n\t\tDayOfMonth: nil,\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSnapshotPlan\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.enable_snapshot_plan(\n storage_box=StorageBox(id=123),\n snapshot_plan=StorageBoxSnapshotPlan(\n max_snapshots=10,\n minute=30,\n hour=3,\n day_of_week=7,\n day_of_month=None,\n ),\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box enable-snapshot-plan $STORAGEBOX \\\n --max-snapshots 10 \\\n --minute 30 \\\n --hour 3 \\\n --day-of-week 7"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions/reset_password": {
"post": {
"description": "Reset the password of a Storage Box.\n",
"operationId": "reset_storage_box_password",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/reset_password_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "reset_password",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/reset_password_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Reset Password",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.ResetPassword(ctx, &hcloud.StorageBox{ID: 123},\n\t\thcloud.StorageBoxResetPasswordOpts{Password: \"string\"})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.reset_password(\n storage_box=StorageBox(id=123), password=\"string\"\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box reset-password --password \"new-password\" $STORAGEBOX"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions/rollback_snapshot": {
"post": {
"description": "Rolls back a Storage Box to the given Storage Box Snapshot.\n\nThis will remove all newer Storage Box Snapshot and\nirrevocably delete all data that was since written to the Storage Box.\n",
"operationId": "rollback_snapshot",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rollback_snapshot_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "rollback_snapshot",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
},
{
"id": 42,
"type": "snapshot"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/rollback_snapshot_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Rollback Snapshot",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.RollbackSnapshot(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxRollbackSnapshotOpts{\n\t\tSnapshot: &hcloud.StorageBoxSnapshot{Name: \"my-snapshot\"},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSnapshot\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.rollback_snapshot(\n storage_box=StorageBox(id=123), snapshot=StorageBoxSnapshot(name=\"my-snapshot\")\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box rollback-snapshot --snapshot \"my-snapshot\" $STORAGEBOX"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions/update_access_settings": {
"post": {
"description": "Update access settings of a primary Storage Box account.\n\nThis endpoints supports partial updates. Omitted optional parameters do not result in any changes to the respective properties.\n",
"operationId": "update_storage_box_access_settings",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update_access_settings_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "update_access_settings",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/update_access_settings_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update Access Settings",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.UpdateAccessSettings(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxUpdateAccessSettingsOpts{\n\t\tReachableExternally: hcloud.Ptr(false),\n\t\tSambaEnabled: hcloud.Ptr(false),\n\t\tSSHEnabled: hcloud.Ptr(false),\n\t\tWebDAVEnabled: hcloud.Ptr(false),\n\t\tZFSEnabled: hcloud.Ptr(false),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxAccessSettings\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.update_access_settings(\n storage_box=StorageBox(id=123),\n access_settings=StorageBoxAccessSettings(\n reachable_externally=False,\n samba_enabled=False,\n ssh_enabled=False,\n webdav_enabled=False,\n zfs_enabled=False,\n ),\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box update-access-settings $STORAGEBOX \\\n --reachable-externally \\\n --enable-samba=false \\\n --enable-ssh=true \\\n --enable-webdav \\\n --enable-zfs"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action object for a Storage Box.\n",
"operationId": "get_action_for_storage_box",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Storage Box",
"tags": [
"storage_boxes"
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/folders": {
"get": {
"description": "Returns a list of (sub)folders in a Storage Box.\n\nThe folder location is specified by the `path` query parameter.\n",
"operationId": "list_folders_of_storage_box",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Relative path for which the listing is to be made.",
"in": "query",
"name": "path",
"required": false,
"schema": {
"default": ".",
"example": "./documents",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "A list of directories the Storage Box contains.",
"value": {
"folders": [
"offsite-backup",
"photos"
]
}
}
},
"schema": {
"$ref": "#/components/schemas/list_folders_of_storage_box_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List folders of a Storage Box",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.Folders(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxFoldersOpts{\n\t\tPath: \".\",\n\t})\n\n\tfolders := result.Folders\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.get_folders(\n storage_box=StorageBox(id=123),\n)\n\nfolders = response.folders"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box folders --path \"subfolder\" $STORAGEBOX"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/snapshots": {
"get": {
"description": "Returns a list of Storage Box Snapshot.\n\nBoth snapshots created manually and by the snapshot plan are returned.\n",
"operationId": "list_snapshots",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter wether a Storage Box Snapshot is automatic.\n",
"in": "query",
"name": "is_automatic",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"snapshots": [
{
"created": "2025-02-12T11:35:19.000Z",
"description": "my-description",
"id": 1,
"is_automatic": false,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": null
},
"name": "2025-02-12T11-35-19",
"stats": {
"size": 2097152,
"size_filesystem": 1048576
},
"storage_box": 42
},
{
"created": "2025-02-22:00:02.000Z",
"description": "",
"id": 2,
"is_automatic": true,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": null
},
"name": "snapshot-daily--2025-02-12T22-00-02",
"stats": {
"size": 2097152,
"size_filesystem": 1048576
},
"storage_box": 42
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/list_snapshots_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Snapshots",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsnapshots, err := client.StorageBox.AllSnapshots(ctx, &hcloud.StorageBox{ID: 123})\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nsnapshots = client.storage_boxes.get_snapshot_all(storage_box=StorageBox(id=123))"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box snapshot list $STORAGEBOX"
}
]
},
"post": {
"description": "Creates a Storage Box Snapshot.\n",
"operationId": "create_snapshot",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_snapshot_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "create_snapshot",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
},
{
"id": 43,
"type": "storage_box_snapshot"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"snapshot": {
"id": 42,
"storage_box": 43
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_snapshot_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Snapshot",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.CreateSnapshot(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxSnapshotCreateOpts{\n\t\tDescription: \"snapshot-0001\",\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\tsnapshot := result.Snapshot\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.create_snapshot(\n storage_box=StorageBox(id=123),\n description=\"snapshot-0001\",\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n)\n\nresponse.action.wait_until_finished()\n\nsnapshot = response.snapshot"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box snapshot create $STORAGEBOX \\\n --description \"snapshot-0001\" \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/snapshots/{snapshot_id}": {
"delete": {
"description": "Deletes a Storage Box Snapshot.\n",
"operationId": "delete_snapshot",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Snapshot.",
"in": "path",
"name": "snapshot_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Snapshot.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "delete_snapshot",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
},
{
"id": 42,
"type": "storage_box_snapshot"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/delete_snapshot_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Snapshot",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.DeleteSnapshot(ctx, &hcloud.StorageBoxSnapshot{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSnapshot\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.delete_snapshot(\n snapshot=StorageBoxSnapshot(\n storage_box=StorageBox(id=123),\n id=456,\n )\n)\n\nresponse.action.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box snapshot delete $STORAGEBOX $SNAPSHOT"
}
]
},
"get": {
"description": "Returns a specific Storage Box Snapshot.\n",
"operationId": "get_snapshot",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Snapshot.",
"in": "path",
"name": "snapshot_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Snapshot.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_snapshot_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Snapshot",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccount, _, err := client.StorageBox.GetSnapshot(ctx, &hcloud.StorageBox{ID: 123}, \"my-snapshot\")\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nsnapshot = client.storage_boxes.get_snapshot_by_id(\n storage_box=StorageBox(id=123),\n id=456,\n)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box snapshot describe $STORAGEBOX $SNAPSHOT"
}
]
},
"put": {
"description": "Updates a Storage Box Snapshot.\n",
"operationId": "replace_snapshot",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Snapshot.",
"in": "path",
"name": "snapshot_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Snapshot.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_snapshot_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_snapshot_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Snapshot",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccount, _, err := client.StorageBox.UpdateSnapshot(ctx, &hcloud.StorageBoxSnapshot{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSnapshotUpdateOpts{\n\t\tDescription: hcloud.Ptr(\"snapshot-0001\"),\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}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSnapshot\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box = client.storage_boxes.update_snapshot(\n snapshot=StorageBoxSnapshot(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n description=\"snapshot-0001\",\n)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box snapshot update $STORAGEBOX $SNAPSHOT --name \"My Storage Box\"\nhcloud storage-box snapshot add-label --overwrite $STORAGEBOX $SNAPSHOT \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud storage-box snapshot remove-label $STORAGEBOX $SNAPSHOT \\\n \"environment\" \"example.com\" \"just-a-key\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/subaccounts": {
"get": {
"description": "Returns a list of Storage Box Subaccount.\n",
"operationId": "list_subaccounts",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter Storage Box Subaccounts by username. The response will only contain the resources\nmatching exactly the specified username.\n",
"in": "query",
"name": "username",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"subaccounts": [
{
"access_settings": {
"reachable_externally": true,
"readonly": false,
"samba_enabled": false,
"ssh_enabled": true,
"webdav_enabled": false
},
"created": "2025-02-22:00:02.000Z",
"description": "host01 backup",
"home_directory": "my_backups/host01.my.company",
"id": 42,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": null
},
"name": "my-name",
"server": "u1337-sub1.your-storagebox.de",
"storage_box": 42,
"username": "u1337-sub1"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/list_subaccounts_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Subaccounts",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccounts, err := client.StorageBox.AllSubaccounts(ctx, &hcloud.StorageBox{ID: 123})\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nsubaccounts = client.storage_boxes.get_subaccount_all(storage_box=StorageBox(id=123))"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box subaccount list $STORAGEBOX"
}
]
},
"post": {
"description": "Creates a Storage Box Subaccount.\n\nA Storage Box Subaccount will use a separate home directory.\n",
"operationId": "create_subaccount",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_subaccount_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "create_subaccount",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
},
{
"id": 43,
"type": "storage_box_subaccount"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"subaccount": {
"id": 42,
"storage_box": 43
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_subaccount_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Subaccount",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.CreateSubaccount(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxSubaccountCreateOpts{\n\t\tHomeDirectory: \"my-backup/server01\",\n\t\tPassword: \"string\",\n\t\tAccessSettings: &hcloud.StorageBoxSubaccountCreateOptsAccessSettings{\n\t\t\tReachableExternally: hcloud.Ptr(false),\n\t\t\tReadonly: hcloud.Ptr(false),\n\t\t\tSambaEnabled: hcloud.Ptr(false),\n\t\t\tSSHEnabled: hcloud.Ptr(false),\n\t\t\tWebDAVEnabled: hcloud.Ptr(false),\n\t\t},\n\t\tDescription: \"my-backup-server01\",\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\tsubaccount := result.Subaccount\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccountAccessSettings\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.create_subaccount(\n storage_box=StorageBox(id=123),\n home_directory=\"my-backup/server01\",\n password=\"string\",\n access_settings=StorageBoxSubaccountAccessSettings(\n reachable_externally=False,\n readonly=False,\n samba_enabled=False,\n ssh_enabled=False,\n webdav_enabled=False,\n ),\n description=\"my-backup-server01\",\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n)\n\nresponse.action.wait_until_finished()\n\nsubaccount = response.subaccount"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box subaccount create $STORAGEBOX \\\n --home-directory \"my-backup/server01\" \\\n --password \"string\" \\\n --reachable-externally \\\n --enable-samba=true \\\n --enable-ssh=false \\\n --enable-webdav=false \\\n --readonly \\\n --description \"my-backup-server01\" \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/subaccounts/{subaccount_id}": {
"delete": {
"description": "Deletes a Storage Box Subaccount.\n",
"operationId": "delete_subaccount",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Subaccount.",
"in": "path",
"name": "subaccount_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Subaccount.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "delete_subaccount",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
},
{
"id": 42,
"type": "storage_box_subaccount"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/delete_subaccount_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Subaccount",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.DeleteSubaccount(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccount\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.delete_subaccount(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n )\n)\n\nresponse.action.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box subaccount delete $SUBACCOUNT"
}
]
},
"get": {
"description": "Returns a specific Storage Box Subaccount.\n",
"operationId": "get_subaccount",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Subaccount.",
"in": "path",
"name": "subaccount_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Subaccount.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_subaccount_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Subaccount",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccount, _, err := client.StorageBox.GetSubaccount(ctx, &hcloud.StorageBox{ID: 123}, \"my-subaccount\")\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nsubaccount = client.storage_boxes.get_subaccount_by_id(\n storage_box=StorageBox(id=123),\n id=456,\n)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box subaccount describe $SUBACCOUNT"
}
]
},
"put": {
"description": "Updates a Storage Box Subaccount.\n",
"operationId": "replace_subaccount",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Subaccount.",
"in": "path",
"name": "subaccount_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Subaccount.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_subaccount_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_subaccount_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Subaccount",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccount, _, err := client.StorageBox.UpdateSubaccount(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSubaccountUpdateOpts{\n\t\tDescription: hcloud.Ptr(\"my-backup-server01\"),\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}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccount\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box = client.storage_boxes.update_subaccount(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n description=\"my-backup-server01\",\n)"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box subaccount update $STORAGEBOX $SUBACCOUNT --description \"my-backup-server01\"\nhcloud storage-box subaccount add-label --overwrite $STORAGEBOX $SUBACCOUNT \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud storage-box subaccount remove-label $STORAGEBOX $SUBACCOUNT \\\n \"environment\" \"example.com\" \"just-a-key\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory": {
"post": {
"description": "Change the home directory of a Storage Box Subaccount.\n",
"operationId": "change_home_directory",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Subaccount.",
"in": "path",
"name": "subaccount_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Subaccount.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_home_directory_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "change_home_directory",
"error": null,
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
},
{
"id": 42,
"type": "storage_box_subaccount"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_home_directory_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change Home Directory",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.ChangeSubaccountHomeDirectory(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSubaccountChangeHomeDirectoryOpts{\n\t\tHomeDirectory: \"my-backup/server01\",\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccount\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.change_subaccount_home_directory(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n home_directory=\"my-backup/server01\",\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box subaccount change-home-directory --home-directory \"my-backup/server01\" $STORAGEBOX $SUBACCOUNT"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/reset_subaccount_password": {
"post": {
"description": "Reset the password of a Storage Box Subaccount.\n",
"operationId": "reset_storage_box_subaccount_password",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Subaccount.",
"in": "path",
"name": "subaccount_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Subaccount.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/reset_password_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "reset_subaccount_password",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
},
{
"id": 42,
"type": "storage_box_subaccount"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/reset_password_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Reset Password",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.ResetSubaccountPassword(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSubaccountResetPasswordOpts{\n\t\tPassword: \"string\",\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccount\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.reset_subaccount_password(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n password=\"string\",\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box subaccount reset-password --password \"string\" $STORAGEBOX $SUBACCOUNT"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/update_access_settings": {
"post": {
"description": "Updates the access settings of a Storage Box Subaccount.\n\nThis endpoints supports partial updates. Omitted optional parameters do not result in any changes to the respective properties.\n",
"operationId": "update_storage_box_subaccount_access_settings",
"parameters": [
{
"description": "ID of the Storage Box.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Storage Box.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
},
{
"description": "ID of the Storage Box Subaccount.",
"in": "path",
"name": "subaccount_id",
"required": true,
"schema": {
"description": "ID of the Storage Box Subaccount.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update_access_settings_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"description": "Action successfully created.",
"value": {
"action": {
"command": "update_access_settings",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "storage_box"
},
{
"id": 42,
"type": "storage_box_subaccount"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/update_access_settings_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update Access Settings",
"tags": [
"storage_boxes"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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.StorageBox.UpdateSubaccountAccessSettings(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSubaccountUpdateAccessSettingsOpts{\n\t\tReachableExternally: hcloud.Ptr(false),\n\t\tReadonly: hcloud.Ptr(false),\n\t\tSambaEnabled: hcloud.Ptr(false),\n\t\tSSHEnabled: hcloud.Ptr(false),\n\t\tWebDAVEnabled: hcloud.Ptr(false),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}"
},
{
"label": "Python",
"lang": "Python",
"source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import (\n StorageBox,\n StorageBoxSubaccount,\n StorageBoxSubaccountAccessSettings,\n)\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.update_subaccount_access_settings(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n access_settings=StorageBoxSubaccountAccessSettings(\n reachable_externally=False,\n readonly=False,\n samba_enabled=False,\n ssh_enabled=False,\n webdav_enabled=False,\n ),\n)\n\naction.wait_until_finished()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud storage-box subaccount update-access-settings $STORAGEBOX $SUBACCOUNT \\\n --reachable-externally \\\n --enable-samba=true \\\n --enable-ssh=false \\\n --enable-webdav=false \\\n --readonly"
}
]
},
"servers": [
{
"url": "https://api.hetzner.com/v1"
}
]
},
"/zones": {
"get": {
"description": "Returns all Zones.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_zones",
"parameters": [
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by their mode. The response will only contain the resources\nmatching exactly the specified mode.\n",
"in": "query",
"name": "mode",
"required": false,
"schema": {
"description": "Mode of the Zone.\n\nFor more information, see Zone Modes.\n",
"enum": [
"primary",
"secondary"
],
"example": "primary",
"type": "string"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_zones_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Zones",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone list"
}
]
},
"post": {
"description": "Creates a Zone.\n\nA default `SOA` and three `NS` resource records with the assigned Hetzner\nnameservers are created automatically.\n",
"operationId": "create_zone",
"requestBody": {
"content": {
"application/json": {
"examples": {
"primary": {
"value": {
"labels": {
"key": "value"
},
"mode": "primary",
"name": "example.com",
"rrsets": [
{
"name": "www",
"records": [
{
"comment": "My web server at Hetzner Cloud.",
"value": "198.51.100.1"
}
],
"type": "A"
}
],
"ttl": 10800
}
},
"primary from zone file": {
"value": {
"labels": {
"key": "value"
},
"mode": "primary",
"name": "example.com",
"ttl": 10800,
"zonefile": "$ORIGIN\texample.com.\n$TTL\t10800\n\n@\tIN\tA\t198.51.100.1 ; My web server at Hetzner Cloud.\n"
}
},
"secondary": {
"value": {
"labels": {
"key": "value"
},
"mode": "secondary",
"name": "example.com",
"primary_nameservers": [
{
"address": "198.51.100.1",
"port": 53
},
{
"address": "203.0.113.1",
"port": 53
}
],
"ttl": 10800
}
}
},
"schema": {
"$ref": "#/components/schemas/create_zone_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "create_zone",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
},
"zone": {
"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"
},
"created": "2016-01-30T23:50:00Z",
"id": 42,
"labels": {
"key": "value"
},
"mode": "primary",
"name": "example.com",
"protection": {
"delete": false
},
"record_count": 4,
"registrar": "hetzner",
"status": "ok",
"ttl": 3600
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_zone_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create a Zone",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go (primary from zone file)",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Go (primary)",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Go (secondary)",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python (primary from zone file)",
"lang": "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.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"
},
{
"label": "Python (primary)",
"lang": "Python",
"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"
},
{
"label": "Python (secondary)",
"lang": "Python",
"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"
},
{
"label": "CLI (primary from zone file)",
"lang": "Shell",
"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')"
},
{
"label": "CLI (primary)",
"lang": "Shell",
"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\""
},
{
"label": "CLI (secondary)",
"lang": "Shell",
"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 ]')"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/actions": {
"get": {
"description": "Returns all Zone Actions.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_zone_actions",
"parameters": [
{
"description": "Filter the actions by ID. Can be used multiple times. The response will only contain\nactions matching the specified IDs.\n",
"in": "query",
"name": "id",
"required": false,
"schema": {
"items": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
},
"type": "array"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/actions/{id}": {
"get": {
"description": "Returns a specific Action.\n",
"operationId": "get_zone_action",
"parameters": [
{
"description": "ID of the Action.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}": {
"delete": {
"description": "Deletes a Zone.\n",
"operationId": "delete_zone",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "delete_zone",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:50:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/delete_zone_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete a Zone",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone delete $ZONE"
}
]
},
"get": {
"description": "Returns a single Zone.\n",
"operationId": "get_zone",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_zone_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get a Zone",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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\")"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone describe $ZONE"
}
]
},
"put": {
"description": "Updates a Zone.\n\nTo modify resource record sets (RRSets), use the RRSet Actions\nendpoints.\n",
"operationId": "replace_zone",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_zone_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"zone": {
"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"
},
"created": "2016-01-30T23:50:00Z",
"id": 42,
"labels": {
"key": "value"
},
"mode": "primary",
"name": "example.com",
"protection": {
"delete": false
},
"record_count": 4,
"registrar": "hetzner",
"status": "ok",
"ttl": 3600
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_zone_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update a Zone",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/actions": {
"get": {
"description": "Returns all Actions for a Zone.\n\nUse the provided URI parameters to modify the result.\n",
"operationId": "list_actions_for_zone",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"description": "Sort actions by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"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"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter the actions by status. Can be used multiple times. The response will only\ncontain actions matching the specified statuses.\n",
"in": "query",
"name": "status",
"required": false,
"schema": {
"items": {
"description": "Status of the Action.",
"enum": [
"running",
"success",
"error"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_actions_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List Actions for a Zone",
"tags": [
"zones"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/actions/change_primary_nameservers": {
"post": {
"description": "Overwrites the primary nameservers of a Zone.\n\nOnly applicable for 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",
"operationId": "change_zones_primary_nameservers",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_zones_primary_nameservers_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_primary_nameservers",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_zones_primary_nameservers_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change a Zone's Primary Nameservers",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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]')"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/actions/change_protection": {
"post": {
"description": "Changes the protection configuration of a Zone.\n",
"operationId": "change_zones_protection",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_zones_protection_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_protection",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_zones_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change a Zone's Protection",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone enable-protection $ZONE delete\nhcloud zone disable-protection $ZONE delete"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/actions/change_ttl": {
"post": {
"description": "Changes the default Time To Live (TTL) of a Zone.\n\nThis TTL is used for RRSets that do not explicitly define a TTL.\n\nOnly applicable for 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",
"operationId": "change_zones_default_ttl",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_zones_default_ttl_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_ttl",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 1,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_zones_default_ttl_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change a Zone's Default TTL",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone change-ttl $ZONE --ttl 10800"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/actions/import_zonefile": {
"post": {
"description": "Imports a zone file, replacing all resource record sets (RRSets).\n\nThe import will fail if existing RRSet are `change` protected.\n\nSee Zone file import for more details.\nOnly applicable for 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",
"operationId": "import_zone_file",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/import_zone_file_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "import_zonefile",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/import_zone_file_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Import a Zone file",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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')"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/actions/{action_id}": {
"get": {
"description": "Returns a specific Action for a Zone.\n",
"operationId": "get_action_for_zone",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"description": "ID of the Action.",
"in": "path",
"name": "action_id",
"required": true,
"schema": {
"description": "ID of the Action.",
"example": 42,
"format": "int64",
"maximum": 9007199254740991,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "import_zonefile",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/get_action_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an Action for a Zone",
"tags": [
"zones"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/rrsets": {
"get": {
"description": "Returns all RRSets in the Zone.\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 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",
"operationId": "list_rrsets",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"description": "Filter resources by their name. The response will only contain the resources\nmatching exactly the specified name.\n",
"in": "query",
"name": "name",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Filter resources by their type. Can be used multiple times. The response will only\ncontain resources matching the specified types.\n",
"in": "query",
"name": "type",
"required": false,
"schema": {
"items": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
},
"type": "array"
}
},
{
"description": "Filter resources by labels. The response will only contain resources matching the\nlabel selector. For more information, see \"Label Selector\".\n",
"in": "query",
"name": "label_selector",
"required": false,
"schema": {
"type": "string"
}
},
{
"description": "Sort resources by field and direction. Can be used multiple times. For more\ninformation, see \"Sorting\".\n",
"in": "query",
"name": "sort",
"required": false,
"schema": {
"items": {
"enum": [
"id",
"id:asc",
"id:desc",
"name",
"name:asc",
"name:desc",
"created",
"created:asc",
"created:desc"
],
"type": "string"
},
"type": "array"
}
},
{
"description": "Page number to return. For more information, see \"Pagination\".",
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"example": 1,
"format": "int64",
"type": "integer"
}
},
{
"description": "Maximum number of entries returned per page. For more information, see \"Pagination\".",
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 25,
"example": 25,
"format": "int64",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/list_rrsets_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "List RRSets",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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\"))"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone rrset list $ZONE"
}
]
},
"post": {
"description": "Create an RRSet in the Zone.\n\nOnly applicable for 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",
"operationId": "create_rrset",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/resource_record_set_to_create"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "create_rrset",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
},
"rrset": {
"id": "www/A",
"labels": {
"key": "value"
},
"name": "www",
"protection": {
"change": false
},
"records": [
{
"comment": "My web server at Hetzner Cloud.",
"value": "198.51.100.1"
}
],
"ttl": 3600,
"type": "A",
"zone": 42
}
}
}
},
"schema": {
"$ref": "#/components/schemas/create_rrset_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Create an RRSet",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"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=\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}": {
"delete": {
"description": "Deletes an RRSet from the Zone.\n\nOnly applicable for 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",
"operationId": "delete_rrset",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "delete_rrset",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/delete_rrset_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Delete an RRSet",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone rrset delete $ZONE $RR_NAME $RR_TYPE"
}
]
},
"get": {
"description": "Returns a single RRSet from the Zone.\n\nOnly applicable for 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",
"operationId": "get_rrset",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/get_rrset_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Get an RRSet",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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\")"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone rrset describe $ZONE $RR_NAME $RR_TYPE"
}
]
},
"put": {
"description": "Updates an RRSet in the Zone.\n\nOnly applicable for 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",
"operationId": "replace_rrset",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/replace_rrset_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"rrset": {
"id": "www/A",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"name": "www",
"protection": {
"change": false
},
"records": [
{
"comment": "My web server at Hetzner Cloud.",
"value": "198.51.100.1"
}
],
"ttl": null,
"type": "A",
"zone": 42
}
}
}
},
"schema": {
"$ref": "#/components/schemas/replace_rrset_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update an RRSet",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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)"
},
{
"label": "CLI",
"lang": "Shell",
"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\""
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/add_records": {
"post": {
"description": "Adds resource records (RRs) to an RRSet in the Zone.\n\nFor convenience, the RRSet will be automatically created if it doesn't exist. Otherwise, the new\nrecords are appended to the existing RRSet.\n\nOnly applicable for 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",
"operationId": "add_records_to_rrset",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/add_records_to_rrset_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "add_rrset_records",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/add_records_to_rrset_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Add Records to an RRSet",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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]')"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_protection": {
"post": {
"description": "Changes the protection of an RRSet in the Zone.\n\nOnly applicable for 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",
"operationId": "change_rrsets_protection",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_rrsets_protection_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_rrset_protection",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_rrsets_protection_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change an RRSet's Protection",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone rrset enable-protection $ZONE $RR_NAME $RR_TYPE change\nhcloud zone rrset disable-protection $ZONE $RR_NAME $RR_TYPE change"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/change_ttl": {
"post": {
"description": "Changes the Time To Live (TTL) of an RRSet in the Zone.\n\nOnly applicable for 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",
"operationId": "change_rrsets_ttl",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/change_rrsets_ttl_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "change_rrset_ttl",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/change_rrsets_ttl_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Change an RRSet's TTL",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone rrset change-ttl $ZONE $RR_NAME $RR_TYPE --ttl 3600"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/remove_records": {
"post": {
"description": "Removes resource records (RRs) from an existing RRSet in the Zone.\n\nFor convenience, the RRSet will be automatically deleted if it doesn't contain any RRs afterwards.\n\nOnly applicable for 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",
"operationId": "remove_records_from_rrset",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/remove_records_from_rrset_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "remove_rrset_records",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/remove_records_from_rrset_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Remove Records from an RRSet",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone rrset remove-records $ZONE $RR_NAME $RR_TYPE --record 198.51.100.1"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/set_records": {
"post": {
"description": "Overwrites the resource records (RRs) of an existing RRSet in the Zone.\n\nOnly applicable for 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",
"operationId": "set_records_of_rrset",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/set_records_of_rrset_request"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "set_rrset_records",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/set_records_of_rrset_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Set Records of an RRSet",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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()"
},
{
"label": "CLI",
"lang": "Shell",
"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]')"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/rrsets/{rr_name}/{rr_type}/actions/update_records": {
"post": {
"description": "Updates resource records' (RRs) comments of an existing RRSet in the Zone.\n\nOnly applicable for 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",
"operationId": "update_records_of_rrset",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
},
{
"in": "path",
"name": "rr_name",
"required": true,
"schema": {
"description": "Name of the RRSet.\n\nThe name must be in lower case, and must not end with a dot or the Zone\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 apex, use `@`.\n",
"example": "www",
"type": "string"
}
},
{
"in": "path",
"name": "rr_type",
"required": true,
"schema": {
"description": "Type of the RRSet.\n",
"enum": [
"A",
"AAAA",
"CAA",
"CNAME",
"DS",
"HINFO",
"HTTPS",
"MX",
"NS",
"PTR",
"RP",
"SOA",
"SRV",
"SVCB",
"TLSA",
"TXT"
],
"example": "A",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update_records_of_rrset_request"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"default": {
"value": {
"action": {
"command": "update_rrset_records",
"error": null,
"finished": null,
"id": 1,
"progress": 50,
"resources": [
{
"id": 42,
"type": "zone"
}
],
"started": "2016-01-30T23:55:00Z",
"status": "running"
}
}
}
},
"schema": {
"$ref": "#/components/schemas/update_records_of_rrset_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Update Records of an RRSet",
"tags": [
"zones"
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
},
"/zones/{id_or_name}/zonefile": {
"get": {
"description": "Returns a generated Zone 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 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",
"operationId": "export_zone_file",
"parameters": [
{
"description": "ID or Name of the Zone.",
"in": "path",
"name": "id_or_name",
"required": true,
"schema": {
"description": "ID or Name of the Zone.",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/export_zone_file_response"
}
}
},
"description": "Request succeeded."
},
"4xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a user error."
},
"5xx": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_response"
}
}
},
"description": "Request failed with a server error."
}
},
"summary": "Export a Zone file",
"tags": [
"zones"
],
"x-codeSamples": [
{
"label": "Go",
"lang": "Go",
"source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\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}"
},
{
"label": "Python",
"lang": "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"
},
{
"label": "CLI",
"lang": "Shell",
"source": "hcloud zone export-zonefile $ZONE"
}
]
},
"servers": [
{
"url": "https://api.hetzner.cloud/v1"
}
]
}
},
"security": [
{
"APIToken": []
}
]
}