Cloud API

Hetzner Cloud API

This is the official API documentation for the Public Hetzner Cloud.

Introduction

The Hetzner Cloud API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.

As an alternative to working directly with our API you may also consider to use:

Also you can find a list of libraries, tools, and integrations on GitHub.

If you are developing integrations based on our API and your product is Open Source you may be eligible for a free one time €50 (excl. VAT) credit on your account. Please contact us via the the support page on your Cloud Console and let us know the following:

  • The type of integration you would like to develop
  • Link to the GitHub repo you will use for the Project
  • Link to some other Open Source work you have already done (if you have done so)

Getting Started

To get started using the API you first need an API token. Sign in into the Hetzner Cloud Console choose a Project, go to Access → Tokens, and create a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is jEheVytlAoFl7F8MqUQ7jAo2hOXASztX.

You’re now ready to do your first request against the API. To get a list of all Servers in your Project, issue the example request on the right side using curl.

Make sure to replace the token in the example command with the token you have just created. Since your Project probably does not contain any Servers yet, the example response will look like the response on the right side. We will almost always provide a resource root like servers inside the example response. A response can also contain a meta object with information like Pagination.

Example Request

curl -H "Authorization: Bearer jEheVytlAoFl7F8MqUQ7jAo2hOXASztX" \
    https://api.hetzner.cloud/v1/servers

Example Response

{
    "servers": [],
    "meta": {
        "pagination": {
            "page": 1,
            "per_page": 25,
            "previous_page": null,
            "next_page": null,
            "last_page": 1,
            "total_entries": 0
        }
    }
}

Authentication

All requests to the Hetzner Cloud API must be authenticated via a API token. Include your secret API token in every request you send to the API with the Authorization HTTP header.

Authorization: Bearer

To create a new API token for your Project, switch into the Hetzner Cloud Console choose a Project, go to Access → Security, and create a new token.

Example Authorization header

Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj

Errors

Errors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code.

The error response contains the following keys:

Keys Meaning
code Short string indicating the type of error (machine-parsable)
message Textual description on what has gone wrong
details An object providing for details on the error (schema depends on code)

Error Codes

Code Description
forbidden Insufficient permissions for this request
invalid_input Error while parsing or processing the input
json_error Invalid JSON input in your request
locked The item you are trying to access is locked (there is already an Action running)
not_found Entity not found
rate_limit_exceeded Error when sending too many requests
resource_limit_exceeded Error when exceeding the maximum quantity of a resource for an account
resource_unavailable The requested resource is currently unavailable
service_error Error within a service
uniqueness_error One or more of the objects fields must be unique
protected The Action you are trying to start is protected for this resource
maintenance Cannot perform operation due to maintenance
conflict The resource has changed during the request, please retry
unsupported_error The corresponding resource does not support the Action

Example response

{
  "error": {
    "code": "invalid_input",
    "message": "invalid input in field 'broken_field': is too long",
    "details": {
      "fields": [
        {
          "name": "broken_field",
          "messages": ["is too long"]
        }
      ]
    }
  }
}

invalid_input

{
  "error": {
    "code": "invalid_input",
    "message": "invalid input in field 'broken_field': is too long",
    "details": {
      "fields": [
        {
          "name": "broken_field",
          "messages": ["is too long"]
        }
      ]
    }
  }
}

uniqueness_error

{
  "error": {
    "code": "uniqueness_error",
    "message": "SSH key with the same fingerprint already exists",
    "details": {
      "fields": [
        {
          "name": "public_key"
        }
      ]
    }
  }
}

resource_limit_exceeded

{
  "error": {
    "code": "resource_limit_exceeded",
    "message": "project limit exceeded",
    "details": {
      "limits": [
        {
          "name": "project_limit"
        }
      ]
    }
  }
}

Labels

Labels are key/value pairs that can be attached to Servers, Floating IPs, Volumes, SSH keys and Images.

Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

Valid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.

The hetzner.cloud/ prefix is reserved and cannot be used.

Example Labels

{
  "labels": {
    "environment":"development",
    "service":"backend",
    "example.com/my":"label",
    "just-a-key":""
  }
}

Label Selector

For resources with labels, you can filter resources by their labels using the label selector query language.

Expression Meaning
k==v / k=v Value of key k does equal value v
k!=v Value of key k does not equal value v
k Key k is present
!k Key k is not present
k in (v1,v2,v3) Value of key k is v1, v2, or v3
k notin (v1,v2,v3) Value of key k is neither v1, nor v2, nor v3
k1==v,!k2 Value of key k1 is v and key k2 is not present

Examples

  • Returns all resources that have a env=production label and that don't have a type=database label:

    env=production,type!=database

  • Returns all resources that have a env=testing or env=staging label:

    env in (testing,staging)

  • Returns all resources that don't have a type label:

    !type

Pagination

Responses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:

  • A page parameter specifies the page to fetch. The number of the first page is 1.
  • A per_page parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation.

Responses contain a Link header with pagination information.

Additionally, if the response body is JSON and the root object is an object, that object has a pagination object inside the meta object with pagination information:

The keys previous_page, next_page, last_page, and total_entries may be null when on the first page, last page, or when the total number of entries is unknown.

Line breaks have been added for display purposes only and responses may only contain some of the above rel values.

Example Pagination

{
    "servers": [...],
    "meta": {
        "pagination": {
            "page": 2,
            "per_page": 25,
            "previous_page": 1,
            "next_page": 3,
            "last_page": 4,
            "total_entries": 100
        }
    }
}

Example Pagination Link header

Link: <https://api.hetzner.cloud/actions?page=2&per_page=5>; rel="prev",
      <https://api.hetzner.cloud/actions?page=4&per_page=5>; rel="next",
      <https://api.hetzner.cloud/actions?page=6&per_page=5>; rel="last"

Rate Limiting

All requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a 429 Too Many Requests error. Burst requests are allowed. Responses contain serveral headers which provide information about your current rate limit status.

  • The RateLimit-Limit header contains the total number of requests you can perform per hour.
  • The RateLimit-Remaining header contains the number of requests remaining in the current rate limit time frame.
  • The RateLimit-Reset header contains a UNIX timestamp of the point in time when your rate limit will have recovered and you will have the full number of requests available again.

The default limit is 3600 requests per hour and per Project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second.

Server Metadata

Your Server can discover metadata about itself by doing a HTTP request to specific URLs. The following data is available:

Data Format Contents
hostname text Name of the Server as set in the api
instance-id number ID of the server
public-ipv4 text Primary public IPv4 address
private-networks yaml Details about the private networks the Server is attached to

Example: Hostname

$ curl http://169.254.169.254/hetzner/v1/metadata/hostname
my-server

Example: Instance ID

$ curl http://169.254.169.254/hetzner/v1/metadata/instance-id
42

Example: Public IPv4

$ curl http://169.254.169.254/hetzner/v1/metadata/public-ipv4
1.2.3.4

Example: Private Networks

$ curl http://169.254.169.254/hetzner/v1/metadata/private-networks

- ip: 10.0.0.2
  alias_ips: [10.0.0.3, 10.0.0.4]
  interface_num: 1
  mac_address: 86:00:00:2a:7d:e0
  network_id: 1234
  network_name: nw-test1
  network: 10.0.0.0/8
  subnet: 10.0.0.0/24
  gateway: 10.0.0.1
- ip: 192.168.0.2
  alias_ips: []
  interface_num: 2
  mac_address: 86:00:00:2a:7d:e1
  network_id: 4321
  network_name: nw-test2
  network: 192.168.0.0/16
  subnet: 192.168.0.0/24
  gateway: 192.168.0.1

Sorting

Some responses which return multiple items support sorting. If they do support sorting the documentation states which fields can be used for sorting. You specify sorting with the sort query string parameter. You can sort by multiple fields. You can set the sort direction by appending :asc or :desc to the field name. By default, ascending sorting is used.

Example: Sorting

https://api.hetzner.cloud/actions?sort=status
https://api.hetzner.cloud/actions?sort=status:asc
https://api.hetzner.cloud/actions?sort=status:desc
https://api.hetzner.cloud/actions?sort=status:asc&sort=command:desc

Changelog

You can find our changelog on our Developer Hub.

Actions

Actions show the results and progress of asynchronous requests to the API.

List all Actions

Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status parameter.

HTTP Request

GET /actions

Query Parameters

Response

The actions key contains a list of Actions

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 13,
      "command": "start_server",
      "status": "success",
      "progress": 100,
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:56:00+00:00",
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}

Get an Action

Returns a specific Action object.

HTTP Request

GET /actions/{id}

Path Parameters

Response

The action key in the reply has this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/actions/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 13,
    "command": "start_server",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Certificates

TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic.

Get all Certificates

Returns all Certificate objects.

HTTP Request

GET /certificates

Query Parameters

Response

The certificates key in the reply contains an array of Certificate objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/certificates'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "certificates": [
    {
      "id": 897,
      "name": "my website cert",
      "labels": {},
      "certificate": "-----BEGIN CERTIFICATE-----\n...",
      "created": "2019-01-08T12:10:00+00:00",
      "not_valid_before": "2019-01-08T10:00:00+00:00",
      "not_valid_after": "2019-07-08T09:59:59+00:00",
      "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",
      "used_by": [
        {
          "id": 42,
          "type": "server"
        }
      ]
    }
  ]
}

Create a Certificate

Creates a new Certificate.

HTTP Request

POST /certificates

Request

Response

The certificate key contains the Certificate that was just created

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"my website cert","labels":{},"certificate":"-----BEGIN CERTIFICATE-----\n...","private_key":"-----BEGIN PRIVATE KEY-----\n..."}' \
	'https://api.hetzner.cloud/v1/certificates'

Request

{
  "name": "my website cert",
  "labels": {},
  "certificate": "-----BEGIN CERTIFICATE-----\n...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n..."
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "certificate": {
    "id": 897,
    "name": "my website cert",
    "labels": {},
    "certificate": "-----BEGIN CERTIFICATE-----\n...",
    "created": "2019-01-08T12:10:00+00:00",
    "not_valid_before": "2019-01-08T10:00:00+00:00",
    "not_valid_after": "2019-07-08T09:59:59+00:00",
    "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",
    "used_by": [
      {
        "id": 42,
        "type": "server"
      }
    ]
  }
}

Get a Certificate

Gets a specific Certificate object.

HTTP Request

GET /certificates/{id}

Path Parameters

Response

The certificate key in the reply contains a Certificate object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/certificates/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "certificate": {
    "id": 897,
    "name": "my website cert",
    "labels": {},
    "certificate": "-----BEGIN CERTIFICATE-----\n...",
    "created": "2019-01-08T12:10:00+00:00",
    "not_valid_before": "2019-01-08T10:00:00+00:00",
    "not_valid_after": "2019-07-08T09:59:59+00:00",
    "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",
    "used_by": [
      {
        "id": 42,
        "type": "server"
      }
    ]
  }
}

Update a Certificate

Updates the Certificate properties.

Note that when updating labels, the Certificate’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

Note: if the Certificate object changes during the request, the response will be a “conflict” error.

HTTP Request

PUT /certificates/{id}

Path Parameters

Request

Response

The certificate key contains the Certificate that was just created

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"my website cert","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/certificates/{id}'

Request

{
  "name": "my website cert",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "certificate": {
    "id": 897,
    "name": "my website cert",
    "labels": {
      "labelkey": "value"
    },
    "certificate": "-----BEGIN CERTIFICATE-----\n...",
    "created": "2019-01-08T12:10:00+00:00",
    "not_valid_before": "2019-01-08T10:00:00+00:00",
    "not_valid_after": "2019-07-08T09:59:59+00:00",
    "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",
    "used_by": [
      {
        "id": 42,
        "type": "server"
      }
    ]
  }
}

Delete a Certificate

Deletes a Certificate.

HTTP Request

DELETE /certificates/{id}

Path Parameters

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/certificates/{id}'

Response headers

Status: 204

Datacenters

Each Datacenter represents a physical entity where virtual machines are hosted. Note that Datacenters are not guaranteed to be entirely independent failure domains.

Datacenters in the same Location are connected by very low latency links.

Datacenter names are made up of their Location and Datacenter number, for example fsn1-dc8 means Datacenter 8 in Location fsn1.

Get all Datacenters

Returns all Datacenter objects.

HTTP Request

GET /datacenters

Query Parameters

Response

The reply contains the datacenters and recommendation keys

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/datacenters'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "datacenters": [
    {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein DC Park 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Faleknstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071,
        "network_zone": "eu-central"
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ],
        "available_for_migration": [
          1,
          2,
          3
        ]
      }
    }
  ],
  "recommendation": 1
}

Get a Datacenter

Returns a specific Datacenter object.

HTTP Request

GET /datacenters/{id}

Path Parameters

Response

The datacenter key in the reply contains a Datacenter object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/datacenters/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "datacenter": {
    "id": 1,
    "name": "fsn1-dc8",
    "description": "Falkenstein DC Park 8",
    "location": {
      "id": 1,
      "name": "fsn1",
      "description": "Faleknstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "server_types": {
      "supported": [
        1,
        2,
        3
      ],
      "available": [
        1,
        2,
        3
      ],
      "available_for_migration": [
        1,
        2,
        3
      ]
    }
  }
}

Floating IPs

Floating IPs help you to create highly available setups. You can assign a Floating IP to any Server. The Server can then use this IP. You can reassign it to a different Server at any time, or you can choose to unassign the IP from Servers all together.

Floating IPs can be used globally. This means you can assign a Floating IP to a Server in one Location and later reassign it to a Server in a different Location. For optimal routing and latency Floating IPs should be used in the Location they were created in.

For Floating IPs to work with your Server, you must configure them inside your operation system.

Floating IPs of type ipv4 use a single IPv4 address as their ip property. Floating IPs of type ipv6 use a /64 network such as fc00::/64 as their ip property. Any IP address within that network can be used on your host.

Floating IPs are billed on a monthly basis.

Get all Floating IPs

Returns all Floating IP objects.

HTTP Request

GET /floating_ips

Query Parameters

Response

The floating_ips key in the reply contains an array of Floating IP objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "floating_ips": [
    {
      "id": 4711,
      "name": "Web Frontend",
      "description": "Web Frontend",
      "ip": "131.232.99.1",
      "type": "ipv4",
      "server": 42,
      "dns_ptr": [
        {
          "ip": "2001:db8::1",
          "dns_ptr": "server.example.com"
        }
      ],
      "home_location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071,
        "network_zone": "eu-central"
      },
      "blocked": false,
      "protection": {
        "delete": false
      },
      "labels": {},
      "created": "2016-01-30T23:50:00+00:00"
    }
  ]
}

Create a Floating IP

Creates a new Floating IP assigned to a Server. If you want to create a Floating IP that is not bound to a Server, you need to provide the home_location key instead of server. This can be either the ID or the name of the Location this IP shall be created in. Note that a 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.

HTTP Request

POST /floating_ips

Request

The type argument is required while home_location and server are mutually exclusive.

Response

The floating_ip key in the reply contains the object that was just created

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"type":"ipv4","server":42,"home_location":"fsn1","description":"Web Frontend","name":"Web Frontend","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/floating_ips'

Request

{
  "type": "ipv4",
  "server": 42,
  "home_location": "fsn1",
  "description": "Web Frontend",
  "name": "Web Frontend",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "floating_ip": {
    "id": 4711,
    "name": "Web Frontend",
    "description": "Web Frontend",
    "ip": "131.232.99.1",
    "type": "ipv4",
    "server": 42,
    "dns_ptr": [
      {
        "ip": "2001:db8::1",
        "dns_ptr": "server.example.com"
      }
    ],
    "home_location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "blocked": false,
    "protection": {
      "delete": false
    },
    "labels": {},
    "created": "2016-01-30T23:50:00+00:00"
  },
  "action": {
    "id": 13,
    "command": "create_floating_ip",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Get a Floating IP

Returns a specific Floating IP object.

HTTP Request

GET /floating_ips/{id}

Path Parameters

Response

The floating_ip key in the reply contains a Floating IP object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "floating_ip": {
    "id": 4711,
    "name": "Web Frontend",
    "description": "Web Frontend",
    "ip": "131.232.99.1",
    "type": "ipv4",
    "server": 42,
    "dns_ptr": [
      {
        "ip": "2001:db8::1",
        "dns_ptr": "server.example.com"
      }
    ],
    "home_location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "blocked": false,
    "protection": {
      "delete": false
    },
    "labels": {},
    "created": "2016-01-30T23:50:00+00:00"
  }
}

Update a Floating IP

Updates the description or labels of a Floating IP. Also note that when updating labels, the Floating IP’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

HTTP Request

PUT /floating_ips/{id}

Path Parameters

Request

Response

The floating_ip key in the reply contains the modified Floating IP object with the new description

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"Web Frontend","description":"Web Frontend","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/floating_ips/{id}'

Request

{
  "name": "Web Frontend",
  "description": "Web Frontend",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "floating_ip": {
    "id": 4711,
    "name": "Web Frontend",
    "description": "Web Frontend",
    "ip": "131.232.99.1",
    "type": "ipv4",
    "server": 42,
    "dns_ptr": [
      {
        "ip": "2001:db8::1",
        "dns_ptr": "server.example.com"
      }
    ],
    "home_location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "blocked": false,
    "protection": {
      "delete": false
    },
    "labels": {
      "labelkey": "value"
    },
    "created": "2016-01-30T23:50:00+00:00"
  }
}

Delete a Floating IP

Deletes a Floating IP. If it is currently assigned to a Server it will automatically get unassigned.

HTTP Request

DELETE /floating_ips/{id}

Path Parameters

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}'

Response headers

Status: 204

Floating IP Actions

Get all Actions for a Floating IP

Returns all Action objects for a Floating IP. You can sort the results by using the sort URI parameter, and filter them with the status parameter.

HTTP Request

GET /floating_ips/{id}/actions

Path Parameters

Query Parameters

Response

The actions key contains a list of Actions

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 13,
      "command": "assign_floating_ip",
      "status": "success",
      "progress": 100,
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:56:00+00:00",
      "resources": [
        {
          "id": 42,
          "type": "server"
        },
        {
          "id": 4711,
          "type": "floating_ip"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}

Get an Action for a Floating IP

Returns a specific Action object for a Floating IP.

HTTP Request

GET /floating_ips/{id}/actions/{action_id}

Path Parameters

Response

The action key in the reply has this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 13,
    "command": "assign_floating_ip",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Assign a Floating IP to a Server

Assigns a Floating IP to a Server.

HTTP Request

POST /floating_ips/{id}/actions/assign

Path Parameters

Request

Response

The action key contains the assign Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"server":42}' \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions/assign'

Request

{
  "server": 42
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "assign_floating_ip",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Unassign a Floating IP

Unassigns a Floating IP, resulting in it being unreachable. You may assign it to a Server again at a later time.

HTTP Request

POST /floating_ips/{id}/actions/unassign

Path Parameters

Response

The action key contains the unassign Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions/unassign'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "unassign_floating_ip",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change reverse DNS entry for a Floating IP

Changes the hostname that will appear when getting the hostname belonging to this Floating IP.

HTTP Request

POST /floating_ips/{id}/actions/change_dns_ptr

Path Parameters

Request

Select the IP address for which to change the DNS entry by passing ip. For a Floating IP of type ipv4 this must exactly match the IP address of the Floating IP. For a Floating IP of type ipv6 this must be a single IP within the IPv6 /64 range that belongs to this Floating IP.

The target hostname is set by passing dns_ptr.

Response

The action key contains the change_dns_ptr Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip":"1.2.3.4","dns_ptr":"server02.example.com"}' \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_dns_ptr'

Request

{
  "ip": "1.2.3.4",
  "dns_ptr": "server02.example.com"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_dns_ptr",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change Floating IP Protection

Changes the protection configuration of the Floating IP.

HTTP Request

POST /floating_ips/{id}/actions/change_protection

Path Parameters

Request

Response

The action key contains the change_protection Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_protection'

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Images

Images are blueprints for your VM disks. They can be of different types:

System Images

Distribution Images maintained by us, e.g. “Ubuntu 20.04”

Snapshot Images

Maintained by you, for example “Ubuntu 20.04 with my own settings”. These are billed per GB per month.

Backup Images

Daily Backups of your Server. Will automatically be created for Servers which have backups enabled (POST /servers/{id}/actions/enable_backup)

Bound to exactly one Server. If you delete the Server, you also delete all backups bound to it. You may convert backup Images to snapshot Images to keep them.

These are billed at 20% of your instance price for 7 backup slots.

Get all Images

Returns all Image objects. You can select specific Image types only and sort the results by using URI parameters.

HTTP Request

GET /images

Query Parameters

Response

The images key in the reply contains an array of Image objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "images": [
    {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-20.04",
      "description": "Ubuntu 20.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50:00+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "20.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00",
      "labels": {}
    }
  ]
}

Get an Image

Returns a specific Image object.

HTTP Request

GET /images/{id}

Path Parameters

Response

The image key in the reply contains an Image object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "image": {
    "id": 4711,
    "type": "snapshot",
    "status": "available",
    "name": "ubuntu-20.04",
    "description": "Ubuntu 20.04 Standard 64 bit",
    "image_size": 2.3,
    "disk_size": 10,
    "created": "2016-01-30T23:50:00+00:00",
    "created_from": {
      "id": 1,
      "name": "Server"
    },
    "bound_to": null,
    "os_flavor": "ubuntu",
    "os_version": "20.04",
    "rapid_deploy": false,
    "protection": {
      "delete": false
    },
    "deprecated": "2018-02-28T00:00:00+00:00",
    "labels": {}
  }
}

Update an Image

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.

Note that when updating labels, the current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

HTTP Request

PUT /images/{id}

Path Parameters

Request

Response

The image key in the reply contains the modified Image object

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"description":"My new Image description","type":"snapshot","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/images/{id}'

Request

{
  "description": "My new Image description",
  "type": "snapshot",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "image": {
    "id": 4711,
    "type": "snapshot",
    "status": "available",
    "name": null,
    "description": "My new Image description",
    "image_size": 2.3,
    "disk_size": 10,
    "created": "2016-01-30T23:50:00+00:00",
    "created_from": {
      "id": 1,
      "name": "Server"
    },
    "bound_to": null,
    "os_flavor": "ubuntu",
    "os_version": "20.04",
    "rapid_deploy": false,
    "protection": {
      "delete": false
    },
    "deprecated": "2018-02-28T00:00:00+00:00",
    "labels": {
      "labelkey": "value"
    }
  }
}

Delete an Image

Deletes an Image. Only Images of type snapshot and backup can be deleted.

HTTP Request

DELETE /images/{id}

Path Parameters

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images/{id}'

Response headers

Status: 204

Image Actions

Get all Actions for an Image

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.

HTTP Request

GET /images/{id}/actions

Path Parameters

Query Parameters

Response

The actions key contains a list of Actions

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 13,
      "command": "change_protection",
      "status": "success",
      "progress": 100,
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:56:00+00:00",
      "resources": [
        {
          "id": 4711,
          "type": "image"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}

Get an Action for an Image

Returns a specific Action for an Image.

HTTP Request

GET /images/{id}/actions/{action_id}

Path Parameters

Response

The action key contains the Image Action

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "image"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change Image Protection

Changes the protection configuration of the Image. Can only be used on snapshots.

HTTP Request

POST /images/{id}/actions/change_protection

Path Parameters

Request

Response

The action key contains the change_protection Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/images/{id}/actions/change_protection'

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "image"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

ISOs

ISOs are read-only Images of DVDs. While we recommend using our Image functionality to install your Servers we also provide some stock ISOs so you can install more exotic operating systems by yourself.

On request our support uploads a private ISO just for you. These are marked with type private and only visible in your Project.

To attach an ISO to your Server use POST /servers/{id}/actions/attach_iso.

Get all ISOs

Returns all available ISO objects.

HTTP Request

GET /isos

Query Parameters

Response

The isos key in the reply contains an array of iso objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/isos'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "isos": [
    {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    }
  ]
}

Get an ISO

Returns a specific ISO object.

HTTP Request

GET /isos/{id}

Path Parameters

Response

The iso key in the reply contains an array of ISO objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/isos/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "iso": {
    "id": 4711,
    "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
    "description": "FreeBSD 11.0 x64",
    "type": "public",
    "deprecated": "2018-02-28T00:00:00+00:00"
  }
}

Load Balancers

Get all Load Balancers

Gets all existing Load Balancers that you have available.

HTTP Request

GET /load_balancers

Query Parameters

Response

The load_balancers key contains a list of Load Balancers

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancers": [
    {
      "id": 4711,
      "name": "Web Frontend",
      "public_net": {
        "enabled": false,
        "ipv4": {
          "ip": "1.2.3.4"
        },
        "ipv6": {
          "ip": "2001:db8::1"
        }
      },
      "private_net": [
        {
          "network": 4711,
          "ip": "10.0.0.2"
        }
      ],
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071,
        "network_zone": "eu-central"
      },
      "load_balancer_type": {
        "id": 1,
        "name": "lb11",
        "description": "LB11",
        "max_connections": 20000,
        "max_services": 5,
        "max_targets": 25,
        "max_assigned_certificates": 10,
        "deprecated": "2016-01-30T23:50:00+00:00",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            },
            "price_monthly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            }
          }
        ]
      },
      "protection": {
        "delete": false
      },
      "labels": {},
      "created": "2016-01-30T23:50:00+00:00",
      "services": [
        {
          "protocol": "https",
          "listen_port": 443,
          "destination_port": 80,
          "proxyprotocol": false,
          "health_check": {
            "protocol": "http",
            "port": 4711,
            "interval": 15,
            "timeout": 10,
            "retries": 3,
            "http": {
              "domain": "example.com",
              "path": "/",
              "response": "{\"status\": \"ok\"}",
              "status_codes": [
                "2??",
                "3??"
              ],
              "tls": false
            }
          },
          "http": {
            "cookie_name": "HCLBSTICKY",
            "cookie_lifetime": 300,
            "certificates": [
              897
            ],
            "redirect_http": true,
            "sticky_sessions": true
          }
        }
      ],
      "targets": [
        {
          "type": "server",
          "server": {
            "id": 80
          },
          "health_status": [
            {
              "listen_port": 443,
              "status": "healthy"
            }
          ],
          "use_private_ip": false,
          "label_selector": {
            "selector": "env=prod"
          },
          "ip": {
            "ip": "203.0.113.1"
          },
          "targets": [
            {
              "type": "server",
              "label_selector": null,
              "server": {
                "id": 80
              },
              "health_status": [
                {
                  "listen_port": 443,
                  "status": "healthy"
                }
              ]
            }
          ]
        }
      ],
      "algorithm": {
        "type": "round_robin"
      },
      "outgoing_traffic": null,
      "ingoing_traffic": null,
      "included_traffic": 10000
    }
  ]
}

Create a Load Balancer

Creates a Load Balancer.

Call specific error codes

Code Description
cloud_resource_ip_not_allowed The IP you are trying to add as a target belongs to a Hetzner Cloud resource
ip_not_owned The IP is not owned by the owner of the project of the Load Balancer
load_balancer_not_attached_to_network The Load Balancer is not attached to a network
robot_unavailable Robot was not available. The caller may retry the operation after a short delay.
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
source_port_already_used The source port you are trying to add is already in use
target_already_defined The Load Balancer target you are trying to define is already defined

HTTP Request

POST /load_balancers

Request

Response

The load_balancer key contains the Load Balancer that was just created

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"Web Frontend","load_balancer_type":"lb11","algorithm":{"type":"round_robin"},"services":[{"protocol":"https","listen_port":443,"destination_port":80,"proxyprotocol":false,"health_check":{"protocol":"http","port":4711,"interval":15,"timeout":10,"retries":3,"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false}},"http":{"cookie_name":"HCLBSTICKY","cookie_lifetime":300,"certificates":[897],"redirect_http":true,"sticky_sessions":true}}],"targets":[{"type":"server","server":{"id":80},"health_status":[{"listen_port":443,"status":"healthy"}],"use_private_ip":false,"label_selector":{"selector":"env=prod"},"ip":{"ip":"203.0.113.1"},"targets":[{"type":"server","label_selector":null,"server":{"id":80},"health_status":[{"listen_port":443,"status":"healthy"}]}]}],"labels":{"labelkey":"value"},"public_interface":true,"network":123}' \
	'https://api.hetzner.cloud/v1/load_balancers'

Request

{
  "name": "Web Frontend",
  "load_balancer_type": "lb11",
  "algorithm": {
    "type": "round_robin"
  },
  "services": [
    {
      "protocol": "https",
      "listen_port": 443,
      "destination_port": 80,
      "proxyprotocol": false,
      "health_check": {
        "protocol": "http",
        "port": 4711,
        "interval": 15,
        "timeout": 10,
        "retries": 3,
        "http": {
          "domain": "example.com",
          "path": "/",
          "response": "{\"status\": \"ok\"}",
          "status_codes": [
            "2??",
            "3??"
          ],
          "tls": false
        }
      },
      "http": {
        "cookie_name": "HCLBSTICKY",
        "cookie_lifetime": 300,
        "certificates": [
          897
        ],
        "redirect_http": true,
        "sticky_sessions": true
      }
    }
  ],
  "targets": [
    {
      "type": "server",
      "server": {
        "id": 80
      },
      "health_status": [
        {
          "listen_port": 443,
          "status": "healthy"
        }
      ],
      "use_private_ip": false,
      "label_selector": {
        "selector": "env=prod"
      },
      "ip": {
        "ip": "203.0.113.1"
      },
      "targets": [
        {
          "type": "server",
          "label_selector": null,
          "server": {
            "id": 80
          },
          "health_status": [
            {
              "listen_port": 443,
              "status": "healthy"
            }
          ]
        }
      ]
    }
  ],
  "labels": {
    "labelkey": "value"
  },
  "public_interface": true,
  "network": 123
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "load_balancer": {
    "id": 4711,
    "name": "Web Frontend",
    "public_net": {
      "enabled": false,
      "ipv4": {
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "ip": "2001:db8::1"
      }
    },
    "private_net": [
      {
        "network": 4711,
        "ip": "10.0.0.2"
      }
    ],
    "location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "load_balancer_type": {
      "id": 1,
      "name": "lb11",
      "description": "LB11",
      "max_connections": 20000,
      "max_services": 5,
      "max_targets": 25,
      "max_assigned_certificates": 10,
      "deprecated": "2016-01-30T23:50:00+00:00",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ]
    },
    "protection": {
      "delete": false
    },
    "labels": {},
    "created": "2016-01-30T23:50:00+00:00",
    "services": [
      {
        "protocol": "http",
        "listen_port": 443,
        "destination_port": 80,
        "proxyprotocol": false,
        "health_check": {
          "protocol": "http",
          "port": 4711,
          "interval": 15,
          "timeout": 10,
          "retries": 3,
          "http": {
            "domain": "example.com",
            "path": "/",
            "response": "{\"status\": \"ok\"}",
            "status_codes": [
              "2??,3??"
            ],
            "tls": false
          }
        },
        "http": {
          "cookie_name": "HCLBSTICKY",
          "cookie_lifetime": 300,
          "certificates": [
            897
          ],
          "redirect_http": true,
          "sticky_sessions": true
        }
      }
    ],
    "targets": [
      {
        "type": "server",
        "server": {
          "id": 80
        },
        "health_status": [
          {
            "listen_port": 443,
            "status": "healthy"
          }
        ],
        "use_private_ip": true,
        "targets": [
          {
            "type": "server",
            "label_selector": null,
            "server": {
              "id": 80
            },
            "health_status": [
              {
                "listen_port": 443,
                "status": "healthy"
              }
            ],
            "use_private_ip": true
          }
        ]
      }
    ],
    "algorithm": {
      "type": "round_robin"
    },
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321
  },
  "action": {
    "id": 13,
    "command": "create_load_balancer",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Get a Load Balancer

Gets a specific Load Balancer object.

HTTP Request

GET /load_balancers/{id}

Path Parameters

Response

The load_balancer key contains the load Balancer

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancer": {
    "id": 4711,
    "name": "Web Frontend",
    "public_net": {
      "enabled": false,
      "ipv4": {
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "ip": "2001:db8::1"
      }
    },
    "private_net": [
      {
        "network": 4711,
        "ip": "10.0.0.2"
      }
    ],
    "location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "load_balancer_type": {
      "id": 1,
      "name": "lb11",
      "description": "LB11",
      "max_connections": 20000,
      "max_services": 5,
      "max_targets": 25,
      "max_assigned_certificates": 10,
      "deprecated": "2016-01-30T23:50:00+00:00",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ]
    },
    "protection": {
      "delete": false
    },
    "labels": {},
    "created": "2016-01-30T23:50:00+00:00",
    "services": [
      {
        "protocol": "https",
        "listen_port": 443,
        "destination_port": 80,
        "proxyprotocol": false,
        "health_check": {
          "protocol": "http",
          "port": 4711,
          "interval": 15,
          "timeout": 10,
          "retries": 3,
          "http": {
            "domain": "example.com",
            "path": "/",
            "response": "{\"status\": \"ok\"}",
            "status_codes": [
              "2??",
              "3??"
            ],
            "tls": false
          }
        },
        "http": {
          "cookie_name": "HCLBSTICKY",
          "cookie_lifetime": 300,
          "certificates": [
            897
          ],
          "redirect_http": true,
          "sticky_sessions": true
        }
      }
    ],
    "targets": [
      {
        "type": "server",
        "server": {
          "id": 80
        },
        "health_status": [
          {
            "listen_port": 443,
            "status": "healthy"
          }
        ],
        "use_private_ip": false,
        "label_selector": {
          "selector": "env=prod"
        },
        "ip": {
          "ip": "203.0.113.1"
        },
        "targets": [
          {
            "type": "server",
            "label_selector": null,
            "server": {
              "id": 80
            },
            "health_status": [
              {
                "listen_port": 443,
                "status": "healthy"
              }
            ]
          }
        ]
      }
    ],
    "algorithm": {
      "type": "round_robin"
    },
    "outgoing_traffic": null,
    "ingoing_traffic": null,
    "included_traffic": 10000
  }
}

Update a Load Balancer

Updates a Load Balancer. You can update a Load Balancer’s name and a Load Balancer’s labels.

Note that when updating labels, the Load Balancer’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

Note: if the Load Balancer object changes during the request, the response will be a “conflict” error.

HTTP Request

PUT /load_balancers/{id}

Path Parameters

Request

Response

The load_balancer key contains the updated Load Balancer

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"new-name","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}'

Request

{
  "name": "new-name",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancer": {
    "id": 4711,
    "name": "new-name",
    "public_net": {
      "enabled": false,
      "ipv4": {
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "ip": "2001:db8::1"
      }
    },
    "private_net": [
      {
        "network": 4711,
        "ip": "10.0.0.2"
      }
    ],
    "location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "load_balancer_type": {
      "id": 1,
      "name": "lb11",
      "description": "LB11",
      "max_connections": 20000,
      "max_services": 5,
      "max_targets": 25,
      "max_assigned_certificates": 10,
      "deprecated": "2016-01-30T23:50:00+00:00",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ]
    },
    "protection": {
      "delete": false
    },
    "labels": {
      "labelkey": "value"
    },
    "created": "2016-01-30T23:50:00+00:00",
    "services": [
      {
        "protocol": "http",
        "listen_port": 443,
        "destination_port": 80,
        "proxyprotocol": false,
        "health_check": {
          "protocol": "http",
          "port": 4711,
          "interval": 15,
          "timeout": 10,
          "retries": 3,
          "http": {
            "domain": "example.com",
            "path": "/",
            "response": "{\"status\": \"ok\"}",
            "status_codes": [
              "2??,3??"
            ],
            "tls": false
          }
        },
        "http": {
          "cookie_name": "HCLBSTICKY",
          "cookie_lifetime": 300,
          "certificates": [
            897
          ],
          "redirect_http": true,
          "sticky_sessions": true
        }
      }
    ],
    "targets": [
      {
        "type": "server",
        "server": {
          "id": 80
        },
        "health_status": [
          {
            "listen_port": 443,
            "status": "healthy"
          }
        ],
        "use_private_ip": true,
        "label_selector": {
          "selector": "env=prod"
        },
        "ip": {
          "ip": "203.0.113.1"
        },
        "targets": [
          {
            "type": "server",
            "label_selector": null,
            "server": {
              "id": 80
            },
            "health_status": [
              {
                "listen_port": 443,
                "status": "healthy"
              }
            ],
            "use_private_ip": true
          }
        ]
      }
    ],
    "algorithm": {
      "type": "round_robin"
    },
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321
  }
}

Delete a Load Balancer

Deletes a Load Balancer.

HTTP Request

DELETE /load_balancers/{id}

Path Parameters

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}'

Response headers

Status: 204

Get Metrics for a LoadBalancer

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:

Type Timeseries Unit Description
open_connections open_connections number Open connections
requests_per_second requests_per_second requests/s Requests per second
bandwidth bandwidth.in bytes/s Ingress bandwidth
bandwidth.out bytes/s Egress bandwidth

Metrics are available for the last 30 days only.

If you do not provide the step argument we will automatically adjust it so that 200 samples are returned.

We limit the number of samples to a maximum of 500 and will adjust the step parameter accordingly.

HTTP Request

GET /load_balancers/{id}/metrics

Path Parameters

Query Parameters

Response

The metrics key in the reply contains a metrics object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/metrics'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "metrics": {
    "start": "2017-01-01T00:00:00+00:00",
    "end": "2017-01-01T23:00:00+00:00",
    "step": 60,
    "time_series": {
      "name_of_timeseries": {
        "values": [
          [
            1435781470.622,
            "42"
          ],
          [
            1435781471.622,
            "43"
          ]
        ]
      }
    }
  }
}

Load Balancer Actions

Get all Actions for a Load Balancer

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.

HTTP Request

GET /load_balancers/{id}/actions

Path Parameters

Query Parameters

Response

The actions key contains a list of Actions

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 13,
      "command": "add_service",
      "status": "success",
      "progress": 100,
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:56:00+00:00",
      "resources": [
        {
          "id": 4711,
          "type": "load_balancer"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}

Get an Action for a Load Balancer

Returns a specific Action for a Load Balancer.

HTTP Request

GET /load_balancers/{id}/actions/{action_id}

Path Parameters

Response

The action key contains the Load Balancer Action

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Add Service

Adds a service to a Load Balancer.

Call specific error codes

Code Description
source_port_already_used The source port you are trying to add is already in use

HTTP Request

POST /load_balancers/{id}/actions/add_service

Path Parameters

Request

Response

The action key contains the add_service Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"protocol":"https","listen_port":443,"destination_port":80,"proxyprotocol":false,"health_check":{"protocol":"http","port":4711,"interval":15,"timeout":10,"retries":3,"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false}},"http":{"cookie_name":"HCLBSTICKY","cookie_lifetime":300,"certificates":[897],"redirect_http":true,"sticky_sessions":true}}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_service'

Request

{
  "protocol": "https",
  "listen_port": 443,
  "destination_port": 80,
  "proxyprotocol": false,
  "health_check": {
    "protocol": "http",
    "port": 4711,
    "interval": 15,
    "timeout": 10,
    "retries": 3,
    "http": {
      "domain": "example.com",
      "path": "/",
      "response": "{\"status\": \"ok\"}",
      "status_codes": [
        "2??",
        "3??"
      ],
      "tls": false
    }
  },
  "http": {
    "cookie_name": "HCLBSTICKY",
    "cookie_lifetime": 300,
    "certificates": [
      897
    ],
    "redirect_http": true,
    "sticky_sessions": true
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "add_service",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Update Service

Updates a Load Balancer Service.

Call specific error codes

Code Description
source_port_already_used The source port you are trying to add is already in use

HTTP Request

POST /load_balancers/{id}/actions/update_service

Path Parameters

Request

Response

The action key contains the update_service Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"protocol":"https","listen_port":443,"destination_port":80,"proxyprotocol":false,"health_check":{"protocol":"http","port":4711,"interval":15,"timeout":10,"retries":3,"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false}},"http":{"cookie_name":"HCLBSTICKY","cookie_lifetime":300,"certificates":[897],"redirect_http":true,"sticky_sessions":true}}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/update_service'

Request

{
  "protocol": "https",
  "listen_port": 443,
  "destination_port": 80,
  "proxyprotocol": false,
  "health_check": {
    "protocol": "http",
    "port": 4711,
    "interval": 15,
    "timeout": 10,
    "retries": 3,
    "http": {
      "domain": "example.com",
      "path": "/",
      "response": "{\"status\": \"ok\"}",
      "status_codes": [
        "2??",
        "3??"
      ],
      "tls": false
    }
  },
  "http": {
    "cookie_name": "HCLBSTICKY",
    "cookie_lifetime": 300,
    "certificates": [
      897
    ],
    "redirect_http": true,
    "sticky_sessions": true
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "update_service",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Delete Service

Delete a service of a Load Balancer.

HTTP Request

POST /load_balancers/{id}/actions/delete_service

Path Parameters

Request

Response

The action key contains the delete_service Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"listen_port":4711}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/delete_service'

Request

{
  "listen_port": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "delete_service",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Add Target

Adds a target to a Load Balancer.

Call specific error codes

Code Description
cloud_resource_ip_not_allowed The IP you are trying to add as a target belongs to a Hetzner Cloud resource
ip_not_owned The IP you are trying to add as a target is not owned by the Project owner
load_balancer_not_attached_to_network The Load Balancer is not attached to a network
robot_unavailable Robot was not available. The caller may retry the operation after a short delay.
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
target_already_defined The Load Balancer target you are trying to define is already defined

HTTP Request

POST /load_balancers/{id}/actions/add_target

Path Parameters

Request

Response

The action key contains the add_target Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"type":"server","server":{"id":80},"use_private_ip":true,"label_selector":{"selector":"env=prod"},"ip":{"ip":"203.0.113.1"}}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_target'

Request

{
  "type": "server",
  "server": {
    "id": 80
  },
  "use_private_ip": true,
  "label_selector": {
    "selector": "env=prod"
  },
  "ip": {
    "ip": "203.0.113.1"
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "add_target",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Remove Target

Removes a target from a Load Balancer.

HTTP Request

POST /load_balancers/{id}/actions/remove_target

Path Parameters

Request

Response

The action key contains the remove_target Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"type":"server","server":{"id":80},"label_selector":{"selector":"env=prod"},"ip":{"ip":"203.0.113.1"}}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/remove_target'

Request

{
  "type": "server",
  "server": {
    "id": 80
  },
  "label_selector": {
    "selector": "env=prod"
  },
  "ip": {
    "ip": "203.0.113.1"
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "remove_target",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change Algorithm

Change the algorithm that determines to which target new requests are sent.

HTTP Request

POST /load_balancers/{id}/actions/change_algorithm

Path Parameters

Request

Response

The action key contains the change_algorithm Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"type":"round_robin"}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_algorithm'

Request

{
  "type": "round_robin"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_algorithm",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change the Type of a Load Balancer

Changes the type (Max Services, Max Targets and Max Connections) of a Load Balancer.

Call specific error codes

Code Description
invalid_load_balancer_type The Load Balancer type does not fit for the given Load Balancer

HTTP Request

POST /load_balancers/{id}/actions/change_type

Path Parameters

Request

Response

The action key contains the change_load_balancer_type Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"load_balancer_type":"lb21"}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_type'

Request

{
  "load_balancer_type": "lb21"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_load_balancer_type",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Attach a Load Balancer to a Network

Attach a Load Balancer to a Network.

Call specific error codes

Code Description
load_balancer_already_attached The Load Balancer is already attached to a network
ip_not_available The provided Network IP is not available
no_subnet_available No Subnet or IP is available for the Load Balancer within the network

HTTP Request

POST /load_balancers/{id}/actions/attach_to_network

Path Parameters

Request

Response

The action key contains the attach_to_network Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"network":4711,"ip":"10.0.1.1"}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/attach_to_network'

Request

{
  "network": 4711,
  "ip": "10.0.1.1"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "attach_to_network",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Detach a Load Balancer from a Network

Detaches a Load Balancer from a network.

HTTP Request

POST /load_balancers/{id}/actions/detach_from_network

Path Parameters

Request

Response

The action key contains the detach_from_network Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"network":4711}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/detach_from_network'

Request

{
  "network": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "detach_from_network",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Enable the public interface of a Load Balancer

Enable the public interface of a Load Balancer. The Load Balancer will be accessible from the internet via its public IPs.

HTTP Request

POST /load_balancers/{id}/actions/enable_public_interface

Path Parameters

Response

The action key contains the enable_public_interface Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/enable_public_interface'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "enable_public_interface",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Disable the public interface of a Load Balancer

Disable the public interface of a Load Balancer. The Load Balancer will be not accessible from the internet via its public IPs.

Call specific error codes

Code Description
load_balancer_not_attached_to_network The Load Balancer is not attached to a network
targets_without_use_private_ip The Load Balancer has targets that use the public IP instead of the private IP

HTTP Request

POST /load_balancers/{id}/actions/disable_public_interface

Path Parameters

Response

The action key contains the disable_public_interface Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/disable_public_interface'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "disable_public_interface",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change Load Balancer Protection

Changes the protection configuration of a Load Balancer.

HTTP Request

POST /load_balancers/{id}/actions/change_protection

Path Parameters

Request

Response

The action key contains the change_protection Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_protection'

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Load Balancer Types

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.

Currency for all amounts is €. All prices exclude VAT.

Get all Load Balancer Types

Gets all Load Balancer type objects.

HTTP Request

GET /load_balancer_types

Query Parameters

Response

The load_balancer_types key in the reply contains an array of Load Balancer type objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancer_types'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancer_types": [
    {
      "id": 1,
      "name": "lb11",
      "description": "LB11",
      "max_connections": 20000,
      "max_services": 5,
      "max_targets": 25,
      "max_assigned_certificates": 10,
      "deprecated": "2016-01-30T23:50:00+00:00",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ]
    }
  ]
}

Get a Load Balancer Type

Gets a specific Load Balancer type object.

HTTP Request

GET /load_balancer_types/{id}

Path Parameters

Response

The load_balancer_type key in the reply contains a Load Balancer type object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancer_types/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancer_type": {
    "id": 1,
    "name": "lb11",
    "description": "LB11",
    "max_connections": 20000,
    "max_services": 5,
    "max_targets": 25,
    "max_assigned_certificates": 10,
    "deprecated": "2016-01-30T23:50:00+00:00",
    "prices": [
      {
        "location": "fsn1",
        "price_hourly": {
          "net": "1.0000000000",
          "gross": "1.1900000000000000"
        },
        "price_monthly": {
          "net": "1.0000000000",
          "gross": "1.1900000000000000"
        }
      }
    ]
  }
}

Locations

Datacenters are organized by Locations. Datacenters in the same Location are connected with very low latency links.

Get all Locations

Returns all Location objects.

HTTP Request

GET /locations

Query Parameters

Response

The locations key in the reply contains an array of Location objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/locations'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "locations": [
    {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    }
  ]
}

Get a Location

Returns a specific Location object.

HTTP Request

GET /locations/{id}

Path Parameters

Response

The location key in the reply contains a Location object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/locations/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "location": {
    "id": 1,
    "name": "fsn1",
    "description": "Falkenstein DC Park 1",
    "country": "DE",
    "city": "Falkenstein",
    "latitude": 50.47612,
    "longitude": 12.370071,
    "network_zone": "eu-central"
  }
}

Networks

Networks is a private networks feature. These Networks are optional and they coexist with the public network that every Server has by default.

They allow Servers to talk to each other over a dedicated network interface using private IP addresses not available publicly.

The IP addresses are allocated and managed via the API, they must conform to RFC1918 standard. IPs and network interfaces defined under Networks do not provide public internet connectivity, you will need to use the already existing public network interface for that.

Each network has a user selected ip_range which defines all available IP addresses which can be used for Subnets within the Network.

To assign individual IPs to Servers you will need to create Network Subnets, described below.

Currently Networks support IPv4 only.

Subnets

Subnets divide the ip_range from the parent Network object into multiple Subnetworks that you can use for different specific purposes.

For each subnet you need to specify its own ip_range which must be contained within the parent Network’s ip_range. Additionally each subnet must belong to one of the available Network Zones described below. Subnets can not have overlapping IP ranges.

Currently there are two type of subnets:

  • type cloud is used to connect cloud Resources into your Network.
  • type server was used to connect only cloud Servers into your Network. This type is deprecated and is replaced by type cloud.

Network Zones

Network Zones are groups of Locations which have special high-speed network connections between them. The Location object contains the network_zone property each Location belongs to. Currently only one Network zone exists and is called eu-central. It spans the nbg1, fsn1 and hel1 Locations.

IP address management

When a cloud Server is attached to a network without the user specifying an IP it automatically gets an IP address assigned from a subnet of type server in the same network zone. If you specify the optional ip parameter when attaching then we will try to assign that IP. Keep in mind that the Server’s location must be covered by the Subnet’s Network Zone if you specify an IP, or that at least one Subnet with the zone covering Server’s location must exist.

A cloud Server can also have more than one IP address in a Network by specifying aliases. For details see the attach to network action.

The following IP addresses are reserved in networks and can not be used:

  • the first IP of the network ip_range as it will be used as a default gateway for the private Network interface.
  • 172.31.1.1 as it is being used as default gateway for our public Network interfaces.

Routes

Networks also support the notion of routes which are automatically applied to private traffic. A route makes sure that all packets for a given destination IP prefix will be sent to the address specified in its gateway.

Get all Networks

Gets all existing networks that you have available.

HTTP Request

GET /networks

Query Parameters

Response

The networks key contains a list of networks

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "networks": [
    {
      "id": 4711,
      "name": "mynet",
      "ip_range": "10.0.0.0/16",
      "subnets": [
        {
          "type": "cloud",
          "ip_range": "10.0.1.0/24",
          "network_zone": "eu-central",
          "gateway": "10.0.0.1"
        }
      ],
      "routes": [
        {
          "destination": "10.100.1.0/24",
          "gateway": "10.0.1.1"
        }
      ],
      "servers": [
        42
      ],
      "load_balancers": [
        42
      ],
      "protection": {
        "delete": false
      },
      "labels": {},
      "created": "2016-01-30T23:50:00+00:00"
    }
  ]
}

Create a Network

Creates a network with the specified ip_range.

You may specify one or more subnets. You can also add more Subnets later by using the add subnet action. If you do not specify an ip_range in the subnet we will automatically pick the first available /24 range for you.

You may specify one or more routes in routes. You can also add more routes later by using the add route action.

HTTP Request

POST /networks

Request

Response

The network key contains the network that was just created

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"mynet","ip_range":"10.0.0.0/16","labels":{"labelkey":"value"},"subnets":[{"type":"cloud","ip_range":"10.0.1.0/24","network_zone":"eu-central"}],"routes":[{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}]}' \
	'https://api.hetzner.cloud/v1/networks'

Request

{
  "name": "mynet",
  "ip_range": "10.0.0.0/16",
  "labels": {
    "labelkey": "value"
  },
  "subnets": [
    {
      "type": "cloud",
      "ip_range": "10.0.1.0/24",
      "network_zone": "eu-central"
    }
  ],
  "routes": [
    {
      "destination": "10.100.1.0/24",
      "gateway": "10.0.1.1"
    }
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "network": {
    "id": 4711,
    "name": "mynet",
    "ip_range": "10.0.0.0/16",
    "subnets": [
      {
        "type": "cloud",
        "ip_range": "10.0.1.0/24",
        "network_zone": "eu-central",
        "gateway": "10.0.0.1"
      }
    ],
    "routes": [
      {
        "destination": "10.100.1.0/24",
        "gateway": "10.0.1.1"
      }
    ],
    "servers": [
      42
    ],
    "load_balancers": [
      42
    ],
    "protection": {
      "delete": false
    },
    "labels": {},
    "created": "2016-01-30T23:50:00+00:00"
  }
}

Get a Network

Gets a specific network object.

HTTP Request

GET /networks/{id}

Path Parameters

Response

The network key contains the network

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "network": {
    "id": 4711,
    "name": "mynet",
    "ip_range": "10.0.0.0/16",
    "subnets": [
      {
        "type": "cloud",
        "ip_range": "10.0.1.0/24",
        "network_zone": "eu-central",
        "gateway": "10.0.0.1"
      }
    ],
    "routes": [
      {
        "destination": "10.100.1.0/24",
        "gateway": "10.0.1.1"
      }
    ],
    "servers": [
      42
    ],
    "load_balancers": [
      42
    ],
    "protection": {
      "delete": false
    },
    "labels": {},
    "created": "2016-01-30T23:50:00+00:00"
  }
}

Update a Network

Updates the network properties.

Note that when updating labels, the network’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

Note: if the network object changes during the request, the response will be a “conflict” error.

HTTP Request

PUT /networks/{id}

Path Parameters

Request

Response

The network key contains the updated network

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"new-name","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/networks/{id}'

Request

{
  "name": "new-name",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "network": {
    "id": 4711,
    "name": "new-name",
    "ip_range": "10.0.0.0/16",
    "subnets": [
      {
        "type": "cloud",
        "ip_range": "10.0.1.0/24",
        "network_zone": "eu-central",
        "gateway": "10.0.0.1"
      }
    ],
    "routes": [
      {
        "destination": "10.100.1.0/24",
        "gateway": "10.0.1.1"
      }
    ],
    "servers": [
      42
    ],
    "load_balancers": [
      42
    ],
    "protection": {
      "delete": false
    },
    "labels": {
      "labelkey": "value"
    },
    "created": "2016-01-30T23:50:00+00:00"
  }
}

Delete a Network

Deletes a network. If there are Servers attached they will be detached in the background.

Note: if the network object changes during the request, the response will be a “conflict” error.

HTTP Request

DELETE /networks/{id}

Path Parameters

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks/{id}'

Response headers

Status: 204

Network Actions

Get all Actions for a Network

Returns all Action objects for a Network. You can sort the results by using the sort URI parameter, and filter them with the status parameter.

HTTP Request

GET /networks/{id}/actions

Path Parameters

Query Parameters

Response

The actions key contains a list of Actions

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 13,
      "command": "add_subnet",
      "status": "success",
      "progress": 100,
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:56:00+00:00",
      "resources": [
        {
          "id": 4711,
          "type": "network"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}

Get an Action for a Network

Returns a specific Action for a Network.

HTTP Request

GET /networks/{id}/actions/{action_id}

Path Parameters

Response

The action key contains the Network Action

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 13,
    "command": "add_subnet",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Add a subnet to a Network

Adds a new subnet object to the Network. If you do not specify an ip_range for the subnet we will automatically pick the first available /24 range for you if possible.

Note: if the parent Network object changes during the request, the response will be a “conflict” error.

HTTP Request

POST /networks/{id}/actions/add_subnet

Path Parameters

Request

Response

The action key contains the add_subnet Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"type":"cloud","ip_range":"10.0.1.0/24","network_zone":"eu-central"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/add_subnet'

Request

{
  "type": "cloud",
  "ip_range": "10.0.1.0/24",
  "network_zone": "eu-central"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "add_subnet",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Delete a subnet from a Network

Deletes a single subnet entry from a Network. You cannot delete subnets which still have Servers attached. If you have Servers attached you first need to detach all Servers that use IPs from this subnet before you can delete the subnet.

Note: if the Network object changes during the request, the response will be a “conflict” error.

HTTP Request

POST /networks/{id}/actions/delete_subnet

Path Parameters

Request

Response

The action key contains the delete_subnet Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip_range":"10.0.1.0/24"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/delete_subnet'

Request

{
  "ip_range": "10.0.1.0/24"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "delete_subnet",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Add a route to a Network

Adds a route entry to a Network.

Note: if the Network object changes during the request, the response will be a “conflict” error.

HTTP Request

POST /networks/{id}/actions/add_route

Path Parameters

Request

Response

The action key contains the add_route Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/add_route'

Request

{
  "destination": "10.100.1.0/24",
  "gateway": "10.0.1.1"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "add_route",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Delete a route from a Network

Delete a route entry from a Network.

Note: if the Network object changes during the request, the response will be a “conflict” error.

HTTP Request

POST /networks/{id}/actions/delete_route

Path Parameters

Request

Response

The action key contains the delete_route Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/delete_route'

Request

{
  "destination": "10.100.1.0/24",
  "gateway": "10.0.1.1"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "delete_route",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change IP range of a Network

Changes the IP range of a Network. IP ranges can only be extended and never shrunk. You can only add IPs at the end of an existing IP range. This means that the IP part of your existing range must stay the same and you can only change its netmask.

For example if you have a range 10.0.0.0/16 you want to extend then your new range must also start with the IP 10.0.0.0. Your CIDR netmask /16 may change to a number that is smaller than 16 thereby increasing the IP range. So valid entries would be 10.0.0.0/15, 10.0.0.0/14, 10.0.0.0/13 and so on.

After changing the IP range you will have to adjust the routes on your connected Servers by either rebooting them or manually changing the routes to your private Network interface.

Note: if the Network object changes during the request, the response will be a “conflict” error.

HTTP Request

POST /networks/{id}/actions/change_ip_range

Path Parameters

Request

Response

The action key contains the change_ip_range Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip_range":"10.0.0.0/12"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/change_ip_range'

Request

{
  "ip_range": "10.0.0.0/12"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_ip_range",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change Network Protection

Changes the protection configuration of a Network.

Note: if the Network object changes during the request, the response will be a “conflict” error.

HTTP Request

POST /networks/{id}/actions/change_protection

Path Parameters

Request

Response

The action key contains the change_protection Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/change_protection'

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Pricing

Returns prices for resources.

Get all prices

Returns prices for all resources available on the platform. VAT and currency of the Project owner are used for calculations.

Both net and gross prices are included in the response.

HTTP Request

GET /pricing

Response

The pricing key in the reply contains an pricing object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/pricing'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "pricing": {
    "currency": "EUR",
    "vat_rate": "19.000000",
    "image": {
      "price_per_gb_month": {
        "net": "1.0000000000",
        "gross": "1.1900000000000000"
      }
    },
    "floating_ip": {
      "price_monthly": {
        "net": "1.0000000000",
        "gross": "1.1900000000000000"
      }
    },
    "traffic": {
      "price_per_tb": {
        "net": "1.0000000000",
        "gross": "1.1900000000000000"
      }
    },
    "server_backup": {
      "percentage": "20.0000000000"
    },
    "volume": {
      "price_per_gb_month": {
        "net": "1.0000000000",
        "gross": "1.1900000000000000"
      }
    },
    "server_types": [
      {
        "id": 4,
        "name": "cx11",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            },
            "price_monthly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            }
          }
        ]
      }
    ],
    "load_balancer_types": [
      {
        "id": 1,
        "name": "lb11",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            },
            "price_monthly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            }
          }
        ]
      }
    ]
  }
}

Servers

Servers are virtual machines that can be provisioned.

Get all Servers

Returns all existing Server objects

HTTP Request

GET /servers

Query Parameters

Response

A paged array of servers

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "servers": [
    {
      "id": 42,
      "name": "my-server",
      "status": "running",
      "created": "2016-01-30T23:50:00+00:00",
      "public_net": {
        "ipv4": {
          "ip": "1.2.3.4",
          "blocked": false,
          "dns_ptr": "server01.example.com"
        },
        "ipv6": {
          "ip": "2001:db8::/64",
          "blocked": false,
          "dns_ptr": [
            {
              "ip": "2001:db8::1",
              "dns_ptr": "server.example.com"
            }
          ]
        },
        "floating_ips": [
          478
        ]
      },
      "private_net": [
        {
          "network": 4711,
          "ip": "10.0.0.2",
          "alias_ips": [],
          "mac_address": "86:00:ff:2a:7d:e1"
        }
      ],
      "server_type": {
        "id": 1,
        "name": "cx11",
        "description": "CX11",
        "cores": 1,
        "memory": 1,
        "disk": 25,
        "deprecated": false,
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            },
            "price_monthly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            }
          }
        ],
        "storage_type": "local",
        "cpu_type": "shared"
      },
      "datacenter": {
        "id": 1,
        "name": "fsn1-dc8",
        "description": "Falkenstein 1 DC 8",
        "location": {
          "id": 1,
          "name": "fsn1",
          "description": "Falkenstein DC Park 1",
          "country": "DE",
          "city": "Falkenstein",
          "latitude": 50.47612,
          "longitude": 12.370071,
          "network_zone": "eu-central"
        },
        "server_types": {
          "supported": [
            1,
            2,
            3
          ],
          "available": [
            1,
            2,
            3
          ],
          "available_for_migration": [
            1,
            2,
            3
          ]
        }
      },
      "image": {
        "id": 4711,
        "type": "snapshot",
        "status": "available",
        "name": "ubuntu-20.04",
        "description": "Ubuntu 20.04 Standard 64 bit",
        "image_size": 2.3,
        "disk_size": 10,
        "created": "2016-01-30T23:50:00+00:00",
        "created_from": {
          "id": 1,
          "name": "Server"
        },
        "bound_to": null,
        "os_flavor": "ubuntu",
        "os_version": "20.04",
        "rapid_deploy": false,
        "protection": {
          "delete": false
        },
        "deprecated": "2018-02-28T00:00:00+00:00",
        "labels": {}
      },
      "iso": {
        "id": 4711,
        "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
        "description": "FreeBSD 11.0 x64",
        "type": "public",
        "deprecated": "2018-02-28T00:00:00+00:00"
      },
      "rescue_enabled": false,
      "locked": false,
      "backup_window": "22-02",
      "outgoing_traffic": 123456,
      "ingoing_traffic": 123456,
      "included_traffic": 654321,
      "protection": {
        "delete": false,
        "rebuild": false
      },
      "labels": {},
      "volumes": [],
      "load_balancers": []
    }
  ]
}

Create a Server

Creates a new Server. Returns preliminary information about the Server as well as an Action that covers progress of creation.

HTTP Request

POST /servers

Request

Please note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes). For server_type you can either use the ID as listed in /server_types or its name. For image you can either use the ID as listed in /images or its name. If you want to create the Server in a Location, you must set location to the ID or name as listed in /locations. This is the recommended way. You can be even more specific by setting datacenter to the ID or name as listed in /datacenters. However directly specifying the Datacenter is discouraged since supply availability in Datacenters varies greatly and Datacenters may be out of stock for extended periods of time or not serve certain Server types at all. Some properties like start_after_create or automount will trigger Actions after the Server is created. Those Actions are listed in the next_actions field in the response. For accessing your Server we strongly recommend to use SSH keys by passing the respective key IDs in ssh_keys. If you do not specify any ssh_keys we will generate a root password for you and return it in the response. Please note that provided user-data is stored in our systems. While we take measures to protect it we highly recommend that you don’t use it to store passwords or other sensitive information.

Response

The server key in the reply contains a Server object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"my-server","server_type":"cx11","start_after_create":true,"image":"ubuntu-20.04","ssh_keys":["my-ssh-key"],"volumes":[],"networks":[],"user_data":"#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n","labels":{},"automount":false}' \
	'https://api.hetzner.cloud/v1/servers'

Request

{
  "name": "my-server",
  "server_type": "cx11",
  "start_after_create": true,
  "image": "ubuntu-20.04",
  "ssh_keys": [
    "my-ssh-key"
  ],
  "volumes": [],
  "networks": [],
  "user_data": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n",
  "labels": {},
  "automount": false
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "server": {
    "id": 42,
    "name": "my-server",
    "status": "initializing",
    "created": "2016-01-30T23:50:00+00:00",
    "public_net": {
      "ipv4": {
        "ip": "1.2.3.4",
        "blocked": false,
        "dns_ptr": "server01.example.com"
      },
      "ipv6": {
        "ip": "2001:db8::/64",
        "blocked": false,
        "dns_ptr": [
          {
            "ip": "2001:db8::1",
            "dns_ptr": "server.example.com"
          }
        ]
      },
      "floating_ips": [
        478
      ]
    },
    "private_net": [
      {
        "network": 4711,
        "ip": "10.0.0.2",
        "alias_ips": [],
        "mac_address": "86:00:ff:2a:7d:e1"
      }
    ],
    "server_type": {
      "id": 1,
      "name": "cx11",
      "description": "CX11",
      "cores": 1,
      "memory": 1,
      "disk": 25,
      "deprecated": true,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ],
      "storage_type": "local",
      "cpu_type": "shared"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071,
        "network_zone": "eu-central"
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ],
        "available_for_migration": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-20.04",
      "description": "Ubuntu 20.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50:00+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "20.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00",
      "labels": {}
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    },
    "labels": {},
    "volumes": [],
    "load_balancers": []
  },
  "action": {
    "id": 1,
    "command": "create_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  },
  "next_actions": [
    {
      "id": 13,
      "command": "start_server",
      "status": "running",
      "progress": 0,
      "started": "2016-01-30T23:50:00+00:00",
      "finished": null,
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ],
  "root_password": "YItygq1v3GYjjMomLaKc"
}

Get a Server

Returns a specific Server object. The Server must exist inside the Project

HTTP Request

GET /servers/{id}

Path Parameters

Response

The server key in the reply contains a Server object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "server": {
    "id": 42,
    "name": "my-server",
    "status": "running",
    "created": "2016-01-30T23:50:00+00:00",
    "public_net": {
      "ipv4": {
        "ip": "1.2.3.4",
        "blocked": false,
        "dns_ptr": "server01.example.com"
      },
      "ipv6": {
        "ip": "2001:db8::/64",
        "blocked": false,
        "dns_ptr": [
          {
            "ip": "2001:db8::1",
            "dns_ptr": "server.example.com"
          }
        ]
      },
      "floating_ips": [
        478
      ]
    },
    "private_net": [
      {
        "network": 4711,
        "ip": "10.0.0.2",
        "alias_ips": [],
        "mac_address": "86:00:ff:2a:7d:e1"
      }
    ],
    "server_type": {
      "id": 1,
      "name": "cx11",
      "description": "CX11",
      "cores": 1,
      "memory": 1,
      "disk": 25,
      "deprecated": false,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ],
      "storage_type": "local",
      "cpu_type": "shared"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071,
        "network_zone": "eu-central"
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ],
        "available_for_migration": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-20.04",
      "description": "Ubuntu 20.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50:00+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "20.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00",
      "labels": {}
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    },
    "labels": {},
    "volumes": [],
    "load_balancers": []
  }
}

Update a Server

Updates a Server. You can update a Server’s name and a Server’s labels. Please note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes). Also note that when updating labels, the Server’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

HTTP Request

PUT /servers/{id}

Path Parameters

Request

Response

The server key in the reply contains the updated Server

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"my-server","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/servers/{id}'

Request

{
  "name": "my-server",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "server": {
    "id": 42,
    "name": "my-server",
    "status": "running",
    "created": "2016-01-30T23:50:00+00:00",
    "public_net": {
      "ipv4": {
        "ip": "1.2.3.4",
        "blocked": false,
        "dns_ptr": "server01.example.com"
      },
      "ipv6": {
        "ip": "2001:db8::/64",
        "blocked": false,
        "dns_ptr": [
          {
            "ip": "2001:db8::1",
            "dns_ptr": "server.example.com"
          }
        ]
      },
      "floating_ips": [
        478
      ]
    },
    "private_net": [
      {
        "network": 4711,
        "ip": "10.0.0.2",
        "alias_ips": [],
        "mac_address": "86:00:ff:2a:7d:e1"
      }
    ],
    "server_type": {
      "id": 1,
      "name": "cx11",
      "description": "CX11",
      "cores": 1,
      "memory": 1,
      "disk": 25,
      "deprecated": false,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ],
      "storage_type": "local",
      "cpu_type": "shared"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071,
        "network_zone": "eu-central"
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ],
        "available_for_migration": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-20.04",
      "description": "Ubuntu 20.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50:00+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "20.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00",
      "labels": {}
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    },
    "labels": {},
    "volumes": [],
    "load_balancers": []
  }
}

Delete a Server

Deletes a Server. This immediately removes the Server from your account, and it is no longer accessible.

HTTP Request

DELETE /servers/{id}

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 13,
    "command": "delete_server",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Get Metrics for a Server

Get Metrics for specified Server.

You must specify the type of metric to get: cpu, disk or network. You can also specify more than one type by comma separation, e.g. cpu,disk.

Depending on the type you will get different time series data

Type Timeseries Unit Description
cpu cpu percent Percent CPU usage
disk disk.0.iops.read iop/s Number of read IO operations per second
disk.0.iops.write iop/s Number of write IO operations per second
disk.0.bandwidth.read bytes/s Bytes read per second
disk.0.bandwidth.write bytes/s Bytes written per second
network network.0.pps.in packets/s Public Network interface packets per second received
network.0.pps.out packets/s Public Network interface packets per second sent
network.0.bandwidth.in bytes/s Public Network interface bytes/s received
network.0.bandwidth.out bytes/s Public Network interface bytes/s sent

Metrics are available for the last 30 days only.

If you do not provide the step argument we will automatically adjust it so that a maximum of 100 samples are returned.

We limit the number of samples returned to a maximum of 500 and will adjust the step parameter accordingly.

HTTP Request

GET /servers/{id}/metrics

Path Parameters

Query Parameters

Response

The metrics key in the reply contains a metrics object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/metrics'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "metrics": {
    "start": "2017-01-01T00:00:00+00:00",
    "end": "2017-01-01T23:00:00+00:00",
    "step": 60,
    "time_series": {
      "name_of_timeseries": {
        "values": [
          [
            1435781470.622,
            "42"
          ],
          [
            1435781471.622,
            "43"
          ]
        ]
      }
    }
  }
}

Server Actions

Get all Actions for a Server

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.

HTTP Request

GET /servers/{id}/actions

Path Parameters

Query Parameters

Response

The action key contains a list of Actions

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 13,
      "command": "start_server",
      "status": "success",
      "progress": 100,
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:56:00+00:00",
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}

Get an Action for a Server

Returns a specific Action object for a Server.

HTTP Request

GET /servers/{id}/actions/{action_id}

Path Parameters

Response

The action key in the reply has this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 13,
    "command": "start_server",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Power on a Server

Starts a Server by turning its power on.

HTTP Request

POST /servers/{id}/actions/poweron

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/poweron'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "start_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Soft-reboot a Server

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.

HTTP Request

POST /servers/{id}/actions/reboot

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/reboot'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "reboot_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Reset a Server

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.

HTTP Request

POST /servers/{id}/actions/reset

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/reset'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "reset_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Shutdown a Server

Shuts down a Server gracefully by sending an ACPI shutdown request. The Server operating system must support ACPI and react to the request, otherwise the Server will not shut down.

HTTP Request

POST /servers/{id}/actions/shutdown

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/shutdown'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "shutdown_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Power off a Server

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.

HTTP Request

POST /servers/{id}/actions/poweroff

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/poweroff'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "stop_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Reset root Password of a Server

Resets the root password. Only works for Linux systems that are running the qemu guest agent. Server must be powered on (state on) in order for this operation to succeed.

This will generate a new password for this Server and return it.

If this does not succeed you can use the rescue system to netboot the Server and manually change your Server password by hand.

HTTP Request

POST /servers/{id}/actions/reset_password

Path Parameters

Response

The root_password key in the reply contains the new root password that will be active if the Action succeeds.

The action key in the reply contains an Action object with this structure:

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/reset_password'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "root_password": "zCWbFhnu950dUTko5f40",
  "action": {
    "id": 13,
    "command": "reset_password",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Enable Rescue Mode for a Server

Enable the Hetzner Rescue System for this Server. The next time a Server with enabled rescue mode boots it will start a special minimal Linux distribution designed for repair and reinstall.

In case a Server cannot boot on its own you can use this to access a Server’s disks.

Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.

Enabling rescue mode will not reboot your Server — you will have to do this yourself.

HTTP Request

POST /servers/{id}/actions/enable_rescue

Path Parameters

Request

Response

The root_password key in the reply contains the root password that can be used to access the booted rescue system.

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"type":"linux64","ssh_keys":[2323]}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/enable_rescue'

Request

{
  "type": "linux64",
  "ssh_keys": [
    2323
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "root_password": "zCWbFhnu950dUTko5f40",
  "action": {
    "id": 13,
    "command": "enable_rescue",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Disable Rescue Mode for a Server

Disables the Hetzner Rescue System for a Server. This makes a Server start from its disks on next reboot.

Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.

Disabling rescue mode will not reboot your Server — you will have to do this yourself.

HTTP Request

POST /servers/{id}/actions/disable_rescue

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/disable_rescue'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "disable_rescue",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Create Image from a Server

Creates an Image (snapshot) from a Server by copying the contents of its disks. This creates a snapshot of the current state of the disk and copies it into an Image. If the Server is currently running you must make sure that its disk content is consistent. Otherwise, the created Image may not be readable.

To make sure disk content is consistent, we recommend to shut down the Server prior to creating an Image.

You can either create a backup Image that is bound to the Server and therefore will be deleted when the Server is deleted, or you can create an 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.

HTTP Request

POST /servers/{id}/actions/create_image

Path Parameters

Request

Response

The image key in the reply contains an the created Image, which is an object with this structure

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"description":"my image","type":"snapshot","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/create_image'

Request

{
  "description": "my image",
  "type": "snapshot",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "image": {
    "id": 4711,
    "type": "snapshot",
    "status": "creating",
    "name": null,
    "description": "my image",
    "image_size": 2.3,
    "disk_size": 10,
    "created": "2016-01-30T23:50:00+00:00",
    "created_from": {
      "id": 1,
      "name": "Server"
    },
    "bound_to": null,
    "os_flavor": "ubuntu",
    "os_version": "20.04",
    "rapid_deploy": false,
    "protection": {
      "delete": false
    },
    "deprecated": "2018-02-28T00:00:00+00:00",
    "labels": {}
  },
  "action": {
    "id": 13,
    "command": "create_image",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Rebuild a Server from an Image

Rebuilds a Server overwriting its disk with the content of an Image, thereby destroying all data on the target Server

The Image can either be one you have created earlier (backup or snapshot Image) or it can be a completely fresh system Image provided by us. You can get a list of all available Images with GET /images.

Your Server will automatically be powered off before the rebuild command executes.

HTTP Request

POST /servers/{id}/actions/rebuild

Path Parameters

Request

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.

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"image":"ubuntu-20.04"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/rebuild'

Request

{
  "image": "ubuntu-20.04"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "rebuild_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  },
  "root_password": null
}

Change the Type of a Server

Changes the type (Cores, RAM and disk sizes) of a Server.

Server must be powered off for this command to succeed.

This copies the content of its disk, and starts it again.

You can only migrate to Server types with the same storage_type and equal or bigger disks. Shrinking disks is not possible as it might destroy data.

If the disk gets upgraded, the Server type can not be downgraded any more. If you plan to downgrade the Server type, set upgrade_disk to false.

HTTP Request

POST /servers/{id}/actions/change_type

Path Parameters

Request

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"upgrade_disk":true,"server_type":"cx11"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/change_type'

Request

{
  "upgrade_disk": true,
  "server_type": "cx11"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_server_type",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Enable and Configure Backups for a Server

Enables and configures the automatic daily backup option for the Server. Enabling automatic backups will increase the price of the Server by 20%. In return, you will get seven slots where Images of type backup can be stored.

Backups are automatically created daily.

HTTP Request

POST /servers/{id}/actions/enable_backup

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/enable_backup'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "enable_backup",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Disable Backups for a Server

Disables the automatic backup option and deletes all existing Backups for a Server. No more additional charges for backups will be made.

Caution: This immediately removes all existing backups for the Server!

HTTP Request

POST /servers/{id}/actions/disable_backup

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/disable_backup'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "disable_backup",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Attach an ISO to a Server

Attaches an ISO to a Server. The Server will immediately see it as a new disk. An already attached ISO will automatically be detached before the new ISO is attached.

Servers with attached ISOs have a modified boot order: They will try to boot from the ISO first before falling back to hard disk.

HTTP Request

POST /servers/{id}/actions/attach_iso

Path Parameters

Request

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"iso":"FreeBSD-11.0-RELEASE-amd64-dvd1"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/attach_iso'

Request

{
  "iso": "FreeBSD-11.0-RELEASE-amd64-dvd1"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "attach_iso",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Detach an ISO from a Server

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

HTTP Request

POST /servers/{id}/actions/detach_iso

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/detach_iso'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "detach_iso",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change reverse DNS entry for this Server

Changes the hostname that will appear when getting the hostname belonging to the primary IPs (IPv4 and IPv6) of this Server.

Floating IPs assigned to the Server are not affected by this.

HTTP Request

POST /servers/{id}/actions/change_dns_ptr

Path Parameters

Request

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.

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip":"1.2.3.4","dns_ptr":"server01.example.com"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/change_dns_ptr'

Request

{
  "ip": "1.2.3.4",
  "dns_ptr": "server01.example.com"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_dns_ptr",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change Server Protection

Changes the protection configuration of the Server.

HTTP Request

POST /servers/{id}/actions/change_protection

Path Parameters

Request

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true,"rebuild":true}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/change_protection'

Request

{
  "delete": true,
  "rebuild": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Request Console for a Server

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.

HTTP Request

POST /servers/{id}/actions/request_console

Path Parameters

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/request_console'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "wss_url": "wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c",
  "password": "9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x",
  "action": {
    "id": 13,
    "command": "request_console",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Attach a Server to a Network

Attaches a Server to a network. This will complement the fixed public Server interface by adding an additional ethernet interface to the Server which is connected to the specified network.

The Server will get an IP auto assigned from a subnet of type server in the same network_zone.

Using the alias_ips attribute you can also define one or more additional IPs to the Servers. Please note that you will have to configure these IPs by hand on your Server since only the primary IP will be given out by dhcp.

HTTP Request

POST /servers/{id}/actions/attach_to_network

Path Parameters

Request

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"network":4711,"ip":"10.0.1.1","alias_ips":["10.0.1.2"]}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/attach_to_network'

Request

{
  "network": 4711,
  "ip": "10.0.1.1",
  "alias_ips": [
    "10.0.1.2"
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "attach_to_network",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Detach a Server from a Network

Detaches a Server from a network. The interface for this network will vanish.

HTTP Request

POST /servers/{id}/actions/detach_from_network

Path Parameters

Request

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"network":4711}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/detach_from_network'

Request

{
  "network": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "detach_from_network",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change alias IPs of a Network

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.

HTTP Request

POST /servers/{id}/actions/change_alias_ips

Path Parameters

Request

Response

The action key in the reply contains an Action object with this structure

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"network":4711,"alias_ips":["10.0.1.2"]}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/change_alias_ips'

Request

{
  "network": 4711,
  "alias_ips": [
    "10.0.1.2"
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_alias_ips",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Server Types

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.

Currency for all amounts is €. All prices exclude VAT.

Get all Server Types

Gets all Server type objects.

HTTP Request

GET /server_types

Query Parameters

Response

The server_types key in the reply contains an array of Server type objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/server_types'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "server_types": [
    {
      "id": 1,
      "name": "cx11",
      "description": "CX11",
      "cores": 1,
      "memory": 1,
      "disk": 24,
      "deprecated": false,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ],
      "storage_type": "local",
      "cpu_type": "shared"
    }
  ]
}

Get a Server Type

Gets a specific Server type object.

HTTP Request

GET /server_types/{id}

Path Parameters

Response

The server_type key in the reply contains a Server type object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/server_types/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "server_type": {
    "id": 1,
    "name": "cx11",
    "description": "CX11",
    "cores": 1,
    "memory": 1,
    "disk": 24,
    "deprecated": false,
    "prices": [
      {
        "location": "fsn1",
        "price_hourly": {
          "net": "1.0000000000",
          "gross": "1.1900000000000000"
        },
        "price_monthly": {
          "net": "1.0000000000",
          "gross": "1.1900000000000000"
        }
      }
    ],
    "storage_type": "local",
    "cpu_type": "shared"
  }
}

SSH Keys

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.

Get all SSH keys

Returns all SSH key objects.

HTTP Request

GET /ssh_keys

Query Parameters

Response

The ssh_keys key in the reply contains an array of SSH key objects with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/ssh_keys'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "ssh_keys": [
    {
      "id": 2323,
      "name": "My ssh key",
      "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
      "public_key": "ssh-rsa AAAjjk76kgf...Xt",
      "labels": {},
      "created": "2016-01-30T23:50:00+00:00"
    }
  ]
}

Create an SSH key

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.

HTTP Request

POST /ssh_keys

Request

Response

The ssh_key key in the reply contains the object that was just created

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"My ssh key","public_key":"ssh-rsa AAAjjk76kgf...Xt","labels":{}}' \
	'https://api.hetzner.cloud/v1/ssh_keys'

Request

{
  "name": "My ssh key",
  "public_key": "ssh-rsa AAAjjk76kgf...Xt",
  "labels": {}
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "ssh_key": {
    "id": 2323,
    "name": "My ssh key",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt",
    "labels": {},
    "created": "2016-01-30T23:50:00+00:00"
  }
}

Get a SSH key

Returns a specific SSH key object.

HTTP Request

GET /ssh_keys/{id}

Path Parameters

Response

The ssh_key key in the reply contains an SSH key object with this structure

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/ssh_keys/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "ssh_key": {
    "id": 2323,
    "name": "My ssh key",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt",
    "labels": {},
    "created": "2016-01-30T23:50:00+00:00"
  }
}

Update an SSH key

Updates an SSH key. You can update an SSH key name and an SSH key labels.

Please note that when updating labels, the SSH key current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

HTTP Request

PUT /ssh_keys/{id}

Path Parameters

Request

Response

The ssh_key key in the reply contains the modified SSH key object with the new description

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"My ssh key","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/ssh_keys/{id}'

Request

{
  "name": "My ssh key",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "ssh_key": {
    "id": 2323,
    "name": "My ssh key",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt",
    "labels": {
      "labelkey": "value"
    },
    "created": "2016-01-30T23:50:00+00:00"
  }
}

Delete an SSH key

Deletes an SSH key. It cannot be used anymore.

HTTP Request

DELETE /ssh_keys/{id}

Path Parameters

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/ssh_keys/{id}'

Response headers

Status: 204

Volumes

A Volume is a highly-available, scalable, and SSD-based block storage for Servers.

Pricing for Volumes depends on the Volume size and Location, not the actual used storage.

Please see Hetzner Docs for more details about Volumes.

Get all Volumes

Gets all existing Volumes that you have available.

HTTP Request

GET /volumes

Query Parameters

Response

The volumes key contains a list of volumes

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "volumes": [
    {
      "id": 4711,
      "created": "2016-01-30T23:50:11+00:00",
      "name": "database-storage",
      "server": 12,
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071,
        "network_zone": "eu-central"
      },
      "size": 42,
      "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
      "protection": {
        "delete": false
      },
      "labels": {},
      "status": "available",
      "format": "xfs"
    }
  ]
}

Create a Volume

Creates a new Volume attached to a Server. If you want to create a Volume that is not attached to a Server, you need to provide the location key instead of server. This can be either the ID or the name of the Location this Volume will be created in. Note that a Volume can be attached to a Server only in the same Location as the Volume itself.

Specifying the Server during Volume creation will automatically attach the Volume to that Server after it has been initialized. In that case, the next_actions key in the response is an array which contains a single attach_volume action.

The minimum Volume size is 10GB and the maximum size is 10TB (10240GB).

A volume’s name can consist of alphanumeric characters, dashes, underscores, and dots, but has to start and end with an alphanumeric character. The total length is limited to 64 characters. Volume names must be unique per Project.

HTTP Request

POST /volumes

Request

Response

The volume key contains the Volume that was just created

The action key contains the Action tracking Volume creation

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"size":42,"name":"test-database","labels":{"labelkey":"value"},"location":"nbg1","automount":false,"format":"xfs"}' \
	'https://api.hetzner.cloud/v1/volumes'

Request

{
  "size": 42,
  "name": "test-database",
  "labels": {
    "labelkey": "value"
  },
  "location": "nbg1",
  "automount": false,
  "format": "xfs"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "volume": {
    "id": 4711,
    "created": "2016-01-30T23:50:11+00:00",
    "name": "database-storage",
    "server": 12,
    "location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "size": 42,
    "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
    "protection": {
      "delete": false
    },
    "labels": {},
    "status": "available",
    "format": "xfs"
  },
  "action": {
    "id": 13,
    "command": "create_volume",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 554,
        "type": "volume"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  },
  "next_actions": [
    {
      "id": 13,
      "command": "attach_volume",
      "status": "running",
      "progress": 0,
      "started": "2016-01-30T23:50:00+00:00",
      "finished": null,
      "resources": [
        {
          "id": 42,
          "type": "server"
        },
        {
          "id": 554,
          "type": "volume"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}

Get a Volume

Gets a specific Volume object.

HTTP Request

GET /volumes/{id}

Path Parameters

Response

The volume key contains the volume

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "volume": {
    "id": 4711,
    "created": "2016-01-30T23:50:11+00:00",
    "name": "database-storage",
    "server": 12,
    "location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "size": 42,
    "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
    "protection": {
      "delete": false
    },
    "labels": {},
    "status": "available",
    "format": "xfs"
  }
}

Update a Volume

Updates the Volume properties.

Note that when updating labels, the volume’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

HTTP Request

PUT /volumes/{id}

Path Parameters

Request

Response

The volume key contains the updated volume

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"database-storage","labels":{"labelkey":"value"}}' \
	'https://api.hetzner.cloud/v1/volumes/{id}'

Request

{
  "name": "database-storage",
  "labels": {
    "labelkey": "value"
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "volume": {
    "id": 4711,
    "created": "2016-01-30T23:50:11+00:00",
    "name": "database-storage",
    "server": 12,
    "location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "size": 42,
    "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
    "protection": {
      "delete": false
    },
    "labels": {
      "labelkey": "value"
    },
    "status": "available",
    "format": "xfs"
  }
}

Delete a Volume

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.

HTTP Request

DELETE /volumes/{id}

Path Parameters

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}'

Response headers

Status: 204

Volume Actions

Get all Actions for a Volume

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.

HTTP Request

GET /volumes/{id}/actions

Path Parameters

Query Parameters

Response

The actions key contains a list of Actions

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 13,
      "command": "attach_volume",
      "status": "success",
      "progress": 100,
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:56:00+00:00",
      "resources": [
        {
          "id": 42,
          "type": "server"
        },
        {
          "id": 13,
          "type": "volume"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}

Get an Action for a Volume

Returns a specific Action for a Volume.

HTTP Request

GET /volumes/{id}/actions/{action_id}

Path Parameters

Response

The action key contains the Volume Action

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 13,
    "command": "attach_volume",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Attach Volume to a Server

Attaches a Volume to a Server. Works only if the Server is in the same Location as the Volume.

HTTP Request

POST /volumes/{id}/actions/attach

Path Parameters

Request

Response

The action key contains the attach_volume Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"server":43,"automount":false}' \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/attach'

Request

{
  "server": 43,
  "automount": false
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "attach_volume",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 43,
        "type": "server"
      },
      {
        "id": 554,
        "type": "volume"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Detach Volume

Detaches a Volume from the Server it’s attached to. You may attach it to a Server again at a later time.

HTTP Request

POST /volumes/{id}/actions/detach

Path Parameters

Response

The action key contains the detach_volume Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/detach'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "detach_volume",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Resize Volume

Changes the size of a Volume. Note that downsizing a Volume is not possible.

HTTP Request

POST /volumes/{id}/actions/resize

Path Parameters

Request

Response

The action key contains the resize_volume Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"size":50}' \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/resize'

Request

{
  "size": 50
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "resize_volume",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 554,
        "type": "volume"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change Volume Protection

Changes the protection configuration of a Volume.

HTTP Request

POST /volumes/{id}/actions/change_protection

Path Parameters

Request

Response

The action key contains the change_protection Action

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/change_protection'

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 554,
        "type": "volume"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}