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 (e.g. not available for order) |
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 /actionsFilter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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": "running"
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 Action.
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": "running"
19 }
20}TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic.
Returns all Certificate objects.
GET /certificatesid id:asc id:desc name name:asc name:desc created created:asc created:descSort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
Filter resources by their name. The response will only contain the resources matching the specified name.
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
uploaded managedCan be used multiple times. The response will only contain Certificates matching the type.
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "meta": {
30 "pagination": {
31 "last_page": 1,
32 "next_page": null,
33 "page": 1,
34 "per_page": 25,
35 "previous_page": null,
36 "total_entries": 21
37 }
38 }
39}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) for the Resource.
For more information, see "Labels".
Name of the Certificate
Certificate key in PEM format. Required for type uploaded Certificates.
uploaded managedDefault: uploadedChoose between uploading a Certificate in PEM format or requesting a managed Let's Encrypt Certificate.
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 Certificate.
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 Certificate.
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 Certificate.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
New Certificate name
1curl \
2 -X PUT \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"my website cert"}' \
6 "https://api.hetzner.cloud/v1/certificates/$ID"1{
2 "labels": {
3 "environment": "prod",
4 "example.com/my": "label",
5 "just-a-key": ""
6 },
7 "name": "my website cert"
8}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/actionsFilter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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": "running"
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": "running"
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 Certificate.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "meta": {
23 "pagination": {
24 "last_page": 1,
25 "next_page": null,
26 "page": 1,
27 "per_page": 25,
28 "previous_page": null,
29 "total_entries": 21
30 }
31 }
32}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 Datacenters.
GET /datacentersFilter resources by their name. The response will only contain the resources matching the specified name.
id id:asc id:desc name name:asc name:descSort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
25Maximum number of entries returned per page. For more information, see "Pagination".
List of Datacenters.
Recommended Datacenter for creating new resources.
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": 42,
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 single Datacenter.
GET /datacenters/{id}ID of the 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": 42,
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 Firewalls.
Use the provided URI parameters to modify the result.
GET /firewallsid id:asc id:desc name name:asc name:desc created created:asc created:descSort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
Filter resources by their name. The response will only contain the resources matching the specified name.
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "environment": "prod",
27 "example.com/my": "label",
28 "just-a-key": ""
29 },
30 "name": "new-name",
31 "rules": [
32 {
33 "description": null,
34 "destination_ips": [],
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}Create a Firewall.
| Code | Description |
|---|---|
server_already_added |
Server applied more than once |
incompatible_network_type |
The resources network type is not supported by Firewalls |
firewall_resource_not_found |
The resource the Firewall should be attached to was not found |
POST /firewallsResources to apply the Firewall to.
Resources added directly are taking precedence over those added via a Label Selector.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Array of rules.
Rules are limited to 50 entries per Firewall and 500 effective 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 "environment": "prod",
68 "example.com/my": "label",
69 "just-a-key": ""
70 },
71 "name": "new-name",
72 "rules": [
73 {
74 "description": null,
75 "destination_ips": [],
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 the Firewall.
| Code | Description |
|---|---|
resource_in_use |
Firewall still applied to a resource |
DELETE /firewalls/{id}ID of the Firewall.
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/firewalls/$ID"1Status: 204Returns a single Firewall.
GET /firewalls/{id}ID of the Firewall.
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 "environment": "prod",
26 "example.com/my": "label",
27 "just-a-key": ""
28 },
29 "name": "new-name",
30 "rules": [
31 {
32 "description": null,
33 "destination_ips": [],
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}Update a Firewall.
Provided Labels will overwritte the existing ones.
In case of a parallel running change on the Firewall a conflict error will be returned.
PUT /firewalls/{id}ID of the Firewall.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
1curl \
2 -X PUT \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"new-name"}' \
6 "https://api.hetzner.cloud/v1/firewalls/$ID"1{
2 "labels": {
3 "environment": "prod",
4 "example.com/my": "label",
5 "just-a-key": ""
6 },
7 "name": "new-name"
8}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 "environment": "prod",
26 "example.com/my": "label",
27 "just-a-key": ""
28 },
29 "name": "new-name",
30 "rules": [
31 {
32 "description": null,
33 "destination_ips": [],
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}GET /firewalls/actionsFilter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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": "running"
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 the specific Action.
GET /firewalls/actions/{id}ID of the Action.
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": "running"
19 }
20}GET /firewalls/{id}/actionsID of the Firewall.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "meta": {
23 "pagination": {
24 "last_page": 1,
25 "next_page": null,
26 "page": 1,
27 "per_page": 25,
28 "previous_page": null,
29 "total_entries": 21
30 }
31 }
32}Applies a Firewall to multiple resources.
Supported resources:
A server can be applied to a maximum of 5 Firewalls.
| Code | Description |
|---|---|
firewall_already_applied |
Firewall is already applied to resource |
incompatible_network_type |
The network type of the resource is not supported by Firewalls |
firewall_resource_not_found |
The resource the Firewall should be applied to was not found |
private_net_only_server |
The Server the Firewall should be applied to has no public interface |
POST /firewalls/{id}/actions/apply_to_resourcesID of the Firewall.
Resources to apply the Firewall to.
Extends existing resources.
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 a Firewall from multiple resources.
Supported resources:
| Code | Description |
|---|---|
firewall_already_removed |
Firewall is already removed from the resource |
firewall_resource_not_found |
The resource the Firewall should be removed from was not found |
firewall_managed_by_label_selector |
Firewall is applied via a Label Selector and cannot be removed manually |
POST /firewalls/{id}/actions/remove_from_resourcesID of the Firewall.
Resources to remove the Firewall 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}Set the rules of a Firewall.
Overwrites the existing rules with the given ones. Pass an empty array to remove all rules.
Rules are limited to 50 entries per Firewall and 500 effective rules.
POST /firewalls/{id}/actions/set_rulesID of the Firewall.
Array of rules.
Rules are limited to 50 entries per Firewall and 500 effective rules.
Existing rules will be replaced.
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}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.
List multiple Floating IPs.
Use the provided URI parameters to modify the result.
GET /floating_ipsFilter resources by their name. The response will only contain the resources matching the specified name.
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
id id:asc id:desc created created:asc created:descSort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
25Maximum number of entries returned per page. For more information, see "Pagination".
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": 42,
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 "environment": "prod",
27 "example.com/my": "label",
28 "just-a-key": ""
29 },
30 "name": "my-resource",
31 "protection": {
32 "delete": false
33 },
34 "server": 42,
35 "type": "ipv4"
36 }
37 ],
38 "meta": {
39 "pagination": {
40 "last_page": 4,
41 "next_page": 4,
42 "page": 3,
43 "per_page": 25,
44 "previous_page": 2,
45 "total_entries": 100
46 }
47 }
48}Create a Floating IP.
Provide the server attribute to assign the Floating IP to that server or provide a home_location to locate the Floating IP at. Note that the Floating IP can be assigned to a Server in any Location later on. For optimal routing it is advised to use the Floating IP in the same Location it was created in.
POST /floating_ipsThe type argument is required while home_location and server are mutually exclusive.
Description of the Resource.
Home Location for the Floating IP.
Either the ID or the name of the Location.
Only optional if no Server is provided. Routing is optimized for this Locations.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Name of the Resource. Must be unique per Project.
Server the Floating IP is assigned to.
null if not assigned.
ipv4 ipv6Floating IP type
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"description":"This describes my resource","home_location":"fsn1","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"my-resource","server":42,"type":"ipv4"}' \
6 "https://api.hetzner.cloud/v1/floating_ips"1{
2 "description": "This describes my resource",
3 "home_location": "fsn1",
4 "labels": {
5 "environment": "prod",
6 "example.com/my": "label",
7 "just-a-key": ""
8 },
9 "name": "my-resource",
10 "server": 42,
11 "type": "ipv4"
12}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 the IP is assigned to a resource it will be 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 single Floating IP.
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": 42,
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 "environment": "prod",
26 "example.com/my": "label",
27 "just-a-key": ""
28 },
29 "name": "my-resource",
30 "protection": {
31 "delete": false
32 },
33 "server": 42,
34 "type": "ipv4"
35 }
36}Update the description or Labels of a Floating IP. Note that when updating Labels, the Floating IPs current set of Labels will be replaced with the Labels provided with the request. 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.
Description of the Resource.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Name of the Resource. Must be unique per Project.
1curl \
2 -X PUT \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"description":"This describes my resource","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"my-resource"}' \
6 "https://api.hetzner.cloud/v1/floating_ips/$ID"1{
2 "description": "This describes my resource",
3 "labels": {
4 "environment": "prod",
5 "example.com/my": "label",
6 "just-a-key": ""
7 },
8 "name": "my-resource"
9}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}Lists multiple Actions.
Use the provided URI parameters to modify the result.
GET /floating_ips/actionsFilter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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": "running"
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 single Action.
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": "running"
19 }
20}Lists Actions for a Floating IP.
Use the provided URI parameters to modify the result.
GET /floating_ips/{id}/actionsID of the Floating IP.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "meta": {
27 "pagination": {
28 "last_page": 1,
29 "next_page": null,
30 "page": 1,
31 "per_page": 25,
32 "previous_page": null,
33 "total_entries": 21
34 }
35 }
36}Assigns a Floating IP to a Server.
POST /floating_ips/{id}/actions/assignID of the Floating IP.
Server the Floating IP is assigned to.
null if not assigned.
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}Change the reverse DNS records for this Floating IP.
Allows to modify the PTR records set for the IP address.
POST /floating_ips/{id}/actions/change_dns_ptrID of the Floating IP.
The ip attributes specifies for which IP address the record is set. For IPv4 addresses this must be the exact address of the Floating IP. For IPv6 addresses this must be a single address within the /64 subnet of the Floating IP.
The dns_ptr attribute specifies the hostname used for the IP address.
For IPv6 Floating IPs up to 100 entries can be created.
Domain Name to point to.
PTR record content used for reverse DNS.
Single IPv4 or IPv6 address to create pointer for.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"dns_ptr":"server.example.com","ip":"2001:db8::1"}' \
6 "https://api.hetzner.cloud/v1/floating_ips/$ID/actions/change_dns_ptr"1{
2 "dns_ptr": "server.example.com",
3 "ip": "2001:db8::1"
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 settings configured for the Floating IP.
POST /floating_ips/{id}/actions/change_protectionID of the Floating IP.
Prevent the Resource from being deleted.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"delete":false}' \
6 "https://api.hetzner.cloud/v1/floating_ips/$ID/actions/change_protection"1{
2 "delete": false
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.
Results in the IP being unreachable. Can be assigned to another resource again.
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 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 /imagesid id:asc id:desc name name:asc name:desc created created:asc created:descSort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
system snapshot backup appCan be used multiple times.
available creatingCan 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.
Filter resources by their name. The response will only contain the resources matching the specified name.
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
Return only Images with the given architecture.
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "environment": "prod",
19 "example.com/my": "label",
20 "just-a-key": ""
21 },
22 "name": "ubuntu-20.04",
23 "os_flavor": "ubuntu",
24 "os_version": "20.04",
25 "protection": {
26 "delete": false
27 },
28 "rapid_deploy": false,
29 "status": "available",
30 "type": "snapshot"
31 }
32 ],
33 "meta": {
34 "pagination": {
35 "last_page": 4,
36 "next_page": 4,
37 "page": 3,
38 "per_page": 25,
39 "previous_page": 2,
40 "total_entries": 100
41 }
42 }
43}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 "environment": "prod",
18 "example.com/my": "label",
19 "just-a-key": ""
20 },
21 "name": "ubuntu-20.04",
22 "os_flavor": "ubuntu",
23 "os_version": "20.04",
24 "protection": {
25 "delete": false
26 },
27 "rapid_deploy": false,
28 "status": "available",
29 "type": "snapshot"
30 }
31}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) for the Resource.
For more information, see "Labels".
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":{"environment":"prod","example.com/my":"label","just-a-key":""},"type":"snapshot"}' \
6 "https://api.hetzner.cloud/v1/images/$ID"1{
2 "description": "My new Image description",
3 "labels": {
4 "environment": "prod",
5 "example.com/my": "label",
6 "just-a-key": ""
7 },
8 "type": "snapshot"
9}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/actionsFilter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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": "running"
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 Action.
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": "running"
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.
id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:descSort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
running success errorFilter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "meta": {
23 "pagination": {
24 "last_page": 1,
25 "next_page": null,
26 "page": 1,
27 "per_page": 25,
28 "previous_page": null,
29 "total_entries": 21
30 }
31 }
32}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 /isosFilter resources by their name. The response will only contain the resources 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.
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "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 ],
15 "meta": {
16 "pagination": {
17 "last_page": 4,
18 "next_page": 4,
19 "page": 3,
20 "per_page": 25,
21 "previous_page": 2,
22 "total_entries": 100
23 }
24 }
25}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 "deprecation": {
5 "announced": "2023-06-01T00:00:00+00:00",
6 "unavailable_after": "2023-09-01T00:00:00+00:00"
7 },
8 "description": "FreeBSD 11.0 x64",
9 "id": 42,
10 "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
11 "type": "public"
12 }
13}Gets all existing Load Balancers that you have available.
GET /load_balancersid id:asc id:desc name name:asc name:desc created created:asc created:descSort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
Filter resources by their name. The response will only contain the resources matching the specified name.
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
25Maximum number of entries returned per page. For more information, see "Pagination".
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 "environment": "prod",
13 "example.com/my": "label",
14 "just-a-key": ""
15 },
16 "load_balancer_type": {
17 "deprecated": "2016-01-30T23:50:00+00:00",
18 "description": "LB11",
19 "id": 1,
20 "max_assigned_certificates": 10,
21 "max_connections": 20000,
22 "max_services": 5,
23 "max_targets": 25,
24 "name": "lb11",
25 "prices": [
26 {
27 "included_traffic": 654321,
28 "location": "fsn1",
29 "price_hourly": {
30 "gross": "1.1900",
31 "net": "1.0000"
32 },
33 "price_monthly": {
34 "gross": "1.1900",
35 "net": "1.0000"
36 },
37 "price_per_tb_traffic": {
38 "gross": "1.1900",
39 "net": "1.0000"
40 }
41 }
42 ]
43 },
44 "location": {
45 "city": "Falkenstein",
46 "country": "DE",
47 "description": "Falkenstein DC Park 1",
48 "id": 42,
49 "latitude": 50.47612,
50 "longitude": 12.370071,
51 "name": "fsn1",
52 "network_zone": "eu-central"
53 },
54 "name": "my-resource",
55 "outgoing_traffic": null,
56 "private_net": [
57 {
58 "ip": "10.0.0.2",
59 "network": 4711
60 }
61 ],
62 "protection": {
63 "delete": false
64 },
65 "public_net": {
66 "enabled": false,
67 "ipv4": {
68 "dns_ptr": "lb1.example.com",
69 "ip": "1.2.3.4"
70 },
71 "ipv6": {
72 "dns_ptr": "lb1.example.com",
73 "ip": "2001:db8::1"
74 }
75 },
76 "services": [
77 {
78 "destination_port": 80,
79 "health_check": {
80 "http": {
81 "domain": "example.com",
82 "path": "/",
83 "response": "{\"status\": \"ok\"}",
84 "status_codes": [
85 "2??",
86 "3??"
87 ],
88 "tls": false
89 },
90 "interval": 15,
91 "port": 4711,
92 "protocol": "http",
93 "retries": 3,
94 "timeout": 10
95 },
96 "http": {
97 "certificates": [
98 897
99 ],
100 "cookie_lifetime": 300,
101 "cookie_name": "HCLBSTICKY",
102 "redirect_http": true,
103 "sticky_sessions": true
104 },
105 "listen_port": 443,
106 "protocol": "https",
107 "proxyprotocol": false
108 }
109 ],
110 "targets": [
111 {
112 "health_status": [
113 {
114 "listen_port": 443,
115 "status": "healthy"
116 }
117 ],
118 "ip": {
119 "ip": "203.0.113.1"
120 },
121 "label_selector": {
122 "selector": "env=prod"
123 },
124 "server": {
125 "id": 80
126 },
127 "targets": [
128 {
129 "health_status": [
130 {
131 "listen_port": 443,
132 "status": "healthy"
133 }
134 ],
135 "server": {
136 "id": 80
137 },
138 "type": "server",
139 "use_private_ip": false
140 }
141 ],
142 "type": "server",
143 "use_private_ip": false
144 }
145 ]
146 }
147 ],
148 "meta": {
149 "pagination": {
150 "last_page": 4,
151 "next_page": 4,
152 "page": 3,
153 "per_page": 25,
154 "previous_page": 2,
155 "total_entries": 100
156 }
157 }
158}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 |
missing_ipv4 |
The server that you are trying to add as a public target does not have a public IPv4 address |
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) for the Resource.
For more information, see "Labels".
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":{"environment":"prod","example.com/my":"label","just-a-key":""},"load_balancer_type":"lb11","location":"fsn1","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":[{"ip":{"ip":"203.0.113.1"},"label_selector":{"selector":"env=prod"},"server":{"id":80},"type":"server","use_private_ip":true}]}' \
6 "https://api.hetzner.cloud/v1/load_balancers"1{
2 "algorithm": {
3 "type": "round_robin"
4 },
5 "labels": {
6 "environment": "prod",
7 "example.com/my": "label",
8 "just-a-key": ""
9 },
10 "load_balancer_type": "lb11",
11 "location": "fsn1",
12 "name": "Web Frontend",
13 "network": 123,
14 "network_zone": "eu-central",
15 "public_interface": true,
16 "services": [
17 {
18 "destination_port": 80,
19 "health_check": {
20 "http": {
21 "domain": "example.com",
22 "path": "/",
23 "response": "{\"status\": \"ok\"}",
24 "status_codes": [
25 "2??",
26 "3??"
27 ],
28 "tls": false
29 },
30 "interval": 15,