This is the official documentation for the Hetzner Cloud API.
The Hetzner Cloud API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.
As an alternative to working directly with our API you may also consider to use:
Also you can find a list of libraries, tools, and integrations on GitHub.
If you are developing integrations based on our API and your product is Open Source you may be eligible for a free one time €50 (excl. VAT) credit on your account. Please contact us via the the support page on your Cloud Console and let us know the following:
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
LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj
.
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.
1curl -H "Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj" \
2 https://api.hetzner.cloud/v1/servers1{
2 "servers": [],
3 "meta": {
4 "pagination": {
5 "page": 1,
6 "per_page": 25,
7 "previous_page": null,
8 "next_page": null,
9 "last_page": 1,
10 "total_entries": 0
11 }
12 }
13}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.
1Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfjErrors 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) |
| Code | Description |
|---|---|
forbidden
|
Insufficient permissions for this request |
unauthorized
|
Request was made with an invalid or unknown token |
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 |
server_error
|
Error within the API backend |
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 |
1{
2 "error": {
3 "code": "invalid_input",
4 "message": "invalid input in field 'broken_field': is too long",
5 "details": {
6 "fields": [
7 {
8 "name": "broken_field",
9 "messages": ["is too long"]
10 }
11 ]
12 }
13 }
14}1{
2 "error": {
3 "code": "invalid_input",
4 "message": "invalid input in field 'broken_field': is too long",
5 "details": {
6 "fields": [
7 {
8 "name": "broken_field",
9 "messages": ["is too long"]
10 }
11 ]
12 }
13 }
14}1{
2 "error": {
3 "code": "uniqueness_error",
4 "message": "SSH key with the same fingerprint already exists",
5 "details": {
6 "fields": [
7 {
8 "name": "public_key"
9 }
10 ]
11 }
12 }
13}1{
2 "error": {
3 "code": "resource_limit_exceeded",
4 "message": "project limit exceeded",
5 "details": {
6 "limits": [
7 {
8 "name": "project_limit"
9 }
10 ]
11 }
12 }
13}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.
1{
2 "labels": {
3 "environment": "development",
4 "service": "backend",
5 "example.com/my": "label",
6 "just-a-key": ""
7 }
8}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 |
Returns all resources that have a
env=production
label and that don't have a
type=database
label:
env=production,type!=database
Returns all resources that have a
env=testing
or
env=staging
label:
env in (testing,staging)
Returns all resources that don't have a
type
label:
!type
Responses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:
page
parameter specifies the page to fetch. The number of the first page is 1.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.
1{
2 "servers": [...],
3 "meta": {
4 "pagination": {
5 "page": 2,
6 "per_page": 25,
7 "previous_page": 1,
8 "next_page": 3,
9 "last_page": 4,
10 "total_entries": 100
11 }
12 }
13}1Link: <https://api.hetzner.cloud/v1/actions?page=2&per_page=5>; rel="prev",
2 <https://api.hetzner.cloud/v1/actions?page=4&per_page=5>; rel="next",
3 <https://api.hetzner.cloud/v1/actions?page=6&per_page=5>; rel="last"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.
RateLimit-Limit
header contains the total number of requests you can perform per hour.RateLimit-Remaining
header contains the number of requests remaining in the current rate limit time frame.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.
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 |
1$ curl http://169.254.169.254/hetzner/v1/metadata1availability-zone: hel1-dc2
2hostname: my-server
3instance-id: 42
4public-ipv4: 1.2.3.4
5region: eu-central1$ curl http://169.254.169.254/hetzner/v1/metadata/hostname
2my-server1$ curl http://169.254.169.254/hetzner/v1/metadata/instance-id
2421$ curl http://169.254.169.254/hetzner/v1/metadata/public-ipv4
21.2.3.41$ curl http://169.254.169.254/hetzner/v1/metadata/private-networks1- ip: 10.0.0.2
2 alias_ips: [10.0.0.3, 10.0.0.4]
3 interface_num: 1
4 mac_address: 86:00:00:2a:7d:e0
5 network_id: 1234
6 network_name: nw-test1
7 network: 10.0.0.0/8
8 subnet: 10.0.0.0/24
9 gateway: 10.0.0.1
10- ip: 192.168.0.2
11 alias_ips: []
12 interface_num: 2
13 mac_address: 86:00:00:2a:7d:e1
14 network_id: 4321
15 network_name: nw-test2
16 network: 192.168.0.0/16
17 subnet: 192.168.0.0/24
18 gateway: 192.168.0.11$ curl http://169.254.169.254/hetzner/v1/metadata/availability-zone
2hel1-dc21$ curl http://169.254.169.254/hetzner/v1/metadata/region
2eu-centralSome 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.
1https://api.hetzner.cloud/v1/actions?sort=status:asc
2https://api.hetzner.cloud/v1/actions?sort=status:desc
3https://api.hetzner.cloud/v1/actions?sort=status:asc&sort=command:descYou can find all announced deprecations in our Changelog.
Actions show the results and progress of asynchronous requests to the API.
Returns all Action objects. You can
sort
the results by using the sort URI parameter, and filter them with the
status
parameter.
GET /actionsCan be used multiple times, the response will contain only Actions with specified IDs.
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "start_resource",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:55:00+00:00",
10 "id": 42,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 42,
15 "type": "server"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 }
21 ],
22 "meta": {
23 "pagination": {
24 "last_page": 4,
25 "next_page": 4,
26 "page": 3,
27 "per_page": 25,
28 "previous_page": 2,
29 "total_entries": 100
30 }
31 }
32}Returns a specific Action object.
GET /actions/{id}ID of the Resource
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/actions/$ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "start_resource",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:55:00+00:00",
9 "id": 42,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic.
Returns all Certificate objects.
GET /certificatesidid:ascid:descnamename:ascname:desccreatedcreated:asccreated:descCan be used multiple times.
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
uploadedmanagedCan be used multiple times. The response will only contain Certificates matching the type.
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/certificates"1Content-Type: application/json
2Status: 2001{
2 "certificates": [
3 {
4 "certificate": "-----BEGIN CERTIFICATE-----\n...",
5 "created": "2019-01-08T12:10:00+00:00",
6 "domain_names": [
7 "example.com",
8 "webmail.example.com",
9 "www.example.com"
10 ],
11 "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
12 "id": 897,
13 "labels": {
14 "env": "dev"
15 },
16 "name": "my website cert",
17 "not_valid_after": "2019-07-08T09:59:59+00:00",
18 "not_valid_before": "2019-01-08T10:00:00+00:00",
19 "status": null,
20 "type": "uploaded",
21 "used_by": [
22 {
23 "id": 4711,
24 "type": "load_balancer"
25 }
26 ]
27 }
28 ]
29}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.
POST /certificatesCertificate and chain in PEM format, in order so that each record directly certifies the one preceding. Required for type
uploaded
Certificates.
Domains and subdomains that should be contained in the Certificate issued by Let's Encrypt. Required for type
managed
Certificates.
User-defined labels (key-value pairs)
Name of the Certificate
Certificate key in PEM format. Required for type
uploaded
Certificates.
uploadedmanagedChoose between uploading a Certificate in PEM format or requesting a managed Let's Encrypt Certificate. If omitted defaults to
uploaded
.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"domain_names":["example.com","webmail.example.com","www.example.com"],"name":"my website cert","type":"managed"}' \
6 "https://api.hetzner.cloud/v1/certificates"1{
2 "domain_names": [
3 "example.com",
4 "webmail.example.com",
5 "www.example.com"
6 ],
7 "name": "my website cert",
8 "type": "managed"
9}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "create_certificate",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": null,
9 "id": 13,
10 "progress": 0,
11 "resources": [
12 {
13 "id": 879,
14 "type": "certificate"
15 }
16 ],
17 "started": "2019-01-08T12:10:00+00:00",
18 "status": "running"
19 },
20 "certificate": {
21 "certificate": null,
22 "created": "2019-01-08T12:10:00+00:00",
23 "domain_names": [
24 "example.com",
25 "webmail.example.com",
26 "www.example.com"
27 ],
28 "fingerprint": null,
29 "id": 897,
30 "labels": {
31 "env": "dev"
32 },
33 "name": "my website cert",
34 "not_valid_after": null,
35 "not_valid_before": null,
36 "status": {
37 "error": null,
38 "issuance": "pending",
39 "renewal": "unavailable"
40 },
41 "type": "managed",
42 "used_by": [
43 {
44 "id": 4711,
45 "type": "load_balancer"
46 }
47 ]
48 }
49}Deletes a Certificate.
DELETE /certificates/{id}ID of the resource
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/certificates/$ID"1Status: 204Gets a specific Certificate object.
GET /certificates/{id}ID of the resource
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/certificates/$ID"1Content-Type: application/json
2Status: 2001{
2 "certificate": {
3 "certificate": "-----BEGIN CERTIFICATE-----\n...",
4 "created": "2019-01-08T12:10:00+00:00",
5 "domain_names": [
6 "example.com",
7 "webmail.example.com",
8 "www.example.com"
9 ],
10 "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
11 "id": 897,
12 "labels": {
13 "env": "dev"
14 },
15 "name": "my website cert",
16 "not_valid_after": "2019-07-08T09:59:59+00:00",
17 "not_valid_before": "2019-01-08T10:00:00+00:00",
18 "status": null,
19 "type": "uploaded",
20 "used_by": [
21 {
22 "id": 4711,
23 "type": "load_balancer"
24 }
25 ]
26 }
27}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.
PUT /certificates/{id}ID of the resource
User-defined labels (key-value pairs)
New Certificate name
1curl \
2 -X PUT \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"labels":{"labelkey":"value"},"name":"my website cert"}' \
6 "https://api.hetzner.cloud/v1/certificates/$ID"1{
2 "labels": {
3 "labelkey": "value"
4 },
5 "name": "my website cert"
6}1Content-Type: application/json
2Status: 2001{
2 "certificate": {
3 "certificate": "-----BEGIN CERTIFICATE-----\n...",
4 "created": "2019-01-08T12:10:00+00:00",
5 "domain_names": [
6 "example.com",
7 "webmail.example.com",
8 "www.example.com"
9 ],
10 "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
11 "id": 897,
12 "labels": {
13 "labelkey": "value"
14 },
15 "name": "my website cert",
16 "not_valid_after": "2019-07-08T09:59:59+00:00",
17 "not_valid_before": "2019-01-08T10:00:00+00:00",
18 "status": null,
19 "type": "uploaded",
20 "used_by": [
21 {
22 "id": 4711,
23 "type": "load_balancer"
24 }
25 ]
26 }
27}Returns all Action objects. You can
sort
the results by using the sort URI parameter, and filter them with the
status
and
id
parameter.
GET /certificates/actionsCan be used multiple times, the response will contain only Actions with specified IDs.
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/certificates/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "start_resource",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:55:00+00:00",
10 "id": 42,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 42,
15 "type": "server"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 }
21 ],
22 "meta": {
23 "pagination": {
24 "last_page": 4,
25 "next_page": 4,
26 "page": 3,
27 "per_page": 25,
28 "previous_page": 2,
29 "total_entries": 100
30 }
31 }
32}Returns a specific Action object.
GET /certificates/actions/{id}ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/certificates/actions/$ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "start_resource",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:55:00+00:00",
9 "id": 42,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}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.
GET /certificates/{id}/actionsID of the Action.
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/certificates/$ID/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "issue_certificate",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2021-01-30T23:57:00+00:00",
10 "id": 14,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 896,
15 "type": "certificate"
16 }
17 ],
18 "started": "2021-01-30T23:55:00+00:00",
19 "status": "success"
20 }
21 ]
22}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
.
| 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 |
POST /certificates/{id}/actions/retryID of the Certificate
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/certificates/$ID/actions/retry"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "issue_certificate",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2021-01-30T23:57:00+00:00",
9 "id": 14,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 896,
14 "type": "certificate"
15 }
16 ],
17 "started": "2021-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Returns a specific Action for a Certificate. Only type
managed
Certificates have Actions.
GET /certificates/{id}/actions/{action_id}ID of the Certificate
ID of the Action
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/certificates/$ID/actions/$ACTION_ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "issue_certificate",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2021-01-30T23:57:00+00:00",
9 "id": 14,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 896,
14 "type": "certificate"
15 }
16 ],
17 "started": "2021-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}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.
Returns all Datacenter objects.
GET /datacentersCan 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.
idid:ascid:descnamename:ascname:descCan be used multiple times.
Page to load.
Items to load per page.
The Datacenter which is recommended to be used to create new Servers.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/datacenters"1Content-Type: application/json
2Status: 2001{
2 "datacenters": [
3 {
4 "description": "Falkenstein DC Park 8",
5 "id": 42,
6 "location": {
7 "city": "Falkenstein",
8 "country": "DE",
9 "description": "Falkenstein DC Park 1",
10 "id": 1,
11 "latitude": 50.47612,
12 "longitude": 12.370071,
13 "name": "fsn1",
14 "network_zone": "eu-central"
15 },
16 "name": "fsn1-dc8",
17 "server_types": {
18 "available": [
19 1,
20 2,
21 3
22 ],
23 "available_for_migration": [
24 1,
25 2,
26 3
27 ],
28 "supported": [
29 1,
30 2,
31 3
32 ]
33 }
34 }
35 ],
36 "meta": {
37 "pagination": {
38 "last_page": 4,
39 "next_page": 4,
40 "page": 3,
41 "per_page": 25,
42 "previous_page": 2,
43 "total_entries": 100
44 }
45 },
46 "recommendation": 1
47}Returns a specific Datacenter object.
GET /datacenters/{id}ID of Datacenter
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/datacenters/$ID"1Content-Type: application/json
2Status: 2001{
2 "datacenter": {
3 "description": "Falkenstein DC Park 8",
4 "id": 42,
5 "location": {
6 "city": "Falkenstein",
7 "country": "DE",
8 "description": "Falkenstein DC Park 1",
9 "id": 1,
10 "latitude": 50.47612,
11 "longitude": 12.370071,
12 "name": "fsn1",
13 "network_zone": "eu-central"
14 },
15 "name": "fsn1-dc8",
16 "server_types": {
17 "available": [
18 1,
19 2,
20 3
21 ],
22 "available_for_migration": [
23 1,
24 2,
25 3
26 ],
27 "supported": [
28 1,
29 2,
30 3
31 ]
32 }
33 }
34}Firewalls can limit the network access to or from your resources.
in rule all inbound traffic will be dropped. The default for in is DROP.out rule all outbound traffic will be accepted. The default for out is ACCEPT.Returns all Firewall objects.
GET /firewallsidid:ascid:descnamename:ascname:desccreatedcreated:asccreated:descCan be used multiple times.
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/firewalls"1Content-Type: application/json
2Status: 2001{
2 "firewalls": [
3 {
4 "applied_to": [
5 {
6 "applied_to_resources": [
7 {
8 "server": {
9 "id": 42
10 },
11 "type": "server"
12 }
13 ],
14 "label_selector": {
15 "selector": "env=prod"
16 },
17 "server": {
18 "id": 42
19 },
20 "type": "server"
21 }
22 ],
23 "created": "2016-01-30T23:55:00+00:00",
24 "id": 42,
25 "labels": {},
26 "name": "my-resource",
27 "rules": [
28 {
29 "description": null,
30 "destination_ips": [
31 "28.239.13.1/32",
32 "28.239.14.0/24",
33 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
34 ],
35 "direction": "in",
36 "port": "80",
37 "protocol": "tcp",
38 "source_ips": [
39 "28.239.13.1/32",
40 "28.239.14.0/24",
41 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
42 ]
43 }
44 ]
45 }
46 ],
47 "meta": {
48 "pagination": {
49 "last_page": 4,
50 "next_page": 4,
51 "page": 3,
52 "per_page": 25,
53 "previous_page": 2,
54 "total_entries": 100
55 }
56 }
57}Creates a new Firewall.
| 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 |
POST /firewallsResources the Firewall should be applied to after creation
User-defined labels (key-value pairs)
Name of the Firewall
Array of rules
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -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"]}]}' \
6 "https://api.hetzner.cloud/v1/firewalls"1{
2 "apply_to": [
3 {
4 "server": {
5 "id": 42
6 },
7 "type": "server"
8 }
9 ],
10 "labels": {
11 "env": "dev"
12 },
13 "name": "Corporate Intranet Protection",
14 "rules": [
15 {
16 "description": "Allow port 80",
17 "direction": "in",
18 "port": "80",
19 "protocol": "tcp",
20 "source_ips": [
21 "28.239.13.1/32",
22 "28.239.14.0/24",
23 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
24 ]
25 }
26 ]
27}1Content-Type: application/json
2Status: 2011{
2 "actions": [
3 {
4 "command": "set_firewall_rules",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:56:00+00:00",
10 "id": 13,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 38,
15 "type": "firewall"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 },
21 {
22 "command": "apply_firewall",
23 "error": {
24 "code": "action_failed",
25 "message": "Action failed"
26 },
27 "finished": "2016-01-30T23:56:00+00:00",
28 "id": 14,
29 "progress": 100,
30 "resources": [
31 {
32 "id": 42,
33 "type": "server"
34 },
35 {
36 "id": 38,
37 "type": "firewall"
38 }
39 ],
40 "started": "2016-01-30T23:55:00+00:00",
41 "status": "success"
42 }
43 ],
44 "firewall": {
45 "applied_to": [
46 {
47 "applied_to_resources": [
48 {
49 "server": {
50 "id": 42
51 },
52 "type": "server"
53 }
54 ],
55 "label_selector": {
56 "selector": "env=prod"
57 },
58 "server": {
59 "id": 42
60 },
61 "type": "server"
62 }
63 ],
64 "created": "2016-01-30T23:55:00+00:00",
65 "id": 42,
66 "labels": {},
67 "name": "my-resource",
68 "rules": [
69 {
70 "description": null,
71 "destination_ips": [
72 "28.239.13.1/32",
73 "28.239.14.0/24",
74 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
75 ],
76 "direction": "in",
77 "port": "80",
78 "protocol": "tcp",
79 "source_ips": [
80 "28.239.13.1/32",
81 "28.239.14.0/24",
82 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
83 ]
84 }
85 ]
86 }
87}Deletes a Firewall.
| Code | Description |
|---|---|
resource_in_use
|
Firewall must not be in use to be deleted |
DELETE /firewalls/{id}ID of the resource
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/firewalls/$ID"1Status: 204Gets a specific Firewall object.
GET /firewalls/{id}ID of the resource
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/firewalls/$ID"1Content-Type: application/json
2Status: 2001{
2 "firewall": {
3 "applied_to": [
4 {
5 "applied_to_resources": [
6 {
7 "server": {
8 "id": 42
9 },
10 "type": "server"
11 }
12 ],
13 "label_selector": {
14 "selector": "env=prod"
15 },
16 "server": {
17 "id": 42
18 },
19 "type": "server"
20 }
21 ],
22 "created": "2016-01-30T23:55:00+00:00",
23 "id": 42,
24 "labels": {},
25 "name": "my-resource",
26 "rules": [
27 {
28 "description": null,
29 "destination_ips": [
30 "28.239.13.1/32",
31 "28.239.14.0/24",
32 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
33 ],
34 "direction": "in",
35 "port": "80",
36 "protocol": "tcp",
37 "source_ips": [
38 "28.239.13.1/32",
39 "28.239.14.0/24",
40 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
41 ]
42 }
43 ]
44 }
45}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.
PUT /firewalls/{id}ID of the resource
User-defined labels (key-value pairs)
New Firewall name
1curl \
2 -X PUT \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"labels":{"labelkey":"value"},"name":"new-name"}' \
6 "https://api.hetzner.cloud/v1/firewalls/$ID"1{
2 "labels": {
3 "labelkey": "value"
4 },
5 "name": "new-name"
6}1Content-Type: application/json
2Status: 2001{
2 "firewall": {
3 "applied_to": [
4 {
5 "applied_to_resources": [
6 {
7 "server": {
8 "id": 42
9 },
10 "type": "server"
11 }
12 ],
13 "label_selector": {
14 "selector": "env=prod"
15 },
16 "server": {
17 "id": 42
18 },
19 "type": "server"
20 }
21 ],
22 "created": "2016-01-30T23:55:00+00:00",
23 "id": 42,
24 "labels": {},
25 "name": "my-resource",
26 "rules": [
27 {
28 "description": null,
29 "destination_ips": [
30 "28.239.13.1/32",
31 "28.239.14.0/24",
32 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
33 ],
34 "direction": "in",
35 "port": "80",
36 "protocol": "tcp",
37 "source_ips": [
38 "28.239.13.1/32",
39 "28.239.14.0/24",
40 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
41 ]
42 }
43 ]
44 }
45}Returns all Action objects. You can
sort
the results by using the sort URI parameter, and filter them with the
status
and
id
parameter.
GET /firewalls/actionsCan be used multiple times, the response will contain only Actions with specified IDs.
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/firewalls/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "start_resource",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:55:00+00:00",
10 "id": 42,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 42,
15 "type": "server"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 }
21 ],
22 "meta": {
23 "pagination": {
24 "last_page": 4,
25 "next_page": 4,
26 "page": 3,
27 "per_page": 25,
28 "previous_page": 2,
29 "total_entries": 100
30 }
31 }
32}Returns a specific Action object.
GET /firewalls/actions/{id}ID of the Resource
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/firewalls/actions/$ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "start_resource",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:55:00+00:00",
9 "id": 42,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}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.
GET /firewalls/{id}/actionsID of the Action.
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/firewalls/$ID/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "set_firewall_rules",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:56:00+00:00",
10 "id": 13,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 38,
15 "type": "firewall"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 }
21 ]
22}Applies one Firewall to multiple resources.
Currently servers (public network interface) and label selectors are supported.
| 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 |
POST /firewalls/{id}/actions/apply_to_resourcesID of the Firewall
Resources the Firewall should be applied to
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"apply_to":[{"server":{"id":42},"type":"server"}]}' \
6 "https://api.hetzner.cloud/v1/firewalls/$ID/actions/apply_to_resources"1{
2 "apply_to": [
3 {
4 "server": {
5 "id": 42
6 },
7 "type": "server"
8 }
9 ]
10}1Content-Type: application/json
2Status: 2011{
2 "actions": [
3 {
4 "command": "apply_firewall",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:56:00+00:00",
10 "id": 14,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 42,
15 "type": "server"
16 },
17 {
18 "id": 38,
19 "type": "firewall"
20 }
21 ],
22 "started": "2016-01-30T23:55:00+00:00",
23 "status": "success"
24 }
25 ]
26}Removes one Firewall from multiple resources.
Currently only Servers (and their public network interfaces) are supported.
| 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 |
POST /firewalls/{id}/actions/remove_from_resourcesID of the Firewall
Resources the Firewall should be removed from
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"remove_from":[{"server":{"id":42},"type":"server"}]}' \
6 "https://api.hetzner.cloud/v1/firewalls/$ID/actions/remove_from_resources"1{
2 "remove_from": [
3 {
4 "server": {
5 "id": 42
6 },
7 "type": "server"
8 }
9 ]
10}1Content-Type: application/json
2Status: 2011{
2 "actions": [
3 {
4 "command": "remove_firewall",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:56:00+00:00",
10 "id": 14,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 42,
15 "type": "server"
16 },
17 {
18 "id": 38,
19 "type": "firewall"
20 }
21 ],
22 "started": "2016-01-30T23:55:00+00:00",
23 "status": "success"
24 }
25 ]
26}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.
| Code | Description |
|---|---|
firewall_resource_not_found
|
The resource the Firewall should be attached to was not found |
POST /firewalls/{id}/actions/set_rulesID of the Firewall
Array of rules
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -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"]}]}' \
6 "https://api.hetzner.cloud/v1/firewalls/$ID/actions/set_rules"1{
2 "rules": [
3 {
4 "description": "Allow port 80",
5 "direction": "in",
6 "port": "80",
7 "protocol": "tcp",
8 "source_ips": [
9 "28.239.13.1/32",
10 "28.239.14.0/24",
11 "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
12 ]
13 }
14 ]
15}1Content-Type: application/json
2Status: 2011{
2 "actions": [
3 {
4 "command": "set_firewall_rules",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:56:00+00:00",
10 "id": 13,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 38,
15 "type": "firewall"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 },
21 {
22 "command": "apply_firewall",
23 "error": {
24 "code": "action_failed",
25 "message": "Action failed"
26 },
27 "finished": "2016-01-30T23:56:00+00:00",
28 "id": 14,
29 "progress": 100,
30 "resources": [
31 {
32 "id": 38,
33 "type": "firewall"
34 },
35 {
36 "id": 42,
37 "type": "server"
38 }
39 ],
40 "started": "2016-01-30T23:55:00+00:00",
41 "status": "success"
42 }
43 ]
44}Returns a specific Action for a Firewall.
GET /firewalls/{id}/actions/{action_id}ID of the Firewall
ID of the Action
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/firewalls/$ID/actions/$ACTION_ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "set_firewall_rules",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 38,
14 "type": "firewall"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}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.
Returns all Floating IP objects.
GET /floating_ipsCan be used to filter Floating IPs by their name. The response will only contain the Floating IP matching the specified name.
Can be used to filter Floating IPs by labels. The response will only contain Floating IPs matching the label selector.
idid:ascid:desccreatedcreated:asccreated:descCan be used multiple times. Choices id id:asc id:desc created created:asc created:desc
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/floating_ips"1Content-Type: application/json
2Status: 2001{
2 "floating_ips": [
3 {
4 "blocked": false,
5 "created": "2016-01-30T23:55:00+00:00",
6 "description": "this describes my resource",
7 "dns_ptr": [
8 {
9 "dns_ptr": "server.example.com",
10 "ip": "2001:db8::1"
11 }
12 ],
13 "home_location": {
14 "city": "Falkenstein",
15 "country": "DE",
16 "description": "Falkenstein DC Park 1",
17 "id": 1,
18 "latitude": 50.47612,
19 "longitude": 12.370071,
20 "name": "fsn1",
21 "network_zone": "eu-central"
22 },
23 "id": 42,
24 "ip": "131.232.99.1",
25 "labels": {},
26 "name": "my-resource",
27 "protection": {
28 "delete": false
29 },
30 "server": 42,
31 "type": "ipv4"
32 }
33 ],
34 "meta": {
35 "pagination": {
36 "last_page": 4,
37 "next_page": 4,
38 "page": 3,
39 "per_page": 25,
40 "previous_page": 2,
41 "total_entries": 100
42 }
43 }
44}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.
POST /floating_ipsThe
type
argument is required while
home_location
and
server
are mutually exclusive.
Home Location (routing is optimized for that Location). Only optional if Server argument is passed.
User-defined labels (key-value pairs)
ID of the Server to assign the Floating IP to
ipv4ipv6Floating IP type
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"description":"Web Frontend","home_location":"fsn1","labels":{"labelkey":"value"},"name":"Web Frontend","server":42,"type":"ipv4"}' \
6 "https://api.hetzner.cloud/v1/floating_ips"1{
2 "description": "Web Frontend",
3 "home_location": "fsn1",
4 "labels": {
5 "labelkey": "value"
6 },
7 "name": "Web Frontend",
8 "server": 42,
9 "type": "ipv4"
10}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "create_floating_ip",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": null,
9 "id": 13,
10 "progress": 0,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 }
16 ],
17 "started": "2016-01-30T23:50:00+00:00",
18 "status": "running"
19 },
20 "floating_ip": {
21 "blocked": false,
22 "created": "2016-01-30T23:50:00+00:00",
23 "description": "Web Frontend",
24 "dns_ptr": [
25 {
26 "dns_ptr": "server.example.com",
27 "ip": "2001:db8::1"
28 }
29 ],
30 "home_location": {
31 "city": "Falkenstein",
32 "country": "DE",
33 "description": "Falkenstein DC Park 1",
34 "id": 1,
35 "latitude": 50.47612,
36 "longitude": 12.370071,
37 "name": "fsn1",
38 "network_zone": "eu-central"
39 },
40 "id": 4711,
41 "ip": "131.232.99.1",
42 "labels": {
43 "env": "dev"
44 },
45 "name": "Web Frontend",
46 "protection": {
47 "delete": false
48 },
49 "server": 42,
50 "type": "ipv4"
51 }
52}Deletes a Floating IP. If it is currently assigned to a Server it will automatically get unassigned.
DELETE /floating_ips/{id}ID of the Floating IP
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/floating_ips/$ID"1Status: 204Returns a specific Floating IP object.
GET /floating_ips/{id}ID of the Floating IP
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/floating_ips/$ID"1Content-Type: application/json
2Status: 2001{
2 "floating_ip": {
3 "blocked": false,
4 "created": "2016-01-30T23:55:00+00:00",
5 "description": "this describes my resource",
6 "dns_ptr": [
7 {
8 "dns_ptr": "server.example.com",
9 "ip": "2001:db8::1"
10 }
11 ],
12 "home_location": {
13 "city": "Falkenstein",
14 "country": "DE",
15 "description": "Falkenstein DC Park 1",
16 "id": 1,
17 "latitude": 50.47612,
18 "longitude": 12.370071,
19 "name": "fsn1",
20 "network_zone": "eu-central"
21 },
22 "id": 42,
23 "ip": "131.232.99.1",
24 "labels": {},
25 "name": "my-resource",
26 "protection": {
27 "delete": false
28 },
29 "server": 42,
30 "type": "ipv4"
31 }
32}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.
PUT /floating_ips/{id}ID of the Floating IP
New Description to set
User-defined labels (key-value pairs)
New unique name to set
1curl \
2 -X PUT \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"description":"Web Frontend","labels":{"labelkey":"value"},"name":"Web Frontend"}' \
6 "https://api.hetzner.cloud/v1/floating_ips/$ID"1{
2 "description": "Web Frontend",
3 "labels": {
4 "labelkey": "value"
5 },
6 "name": "Web Frontend"
7}1Content-Type: application/json
2Status: 2001{
2 "floating_ip": {
3 "blocked": false,
4 "created": "2016-01-30T23:50:00+00:00",
5 "description": "Web Frontend",
6 "dns_ptr": [
7 {
8 "dns_ptr": "server.example.com",
9 "ip": "2001:db8::1"
10 }
11 ],
12 "home_location": {
13 "city": "Falkenstein",
14 "country": "DE",
15 "description": "Falkenstein DC Park 1",
16 "id": 1,
17 "latitude": 50.47612,
18 "longitude": 12.370071,
19 "name": "fsn1",
20 "network_zone": "eu-central"
21 },
22 "id": 4711,
23 "ip": "131.232.99.1",
24 "labels": {
25 "labelkey": "value"
26 },
27 "name": "Web Frontend",
28 "protection": {
29 "delete": false
30 },
31 "server": 42,
32 "type": "ipv4"
33 }
34}Returns all Action objects. You can
sort
the results by using the sort URI parameter, and filter them with the
status
and
id
parameter.
GET /floating_ips/actionsCan be used multiple times, the response will contain only Actions with specified IDs.
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/floating_ips/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "start_resource",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:55:00+00:00",
10 "id": 42,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 42,
15 "type": "server"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 }
21 ],
22 "meta": {
23 "pagination": {
24 "last_page": 4,
25 "next_page": 4,
26 "page": 3,
27 "per_page": 25,
28 "previous_page": 2,
29 "total_entries": 100
30 }
31 }
32}Returns a specific Action object.
GET /floating_ips/actions/{id}ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/floating_ips/actions/$ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "start_resource",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:55:00+00:00",
9 "id": 42,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}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.
GET /floating_ips/{id}/actionsID of the Floating IP
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/floating_ips/$ID/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "assign_floating_ip",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:56:00+00:00",
10 "id": 13,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 4711,
15 "type": "server"
16 },
17 {
18 "id": 4712,
19 "type": "floating_ip"
20 }
21 ],
22 "started": "2016-01-30T23:55:00+00:00",
23 "status": "success"
24 }
25 ]
26}Assigns a Floating IP to a Server.
POST /floating_ips/{id}/actions/assignID of the Floating IP
ID of the Server the Floating IP shall be assigned to
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"server":42}' \
6 "https://api.hetzner.cloud/v1/floating_ips/$ID/actions/assign"1{
2 "server": 42
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "assign_floating_ip",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 },
16 {
17 "id": 4711,
18 "type": "floating_ip"
19 }
20 ],
21 "started": "2016-01-30T23:55:00+00:00",
22 "status": "success"
23 }
24}Changes the hostname that will appear when getting the hostname belonging to this Floating IP.
POST /floating_ips/{id}/actions/change_dns_ptrID of the Floating IP
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. You can add up to 100 IPv6 reverse DNS entries.
The target hostname is set by passing
dns_ptr
.
Hostname to set as a reverse DNS PTR entry, will reset to original default value if
null
IP address for which to set the reverse DNS entry
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"dns_ptr":"server02.example.com","ip":"1.2.3.4"}' \
6 "https://api.hetzner.cloud/v1/floating_ips/$ID/actions/change_dns_ptr"1{
2 "dns_ptr": "server02.example.com",
3 "ip": "1.2.3.4"
4}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "change_dns_ptr",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 4711,
14 "type": "floating_ip"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Changes the protection configuration of the Floating IP.
POST /floating_ips/{id}/actions/change_protectionID of the Floating IP
If true, prevents the Floating IP from being deleted
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"delete":true}' \
6 "https://api.hetzner.cloud/v1/floating_ips/$ID/actions/change_protection"1{
2 "delete": true
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "change_protection",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 4711,
14 "type": "floating_ip"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Unassigns a Floating IP, resulting in it being unreachable. You may assign it to a Server again at a later time.
POST /floating_ips/{id}/actions/unassignID of the Floating IP
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/floating_ips/$ID/actions/unassign"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "unassign_floating_ip",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 },
16 {
17 "id": 4711,
18 "type": "floating_ip"
19 }
20 ],
21 "started": "2016-01-30T23:55:00+00:00",
22 "status": "success"
23 }
24}Returns a specific Action object for a Floating IP.
GET /floating_ips/{id}/actions/{action_id}ID of the Floating IP
ID of the Action
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/floating_ips/$ID/actions/$ACTION_ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "assign_floating_ip",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 },
16 {
17 "id": 4711,
18 "type": "floating_ip"
19 }
20 ],
21 "started": "2016-01-30T23:55:00+00:00",
22 "status": "success"
23 }
24}Images are blueprints for your VM disks. They can be of different types:
Distribution Images maintained by us, e.g. “Ubuntu 20.04”
Maintained by you, for example “Ubuntu 20.04 with my own settings”. These are billed per GB per month.
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.
Prebuild images with specific software configurations, e.g. “Wordpress”. All app images are created by us.
Returns all Image objects. You can select specific Image types only and sort the results by using URI parameters.
GET /imagesidid:ascid:descnamename:ascname:desccreatedcreated:asccreated:descCan be used multiple times.
systemsnapshotbackupappCan be used multiple times.
availablecreatingCan be used multiple times. The response will only contain Images matching the status.
Can be used multiple times. Server ID linked to the Image. Only available for Images of type
backup
Can be used multiple times.
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
Return only Images with the given architecture.
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/images"1Content-Type: application/json
2Status: 2001{
2 "images": [
3 {
4 "architecture": "x86",
5 "bound_to": null,
6 "created": "2016-01-30T23:55:00+00:00",
7 "created_from": {
8 "id": 1,
9 "name": "Server"
10 },
11 "deleted": null,
12 "deprecated": "2018-02-28T00:00:00+00:00",
13 "description": "Ubuntu 20.04 Standard 64 bit",
14 "disk_size": 10,
15 "id": 42,
16 "image_size": 2.3,
17 "labels": {},
18 "name": "ubuntu-20.04",
19 "os_flavor": "ubuntu",
20 "os_version": "20.04",
21 "protection": {
22 "delete": false
23 },
24 "rapid_deploy": false,
25 "status": "available",
26 "type": "snapshot"
27 }
28 ],
29 "meta": {
30 "pagination": {
31 "last_page": 4,
32 "next_page": 4,
33 "page": 3,
34 "per_page": 25,
35 "previous_page": 2,
36 "total_entries": 100
37 }
38 }
39}Deletes an Image. Only Images of type
snapshot
and
backup
can be deleted.
DELETE /images/{id}ID of the Image
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/images/$ID"1Status: 204Returns a specific Image object.
GET /images/{id}ID of the Image
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/images/$ID"1Content-Type: application/json
2Status: 2001{
2 "image": {
3 "architecture": "x86",
4 "bound_to": null,
5 "created": "2016-01-30T23:55:00+00:00",
6 "created_from": {
7 "id": 1,
8 "name": "Server"
9 },
10 "deleted": null,
11 "deprecated": "2018-02-28T00:00:00+00:00",
12 "description": "Ubuntu 20.04 Standard 64 bit",
13 "disk_size": 10,
14 "id": 42,
15 "image_size": 2.3,
16 "labels": {},
17 "name": "ubuntu-20.04",
18 "os_flavor": "ubuntu",
19 "os_version": "20.04",
20 "protection": {
21 "delete": false
22 },
23 "rapid_deploy": false,
24 "status": "available",
25 "type": "snapshot"
26 }
27}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.
PUT /images/{id}ID of the Image
New description of Image
User-defined labels (key-value pairs)
snapshotDestination Image type to convert to
1curl \
2 -X PUT \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"description":"My new Image description","labels":{"labelkey":"value"},"type":"snapshot"}' \
6 "https://api.hetzner.cloud/v1/images/$ID"1{
2 "description": "My new Image description",
3 "labels": {
4 "labelkey": "value"
5 },
6 "type": "snapshot"
7}1Content-Type: application/json
2Status: 2001{
2 "image": {
3 "architecture": "x86",
4 "bound_to": null,
5 "created": "2016-01-30T23:50:00+00:00",
6 "created_from": {
7 "id": 1,
8 "name": "Server"
9 },
10 "deleted": null,
11 "deprecated": "2018-02-28T00:00:00+00:00",
12 "description": "My new Image description",
13 "disk_size": 10,
14 "id": 4711,
15 "image_size": 2.3,
16 "labels": {
17 "labelkey": "value"
18 },
19 "name": null,
20 "os_flavor": "ubuntu",
21 "os_version": "20.04",
22 "protection": {
23 "delete": false
24 },
25 "rapid_deploy": false,
26 "status": "available",
27 "type": "snapshot"
28 }
29}Returns all Action objects. You can
sort
the results by using the sort URI parameter, and filter them with the
status
and
id
parameter.
GET /images/actionsCan be used multiple times, the response will contain only Actions with specified IDs.
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/images/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "start_resource",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:55:00+00:00",
10 "id": 42,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 42,
15 "type": "server"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 }
21 ],
22 "meta": {
23 "pagination": {
24 "last_page": 4,
25 "next_page": 4,
26 "page": 3,
27 "per_page": 25,
28 "previous_page": 2,
29 "total_entries": 100
30 }
31 }
32}Returns a specific Action object.
GET /images/actions/{id}ID of the Resource
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/images/actions/$ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "start_resource",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:55:00+00:00",
9 "id": 42,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 42,
14 "type": "server"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}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.
GET /images/{id}/actionsID of the Image
idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:descCan be used multiple times.
runningsuccesserrorCan be used multiple times, the response will contain only Actions with specified statuses
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/images/$ID/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "change_protection",
5 "error": {
6 "code": "action_failed",
7 "message": "Action failed"
8 },
9 "finished": "2016-01-30T23:56:00+00:00",
10 "id": 13,
11 "progress": 100,
12 "resources": [
13 {
14 "id": 4711,
15 "type": "image"
16 }
17 ],
18 "started": "2016-01-30T23:55:00+00:00",
19 "status": "success"
20 }
21 ]
22}Changes the protection configuration of the Image. Can only be used on snapshots.
POST /images/{id}/actions/change_protectionID of the Image
If true, prevents the snapshot from being deleted
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"delete":true}' \
6 "https://api.hetzner.cloud/v1/images/$ID/actions/change_protection"1{
2 "delete": true
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "change_protection",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 4711,
14 "type": "image"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Returns a specific Action for an Image.
GET /images/{id}/actions/{action_id}ID of the Image
ID of the Action
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/images/$ID/actions/$ACTION_ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "change_protection",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 4711,
14 "type": "image"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}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.
Returns all available ISO objects.
GET /isosCan be used to filter ISOs by their name. The response will only contain the ISO matching the specified name.
Return only ISOs with the given architecture.
Include Images with wildcard architecture (architecture is null). Works only if architecture filter is specified.
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/isos"1Content-Type: application/json
2Status: 2001{
2 "isos": [
3 {
4 "architecture": "x86",
5 "deprecated": "2018-02-28T00:00:00+00:00",
6 "deprecation": {
7 "announced": "2023-06-01T00:00:00+00:00",
8 "unavailable_after": "2023-09-01T00:00:00+00:00"
9 },
10 "description": "FreeBSD 11.0 x64",
11 "id": 42,
12 "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
13 "type": "public"
14 }
15 ],
16 "meta": {
17 "pagination": {
18 "last_page": 4,
19 "next_page": 4,
20 "page": 3,
21 "per_page": 25,
22 "previous_page": 2,
23 "total_entries": 100
24 }
25 }
26}Returns a specific ISO object.
GET /isos/{id}ID of the ISO
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/isos/$ID"1Content-Type: application/json
2Status: 2001{
2 "iso": {
3 "architecture": "x86",
4 "deprecated": "2018-02-28T00:00:00+00:00",
5 "deprecation": {
6 "announced": "2023-06-01T00:00:00+00:00",
7 "unavailable_after": "2023-09-01T00:00:00+00:00"
8 },
9 "description": "FreeBSD 11.0 x64",
10 "id": 42,
11 "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
12 "type": "public"
13 }
14}Gets all existing Load Balancers that you have available.
GET /load_balancersidid:ascid:descnamename:ascname:desccreatedcreated:asccreated:descCan be used multiple times.
Can be used to filter resources by their name. The response will only contain the resources matching the specified name
Can be used to filter resources by labels. The response will only contain resources matching the label selector.
Page to load.
Items to load per page.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/load_balancers"1Content-Type: application/json
2Status: 2001{
2 "load_balancers": [
3 {
4 "algorithm": {
5 "type": "round_robin"
6 },
7 "created": "2016-01-30T23:55:00+00:00",
8 "id": 42,
9 "included_traffic": 10000,
10 "ingoing_traffic": null,
11 "labels": {},
12 "load_balancer_type": {
13 "deprecated": "2016-01-30T23:50:00+00:00",
14 "description": "LB11",
15 "id": 1,
16 "max_assigned_certificates": 10,
17 "max_connections": 20000,
18 "max_services": 5,
19 "max_targets": 25,
20 "name": "lb11",
21 "prices": [
22 {
23 "location": "fsn1",
24 "price_hourly": {
25 "gross": "1.1900000000000000",
26 "net": "1.0000000000"
27 },
28 "price_monthly": {
29 "gross": "1.1900000000000000",
30 "net": "1.0000000000"
31 }
32 }
33 ]
34 },
35 "location": {
36 "city": "Falkenstein",
37 "country": "DE",
38 "description": "Falkenstein DC Park 1",
39 "id": 1,
40 "latitude": 50.47612,
41 "longitude": 12.370071,
42 "name": "fsn1",
43 "network_zone": "eu-central"
44 },
45 "name": "my-resource",
46 "outgoing_traffic": null,
47 "private_net": [
48 {
49 "ip": "10.0.0.2",
50 "network": 4711
51 }
52 ],
53 "protection": {
54 "delete": false
55 },
56 "public_net": {
57 "enabled": false,
58 "ipv4": {
59 "dns_ptr": "lb1.example.com",
60 "ip": "1.2.3.4"
61 },
62 "ipv6": {
63 "dns_ptr": "lb1.example.com",
64 "ip": "2001:db8::1"
65 }
66 },
67 "services": [
68 {
69 "destination_port": 80,
70 "health_check": {
71 "http": {
72 "domain": "example.com",
73 "path": "/",
74 "response": "{\"status\": \"ok\"}",
75 "status_codes": [
76 "2??",
77 "3??"
78 ],
79 "tls": false
80 },
81 "interval": 15,
82 "port": 4711,
83 "protocol": "http",
84 "retries": 3,
85 "timeout": 10
86 },
87 "http": {
88 "certificates": [
89 897
90 ],
91 "cookie_lifetime": 300,
92 "cookie_name": "HCLBSTICKY",
93 "redirect_http": true,
94 "sticky_sessions": true
95 },
96 "listen_port": 443,
97 "protocol": "https",
98 "proxyprotocol": false
99 }
100 ],
101 "targets": [
102 {
103 "health_status": [
104 {
105 "listen_port": 443,
106 "status": "healthy"
107 }
108 ],
109 "ip": {
110 "ip": "203.0.113.1"
111 },
112 "label_selector": {
113 "selector": "env=prod"
114 },
115 "server": {
116 "id": 80
117 },
118 "targets": [
119 {
120 "health_status": [
121 {
122 "listen_port": 443,
123 "status": "healthy"
124 }
125 ],
126 "server": {
127 "id": 80
128 },
129 "type": "server",
130 "use_private_ip": false
131 }
132 ],
133 "type": "server",
134 "use_private_ip": false
135 }
136 ]
137 }
138 ],
139 "meta": {
140 "pagination": {
141 "last_page": 4,
142 "next_page": 4,
143 "page": 3,
144 "per_page": 25,
145 "previous_page": 2,
146 "total_entries": 100
147 }
148 }
149}Creates a Load Balancer.
| 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 |
POST /load_balancersAlgorithm of the Load Balancer
User-defined labels (key-value pairs)
ID or name of the Load Balancer type this Load Balancer should be created with
ID or name of Location to create Load Balancer in
Name of the Load Balancer
ID of the network the Load Balancer should be attached to on creation
Name of network zone
Enable or disable the public interface of the Load Balancer
Array of services
Array of targets
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -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}]}' \
6 "https://api.hetzner.cloud/v1/load_balancers"1{
2 "algorithm": {
3 "type": "round_robin"
4 },
5 "labels": {
6 "labelkey": "value"
7 },
8 "load_balancer_type": "lb11",
9 "location": "string",
10 "name": "Web Frontend",
11 "network": 123,
12 "network_zone": "eu-central",
13 "public_interface": true,
14 "services": [
15 {
16 "destination_port": 80,
17 "health_check": {
18 "http": {
19 "domain": "example.com",
20 "path": "/",
21 "response": "{\"status\": \"ok\"}",
22 "status_codes": [
23 "2??",
24 "3??"
25 ],
26 "tls": false
27 },
28 "interval": 15,
29 "port": 4711,
30 "protocol": "http",
31 "retries": 3,
32 "timeout": 10
33 },
34 "http": {
35 "certificates": [
36 897
37 ],
38 "cookie_lifetime": 300,
39 "cookie_name": "HCLBSTICKY",
40 "redirect_http": true,
41 "sticky_sessions": true
42 },
43 "listen_port": 443,
44 "protocol": "https",
45 "proxyprotocol": false
46 }
47 ],
48 "targets": [
49 {
50 "health_status": [
51 {
52 "listen_port": 443,
53 "status": "healthy"
54 }
55 ],
56 "ip": {
57 "ip": "203.0.113.1"
58 },
59 "label_selector": {
60 "selector": "env=prod"
61 },
62 "server": {
63 "id": 80
64 },
65 "targets": [
66 {
67 "health_status": [
68 {
69 "listen_port": 443,
70 "status": "healthy"
71 }
72 ],
73 "server": {
74 "id": 80
75 },
76 "type": "server",
77 "use_private_ip": false
78 }
79 ],
80 "type": "server",
81 "use_private_ip": false
82 }
83 ]
84}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "create_load_balancer",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": "2016-01-30T23:56:00+00:00",
9 "id": 13,
10 "progress": 100,
11 "resources": [
12 {
13 "id": 4711,
14 "type": "load_balancer"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 },
20 "load_balancer": {
21 "algorithm": {
22 "type": "round_robin"
23 },
24 "created": "2016-01-30T23:50:00+00:00",
25 "id": 4711,
26 "included_traffic": 654321,
27 "ingoing_traffic": 123456,
28 "labels": {
29 "env": "dev"
30 },
31 "load_balancer_type": {
32 "deprecated": "2016-01-30T23:50:00+00:00",
33 "description": "LB11",
34 "id": 1,
35 "max_assigned_certificates": 10,
36 "max_connections": 20000,
37 "max_services": 5,
38 "max_targets": 25,
39 "name": "lb11",
40 "prices": [
41 {
42 "location": "fsn1",
43 "price_hourly": {
44 "gross": "1.1900000000000000",
45 "net": "1.0000000000"
46 },
47 "price_monthly": {
48 "gross": "1.1900000000000000",
49 "net": "1.0000000000"
50 }
51 }
52 ]
53 },
54 "location": {
55 "city": "Falkenstein",
56 "country": "DE",
57 "description": "Falkenstein DC Park 1",
58 "id": 1,
59 "latitude": 50.47612,
60 "longitude": 12.370071,
61 "name": "fsn1",
62 "network_zone": "eu-central"
63 },
64 "name": "Web Frontend",
65 "outgoing_traffic": 123456,
66 "private_net": [
67 {
68 "ip": "10.0.0.2",
69 "network": 4711
70 }
71 ],
72 "protection": {
73 "delete": false
74 },
75 "public_net": {
76 "enabled": false,
77 "ipv4": {
78 "ip": "1.2.3.4"
79 },
80 "ipv6": {
81 "ip": "2001:db8::1"
82 }
83 },
84 "services": [
85 {
86 "destination_port": 80,
87 "health_check": {
88 "http": {
89 "domain": "example.com",
90 "path": "/",
91 "response": "{\"status\": \"ok\"}",
92 "status_codes": [
93 "2??,3??"
94 ],
95 "tls": false
96 },
97 "interval": 15,
98 "port": 4711,
99 "protocol": "http",
100 "retries": 3,
101 "timeout": 10
102 },
103 "http": {
104 "certificates": [
105 897
106 ],
107 "cookie_lifetime": 300,
108 "cookie_name": "HCLBSTICKY",
109 "redirect_http": true,
110 "sticky_sessions": true
111 },
112 "listen_port": 443,
113 "protocol": "http",
114 "proxyprotocol": false
115 }
116 ],
117 "targets": [
118 {
119 "health_status": [
120 {
121 "listen_port": 443,