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:
- Our CLI program hcloud
- Our library for Go
- Our library for Python
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 Security
→ API Tokens
, and generate a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is 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.
To create a new API token for your Project, switch into the Hetzner Cloud Console choose a Project, go to Security
→ API Tokens
, and generate 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 |
token_readonly |
The token is only allowed to perform GET requests |
unavailable |
A service or product is currently not available |
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 all resources.
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 atype=database
label:env=production,type!=database
Returns all resources that have a
env=testing
orenv=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/v1/actions?page=2&per_page=5>; rel="prev",
<https://api.hetzner.cloud/v1/actions?page=4&per_page=5>; rel="next",
<https://api.hetzner.cloud/v1/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 |
availability-zone | text | Name of the availability zone that Server runs in |
region | text | Network zone, e.g. eu-central |
Example: Summary
$ curl http://169.254.169.254/hetzner/v1/metadata
availability-zone: hel1-dc2
hostname: my-server
instance-id: 42
public-ipv4: 1.2.3.4
region: eu-central
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
Example: Availability Zone
$ curl http://169.254.169.254/hetzner/v1/metadata/availability-zone
hel1-dc2
Example: Region
$ curl http://169.254.169.254/hetzner/v1/metadata/region
eu-central
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/v1/actions?sort=status
https://api.hetzner.cloud/v1/actions?sort=status:asc
https://api.hetzner.cloud/v1/actions?sort=status:desc
https://api.hetzner.cloud/v1/actions?sort=status:asc&sort=command:desc
Actions
Actions show the results and progress of asynchronous requests to the API.
Get 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
- idinteger
Can be used multiple times, the response will contain only Actions with specified IDs
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
- metaobject
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": [
{
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:55:00+00:00",
"id": 42,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
],
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
}
}
Get an Action
Returns a specific Action object.
HTTP Request
GET /actions/{id}
Path Parameters
- idinteger required
ID of the Resource
Response
- actionobject required
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": {
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:55:00+00:00",
"id": 42,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- sortstringPossible enum values:
id
id:asc
id:desc
name
name:asc
name:desc
created
created:asc
created:desc
Can be used multiple times.
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
- typestringPossible enum values:
uploaded
managed
Can be used multiple times. The response will only contain Certificates matching the type.
Response
- certificatesarray of objects required
- metaobject
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": [
{
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00+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",
"id": 897,
"labels": {
"env": "dev"
},
"name": "my website cert",
"not_valid_after": "2019-07-08T09:59:59+00:00",
"not_valid_before": "2019-01-08T10:00:00+00:00",
"status": null,
"type": "uploaded",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
]
}
Create a Certificate
Creates a new Certificate.
The default type uploaded allows for uploading your existing certificate
and private_key
in PEM format. You have to monitor its expiration date and handle renewal yourself.
In contrast, type managed requests a new Certificate from Let's Encrypt for the specified domain_names
. Only domains managed by Hetzner DNS are supported. We handle renewal and timely alert the project owner via email if problems occur.
For type managed
Certificates the action
key of the response contains the Action that allows for tracking the issuance process. For type uploaded
Certificates the action
is always null.
HTTP Request
POST /certificates
Request
- certificatestring
Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. Required for type
uploaded
Certificates. - domain_namesarray of strings
Domains and subdomains that should be contained in the Certificate issued by Let's Encrypt. Required for type
managed
Certificates. - labelsobject
User-defined labels (key-value pairs)
- namestring required
Name of the Certificate
- private_keystring
Certificate key in PEM format. Required for type
uploaded
Certificates. - typestringPossible enum values:
uploaded
managed
Choose between uploading a Certificate in PEM format or requesting a managed Let's Encrypt Certificate. If omitted defaults to
uploaded
.
Response
- actionobject – nullable
- certificateobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"domain_names":["example.com","webmail.example.com","www.example.com"],"name":"my website cert","type":"managed"}' \
'https://api.hetzner.cloud/v1/certificates'
Request
{
"domain_names": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"name": "my website cert",
"type": "managed"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "create_certificate",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 879,
"type": "certificate"
}
],
"started": "2019-01-08T12:10:00+00:00",
"status": "running"
},
"certificate": {
"certificate": null,
"created": "2019-01-08T12:10:00+00:00",
"domain_names": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"fingerprint": null,
"id": 897,
"labels": {
"env": "dev"
},
"name": "my website cert",
"not_valid_after": null,
"not_valid_before": null,
"status": {
"error": null,
"issuance": "pending",
"renewal": "unavailable"
},
"type": "managed",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}
Delete a Certificate
Deletes a Certificate.
HTTP Request
DELETE /certificates/{id}
Path Parameters
- idinteger required
ID of the resource
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/certificates/{id}'
Response headers
Status: 204
Get a Certificate
Gets a specific Certificate object.
HTTP Request
GET /certificates/{id}
Path Parameters
- idinteger required
ID of the resource
Response
- certificateobject required
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": {
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00+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",
"id": 897,
"labels": {
"env": "dev"
},
"name": "my website cert",
"not_valid_after": "2019-07-08T09:59:59+00:00",
"not_valid_before": "2019-01-08T10:00:00+00:00",
"status": null,
"type": "uploaded",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}
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
- idinteger required
ID of the resource
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring
New Certificate name
Response
- certificateobject required
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{"labelkey":"value"},"name":"my website cert"}' \
'https://api.hetzner.cloud/v1/certificates/{id}'
Request
{
"labels": {
"labelkey": "value"
},
"name": "my website cert"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"certificate": {
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00+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",
"id": 897,
"labels": {
"labelkey": "value"
},
"name": "my website cert",
"not_valid_after": "2019-07-08T09:59:59+00:00",
"not_valid_before": "2019-01-08T10:00:00+00:00",
"status": null,
"type": "uploaded",
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}
Certificate Actions
Get all Actions for a Certificate
Returns all Action objects for a Certificate. You can sort the results by using the sort
URI parameter, and filter them with the status
parameter.
Only type managed
Certificates can have Actions. For type uploaded
Certificates the actions
key will always contain an empty array.
HTTP Request
GET /certificates/{id}/actions
Path Parameters
- idinteger required
ID of the Resource
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
- metaobject
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/certificates/{id}/actions'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"actions": [
{
"command": "issue_certificate",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2021-01-30T23:57:00+00:00",
"id": 14,
"progress": 100,
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"started": "2021-01-30T23:55:00+00:00",
"status": "success"
}
]
}
Get an Action for a Certificate
Returns a specific Action for a Certificate. Only type managed
Certificates have Actions.
HTTP Request
GET /certificates/{id}/actions/{action_id}
Path Parameters
- idinteger required
ID of the Certificate
- action_idinteger required
ID of the Action
Response
- actionobject required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/certificates/{id}/actions/{action_id}'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"action": {
"command": "issue_certificate",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2021-01-30T23:57:00+00:00",
"id": 14,
"progress": 100,
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"started": "2021-01-30T23:55:00+00:00",
"status": "success"
}
}
Retry Issuance or Renewal
Retry a failed Certificate issuance or renewal.
Only applicable if the type of the Certificate is managed
and the issuance or renewal status is failed
.
Call specific error codes
Code | Description |
---|---|
caa_record_does_not_allow_ca |
CAA record does not allow certificate authority |
ca_dns_validation_failed |
Certificate Authority: DNS validation failed |
ca_too_many_authorizations_failed_recently |
Certificate Authority: Too many authorizations failed recently |
ca_too_many_certificates_issued_for_registered_domain |
Certificate Authority: Too many certificates issued for registered domain |
ca_too_many_duplicate_certificates |
Certificate Authority: Too many duplicate certificates |
could_not_verify_domain_delegated_to_zone |
Could not verify domain delegated to zone |
dns_zone_not_found |
DNS zone not found |
dns_zone_is_secondary_zone |
DNS zone is a secondary zone |
HTTP Request
POST /certificates/{id}/actions/retry
Path Parameters
- idinteger required
ID of the Certificate
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/certificates/{id}/actions/retry'
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "issue_certificate",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2021-01-30T23:57:00+00:00",
"id": 14,
"progress": 100,
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"started": "2021-01-30T23:55:00+00:00",
"status": "success"
}
}
Datacenters
Each Datacenter represents a virtual Datacenter which is made up of possible many physical Datacenters where Servers are hosted.
Datacenter names are composed from their Location and virtual Datacenter number, for example fsn1-dc14
means virtual Datacenter 14
in Location fsn1
.
Right now there is only one Datacenter for each Location. The Datacenter numbers for fsn
, nbg
and hel
are arbitrarily set to 14
, 3
and 2
for historic reasons and do not represent real physical Hetzner datacenters.
Get all Datacenters
Returns all Datacenter objects.
HTTP Request
GET /datacenters
Query Parameters
- namestring
Can be used to filter Datacenters by their name. The response will only contain the Datacenter matching the specified name. When the name does not match the Datacenter name format, an
invalid_input
error is returned.
Response
- datacentersarray of objects required
- recommendationnumber required
The Datacenter which is recommended to be used to create new Servers.
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": [
{
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
}
],
"recommendation": 1
}
Get a Datacenter
Returns a specific Datacenter object.
HTTP Request
GET /datacenters/{id}
Path Parameters
- idinteger required
ID of Datacenter
Response
- datacenterobject required
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": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
}
}
Firewalls
Firewalls can limit the network access to or from your resources.
- When applying a firewall with no
in
rule all inbound traffic will be dropped. The default forin
isDROP
. - When applying a firewall with no
out
rule all outbound traffic will be accepted. The default forout
isACCEPT
.
Get all Firewalls
Returns all Firewall objects.
HTTP Request
GET /firewalls
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
name
name:asc
name:desc
created
created:asc
created:desc
Can be used multiple times.
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
Response
- firewallsarray of objects required
- metaobject
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/firewalls'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"firewalls": [
{
"applied_to": [
{
"applied_to_resources": [
{
"server": {
"id": 42
},
"type": "server"
}
],
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 42
},
"type": "server"
}
],
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"labels": {},
"name": "my-resource",
"rules": [
{
"description": null,
"destination_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
]
}
],
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
}
}
Create a Firewall
Creates a new Firewall.
Call specific error codes
Code | Description |
---|---|
server_already_added |
Server added more than one time to resource |
incompatible_network_type |
The Network type is incompatible for the given resource |
firewall_resource_not_found |
The resource the Firewall should be attached to was not found |
HTTP Request
POST /firewalls
Request
- apply_toarray of objects
Resources the Firewall should be applied to after creation
- labelsobject
User-defined labels (key-value pairs)
- namestring required
Name of the Firewall
- rulesarray of objects
Array of rules
Response
- actionsarray of objects
- firewallobject
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"apply_to":[{"server":{"id":42},"type":"server"}],"labels":{"env":"dev"},"name":"Corporate Intranet Protection","rules":[{"description":"Allow port 80","direction":"in","port":"80","protocol":"tcp","source_ips":["28.239.13.1/32","28.239.14.0/24","ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"]}]}' \
'https://api.hetzner.cloud/v1/firewalls'
Request
{
"apply_to": [
{
"server": {
"id": 42
},
"type": "server"
}
],
"labels": {
"env": "dev"
},
"name": "Corporate Intranet Protection",
"rules": [
{
"description": "Allow port 80",
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
]
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"actions": [
{
"command": "set_firewall_rules",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
},
{
"command": "apply_firewall",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 14,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
],
"firewall": {
"applied_to": [
{
"applied_to_resources": [
{
"server": {
"id": 42
},
"type": "server"
}
],
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 42
},
"type": "server"
}
],
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"labels": {},
"name": "my-resource",
"rules": [
{
"description": null,
"destination_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
]
}
}
Delete a Firewall
Deletes a Firewall.
Call specific error codes
Code | Description |
---|---|
resource_in_use |
Firewall must not be in use to be deleted |
HTTP Request
DELETE /firewalls/{id}
Path Parameters
- idinteger required
ID of the resource
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/firewalls/{id}'
Response headers
Status: 204
Get a Firewall
Gets a specific Firewall object.
HTTP Request
GET /firewalls/{id}
Path Parameters
- idinteger required
ID of the resource
Response
- firewallobject required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/firewalls/{id}'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"firewall": {
"applied_to": [
{
"applied_to_resources": [
{
"server": {
"id": 42
},
"type": "server"
}
],
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 42
},
"type": "server"
}
],
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"labels": {},
"name": "my-resource",
"rules": [
{
"description": null,
"destination_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
]
}
}
Update a Firewall
Updates the Firewall.
Note that when updating labels, the Firewall'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 Firewall object changes during the request, the response will be a “conflict” error.
HTTP Request
PUT /firewalls/{id}
Path Parameters
- idinteger required
ID of the resource
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring
New Firewall name
Response
- firewallobject required
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{"labelkey":"value"},"name":"new-name"}' \
'https://api.hetzner.cloud/v1/firewalls/{id}'
Request
{
"labels": {
"labelkey": "value"
},
"name": "new-name"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"firewall": {
"applied_to": [
{
"applied_to_resources": [
{
"server": {
"id": 42
},
"type": "server"
}
],
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 42
},
"type": "server"
}
],
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"labels": {},
"name": "my-resource",
"rules": [
{
"description": null,
"destination_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
]
}
}
Firewall Actions
Get all Actions for a Firewall
Returns all Action objects for a Firewall. You can sort the results by using the sort
URI parameter, and filter them with the status
parameter.
HTTP Request
GET /firewalls/{id}/actions
Path Parameters
- idinteger required
ID of the Resource
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
- metaobject
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/firewalls/{id}/actions'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"actions": [
{
"command": "set_firewall_rules",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
Get an Action for a Firewall
Returns a specific Action for a Firewall.
HTTP Request
GET /firewalls/{id}/actions/{action_id}
Path Parameters
- idinteger required
ID of the Firewall
- action_idinteger required
ID of the Action
Response
- actionobject required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/firewalls/{id}/actions/{action_id}'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"action": {
"command": "set_firewall_rules",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
Apply to Resources
Applies one Firewall to multiple resources.
Currently servers (public network interface) and label selectors are supported.
Call specific error codes
Code | Description |
---|---|
firewall_already_applied |
Firewall was already applied on resource |
incompatible_network_type |
The Network type is incompatible for the given resource |
firewall_resource_not_found |
The resource the Firewall should be attached to was not found |
HTTP Request
POST /firewalls/{id}/actions/apply_to_resources
Path Parameters
- idinteger required
ID of the Firewall
Request
- apply_toarray of objects required
Resources the Firewall should be applied to
Response
- actionsarray of objects required
- metaobject
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"apply_to":[{"server":{"id":42},"type":"server"}]}' \
'https://api.hetzner.cloud/v1/firewalls/{id}/actions/apply_to_resources'
Request
{
"apply_to": [
{
"server": {
"id": 42
},
"type": "server"
}
]
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"actions": [
{
"command": "apply_firewall",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 14,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
Remove from Resources
Removes one Firewall from multiple resources.
Currently only Servers (and their public network interfaces) are supported.
Call specific error codes
Code | Description |
---|---|
firewall_already_removed |
Firewall was already removed from the resource |
firewall_resource_not_found |
The resource the Firewall should be attached to was not found |
firewall_managed_by_label_selector |
Firewall was applied via label selector and cannot be removed manually |
HTTP Request
POST /firewalls/{id}/actions/remove_from_resources
Path Parameters
- idinteger required
ID of the Firewall
Request
- remove_fromarray of objects required
Resources the Firewall should be removed from
Response
- actionsarray of objects required
- metaobject
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"remove_from":[{"server":{"id":42},"type":"server"}]}' \
'https://api.hetzner.cloud/v1/firewalls/{id}/actions/remove_from_resources'
Request
{
"remove_from": [
{
"server": {
"id": 42
},
"type": "server"
}
]
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"actions": [
{
"command": "remove_firewall",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 14,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
Set Rules
Sets the rules of a Firewall.
All existing rules will be overwritten. Pass an empty rules
array to remove all rules.
The maximum amount of rules that can be defined is 50.
Call specific error codes
Code | Description |
---|---|
firewall_resource_not_found |
The resource the Firewall should be attached to was not found |
HTTP Request
POST /firewalls/{id}/actions/set_rules
Path Parameters
- idinteger required
ID of the Firewall
Request
- rulesarray of objects required
Array of rules
Response
- actionsarray of objects required
- metaobject
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"rules":[{"description":"Allow port 80","direction":"in","port":"80","protocol":"tcp","source_ips":["28.239.13.1/32","28.239.14.0/24","ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"]}]}' \
'https://api.hetzner.cloud/v1/firewalls/{id}/actions/set_rules'
Request
{
"rules": [
{
"description": "Allow port 80",
"direction": "in",
"port": "80",
"protocol": "tcp",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
]
}
]
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"actions": [
{
"command": "set_firewall_rules",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
},
{
"command": "apply_firewall",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 14,
"progress": 100,
"resources": [
{
"id": 38,
"type": "firewall"
},
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
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
- namestring
Can be used to filter Floating IPs by their name. The response will only contain the Floating IP matching the specified name.
- label_selectorstring
Can be used to filter Floating IPs by labels. The response will only contain Floating IPs matching the label selector.
- sortstringPossible enum values:
id
id:asc
id:desc
created
created:asc
created:desc
Can be used multiple times. Choices id id:asc id:desc created created:asc created:desc
Response
- floating_ipsarray of objects required
- metaobject
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": [
{
"blocked": false,
"created": "2016-01-30T23:55:00+00:00",
"description": "this describes my resource",
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"home_location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"id": 42,
"ip": "131.232.99.1",
"labels": {},
"name": "my-resource",
"protection": {
"delete": false
},
"server": 42,
"type": "ipv4"
}
],
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
}
}
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.
- descriptionstring
- home_locationstring
Home Location (routing is optimized for that Location). Only optional if Server argument is passed.
- labelsobject
User-defined labels (key-value pairs)
- namestring
- serverinteger
Server to assign the Floating IP to
- typestring requiredPossible enum values:
ipv4
ipv6
Floating IP type
Response
- actionobject
- floating_ipobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"Web Frontend","home_location":"fsn1","labels":{"labelkey":"value"},"name":"Web Frontend","server":42,"type":"ipv4"}' \
'https://api.hetzner.cloud/v1/floating_ips'
Request
{
"description": "Web Frontend",
"home_location": "fsn1",
"labels": {
"labelkey": "value"
},
"name": "Web Frontend",
"server": 42,
"type": "ipv4"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "create_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
},
"floating_ip": {
"blocked": false,
"created": "2016-01-30T23:50:00+00:00",
"description": "Web Frontend",
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"home_location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"id": 4711,
"ip": "131.232.99.1",
"labels": {
"env": "dev"
},
"name": "Web Frontend",
"protection": {
"delete": false
},
"server": 42,
"type": "ipv4"
}
}
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
- idinteger required
ID of the Floating IP
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/floating_ips/{id}'
Response headers
Status: 204
Get a Floating IP
Returns a specific Floating IP object.
HTTP Request
GET /floating_ips/{id}
Path Parameters
- idinteger required
ID of the Floating IP
Response
- floating_ipobject required
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": {
"blocked": false,
"created": "2016-01-30T23:55:00+00:00",
"description": "this describes my resource",
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"home_location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"id": 42,
"ip": "131.232.99.1",
"labels": {},
"name": "my-resource",
"protection": {
"delete": false
},
"server": 42,
"type": "ipv4"
}
}
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
- idinteger required
ID of the Floating IP
Request
- descriptionstring
New Description to set
- labelsobject
User-defined labels (key-value pairs)
- namestring
New unique name to set
Response
- floating_ipobject required
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"Web Frontend","labels":{"labelkey":"value"},"name":"Web Frontend"}' \
'https://api.hetzner.cloud/v1/floating_ips/{id}'
Request
{
"description": "Web Frontend",
"labels": {
"labelkey": "value"
},
"name": "Web Frontend"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"floating_ip": {
"blocked": false,
"created": "2016-01-30T23:50:00+00:00",
"description": "Web Frontend",
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"home_location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"id": 4711,
"ip": "131.232.99.1",
"labels": {
"labelkey": "value"
},
"name": "Web Frontend",
"protection": {
"delete": false
},
"server": 42,
"type": "ipv4"
}
}
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
- idinteger required
ID of the Floating IP
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
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": [
{
"command": "assign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "server"
},
{
"id": 4712,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
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
- idinteger required
ID of the Floating IP
- action_idinteger required
ID of the Action
Response
- actionobject required
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": {
"command": "assign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
Assign a Floating IP to a Server
Assigns a Floating IP to a Server.
HTTP Request
POST /floating_ips/{id}/actions/assign
Path Parameters
- idinteger required
ID of the Floating IP
Request
- serverinteger required
ID of the Server the Floating IP shall be assigned to
Response
- actionobject required
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": {
"command": "assign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Floating IP
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
.
- dns_ptrstring – nullablerequired
Hostname to set as a reverse DNS PTR entry, will reset to original default value if
null
- ipstring required
IP address for which to set the reverse DNS entry
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"dns_ptr":"server02.example.com","ip":"1.2.3.4"}' \
'https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_dns_ptr'
Request
{
"dns_ptr": "server02.example.com",
"ip": "1.2.3.4"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "change_dns_ptr",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
Change Floating IP Protection
Changes the protection configuration of the Floating IP.
HTTP Request
POST /floating_ips/{id}/actions/change_protection
Path Parameters
- idinteger required
ID of the Floating IP
Request
- deleteboolean
If true, prevents the Floating IP from being deleted
Response
- actionobject required
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": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Floating IP
Response
- actionobject required
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": {
"command": "unassign_floating_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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.
App Images
Prebuild images with specific software configurations, e.g. “Wordpress”. All app images are created by us.
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
- sortstringPossible enum values:
id
id:asc
id:desc
name
name:asc
name:desc
created
created:asc
created:desc
Can be used multiple times.
- typestringPossible enum values:
system
snapshot
backup
app
Can be used multiple times.
- statusstringPossible enum values:
available
creating
Can be used multiple times. The response will only contain Images matching the status.
- bound_tostring
Can be used multiple times. Server ID linked to the Image. Only available for Images of type
backup
- include_deprecatedboolean
Can be used multiple times.
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
Response
- imagesarray of objects required
- metaobject
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": [
{
"bound_to": null,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "Ubuntu 20.04 Standard 64 bit",
"disk_size": 10,
"id": 42,
"image_size": 2.3,
"labels": {},
"name": "ubuntu-20.04",
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
}
],
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
}
}
Delete an Image
Deletes an Image. Only Images of type snapshot
and backup
can be deleted.
HTTP Request
DELETE /images/{id}
Path Parameters
- idinteger required
ID of the Image
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/images/{id}'
Response headers
Status: 204
Get an Image
Returns a specific Image object.
HTTP Request
GET /images/{id}
Path Parameters
- idinteger required
ID of the Image
Response
- imageobject
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": {
"bound_to": null,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "Ubuntu 20.04 Standard 64 bit",
"disk_size": 10,
"id": 42,
"image_size": 2.3,
"labels": {},
"name": "ubuntu-20.04",
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
}
}
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
- idinteger required
ID of the Image
Request
- descriptionstring
New description of Image
- labelsobject
User-defined labels (key-value pairs)
- typestringPossible enum values:
snapshot
Destination Image type to convert to
Response
- imageobject
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"My new Image description","labels":{"labelkey":"value"},"type":"snapshot"}' \
'https://api.hetzner.cloud/v1/images/{id}'
Request
{
"description": "My new Image description",
"labels": {
"labelkey": "value"
},
"type": "snapshot"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"image": {
"bound_to": null,
"build_id": "c313fe40383af26094a5a92026054320ab55abc7",
"created": "2016-01-30T23:50:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "My new Image description",
"disk_size": 10,
"id": 4711,
"image_size": 2.3,
"labels": {
"labelkey": "value"
},
"name": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
}
}
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
- idinteger required
ID of the Image
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
- metaobject
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": [
{
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "image"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
Get an Action for an Image
Returns a specific Action for an Image.
HTTP Request
GET /images/{id}/actions/{action_id}
Path Parameters
- idinteger required
ID of the Image
- action_idinteger required
ID of the Action
Response
- actionobject required
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": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "image"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Image
Request
- deleteboolean
If true, prevents the snapshot from being deleted
Response
- actionobject required
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": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "image"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- namestring
Can be used to filter ISOs by their name. The response will only contain the ISO matching the specified name.
Response
- isosarray of objects required
- metaobject
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": [
{
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "FreeBSD 11.0 x64",
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"type": "public"
}
],
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
}
}
Get an ISO
Returns a specific ISO object.
HTTP Request
GET /isos/{id}
Path Parameters
- idinteger required
ID of the ISO
Response
- isoobject required
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": {
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "FreeBSD 11.0 x64",
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"type": "public"
}
}
Load Balancers
Get all Load Balancers
Gets all existing Load Balancers that you have available.
HTTP Request
GET /load_balancers
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
name
name:asc
name:desc
created
created:asc
created:desc
Can be used multiple times.
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
Response
- load_balancersarray of objects required
- metaobject
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": [
{
"algorithm": {
"type": "round_robin"
},
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"included_traffic": 10000,
"ingoing_traffic": null,
"labels": {},
"load_balancer_type": {
"deprecated": "2016-01-30T23:50:00+00:00",
"description": "LB11",
"id": 1,
"max_assigned_certificates": 10,
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"name": "lb11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
},
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "my-resource",
"outgoing_traffic": null,
"private_net": [
{
"ip": "10.0.0.2",
"network": 4711
}
],
"protection": {
"delete": false
},
"public_net": {
"enabled": false,
"ipv4": {
"dns_ptr": "lb1.example.com",
"ip": "1.2.3.4"
},
"ipv6": {
"dns_ptr": "lb1.example.com",
"ip": "2001:db8::1"
}
},
"services": [
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "https",
"proxyprotocol": false
}
],
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"ip": {
"ip": "203.0.113.1"
},
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 80
},
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"server": {
"id": 80
},
"type": "server",
"use_private_ip": false
}
],
"type": "server",
"use_private_ip": false
}
]
}
],
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
}
}
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
- algorithmobject required
Algorithm of the Load Balancer
- labelsobject
User-defined labels (key-value pairs)
- load_balancer_typestring required
ID or name of the Load Balancer type this Load Balancer should be created with
- locationstring
ID or name of Location to create Load Balancer in
- namestring required
Name of the Load Balancer
- networkinteger
ID of the network the Load Balancer should be attached to on creation
- network_zonestring
Name of network zone
- public_interfaceboolean
Enable or disable the public interface of the Load Balancer
- servicesarray of objects
Array of services
- targetsarray of objects
Array of targets
Response
- actionobject required
- load_balancerobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"algorithm":{"type":"round_robin"},"labels":{"labelkey":"value"},"load_balancer_type":"lb11","location":"string","name":"Web Frontend","network":123,"network_zone":"eu-central","public_interface":true,"services":[{"destination_port":80,"health_check":{"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false},"interval":15,"port":4711,"protocol":"http","retries":3,"timeout":10},"http":{"certificates":[897],"cookie_lifetime":300,"cookie_name":"HCLBSTICKY","redirect_http":true,"sticky_sessions":true},"listen_port":443,"protocol":"https","proxyprotocol":false}],"targets":[{"health_status":[{"listen_port":443,"status":"healthy"}],"ip":{"ip":"203.0.113.1"},"label_selector":{"selector":"env=prod"},"server":{"id":80},"targets":[{"health_status":[{"listen_port":443,"status":"healthy"}],"server":{"id":80},"type":"server","use_private_ip":false}],"type":"server","use_private_ip":false}]}' \
'https://api.hetzner.cloud/v1/load_balancers'
Request
{
"algorithm": {
"type": "round_robin"
},
"labels": {
"labelkey": "value"
},
"load_balancer_type": "lb11",
"location": "string",
"name": "Web Frontend",
"network": 123,
"network_zone": "eu-central",
"public_interface": true,
"services": [
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "https",
"proxyprotocol": false
}
],
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"ip": {
"ip": "203.0.113.1"
},
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 80
},
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"server": {
"id": 80
},
"type": "server",
"use_private_ip": false
}
],
"type": "server",
"use_private_ip": false
}
]
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "create_load_balancer",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
},
"load_balancer": {
"algorithm": {
"type": "round_robin"
},
"created": "2016-01-30T23:50:00+00:00",
"id": 4711,
"included_traffic": 654321,
"ingoing_traffic": 123456,
"labels": {
"env": "dev"
},
"load_balancer_type": {
"deprecated": "2016-01-30T23:50:00+00:00",
"description": "LB11",
"id": 1,
"max_assigned_certificates": 10,
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"name": "lb11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
},
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "Web Frontend",
"outgoing_traffic": 123456,
"private_net": [
{
"ip": "10.0.0.2",
"network": 4711
}
],
"protection": {
"delete": false
},
"public_net": {
"enabled": false,
"ipv4": {
"ip": "1.2.3.4"
},
"ipv6": {
"ip": "2001:db8::1"
}
},
"services": [
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??,3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "http",
"proxyprotocol": false
}
],
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"server": {
"id": 80
},
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"label_selector": null,
"server": {
"id": 80
},
"type": "server",
"use_private_ip": true
}
],
"type": "server",
"use_private_ip": true
}
]
}
}
Delete a Load Balancer
Deletes a Load Balancer.
HTTP Request
DELETE /load_balancers/{id}
Path Parameters
- idinteger required
ID of the Load Balancer
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/load_balancers/{id}'
Response headers
Status: 204
Get a Load Balancer
Gets a specific Load Balancer object.
HTTP Request
GET /load_balancers/{id}
Path Parameters
- idinteger required
ID of the Load Balancer
Response
- load_balancerobject required
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": {
"algorithm": {
"type": "round_robin"
},
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"included_traffic": 10000,
"ingoing_traffic": null,
"labels": {},
"load_balancer_type": {
"deprecated": "2016-01-30T23:50:00+00:00",
"description": "LB11",
"id": 1,
"max_assigned_certificates": 10,
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"name": "lb11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
},
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "my-resource",
"outgoing_traffic": null,
"private_net": [
{
"ip": "10.0.0.2",
"network": 4711
}
],
"protection": {
"delete": false
},
"public_net": {
"enabled": false,
"ipv4": {
"dns_ptr": "lb1.example.com",
"ip": "1.2.3.4"
},
"ipv6": {
"dns_ptr": "lb1.example.com",
"ip": "2001:db8::1"
}
},
"services": [
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "https",
"proxyprotocol": false
}
],
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"ip": {
"ip": "203.0.113.1"
},
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 80
},
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"server": {
"id": 80
},
"type": "server",
"use_private_ip": false
}
],
"type": "server",
"use_private_ip": false
}
]
}
}
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
- idinteger required
ID of the Load Balancer
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring
New Load Balancer name
Response
- load_balancerobject required
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{"labelkey":"value"},"name":"new-name"}' \
'https://api.hetzner.cloud/v1/load_balancers/{id}'
Request
{
"labels": {
"labelkey": "value"
},
"name": "new-name"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"load_balancer": {
"algorithm": {
"type": "round_robin"
},
"created": "2016-01-30T23:50:00+00:00",
"id": 4711,
"included_traffic": 654321,
"ingoing_traffic": 123456,
"labels": {
"labelkey": "value"
},
"load_balancer_type": {
"deprecated": "2016-01-30T23:50:00+00:00",
"description": "LB11",
"id": 1,
"max_assigned_certificates": 10,
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"name": "lb11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
},
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "new-name",
"outgoing_traffic": 123456,
"private_net": [
{
"ip": "10.0.0.2",
"network": 4711
}
],
"protection": {
"delete": false
},
"public_net": {
"enabled": false,
"ipv4": {
"ip": "1.2.3.4"
},
"ipv6": {
"ip": "2001:db8::1"
}
},
"services": [
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??,3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "http",
"proxyprotocol": false
}
],
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"ip": {
"ip": "203.0.113.1"
},
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 80
},
"targets": [
{
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"label_selector": null,
"server": {
"id": 80
},
"type": "server",
"use_private_ip": true
}
],
"type": "server",
"use_private_ip": true
}
]
}
}
Get Metrics for a LoadBalancer
You must specify the type of metric to get: open_connections
, connections_per_second
, requests_per_second
or bandwidth
. You can also specify more than one type by comma separation, e.g. requests_per_second,bandwidth
.
Depending on the type you will get different time series data:
Type | Timeseries | Unit | Description |
---|---|---|---|
open_connections | open_connections | number | Open connections |
connections_per_second | connections_per_second | connections/s | Connections per second |
requests_per_second | requests_per_second | requests/s | Requests per second |
bandwidth | bandwidth.in | bytes/s | Ingress bandwidth |
bandwidth.out | bytes/s | Egress bandwidth |
Metrics are available for the last 30 days only.
If you do not provide the step argument we will automatically adjust it so that 200 samples are returned.
We limit the number of samples to a maximum of 500 and will adjust the step parameter accordingly.
HTTP Request
GET /load_balancers/{id}/metrics
Path Parameters
- idinteger required
ID of the Load Balancer
Query Parameters
- typestring requiredPossible enum values:
open_connections
connections_per_second
requests_per_second
bandwidth
Type of metrics to get
- startstring required
Start of period to get Metrics for (in ISO-8601 format)
- endstring required
End of period to get Metrics for (in ISO-8601 format)
- stepstring
Resolution of results in seconds
Response
- metricsobject required
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": {
"end": "2017-01-01T23:00:00+00:00",
"start": "2017-01-01T00: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
- idinteger required
ID of the Load Balancer
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
- metaobject
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": [
{
"command": "add_service",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
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
- idinteger required
ID of the Load Balancer
- action_idinteger required
ID of the Action
Response
- actionobject required
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": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Load Balancer
Request
- destination_portinteger required
Port the Load Balancer will balance to
- health_checkobject required
Service health check
- httpobject
Configuration option for protocols http and https
- listen_portinteger required
Port the Load Balancer listens on
- protocolstring requiredPossible enum values:
tcp
http
https
Protocol of the Load Balancer
- proxyprotocolboolean required
Is Proxyprotocol enabled or not
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"destination_port":80,"health_check":{"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false},"interval":15,"port":4711,"protocol":"http","retries":3,"timeout":10},"http":{"certificates":[897],"cookie_lifetime":300,"cookie_name":"HCLBSTICKY","redirect_http":true,"sticky_sessions":true},"listen_port":443,"protocol":"https","proxyprotocol":false}' \
'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_service'
Request
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "https",
"proxyprotocol": false
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "add_service",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Load Balancer
Request
- ipobject
IP targets where the traffic should be routed to. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only present for target type "ip".
- label_selectorobject
Configuration for label selector targets, required if type is
label_selector
- serverobject
Configuration for type Server, required if type is
server
- typestring requiredPossible enum values:
server
label_selector
ip
Type of the resource
- use_private_ipboolean
Use the private network IP instead of the public IP of the Server, requires the Server and Load Balancer to be in the same network. Default value is false.
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip":{"ip":"203.0.113.1"},"label_selector":{"selector":"env=prod"},"server":{"id":80},"type":"server","use_private_ip":true}' \
'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_target'
Request
{
"ip": {
"ip": "203.0.113.1"
},
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 80
},
"type": "server",
"use_private_ip": true
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "add_target",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Load Balancer
Request
- ipstring
IP to request to be assigned to this Load Balancer; if you do not provide this then you will be auto assigned an IP address
- networknumber required
ID of an existing network to attach the Load Balancer to
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip":"10.0.1.1","network":4711}' \
'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/attach_to_network'
Request
{
"ip": "10.0.1.1",
"network": 4711
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "attach_to_network",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Load Balancer
Request
- typestring requiredPossible enum values:
round_robin
least_connections
Algorithm of the Load Balancer
Response
- actionobject required
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": {
"command": "change_algorithm",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
Change reverse DNS entry for this Load Balancer
Changes the hostname that will appear when getting the hostname belonging to the public IPs (IPv4 and IPv6) of this Load Balancer.
Floating IPs assigned to the Server are not affected by this.
HTTP Request
POST /load_balancers/{id}/actions/change_dns_ptr
Path Parameters
- idinteger required
ID of the Load Balancer
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
.
- dns_ptrstring – nullablerequired
Hostname to set as a reverse DNS PTR entry
- ipstring required
Public IP address for which the reverse DNS entry should be set
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"dns_ptr":"lb1.example.com","ip":"1.2.3.4"}' \
'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_dns_ptr'
Request
{
"dns_ptr": "lb1.example.com",
"ip": "1.2.3.4"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "change_dns_ptr",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
Change Load Balancer Protection
Changes the protection configuration of a Load Balancer.
HTTP Request
POST /load_balancers/{id}/actions/change_protection
Path Parameters
- idinteger required
ID of the Load Balancer
Request
- deleteboolean
If true, prevents the Load Balancer from being deleted
Response
- actionobject required
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": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Load Balancer
Request
- load_balancer_typestring required
ID or name of Load Balancer type the Load Balancer should migrate to
Response
- actionobject required
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": {
"command": "change_load_balancer_type",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
Delete Service
Delete a service of a Load Balancer.
HTTP Request
POST /load_balancers/{id}/actions/delete_service
Path Parameters
- idinteger required
ID of the Load Balancer
Request
- listen_portnumber required
The listen port of the service you want to delete
Response
- actionobject required
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": {
"command": "delete_service",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Load Balancer
Request
- networknumber required
ID of an existing network to detach the Load Balancer from
Response
- actionobject required
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": {
"command": "detach_from_network",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Load Balancer
Response
- actionobject required
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": {
"command": "disable_public_interface",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Load Balancer
Response
- actionobject required
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": {
"command": "enable_public_interface",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
Remove Target
Removes a target from a Load Balancer.
HTTP Request
POST /load_balancers/{id}/actions/remove_target
Path Parameters
- idinteger required
ID of the Load Balancer
Request
- ipobject
IP targets where the traffic should be routed to. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only present for target type "ip".
- label_selectorobject
Configuration for label selector targets, required if type is
label_selector
- serverobject
Configuration for type Server, required if type is
server
- typestring requiredPossible enum values:
server
label_selector
ip
Type of the resource
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip":{"ip":"203.0.113.1"},"label_selector":{"selector":"env=prod"},"server":{"id":80},"type":"server"}' \
'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/remove_target'
Request
{
"ip": {
"ip": "203.0.113.1"
},
"label_selector": {
"selector": "env=prod"
},
"server": {
"id": 80
},
"type": "server"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "remove_target",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Load Balancer
Request
- destination_portinteger required
Port the Load Balancer will balance to
- health_checkobject required
Service health check
- httpobject
Configuration option for protocols http and https
- listen_portinteger required
Port the Load Balancer listens on
- protocolstring requiredPossible enum values:
tcp
http
https
Protocol of the Load Balancer
- proxyprotocolboolean required
Is Proxyprotocol enabled or not
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"destination_port":80,"health_check":{"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false},"interval":15,"port":4711,"protocol":"http","retries":3,"timeout":10},"http":{"certificates":[897],"cookie_lifetime":300,"cookie_name":"HCLBSTICKY","redirect_http":true,"sticky_sessions":true},"listen_port":443,"protocol":"https","proxyprotocol":false}' \
'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/update_service'
Request
{
"destination_port": 80,
"health_check": {
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
},
"interval": 15,
"port": 4711,
"protocol": "http",
"retries": 3,
"timeout": 10
},
"http": {
"certificates": [
897
],
"cookie_lifetime": 300,
"cookie_name": "HCLBSTICKY",
"redirect_http": true,
"sticky_sessions": true
},
"listen_port": 443,
"protocol": "https",
"proxyprotocol": false
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "update_service",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- namestring
Can be used to filter Load Balancer types by their name. The response will only contain the Load Balancer type matching the specified name.
Response
- load_balancer_typesarray of objects required
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": [
{
"deprecated": "2016-01-30T23:50:00+00:00",
"description": "LB11",
"id": 1,
"max_assigned_certificates": 10,
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"name": "lb11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
}
]
}
Get a Load Balancer Type
Gets a specific Load Balancer type object.
HTTP Request
GET /load_balancer_types/{id}
Path Parameters
- idinteger required
ID of Load Balancer type
Response
- load_balancer_typeobject
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": {
"deprecated": "2016-01-30T23:50:00+00:00",
"description": "LB11",
"id": 1,
"max_assigned_certificates": 10,
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"name": "lb11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
}
}
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
- namestring
Can be used to filter Locations by their name. The response will only contain the Location matching the specified name.
Response
- locationsarray of objects required
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": [
{
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
}
]
}
Get a Location
Returns a specific Location object.
HTTP Request
GET /locations/{id}
Path Parameters
- idinteger required
ID of Location
Response
- locationobject required
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": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
}
}
Primary IPs
Primary IPs help you to create more flexible networking setups. You can assign at most one Primary IP of type ipv4
and one of type ipv6
per Server. This Server then uses these IPs.
You can only unassign a Primary IP from a Server when it's powered off. This Primary IP can then be assigned to a different powered off Server, or you can keep it around for later use.
Primary IPs are bound to a specific Datacenter. You can not assign a Primary IP from one Datacenter to a Server in a different Datacenter. If you need this capability use Floating IPs instead.
If your Server's operating system supports cloud-init there is no further configuration needed to make Primary IPs work.
Primary IPs of type ipv4
use a single IPv4 address as their ip
property. Primary IPs of type ipv6
use a /64 network such as fc00::/64
as their ip
property. Any IP address within that network can be used on your host.
Primary IPs are billed on an hourly basis.
Get all Primary IPs
Returns all Primary IP objects.
HTTP Request
GET /primary_ips
Query Parameters
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
- ipstring
Can be used to filter resources by their ip. The response will only contain the resources matching the specified ip.
- sortstringPossible enum values:
id
id:asc
id:desc
created
created:asc
created:desc
Can be used multiple times. Choices id id:asc id:desc created created:asc created:desc
Response
- metaobject
- primary_ipsarray of objects required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/primary_ips'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
},
"primary_ips": [
{
"assignee_id": 17,
"assignee_type": "server",
"auto_delete": true,
"blocked": false,
"created": "2016-01-30T23:55:00+00:00",
"datacenter": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "131.232.99.1"
}
],
"id": 42,
"ip": "131.232.99.1",
"labels": {},
"name": "my-resource",
"protection": {
"delete": false
},
"type": "ipv4"
}
]
}
Create a Primary IP
Creates a new Primary IP, optionally assigned to a Server.
If you want to create a Primary IP that is not assigned to a Server, you need to provide the datacenter
key instead of assignee_id
. This can be either the ID or the name of the Datacenter this Primary IP shall be created in.
Note that a Primary IP can only be assigned to a Server in the same Datacenter later on.
Call specific error codes
Code | Description |
---|---|
server_not_stopped |
The specified server is running, but needs to be powered off |
server_has_ipv4 |
The server already has an ipv4 address |
server_has_ipv6 |
The server already has an ipv6 address |
HTTP Request
POST /primary_ips
Request
The type
argument is required while datacenter
and assignee_id
are mutually exclusive.
- assignee_idinteger
ID of the resource the Primary IP should be assigned to. Omitted if it should not be assigned.
- assignee_typestring requiredPossible enum values:
server
Resource type the Primary IP can be assigned to
- auto_deleteboolean
Delete the Primary IP when the Server it is assigned to is deleted. If omitted defaults to
false
. - datacenterstring
ID or name of Datacenter the Primary IP will be bound to. Needs to be omitted if
assignee_id
is passed. - labelsobject
User-defined labels (key-value pairs)
- namestring required
- typestring requiredPossible enum values:
ipv4
ipv6
Primary IP type
Response
- actionobject
- primary_ipobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"assignee_id":17,"assignee_type":"server","auto_delete":false,"datacenter":"fsn1-dc8","labels":{"labelkey":"value"},"name":"my-ip","type":"ipv4"}' \
'https://api.hetzner.cloud/v1/primary_ips'
Request
{
"assignee_id": 17,
"assignee_type": "server",
"auto_delete": false,
"datacenter": "fsn1-dc8",
"labels": {
"labelkey": "value"
},
"name": "my-ip",
"type": "ipv4"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "create_primary_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 17,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
},
"primary_ip": {
"assignee_id": 17,
"assignee_type": "server",
"auto_delete": true,
"blocked": false,
"created": "2016-01-30T23:50:00+00:00",
"datacenter": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"id": 42,
"ip": "131.232.99.1",
"labels": {
"labelkey": "value"
},
"name": "my-ip",
"protection": {
"delete": false
},
"type": "ipv4"
}
}
Delete a Primary IP
Deletes a Primary IP.
The Primary IP may be assigned to a Server. In this case it is unassigned automatically. The Server must be powered off (status off
) in order for this operation to succeed.
HTTP Request
DELETE /primary_ips/{id}
Path Parameters
- idinteger required
ID of the resource
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/primary_ips/{id}'
Response headers
Status: 204
Get a Primary IP
Returns a specific Primary IP object.
HTTP Request
GET /primary_ips/{id}
Path Parameters
- idinteger required
ID of the resource
Response
- primary_ipobject required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/primary_ips/{id}'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"primary_ip": {
"assignee_id": 17,
"assignee_type": "server",
"auto_delete": true,
"blocked": false,
"created": "2016-01-30T23:55:00+00:00",
"datacenter": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "131.232.99.1"
}
],
"id": 42,
"ip": "131.232.99.1",
"labels": {},
"name": "my-resource",
"protection": {
"delete": false
},
"type": "ipv4"
}
}
Update a Primary IP
Updates the Primary IP.
Note that when updating labels, the Primary 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.
If the Primary IP object changes during the request, the response will be a “conflict” error.
HTTP Request
PUT /primary_ips/{id}
Path Parameters
- idinteger required
ID of the resource
Request
- auto_deleteboolean
Delete this Primary IP when the resource it is assigned to is deleted
- labelsobject
User-defined labels (key-value pairs)
- namestring
New unique name to set
Response
- primary_ipobject required
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"auto_delete":true,"labels":{"labelkey":"value"},"name":"my-ip"}' \
'https://api.hetzner.cloud/v1/primary_ips/{id}'
Request
{
"auto_delete": true,
"labels": {
"labelkey": "value"
},
"name": "my-ip"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"primary_ip": {
"assignee_id": 17,
"assignee_type": "server",
"auto_delete": true,
"blocked": false,
"created": "2016-01-30T23:55:00+00:00",
"datacenter": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "131.232.99.1"
}
],
"id": 42,
"ip": "131.232.99.1",
"labels": {},
"name": "my-resource",
"protection": {
"delete": false
},
"type": "ipv4"
}
}
Primary IP Actions
Assign a Primary IP to a resource
Assigns a Primary IP to a Server.
A Server can only have one Primary IP of type ipv4
and one of type ipv6
assigned. If you need more IPs use Floating IPs.
The Server must be powered off (status off
) in order for this operation to succeed.
Call specific error codes
Code | Description |
---|---|
server_not_stopped |
The server is running, but needs to be powered off |
primary_ip_already_assigned |
Primary ip is already assigned to a different server |
server_has_ipv4 |
The server already has an ipv4 address |
server_has_ipv6 |
The server already has an ipv6 address |
HTTP Request
POST /primary_ips/{id}/actions/assign
Path Parameters
- idinteger required
ID of the Primary IP
Request
- assignee_idinteger required
ID of a resource of type
assignee_type
- assignee_typestring requiredPossible enum values:
server
Type of resource assigning the Primary IP to
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"assignee_id":4711,"assignee_type":"server"}' \
'https://api.hetzner.cloud/v1/primary_ips/{id}/actions/assign'
Request
{
"assignee_id": 4711,
"assignee_type": "server"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "assign_primary_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "primary_ip"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
Change reverse DNS entry for a Primary IP
Changes the hostname that will appear when getting the hostname belonging to this Primary IP.
HTTP Request
POST /primary_ips/{id}/actions/change_dns_ptr
Path Parameters
- idinteger required
ID of the Primary IP
Request
Select the IP address for which to change the DNS entry by passing ip
. For a Primary IP of type ipv4
this must exactly match the IP address of the Primary IP. For a Primary IP of type ipv6
this must be a single IP within the IPv6 /64 range that belongs to this Primary IP.
The target hostname is set by passing dns_ptr
.
- dns_ptrstring – nullablerequired
Hostname to set as a reverse DNS PTR entry, will reset to original default value if
null
- ipstring required
IP address for which to set the reverse DNS entry
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"dns_ptr":"server02.example.com","ip":"1.2.3.4"}' \
'https://api.hetzner.cloud/v1/primary_ips/{id}/actions/change_dns_ptr'
Request
{
"dns_ptr": "server02.example.com",
"ip": "1.2.3.4"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "change_dns_ptr",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "primary_ip"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
Change Primary IP Protection
Changes the protection configuration of a Primary IP.
A Primary IP can only be delete protected if its auto_delete
property is set to false
.
HTTP Request
POST /primary_ips/{id}/actions/change_protection
Path Parameters
- idinteger required
ID of the Primary IP
Request
- deleteboolean
If true, prevents the Primary IP from being deleted
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"delete":true}' \
'https://api.hetzner.cloud/v1/primary_ips/{id}/actions/change_protection'
Request
{
"delete": true
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "primary_ip"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
Unassign a Primary IP from a resource
Unassigns a Primary IP from a Server.
The Server must be powered off (status off
) in order for this operation to succeed.
Note that only Servers that have at least one network interface (public or private) attached can be powered on.
Call specific error codes
Code | Description |
---|---|
server_not_stopped |
The server is running, but needs to be powered off |
server_is_load_balancer_target |
The server ipv4 address is a loadbalancer target |
HTTP Request
POST /primary_ips/{id}/actions/unassign
Path Parameters
- idinteger required
ID of the Primary IP
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/primary_ips/{id}/actions/unassign'
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "unassign_primary_ip",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "primary_ip"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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 three types of subnet:
- type
cloud
is used to connect cloud Resources into your Network. - type
server
was used to connect only cloud Servers into your Network. This type is deprecated and is replaced by type cloud. - type
vswitch
allows you to connect Dedicated Server vSwitch - and all Dedicated Servers attached to it - into your Network
Subnets of type vswitch
must set a vswitch_id
which is the ID of the existing vSwitch in Hetzner Robot that should be coupled.
Network Zones
Network Zones are groups of Locations which have special high-speed network connections between them. The Location object contains the network_zone
property each Location belongs to. Currently these network zones exist:
Network Zone | Contains Locations |
---|---|
eu-central | nbg1, fsn1, hel1 |
us-east | ash |
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.
Coupling Dedicated Servers
By using subnets of type vswitch
you can couple the Cloud Networks with an existing Dedicated Server vSwitch and enable dedicated and cloud servers to
talk to each other over the Network.
In order for this to work the dedicated servers may only use IPs from the subnet and must have a special network configuration. Please refer to FAQ. vSwitch Layer 2 features are not supported.
Routes
Networks also support the notion of routes which are automatically applied to private traffic. A route makes sure that all packets for a given destination
IP prefix will be sent to the address specified in its gateway
.
Get all Networks
Gets all existing networks that you have available.
HTTP Request
GET /networks
Query Parameters
- namestring
Can be used to filter networks by their name. The response will only contain the networks matching the specified name.
- label_selectorstring
Can be used to filter networks by labels. The response will only contain networks with a matching label selector pattern.
Response
- metaobject
- networksarray of objects required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/networks'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
},
"networks": [
{
"created": "2016-01-30T23:50:00+00:00",
"id": 4711,
"ip_range": "10.0.0.0/16",
"labels": {},
"load_balancers": [
42
],
"name": "mynet",
"protection": {
"delete": false
},
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"subnets": [
{
"gateway": "10.0.0.1",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"type": "cloud"
}
]
}
]
}
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
- ip_rangestring required
IP range of the whole network which must span all included subnets. Must be one of the private IPv4 ranges of RFC1918. Minimum network size is /24. We highly recommend that you pick a larger network with a /16 netmask.
- labelsobject
User-defined labels (key-value pairs)
- namestring required
Name of the network
- routesarray of objects
Array of routes set in this network. The destination of the route must be one of the private IPv4 ranges of RFC1918. The gateway must be a subnet/IP of the ip_range of the network object. The destination must not overlap with an existing ip_range in any subnets or with any destinations in other routes or with the first IP of the networks ip_range or with 172.31.1.1. The gateway cannot be the first IP of the networks ip_range and also cannot be 172.31.1.1.
- subnetsarray of objects
Array of subnets allocated.
Response
- networkobject
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip_range":"10.0.0.0/16","labels":{"labelkey":"value"},"name":"mynet","routes":[{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}],"subnets":[{"ip_range":"10.0.1.0/24","network_zone":"eu-central","type":"cloud","vswitch_id":1000}]}' \
'https://api.hetzner.cloud/v1/networks'
Request
{
"ip_range": "10.0.0.0/16",
"labels": {
"labelkey": "value"
},
"name": "mynet",
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"subnets": [
{
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"type": "cloud",
"vswitch_id": 1000
}
]
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"network": {
"created": "2016-01-30T23:50:00+00:00",
"id": 4711,
"ip_range": "10.0.0.0/16",
"labels": {},
"load_balancers": [
42
],
"name": "mynet",
"protection": {
"delete": false
},
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"subnets": [
{
"gateway": "10.0.0.1",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"type": "cloud"
}
]
}
}
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
- idinteger required
ID of the network
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/networks/{id}'
Response headers
Status: 204
Get a Network
Gets a specific network object.
HTTP Request
GET /networks/{id}
Path Parameters
- idinteger required
ID of the network
Response
- networkobject
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": {
"created": "2016-01-30T23:50:00+00:00",
"id": 4711,
"ip_range": "10.0.0.0/16",
"labels": {},
"load_balancers": [
42
],
"name": "mynet",
"protection": {
"delete": false
},
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"subnets": [
{
"gateway": "10.0.0.1",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"type": "cloud"
}
]
}
}
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
- idinteger required
ID of the network
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring
New network name
Response
- networkobject
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{"labelkey":"value"},"name":"new-name"}' \
'https://api.hetzner.cloud/v1/networks/{id}'
Request
{
"labels": {
"labelkey": "value"
},
"name": "new-name"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"network": {
"created": "2016-01-30T23:50:00+00:00",
"id": 4711,
"ip_range": "10.0.0.0/16",
"labels": {
"labelkey": "value"
},
"load_balancers": [
42
],
"name": "new-name",
"protection": {
"delete": false
},
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"subnets": [
{
"gateway": "10.0.0.1",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"type": "cloud"
}
]
}
}
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
- idinteger required
ID of the Network
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
- metaobject
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": [
{
"command": "add_subnet",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
Get an Action for a Network
Returns a specific Action for a Network.
HTTP Request
GET /networks/{id}/actions/{action_id}
Path Parameters
- idinteger required
ID of the Network
- action_idinteger required
ID of the Action
Response
- actionobject required
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": {
"command": "add_subnet",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Network
Request
- destinationstring required
Destination network or host of this route. Must not overlap with an existing ip_range in any subnets or with any destinations in other routes or with the first IP of the networks ip_range or with 172.31.1.1. Must be one of the private IPv4 ranges of RFC1918.
- gatewaystring required
Gateway for the route. Cannot be the first IP of the networks ip_range, an IP behind a vSwitch or 172.31.1.1, as this IP is being used as a gateway for the public network interface of Servers.
Response
- actionobject required
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": {
"command": "add_route",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Network
Request
- ip_rangestring
Range to allocate IPs from. Must be a Subnet of the ip_range of the parent network object and must not overlap with any other subnets or with any destinations in routes. If the Subnet is of type vSwitch, it also can not overlap with any gateway in routes. Minimum Network size is /30. We suggest that you pick a bigger Network with a /24 netmask.
- network_zonestring required
Name of Network zone. The Location object contains the
network_zone
property each Location belongs to. - typestring requiredPossible enum values:
cloud
server
vswitch
Type of Subnetwork
- vswitch_idinteger
ID of the robot vSwitch. Must be supplied if the subnet is of type vswitch.
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip_range":"10.0.1.0/24","network_zone":"eu-central","type":"cloud","vswitch_id":1000}' \
'https://api.hetzner.cloud/v1/networks/{id}/actions/add_subnet'
Request
{
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"type": "cloud",
"vswitch_id": 1000
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "add_subnet",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Network
Request
- ip_rangestring required
The new prefix for the whole Network
Response
- actionobject required
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": {
"command": "change_ip_range",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Network
Request
- deleteboolean
If true, prevents the Network from being deleted
Response
- actionobject required
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": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Network
Request
- destinationstring required
Destination network or host of this route. Must not overlap with an existing ip_range in any subnets or with any destinations in other routes or with the first IP of the networks ip_range or with 172.31.1.1. Must be one of the private IPv4 ranges of RFC1918.
- gatewaystring required
Gateway for the route. Cannot be the first IP of the networks ip_range, an IP behind a vSwitch or 172.31.1.1, as this IP is being used as a gateway for the public network interface of Servers.
Response
- actionobject required
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": {
"command": "delete_route",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Network
Request
- ip_rangestring required
IP range of subnet to delete
Response
- actionobject required
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": {
"command": "delete_subnet",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
Placement Groups
Placement groups are used to influence the location of interdependent virtual servers in our data centers. The distribution of the different instances within a group is based on a pattern specified in the type. By enforcing certain rules on the placement of instances within our infrastructure, availability can be influenced in a way that fits your needs best.
In spread
placement groups, all virtual servers will run on different physical servers. This decreases the probability that some instances might fail together.
Get all PlacementGroups
Returns all PlacementGroup objects.
HTTP Request
GET /placement_groups
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
name
name:asc
name:desc
created
created:asc
created:desc
Can be used multiple times.
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
- typestringPossible enum values:
spread
Can be used multiple times. The response will only contain PlacementGroups matching the type.
Response
- metaobject
- placement_groupsarray of objects required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/placement_groups'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"placement_groups": [
{
"created": "2019-01-08T12:10:00+00:00",
"id": 897,
"labels": {
"key": "value"
},
"name": "my Placement Group",
"servers": [
4711,
4712
],
"type": "spread"
}
]
}
Create a PlacementGroup
Creates a new PlacementGroup.
HTTP Request
POST /placement_groups
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring required
Name of the PlacementGroup
- typestring requiredPossible enum values:
spread
Define the Placement Group Type.
Response
- actionobject – nullable
- placement_groupobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my Placement Group","type":"spread"}' \
'https://api.hetzner.cloud/v1/placement_groups'
Request
{
"name": "my Placement Group",
"type": "spread"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"placement_group": {
"created": "2019-01-08T12:10:00+00:00",
"id": 897,
"labels": {
"key": "value"
},
"name": "my Placement Group",
"servers": [],
"type": "spread"
}
}
Delete a PlacementGroup
Deletes a PlacementGroup.
HTTP Request
DELETE /placement_groups/{id}
Path Parameters
- idinteger required
ID of the resource
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/placement_groups/{id}'
Response headers
Status: 204
Get a PlacementGroup
Gets a specific PlacementGroup object.
HTTP Request
GET /placement_groups/{id}
Path Parameters
- idinteger required
ID of the resource
Response
- placement_groupobject required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/placement_groups/{id}'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"placement_group": {
"created": "2019-01-08T12:10:00+00:00",
"id": 897,
"labels": {
"key": "value"
},
"name": "my Placement Group",
"servers": [
4711,
4712
],
"type": "spread"
}
}
Update a PlacementGroup
Updates the PlacementGroup properties.
Note that when updating labels, the PlacementGroup’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 PlacementGroup object changes during the request, the response will be a “conflict” error.
HTTP Request
PUT /placement_groups/{id}
Path Parameters
- idinteger required
ID of the resource
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring
New PlacementGroup name
Response
- placement_groupobject required
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{"labelkey":"value"},"name":"my Placement Group"}' \
'https://api.hetzner.cloud/v1/placement_groups/{id}'
Request
{
"labels": {
"labelkey": "value"
},
"name": "my Placement Group"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"placement_group": {
"created": "2019-01-08T12:10:00+00:00",
"id": 897,
"labels": {
"key": "value"
},
"name": "my Placement Group",
"servers": [
4711,
4712
],
"type": "spread"
}
}
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
- pricingobject required
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",
"floating_ip": {
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
},
"floating_ips": [
{
"prices": [
{
"location": "fsn1",
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"type": "ipv4"
}
],
"image": {
"price_per_gb_month": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
},
"load_balancer_types": [
{
"id": 1,
"name": "lb11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
}
],
"primary_ips": [
{
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"type": "ipv4"
}
],
"server_backup": {
"percentage": "20.0000000000"
},
"server_types": [
{
"id": 4,
"name": "cx11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
]
}
],
"traffic": {
"price_per_tb": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
},
"vat_rate": "19.000000",
"volume": {
"price_per_gb_month": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
}
}
Servers
Servers are virtual machines that can be provisioned.
Get all Servers
Returns all existing Server objects
HTTP Request
GET /servers
Query Parameters
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
- sortstringPossible enum values:
id
id:asc
id:desc
name
name:asc
name:desc
created
created:asc
created:desc
Can be used multiple times.
- statusstringPossible enum values:
initializing
starting
running
stopping
off
deleting
rebuilding
migrating
unknown
Can be used multiple times. The response will only contain Server matching the status
Response
- metaobject
- serversarray of objects required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/servers'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
},
"servers": [
{
"backup_window": "22-02",
"created": "2016-01-30T23:55:00+00:00",
"datacenter": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"id": 42,
"image": {
"bound_to": null,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "Ubuntu 20.04 Standard 64 bit",
"disk_size": 10,
"id": 42,
"image_size": 2.3,
"labels": {},
"name": "ubuntu-20.04",
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
},
"included_traffic": 654321,
"ingoing_traffic": 123456,
"iso": {
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "FreeBSD 11.0 x64",
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"type": "public"
},
"labels": {},
"load_balancers": [],
"locked": false,
"name": "my-resource",
"outgoing_traffic": 123456,
"placement_group": {
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"labels": {},
"name": "my-resource",
"servers": [
42
],
"type": "spread"
},
"primary_disk_size": 50,
"private_net": [
{
"alias_ips": [],
"ip": "10.0.0.2",
"mac_address": "86:00:ff:2a:7d:e1",
"network": 4711
}
],
"protection": {
"delete": false,
"rebuild": false
},
"public_net": {
"firewalls": [
{
"id": 42,
"status": "applied"
}
],
"floating_ips": [
478
],
"ipv4": {
"blocked": false,
"dns_ptr": "server01.example.com",
"id": 42,
"ip": "1.2.3.4"
},
"ipv6": {
"blocked": false,
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"id": 42,
"ip": "2001:db8::/64"
}
},
"rescue_enabled": false,
"server_type": {
"cores": 1,
"cpu_type": "shared",
"deprecated": false,
"description": "CX11",
"disk": 25,
"id": 1,
"memory": 1,
"name": "cx11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"storage_type": "local"
},
"status": "running",
"volumes": []
}
]
}
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 we only recommend this if you want to assign a specific Primary IP to the Server which is located in the specified Datacenter.
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.
Call specific error codes
Code | Description |
---|---|
placement_error |
An error during the placement occurred |
primary_ip_assigned |
The specified Primary IP is already assigned to a server |
primary_ip_datacenter_mismatch |
The specified Primary IP is in a different datacenter |
primary_ip_version_mismatch |
The specified Primary IP has the wrong IP Version |
- automountboolean
Auto-mount Volumes after attach
- datacenterstring
ID or name of Datacenter to create Server in (must not be used together with location)
- firewallsarray of objects
Firewalls which should be applied on the Server's public network interface at creation time
- imagestring required
ID or name of the Image the Server is created from
- labelsobject
User-defined labels (key-value pairs)
- locationstring
ID or name of Location to create Server in (must not be used together with datacenter)
- namestring required
Name of the Server to create (must be unique per Project and a valid hostname as per RFC 1123)
- networksarray of integers
Network IDs which should be attached to the Server private network interface at the creation time
- placement_groupinteger
ID of the Placement Group the server should be in
- public_netobject
Public Network options
- server_typestring required
ID or name of the Server type this Server should be created with
- ssh_keysarray of strings
SSH key IDs (
integer
) or names (string
) which should be injected into the Server at creation time - start_after_createboolean
Start Server right after creation. Defaults to true.
- user_datastring
Cloud-Init user data to use during Server creation. This field is limited to 32KiB.
- volumesarray of integers
Volume IDs which should be attached to the Server at the creation time. Volumes must be in the same Location.
Response
- actionobject required
- next_actionsarray of objects required
- root_passwordstring – nullablerequired
Root password when no SSH keys have been specified
- serverobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"automount":false,"datacenter":"nbg1-dc3","firewalls":[{"firewall":38}],"image":"ubuntu-20.04","labels":{},"location":"nbg1","name":"my-server","networks":[456],"placement_group":1,"public_net":{"enable_ipv4":false,"enable_ipv6":false,"ipv4":null,"ipv6":null},"server_type":"cx11","ssh_keys":["my-ssh-key"],"start_after_create":true,"user_data":"#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n","volumes":[123]}' \
'https://api.hetzner.cloud/v1/servers'
Request
{
"automount": false,
"datacenter": "nbg1-dc3",
"firewalls": [
{
"firewall": 38
}
],
"image": "ubuntu-20.04",
"labels": {},
"location": "nbg1",
"name": "my-server",
"networks": [
456
],
"placement_group": 1,
"public_net": {
"enable_ipv4": false,
"enable_ipv6": false,
"ipv4": null,
"ipv6": null
},
"server_type": "cx11",
"ssh_keys": [
"my-ssh-key"
],
"start_after_create": true,
"user_data": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n",
"volumes": [
123
]
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "create_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 1,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
},
"next_actions": [
{
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
],
"root_password": "YItygq1v3GYjjMomLaKc",
"server": {
"backup_window": "22-02",
"created": "2016-01-30T23:50:00+00:00",
"datacenter": {
"description": "Falkenstein 1 DC 8",
"id": 1,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"id": 42,
"image": {
"bound_to": null,
"created": "2016-01-30T23:50:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "Ubuntu 20.04 Standard 64 bit",
"disk_size": 10,
"id": 4711,
"image_size": 2.3,
"labels": {
"env": "dev"
},
"name": "ubuntu-20.04",
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
},
"included_traffic": 654321,
"ingoing_traffic": 123456,
"iso": {
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "FreeBSD 11.0 x64",
"id": 4711,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"type": "public"
},
"labels": {
"env": "dev"
},
"load_balancers": [],
"locked": false,
"name": "my-server",
"outgoing_traffic": 123456,
"primary_disk_size": 50,
"private_net": [
{
"alias_ips": [],
"ip": "10.0.0.2",
"mac_address": "86:00:ff:2a:7d:e1",
"network": 4711
}
],
"protection": {
"delete": false,
"rebuild": false
},
"public_net": {
"firewalls": [
{
"id": 38,
"status": "applied"
}
],
"floating_ips": [
478
],
"ipv4": {
"blocked": false,
"dns_ptr": "server01.example.com",
"ip": "1.2.3.4"
},
"ipv6": {
"blocked": false,
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"ip": "2001:db8::/64"
}
},
"rescue_enabled": false,
"server_type": {
"cores": 1,
"cpu_type": "shared",
"deprecated": true,
"description": "CX11",
"disk": 25,
"id": 1,
"memory": 1,
"name": "cx11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"storage_type": "local"
},
"status": "initializing",
"volumes": []
}
}
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
- idinteger required
ID of the Server
Response
- actionobject
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": {
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:55:00+00:00",
"id": 42,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
Get a Server
Returns a specific Server object. The Server must exist inside the Project
HTTP Request
GET /servers/{id}
Path Parameters
- idinteger required
ID of the Server
Response
- serverobject
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": {
"backup_window": "22-02",
"created": "2016-01-30T23:55:00+00:00",
"datacenter": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"id": 42,
"image": {
"bound_to": null,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "Ubuntu 20.04 Standard 64 bit",
"disk_size": 10,
"id": 42,
"image_size": 2.3,
"labels": {},
"name": "ubuntu-20.04",
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
},
"included_traffic": 654321,
"ingoing_traffic": 123456,
"iso": {
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "FreeBSD 11.0 x64",
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"type": "public"
},
"labels": {},
"load_balancers": [],
"locked": false,
"name": "my-resource",
"outgoing_traffic": 123456,
"placement_group": {
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"labels": {},
"name": "my-resource",
"servers": [
42
],
"type": "spread"
},
"primary_disk_size": 50,
"private_net": [
{
"alias_ips": [],
"ip": "10.0.0.2",
"mac_address": "86:00:ff:2a:7d:e1",
"network": 4711
}
],
"protection": {
"delete": false,
"rebuild": false
},
"public_net": {
"firewalls": [
{
"id": 42,
"status": "applied"
}
],
"floating_ips": [
478
],
"ipv4": {
"blocked": false,
"dns_ptr": "server01.example.com",
"id": 42,
"ip": "1.2.3.4"
},
"ipv6": {
"blocked": false,
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"id": 42,
"ip": "2001:db8::/64"
}
},
"rescue_enabled": false,
"server_type": {
"cores": 1,
"cpu_type": "shared",
"deprecated": false,
"description": "CX11",
"disk": 25,
"id": 1,
"memory": 1,
"name": "cx11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"storage_type": "local"
},
"status": "running",
"volumes": []
}
}
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
- idinteger required
ID of the Server
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring
New name to set
Response
- serverobject
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{"labelkey":"value"},"name":"my-server"}' \
'https://api.hetzner.cloud/v1/servers/{id}'
Request
{
"labels": {
"labelkey": "value"
},
"name": "my-server"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"server": {
"backup_window": "22-02",
"created": "2016-01-30T23:55:00+00:00",
"datacenter": {
"description": "Falkenstein DC Park 8",
"id": 42,
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "fsn1-dc8",
"server_types": {
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
],
"supported": [
1,
2,
3
]
}
},
"id": 42,
"image": {
"bound_to": null,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "Ubuntu 20.04 Standard 64 bit",
"disk_size": 10,
"id": 42,
"image_size": 2.3,
"labels": {},
"name": "ubuntu-20.04",
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "available",
"type": "snapshot"
},
"included_traffic": 654321,
"ingoing_traffic": 123456,
"iso": {
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "FreeBSD 11.0 x64",
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"type": "public"
},
"labels": {},
"load_balancers": [],
"locked": false,
"name": "my-resource",
"outgoing_traffic": 123456,
"placement_group": {
"created": "2016-01-30T23:55:00+00:00",
"id": 42,
"labels": {},
"name": "my-resource",
"servers": [
42
],
"type": "spread"
},
"primary_disk_size": 50,
"private_net": [
{
"alias_ips": [],
"ip": "10.0.0.2",
"mac_address": "86:00:ff:2a:7d:e1",
"network": 4711
}
],
"protection": {
"delete": false,
"rebuild": false
},
"public_net": {
"firewalls": [
{
"id": 42,
"status": "applied"
}
],
"floating_ips": [
478
],
"ipv4": {
"blocked": false,
"dns_ptr": "server01.example.com",
"id": 42,
"ip": "1.2.3.4"
},
"ipv6": {
"blocked": false,
"dns_ptr": [
{
"dns_ptr": "server.example.com",
"ip": "2001:db8::1"
}
],
"id": 42,
"ip": "2001:db8::/64"
}
},
"rescue_enabled": false,
"server_type": {
"cores": 1,
"cpu_type": "shared",
"deprecated": false,
"description": "CX11",
"disk": 25,
"id": 1,
"memory": 1,
"name": "cx11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"storage_type": "local"
},
"status": "running",
"volumes": []
}
}
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 200 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
- idinteger required
ID of the Server
Query Parameters
- typestring requiredPossible enum values:
cpu
disk
network
Type of metrics to get
- startstring required
Start of period to get Metrics for (in ISO-8601 format)
- endstring required
End of period to get Metrics for (in ISO-8601 format)
- stepstring
Resolution of results in seconds
Response
- metricsobject required
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": {
"end": "2017-01-01T23:00:00+00:00",
"start": "2017-01-01T00: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
- idinteger required
ID of the Resource
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
- metaobject
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": [
{
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
Get an Action for a Server
Returns a specific Action object for a Server.
HTTP Request
GET /servers/{id}/actions/{action_id}
Path Parameters
- idinteger required
ID of the Server
- action_idinteger required
ID of the Action
Response
- actionobject required
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": {
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
Add a Server to a Placement Group
Adds a Server to a Placement Group.
Server must be powered off for this command to succeed.
Call specific error codes
Code | Description |
---|---|
server_not_stopped |
The action requires a stopped server |
HTTP Request
POST /servers/{id}/actions/add_to_placement_group
Path Parameters
- idinteger required
ID of the Server
Request
- placement_groupinteger required
ID of Placement Group the Server should be added to
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"placement_group":1}' \
'https://api.hetzner.cloud/v1/servers/{id}/actions/add_to_placement_group'
Request
{
"placement_group": 1
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "add_to_placement_group",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
Request
- isostring required
ID or name of ISO to attach to the Server as listed in GET
/isos
Response
- actionobject required
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": {
"command": "attach_iso",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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.
Call specific error codes
Code | Description |
---|---|
server_already_attached |
The server is already attached to the network |
ip_not_available |
The provided Network IP is not available |
no_subnet_available |
No Subnet or IP is available for the Server within the network |
networks_overlap |
The network IP range overlaps with one of the server networks |
HTTP Request
POST /servers/{id}/actions/attach_to_network
Path Parameters
- idinteger required
ID of the Server
Request
- alias_ipsarray of strings
Additional IPs to be assigned to this Server
- ipstring
IP to request to be assigned to this Server; if you do not provide this then you will be auto assigned an IP address
- networkinteger required
ID of an existing network to attach the Server to
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"alias_ips":["10.0.1.2"],"ip":"10.0.1.1","network":4711}' \
'https://api.hetzner.cloud/v1/servers/{id}/actions/attach_to_network'
Request
{
"alias_ips": [
"10.0.1.2"
],
"ip": "10.0.1.1",
"network": 4711
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "attach_to_network",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
Request
- alias_ipsarray of strings required
New alias IPs to set for this Server
- networkinteger required
ID of an existing Network already attached to the Server
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"alias_ips":["10.0.1.2"],"network":4711}' \
'https://api.hetzner.cloud/v1/servers/{id}/actions/change_alias_ips'
Request
{
"alias_ips": [
"10.0.1.2"
],
"network": 4711
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "change_alias_ips",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
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
.
- dns_ptrstring – nullablerequired
Hostname to set as a reverse DNS PTR entry, reset to original value if
null
- ipstring required
Primary IP address for which the reverse DNS entry should be set
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"dns_ptr":"server01.example.com","ip":"1.2.3.4"}' \
'https://api.hetzner.cloud/v1/servers/{id}/actions/change_dns_ptr'
Request
{
"dns_ptr": "server01.example.com",
"ip": "1.2.3.4"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "change_dns_ptr",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
Change Server Protection
Changes the protection configuration of the Server.
HTTP Request
POST /servers/{id}/actions/change_protection
Path Parameters
- idinteger required
ID of the Server
Request
- deleteboolean
If true, prevents the Server from being deleted (currently delete and rebuild attribute needs to have the same value)
- rebuildboolean
If true, prevents the Server from being rebuilt (currently delete and rebuild attribute needs to have the same value)
Response
- actionobject required
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": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
.
Call specific error codes
Code | Description |
---|---|
invalid_server_type |
The server type does not fit for the given server or is deprecated |
server_not_stopped |
The action requires a stopped server |
HTTP Request
POST /servers/{id}/actions/change_type
Path Parameters
- idinteger required
ID of the Server
Request
- server_typestring required
ID or name of Server type the Server should migrate to
- upgrade_diskboolean required
If false, do not upgrade the disk (this allows downgrading the Server type later)
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"server_type":"cx11","upgrade_disk":true}' \
'https://api.hetzner.cloud/v1/servers/{id}/actions/change_type'
Request
{
"server_type": "cx11",
"upgrade_disk": true
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "change_server_type",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
Request
- descriptionstring
Description of the Image, will be auto-generated if not set
- labelsobject
User-defined labels (key-value pairs)
- typestringPossible enum values:
snapshot
backup
Type of Image to create (default:
snapshot
)
Response
- actionobject
- imageobject
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"my image","labels":{"labelkey":"value"},"type":"snapshot"}' \
'https://api.hetzner.cloud/v1/servers/{id}/actions/create_image'
Request
{
"description": "my image",
"labels": {
"labelkey": "value"
},
"type": "snapshot"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "create_image",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
},
"image": {
"bound_to": null,
"created": "2016-01-30T23:50:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"deleted": null,
"deprecated": "2018-02-28T00:00:00+00:00",
"description": "my image",
"disk_size": 10,
"id": 4711,
"image_size": 2.3,
"labels": {
"env": "dev"
},
"name": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"protection": {
"delete": false
},
"rapid_deploy": false,
"status": "creating",
"type": "snapshot"
}
}
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
- idinteger required
ID of the Server
Request
- networkinteger required
ID of an existing network to detach the Server from
Response
- actionobject required
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": {
"command": "detach_from_network",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "detach_iso",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "disable_backup",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "disable_rescue",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "enable_backup",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Server
Request
- ssh_keysarray of integers
Array of SSH key IDs which should be injected into the rescue system.
- typestringPossible enum values:
linux64
linux32
Type of rescue system to boot (default:
linux64
)
Response
- actionobject
- root_passwordstring
Password that will be set for this Server once the Action succeeds
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ssh_keys":[2323],"type":"linux64"}' \
'https://api.hetzner.cloud/v1/servers/{id}/actions/enable_rescue'
Request
{
"ssh_keys": [
2323
],
"type": "linux64"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "enable_rescue",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
},
"root_password": "zCWbFhnu950dUTko5f40"
}
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
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "stop_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
Power on a Server
Starts a Server by turning its power on.
HTTP Request
POST /servers/{id}/actions/poweron
Path Parameters
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "start_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "reboot_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Server
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.
- imagestring required
ID or name of Image to rebuilt from.
Response
- actionobject
- root_passwordstring – nullable
New root password when not using SSH keys
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": {
"command": "rebuild_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
},
"root_password": null
}
Remove from Placement Group
Removes a Server from a Placement Group.
HTTP Request
POST /servers/{id}/actions/remove_from_placement_group
Path Parameters
- idinteger required
ID of the Server
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/servers/{id}/actions/remove_from_placement_group'
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "remove_from_placement_group",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Server
Response
- actionobject required
- passwordstring required
VNC password to use for this connection (this password only works in combination with a wss_url with valid token)
- wss_urlstring required
URL of websocket proxy to use; this includes a token which is valid for a limited time only
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
{
"action": {
"command": "request_console",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
},
"password": "9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x",
"wss_url": "wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c"
}
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
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "reset_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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 (status running
) in order for this operation to succeed.
This will generate a new password for this Server and return it.
If this does not succeed you can use the rescue system to netboot the Server and manually change your Server password by hand.
HTTP Request
POST /servers/{id}/actions/reset_password
Path Parameters
- idinteger required
ID of the Server
Response
- actionobject
- root_passwordstring
Password that will be set for this Server once the Action succeeds
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
{
"action": {
"command": "reset_password",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
},
"root_password": "zCWbFhnu950dUTko5f40"
}
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
- idinteger required
ID of the Server
Response
- actionobject required
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": {
"command": "shutdown_server",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- namestring
Can be used to filter Server types by their name. The response will only contain the Server type matching the specified name.
Response
- server_typesarray of objects required
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": [
{
"cores": 1,
"cpu_type": "shared",
"deprecated": false,
"description": "CX11",
"disk": 24,
"id": 1,
"memory": 1,
"name": "cx11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"storage_type": "local"
}
]
}
Get a Server Type
Gets a specific Server type object.
HTTP Request
GET /server_types/{id}
Path Parameters
- idinteger required
ID of Server Type
Response
- server_typeobject required
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": {
"cores": 1,
"cpu_type": "shared",
"deprecated": false,
"description": "CX11",
"disk": 24,
"id": 1,
"memory": 1,
"name": "cx11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
},
"price_monthly": {
"gross": "1.1900000000000000",
"net": "1.0000000000"
}
}
],
"storage_type": "local"
}
}
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
- sortstringPossible enum values:
id
id:asc
id:desc
name
name:asc
name:desc
Can be used multiple times.
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- fingerprintstring
Can be used to filter SSH keys by their fingerprint. The response will only contain the SSH key matching the specified fingerprint.
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
Response
- metaobject
- ssh_keysarray of objects required
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
{
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
},
"ssh_keys": [
{
"created": "2016-01-30T23:55:00+00:00",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"id": 42,
"labels": {},
"name": "my-resource",
"public_key": "ssh-rsa AAAjjk76kgf...Xt"
}
]
}
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
- labelsobject
User-defined labels (key-value pairs)
- namestring required
Name of the SSH key
- public_keystring required
Public key
Response
- ssh_keyobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{},"name":"My ssh key","public_key":"ssh-rsa AAAjjk76kgf...Xt"}' \
'https://api.hetzner.cloud/v1/ssh_keys'
Request
{
"labels": {},
"name": "My ssh key",
"public_key": "ssh-rsa AAAjjk76kgf...Xt"
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"ssh_key": {
"created": "2016-01-30T23:55:00+00:00",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"id": 42,
"labels": {},
"name": "my-resource",
"public_key": "ssh-rsa AAAjjk76kgf...Xt"
}
}
Delete an SSH key
Deletes an SSH key. It cannot be used anymore.
HTTP Request
DELETE /ssh_keys/{id}
Path Parameters
- idstring required
ID of the SSH key
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/ssh_keys/{id}'
Response headers
Status: 204
Get a SSH key
Returns a specific SSH key object.
HTTP Request
GET /ssh_keys/{id}
Path Parameters
- idinteger required
ID of the SSH key
Response
- ssh_keyobject required
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": {
"created": "2016-01-30T23:55:00+00:00",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"id": 42,
"labels": {},
"name": "my-resource",
"public_key": "ssh-rsa AAAjjk76kgf...Xt"
}
}
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
- idstring required
ID of the SSH key
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring
New name Name to set
Response
- ssh_keyobject required
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{"labelkey":"value"},"name":"My ssh key"}' \
'https://api.hetzner.cloud/v1/ssh_keys/{id}'
Request
{
"labels": {
"labelkey": "value"
},
"name": "My ssh key"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"ssh_key": {
"created": "2016-01-30T23:50:00+00:00",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"id": 2323,
"labels": {
"labelkey": "value"
},
"name": "My ssh key",
"public_key": "ssh-rsa AAAjjk76kgf...Xt"
}
}
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
- statusstringPossible enum values:
available
creating
Can be used multiple times. The response will only contain Volumes matching the status.
- sortstringPossible enum values:
id
id:asc
id:desc
name
name:asc
name:desc
created
created:asc
created:desc
Can be used multiple times.
- namestring
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
- label_selectorstring
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
Response
- metaobject
- volumesarray of objects required
Example curl
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/volumes'
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"meta": {
"pagination": {
"last_page": 4,
"next_page": 4,
"page": 3,
"per_page": 25,
"previous_page": 2,
"total_entries": 100
}
},
"volumes": [
{
"created": "2016-01-30T23:55:00+00:00",
"format": "xfs",
"id": 42,
"labels": {},
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "my-resource",
"protection": {
"delete": false
},
"server": 12,
"size": 42,
"status": "available"
}
]
}
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.
Call specific error codes
Code | Description |
---|---|
no_space_left_in_location |
There is no volume space left in the given location |
HTTP Request
POST /volumes
Request
- automountboolean
Auto-mount Volume after attach.
server
must be provided. - formatstring
Format Volume after creation. One of:
xfs
,ext4
- labelsobject
User-defined labels (key-value pairs)
- locationstring
Location to create the Volume in (can be omitted if Server is specified)
- namestring required
Name of the volume
- serverinteger
Server to which to attach the Volume once it's created (Volume will be created in the same Location as the server)
- sizeinteger required
Size of the Volume in GB
Response
- actionobject required
- next_actionsarray of objects required
- volumeobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"automount":false,"format":"xfs","labels":{"labelkey":"value"},"location":"nbg1","name":"test-database","size":42}' \
'https://api.hetzner.cloud/v1/volumes'
Request
{
"automount": false,
"format": "xfs",
"labels": {
"labelkey": "value"
},
"location": "nbg1",
"name": "test-database",
"size": 42
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "create_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
},
"next_actions": [
{
"command": "attach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
],
"volume": {
"created": "2016-01-30T23:50:11+00:00",
"format": "xfs",
"id": 4711,
"labels": {
"env": "dev"
},
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "database-storage",
"protection": {
"delete": false
},
"server": 12,
"size": 42,
"status": "available"
}
}
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
- idstring required
ID of the Volume
Example curl
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/volumes/{id}'
Response headers
Status: 204
Get a Volume
Gets a specific Volume object.
HTTP Request
GET /volumes/{id}
Path Parameters
- idinteger required
ID of the Volume
Response
- volumeobject required
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": {
"created": "2016-01-30T23:55:00+00:00",
"format": "xfs",
"id": 42,
"labels": {},
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "my-resource",
"protection": {
"delete": false
},
"server": 12,
"size": 42,
"status": "available"
}
}
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
- idstring required
ID of the Volume to update
Request
- labelsobject
User-defined labels (key-value pairs)
- namestring required
New Volume name
Response
- volumeobject required
Example curl
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"labels":{"labelkey":"value"},"name":"database-storage"}' \
'https://api.hetzner.cloud/v1/volumes/{id}'
Request
{
"labels": {
"labelkey": "value"
},
"name": "database-storage"
}
Response headers
Content-Type: application/json
Status: 200
Response sample
{
"volume": {
"created": "2016-01-30T23:50:11+00:00",
"format": "xfs",
"id": 4711,
"labels": {
"labelkey": "value"
},
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"location": {
"city": "Falkenstein",
"country": "DE",
"description": "Falkenstein DC Park 1",
"id": 1,
"latitude": 50.47612,
"longitude": 12.370071,
"name": "fsn1",
"network_zone": "eu-central"
},
"name": "database-storage",
"protection": {
"delete": false
},
"server": 12,
"size": 42,
"status": "available"
}
}
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
- idinteger required
ID of the Volume
Query Parameters
- sortstringPossible enum values:
id
id:asc
id:desc
command
command:asc
command:desc
status
status:asc
status:desc
progress
progress:asc
progress:desc
started
started:asc
started:desc
finished
finished:asc
finished:desc
Can be used multiple times.
- statusstringPossible enum values:
running
success
error
Can be used multiple times, the response will contain only Actions with specified statuses
Response
- actionsarray of objects required
- metaobject
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": [
{
"command": "attach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 13,
"type": "volume"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
]
}
Get an Action for a Volume
Returns a specific Action for a Volume.
HTTP Request
GET /volumes/{id}/actions/{action_id}
Path Parameters
- idinteger required
ID of the Volume
- action_idinteger required
ID of the Action
Response
- actionobject required
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": {
"command": "attach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Volume
Request
- automountboolean
Auto-mount the Volume after attaching it
- serverinteger required
ID of the Server the Volume will be attached to
Response
- actionobject required
Example curl
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"automount":false,"server":43}' \
'https://api.hetzner.cloud/v1/volumes/{id}/actions/attach'
Request
{
"automount": false,
"server": 43
}
Response headers
Content-Type: application/json
Status: 201
Response sample
{
"action": {
"command": "attach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 43,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
Change Volume Protection
Changes the protection configuration of a Volume.
HTTP Request
POST /volumes/{id}/actions/change_protection
Path Parameters
- idinteger required
ID of the Volume
Request
- deleteboolean
If true, prevents the Volume from being deleted
Response
- actionobject required
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": {
"command": "change_protection",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": "2016-01-30T23:56:00+00:00",
"id": 13,
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:55:00+00:00",
"status": "success"
}
}
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
- idinteger required
ID of the Volume
Response
- actionobject required
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": {
"command": "detach_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 42,
"type": "server"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}
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
- idinteger required
ID of the Volume
Request
- sizenumber required
New Volume size in GB (must be greater than current size)
Response
- actionobject required
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": {
"command": "resize_volume",
"error": {
"code": "action_failed",
"message": "Action failed"
},
"finished": null,
"id": 13,
"progress": 0,
"resources": [
{
"id": 554,
"type": "volume"
}
],
"started": "2016-01-30T23:50:00+00:00",
"status": "running"
}
}