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,
31 "port": 4711,
32 "protocol": "http",
33 "retries": 3,
34 "timeout": 10
35 },
36 "http": {
37 "certificates": [
38 897
39 ],
40 "cookie_lifetime": 300,
41 "cookie_name": "HCLBSTICKY",
42 "redirect_http": true,
43 "sticky_sessions": true
44 },
45 "listen_port": 443,
46 "protocol": "https",
47 "proxyprotocol": false
48 }
49 ],
50 "targets": [
51 {
52 "ip": {
53 "ip": "203.0.113.1"
54 },
55 "label_selector": {
56 "selector": "env=prod"
57 },
58 "server": {
59 "id": 80
60 },
61 "type": "server",
62 "use_private_ip": true
63 }
64 ]
65}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 "included_traffic": 654321,
43 "location": "fsn1",
44 "price_hourly": {
45 "gross": "1.1900000000000000",
46 "net": "1.0000000000"
47 },
48 "price_monthly": {
49 "gross": "1.1900000000000000",
50 "net": "1.0000000000"
51 },
52 "price_per_tb_traffic": {
53 "gross": "1.1900000000000000",
54 "net": "1.0000000000"
55 }
56 }
57 ]
58 },
59 "location": {
60 "city": "Falkenstein",
61 "country": "DE",
62 "description": "Falkenstein DC Park 1",
63 "id": 1,
64 "latitude": 50.47612,
65 "longitude": 12.370071,
66 "name": "fsn1",
67 "network_zone": "eu-central"
68 },
69 "name": "Web Frontend",
70 "outgoing_traffic": 123456,
71 "private_net": [
72 {
73 "ip": "10.0.0.2",
74 "network": 4711
75 }
76 ],
77 "protection": {
78 "delete": false
79 },
80 "public_net": {
81 "enabled": false,
82 "ipv4": {
83 "ip": "1.2.3.4"
84 },
85 "ipv6": {
86 "ip": "2001:db8::1"
87 }
88 },
89 "services": [
90 {
91 "destination_port": 80,
92 "health_check": {
93 "http": {
94 "domain": "example.com",
95 "path": "/",
96 "response": "{\"status\": \"ok\"}",
97 "status_codes": [
98 "2??,3??"
99 ],
100 "tls": false
101 },
102 "interval": 15,
103 "port": 4711,
104 "protocol": "http",
105 "retries": 3,
106 "timeout": 10
107 },
108 "http": {
109 "certificates": [
110 897
111 ],
112 "cookie_lifetime": 300,
113 "cookie_name": "HCLBSTICKY",
114 "redirect_http": true,
115 "sticky_sessions": true
116 },
117 "listen_port": 443,
118 "protocol": "http",
119 "proxyprotocol": false
120 }
121 ],
122 "targets": [
123 {
124 "health_status": [
125 {
126 "listen_port": 443,
127 "status": "healthy"
128 }
129 ],
130 "server": {
131 "id": 80
132 },
133 "targets": [
134 {
135 "health_status": [
136 {
137 "listen_port": 443,
138 "status": "healthy"
139 }
140 ],
141 "server": {
142 "id": 80
143 },
144 "type": "server",
145 "use_private_ip": true
146 }
147 ],
148 "type": "server",
149 "use_private_ip": true
150 }
151 ]
152 }
153}Deletes a Load Balancer.
DELETE /load_balancers/{id}ID of the Load Balancer.
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/load_balancers/$ID"1Status: 204Gets a specific Load Balancer object.
GET /load_balancers/{id}ID of the Load Balancer.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/load_balancers/$ID"1Content-Type: application/json
2Status: 2001{
2 "load_balancer": {
3 "algorithm": {
4 "type": "round_robin"
5 },
6 "created": "2016-01-30T23:55:00+00:00",
7 "id": 42,
8 "included_traffic": 10000,
9 "ingoing_traffic": null,
10 "labels": {
11 "environment": "prod",
12 "example.com/my": "label",
13 "just-a-key": ""
14 },
15 "load_balancer_type": {
16 "deprecated": "2016-01-30T23:50:00+00:00",
17 "description": "LB11",
18 "id": 1,
19 "max_assigned_certificates": 10,
20 "max_connections": 20000,
21 "max_services": 5,
22 "max_targets": 25,
23 "name": "lb11",
24 "prices": [
25 {
26 "included_traffic": 654321,
27 "location": "fsn1",
28 "price_hourly": {
29 "gross": "1.1900",
30 "net": "1.0000"
31 },
32 "price_monthly": {
33 "gross": "1.1900",
34 "net": "1.0000"
35 },
36 "price_per_tb_traffic": {
37 "gross": "1.1900",
38 "net": "1.0000"
39 }
40 }
41 ]
42 },
43 "location": {
44 "city": "Falkenstein",
45 "country": "DE",
46 "description": "Falkenstein DC Park 1",
47 "id": 42,
48 "latitude": 50.47612,
49 "longitude": 12.370071,
50 "name": "fsn1",
51 "network_zone": "eu-central"
52 },
53 "name": "my-resource",
54 "outgoing_traffic": null,
55 "private_net": [
56 {
57 "ip": "10.0.0.2",
58 "network": 4711
59 }
60 ],
61 "protection": {
62 "delete": false
63 },
64 "public_net": {
65 "enabled": false,
66 "ipv4": {
67 "dns_ptr": "lb1.example.com",
68 "ip": "1.2.3.4"
69 },
70 "ipv6": {
71 "dns_ptr": "lb1.example.com",
72 "ip": "2001:db8::1"
73 }
74 },
75 "services": [
76 {
77 "destination_port": 80,
78 "health_check": {
79 "http": {
80 "domain": "example.com",
81 "path": "/",
82 "response": "{\"status\": \"ok\"}",
83 "status_codes": [
84 "2??",
85 "3??"
86 ],
87 "tls": false
88 },
89 "interval": 15,
90 "port": 4711,
91 "protocol": "http",
92 "retries": 3,
93 "timeout": 10
94 },
95 "http": {
96 "certificates": [
97 897
98 ],
99 "cookie_lifetime": 300,
100 "cookie_name": "HCLBSTICKY",
101 "redirect_http": true,
102 "sticky_sessions": true
103 },
104 "listen_port": 443,
105 "protocol": "https",
106 "proxyprotocol": false
107 }
108 ],
109 "targets": [
110 {
111 "health_status": [
112 {
113 "listen_port": 443,
114 "status": "healthy"
115 }
116 ],
117 "ip": {
118 "ip": "203.0.113.1"
119 },
120 "label_selector": {
121 "selector": "env=prod"
122 },
123 "server": {
124 "id": 80
125 },
126 "targets": [
127 {
128 "health_status": [
129 {
130 "listen_port": 443,
131 "status": "healthy"
132 }
133 ],
134 "server": {
135 "id": 80
136 },
137 "type": "server",
138 "use_private_ip": false
139 }
140 ],
141 "type": "server",
142 "use_private_ip": false
143 }
144 ]
145 }
146}Updates a Load Balancer. You can update a Load Balancer’s name and a Load Balancer’s labels.
Note that when updating labels, the Load Balancer’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.
Note: if the Load Balancer object changes during the request, the response will be a “conflict” error.
PUT /load_balancers/{id}ID of the Load Balancer.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
New Load Balancer 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":"new-name"}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$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 "load_balancer": {
3 "algorithm": {
4 "type": "round_robin"
5 },
6 "created": "2016-01-30T23:50:00+00:00",
7 "id": 4711,
8 "included_traffic": 654321,
9 "ingoing_traffic": 123456,
10 "labels": {
11 "labelkey": "value"
12 },
13 "load_balancer_type": {
14 "deprecated": "2016-01-30T23:50:00+00:00",
15 "description": "LB11",
16 "id": 1,
17 "max_assigned_certificates": 10,
18 "max_connections": 20000,
19 "max_services": 5,
20 "max_targets": 25,
21 "name": "lb11",
22 "prices": [
23 {
24 "included_traffic": 654321,
25 "location": "fsn1",
26 "price_hourly": {
27 "gross": "1.1900000000000000",
28 "net": "1.0000000000"
29 },
30 "price_monthly": {
31 "gross": "1.1900000000000000",
32 "net": "1.0000000000"
33 },
34 "price_per_tb_traffic": {
35 "gross": "1.1900000000000000",
36 "net": "1.0000000000"
37 }
38 }
39 ]
40 },
41 "location": {
42 "city": "Falkenstein",
43 "country": "DE",
44 "description": "Falkenstein DC Park 1",
45 "id": 1,
46 "latitude": 50.47612,
47 "longitude": 12.370071,
48 "name": "fsn1",
49 "network_zone": "eu-central"
50 },
51 "name": "new-name",
52 "outgoing_traffic": 123456,
53 "private_net": [
54 {
55 "ip": "10.0.0.2",
56 "network": 4711
57 }
58 ],
59 "protection": {
60 "delete": false
61 },
62 "public_net": {
63 "enabled": false,
64 "ipv4": {
65 "ip": "1.2.3.4"
66 },
67 "ipv6": {
68 "ip": "2001:db8::1"
69 }
70 },
71 "services": [
72 {
73 "destination_port": 80,
74 "health_check": {
75 "http": {
76 "domain": "example.com",
77 "path": "/",
78 "response": "{\"status\": \"ok\"}",
79 "status_codes": [
80 "2??,3??"
81 ],
82 "tls": false
83 },
84 "interval": 15,
85 "port": 4711,
86 "protocol": "http",
87 "retries": 3,
88 "timeout": 10
89 },
90 "http": {
91 "certificates": [
92 897
93 ],
94 "cookie_lifetime": 300,
95 "cookie_name": "HCLBSTICKY",
96 "redirect_http": true,
97 "sticky_sessions": true
98 },
99 "listen_port": 443,
100 "protocol": "http",
101 "proxyprotocol": false
102 }
103 ],
104 "targets": [
105 {
106 "health_status": [
107 {
108 "listen_port": 443,
109 "status": "healthy"
110 }
111 ],
112 "ip": {
113 "ip": "203.0.113.1"
114 },
115 "label_selector": {
116 "selector": "env=prod"
117 },
118 "server": {
119 "id": 80
120 },
121 "targets": [
122 {
123 "health_status": [
124 {
125 "listen_port": 443,
126 "status": "healthy"
127 }
128 ],
129 "server": {
130 "id": 80
131 },
132 "type": "server",
133 "use_private_ip": true
134 }
135 ],
136 "type": "server",
137 "use_private_ip": true
138 }
139 ]
140 }
141}You must specify the type of metric to get: open_connections, connections_per_second, requests_per_second or bandwidth. You can also specify more than one type by comma separation, e.g. requests_per_second,bandwidth.
Depending on the type you will get different time series data:
| Type | Timeseries | Unit | Description |
|---|---|---|---|
| open_connections | open_connections | number | Open connections |
| connections_per_second | connections_per_second | connections/s | Connections per second |
| requests_per_second | requests_per_second | requests/s | Requests per second |
| bandwidth | bandwidth.in | bytes/s | Ingress bandwidth |
| bandwidth.out | bytes/s | Egress bandwidth |
Metrics are available for the last 30 days only.
If you do not provide the step argument we will automatically adjust it so that 200 samples are returned.
We limit the number of samples to a maximum of 500 and will adjust the step parameter accordingly.
GET /load_balancers/{id}/metricsID of the Load Balancer.
open_connections connections_per_second requests_per_second bandwidthType of metrics to get
Start of period to get Metrics for (in ISO-8601 format)
End of period to get Metrics for (in ISO-8601 format)
Resolution of results in seconds
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/load_balancers/$ID/metrics?type=$TYPE&start=$START&end=$END"1Content-Type: application/json
2Status: 2001{
2 "metrics": {
3 "end": "2017-01-01T23:00:00+00:00",
4 "start": "2017-01-01T00:00:00+00:00",
5 "step": 60,
6 "time_series": {
7 "name_of_timeseries": {
8 "values": [
9 [
10 1435781470.622,
11 "42"
12 ],
13 [
14 1435781471.622,
15 "43"
16 ]
17 ]
18 }
19 }
20 }
21}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 /load_balancers/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/load_balancers/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 /load_balancers/actions/{id}ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/load_balancers/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 Load Balancer. You can sort the results by using the sort URI parameter, and filter them with the status parameter.
GET /load_balancers/{id}/actionsID of the Load Balancer.
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/load_balancers/$ID/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "add_service",
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": "load_balancer"
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}Adds a service to a Load Balancer.
| Code | Description |
|---|---|
source_port_already_used |
The source port you are trying to add is already in use |
POST /load_balancers/{id}/actions/add_serviceID of the Load Balancer.
Port the Load Balancer will balance to
Service health check
Configuration option for protocols http and https
Port the Load Balancer listens on
tcp http httpsProtocol of the Load Balancer
Is Proxyprotocol enabled or not
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"destination_port":80,"health_check":{"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false},"interval":15,"port":4711,"protocol":"http","retries":3,"timeout":10},"http":{"certificates":[897],"cookie_lifetime":300,"cookie_name":"HCLBSTICKY","redirect_http":true,"sticky_sessions":true},"listen_port":443,"protocol":"https","proxyprotocol":false}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/add_service"1{
2 "destination_port": 80,
3 "health_check": {
4 "http": {
5 "domain": "example.com",
6 "path": "/",
7 "response": "{\"status\": \"ok\"}",
8 "status_codes": [
9 "2??",
10 "3??"
11 ],
12 "tls": false
13 },
14 "interval": 15,
15 "port": 4711,
16 "protocol": "http",
17 "retries": 3,
18 "timeout": 10
19 },
20 "http": {
21 "certificates": [
22 897
23 ],
24 "cookie_lifetime": 300,
25 "cookie_name": "HCLBSTICKY",
26 "redirect_http": true,
27 "sticky_sessions": true
28 },
29 "listen_port": 443,
30 "protocol": "https",
31 "proxyprotocol": false
32}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "add_service",
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}Adds a target to 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 you are trying to add as a target is not owned by the Project owner |
load_balancer_not_attached_to_network |
The Load Balancer is not attached to a network |
robot_unavailable |
Robot was not available. The caller may retry the operation after a short delay. |
server_not_attached_to_network |
The server you are trying to add as a target is not attached to the same network as the Load Balancer |
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_balancers/{id}/actions/add_targetID of the Load Balancer.
Configuration for an IP target. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only valid and required if type is ip.
Configuration for label selector targets, only valid and required if type is label_selector.
Configuration for type Server, only valid and required if type is server.
server label_selector ipType of the resource
falseUse the private network IP instead of the public IP of the Server, requires the Server and Load Balancer to be in the same network.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"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/$ID/actions/add_target"1{
2 "ip": {
3 "ip": "203.0.113.1"
4 },
5 "label_selector": {
6 "selector": "env=prod"
7 },
8 "server": {
9 "id": 80
10 },
11 "type": "server",
12 "use_private_ip": true
13}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "add_target",
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}Attach a Load Balancer to a Network.
Call specific error codes
| Code | Description |
|---|---|
load_balancer_already_attached |
The Load Balancer is already attached to a network |
ip_not_available |
The provided Network IP is not available |
no_subnet_available |
No Subnet or IP is available for the Load Balancer within the network |
POST /load_balancers/{id}/actions/attach_to_networkID of the Load Balancer.
IP to request to be assigned to this Load Balancer; if you do not provide this then you will be auto assigned an IP address
ID of an existing network to attach the Load Balancer to
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"ip":"10.0.1.1","network":4711}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/attach_to_network"1{
2 "ip": "10.0.1.1",
3 "network": 4711
4}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "attach_to_network",
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}Change the algorithm that determines to which target new requests are sent.
POST /load_balancers/{id}/actions/change_algorithmID of the Load Balancer.
round_robin least_connectionsAlgorithm of the Load Balancer
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"type":"round_robin"}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/change_algorithm"1{
2 "type": "round_robin"
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "change_algorithm",
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}Changes the hostname that will appear when getting the hostname belonging to the public IPs (IPv4 and IPv6) of this Load Balancer.
Floating IPs assigned to the Server are not affected by this.
POST /load_balancers/{id}/actions/change_dns_ptrID of the Load Balancer.
Select the IP address for which to change the DNS entry by passing ip. It can be either IPv4 or IPv6. The target hostname is set by passing dns_ptr.
Hostname to set as a reverse DNS PTR entry
Public IP address for which the reverse DNS entry should be set
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"dns_ptr":"lb1.example.com","ip":"1.2.3.4"}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/change_dns_ptr"1{
2 "dns_ptr": "lb1.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": null,
9 "id": 13,
10 "progress": 0,
11 "resources": [
12 {
13 "id": 42,
14 "type": "load_balancer"
15 }
16 ],
17 "started": "2016-01-30T23:50:00+00:00",
18 "status": "running"
19 }
20}Changes the protection configuration of a Load Balancer.
POST /load_balancers/{id}/actions/change_protectionID of the Load Balancer.
If true, prevents the Load Balancer 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/load_balancers/$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": "load_balancer"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Changes the type (Max Services, Max Targets and Max Connections) of a Load Balancer.
Call specific error codes
| Code | Description |
|---|---|
invalid_load_balancer_type |
The Load Balancer type does not fit for the given Load Balancer |
POST /load_balancers/{id}/actions/change_typeID of the Load Balancer.
ID or name of Load Balancer type the Load Balancer should migrate to
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"load_balancer_type":"lb21"}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/change_type"1{
2 "load_balancer_type": "lb21"
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "change_load_balancer_type",
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}Delete a service of a Load Balancer.
POST /load_balancers/{id}/actions/delete_serviceID of the Load Balancer.
The listen port of the service you want to delete
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"listen_port":443}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/delete_service"1{
2 "listen_port": 443
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "delete_service",
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}Detaches a Load Balancer from a network.
POST /load_balancers/{id}/actions/detach_from_networkID of the Load Balancer.
ID of an existing network to detach the Load Balancer from
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"network":4711}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/detach_from_network"1{
2 "network": 4711
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "detach_from_network",
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 "id": 4711,
18 "type": "network"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Disable the public interface of a Load Balancer. The Load Balancer will be not accessible from the internet via its public IPs.
| Code | Description |
|---|---|
load_balancer_not_attached_to_network |
The Load Balancer is not attached to a network |
targets_without_use_private_ip |
The Load Balancer has targets that use the public IP instead of the private IP |
POST /load_balancers/{id}/actions/disable_public_interfaceID of the Load Balancer.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/disable_public_interface"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "disable_public_interface",
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 "id": 4711,
18 "type": "network"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Enable the public interface of a Load Balancer. The Load Balancer will be accessible from the internet via its public IPs.
POST /load_balancers/{id}/actions/enable_public_interfaceID of the Load Balancer.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/enable_public_interface"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "enable_public_interface",
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 "id": 4711,
18 "type": "network"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Removes a target from a Load Balancer.
POST /load_balancers/{id}/actions/remove_targetID of the Load Balancer.
IP target where the traffic should be routed to. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well. Only present for target type ip.
Configuration for label selector targets, required if type is label_selector
Configuration for type Server, required if type is server
server label_selector ipType of the resource
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"ip":{"ip":"203.0.113.1"},"label_selector":{"selector":"env=prod"},"server":{"id":80},"type":"server"}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/remove_target"1{
2 "ip": {
3 "ip": "203.0.113.1"
4 },
5 "label_selector": {
6 "selector": "env=prod"
7 },
8 "server": {
9 "id": 80
10 },
11 "type": "server"
12}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "remove_target",
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}Updates a Load Balancer Service.
| Code | Description |
|---|---|
source_port_already_used |
The source port you are trying to add is already in use |
POST /load_balancers/{id}/actions/update_serviceID of the Load Balancer.
Port the Load Balancer will balance to
Service health check
Configuration option for protocols http and https
Port the Load Balancer listens on
tcp http httpsProtocol of the Load Balancer
Is Proxyprotocol enabled or not
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"destination_port":80,"health_check":{"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false},"interval":15,"port":4711,"protocol":"http","retries":3,"timeout":10},"http":{"certificates":[897],"cookie_lifetime":300,"cookie_name":"HCLBSTICKY","redirect_http":true,"sticky_sessions":true},"listen_port":443,"protocol":"https","proxyprotocol":false}' \
6 "https://api.hetzner.cloud/v1/load_balancers/$ID/actions/update_service"1{
2 "destination_port": 80,
3 "health_check": {
4 "http": {
5 "domain": "example.com",
6 "path": "/",
7 "response": "{\"status\": \"ok\"}",
8 "status_codes": [
9 "2??",
10 "3??"
11 ],
12 "tls": false
13 },
14 "interval": 15,
15 "port": 4711,
16 "protocol": "http",
17 "retries": 3,
18 "timeout": 10
19 },
20 "http": {
21 "certificates": [
22 897
23 ],
24 "cookie_lifetime": 300,
25 "cookie_name": "HCLBSTICKY",
26 "redirect_http": true,
27 "sticky_sessions": true
28 },
29 "listen_port": 443,
30 "protocol": "https",
31 "proxyprotocol": false
32}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "update_service",
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}Returns a specific Action for a Load Balancer.
GET /load_balancers/{id}/actions/{action_id}ID of the Load Balancer.
ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/load_balancers/$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": "load_balancer"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Load Balancer types define kinds of Load Balancers offered. Each type has an hourly and a monthly cost. You will pay whichever amount is lower for your usage of this specific Load Balancer. Costs may differ between Locations.
Currency for all amounts is €. All prices exclude VAT.
Gets all Load Balancer type objects.
GET /load_balancer_typesFilter resources by their name. The response will only contain the resources matching the specified name.
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_balancer_types"1Content-Type: application/json
2Status: 2001{
2 "load_balancer_types": [
3 {
4 "deprecated": "2016-01-30T23:50:00+00:00",
5 "description": "LB11",
6 "id": 1,
7 "max_assigned_certificates": 10,
8 "max_connections": 20000,
9 "max_services": 5,
10 "max_targets": 25,
11 "name": "lb11",
12 "prices": [
13 {
14 "included_traffic": 654321,
15 "location": "fsn1",
16 "price_hourly": {
17 "gross": "1.1900",
18 "net": "1.0000"
19 },
20 "price_monthly": {
21 "gross": "1.1900",
22 "net": "1.0000"
23 },
24 "price_per_tb_traffic": {
25 "gross": "1.1900",
26 "net": "1.0000"
27 }
28 }
29 ]
30 }
31 ],
32 "meta": {
33 "pagination": {
34 "last_page": 4,
35 "next_page": 4,
36 "page": 3,
37 "per_page": 25,
38 "previous_page": 2,
39 "total_entries": 100
40 }
41 }
42}Gets a specific Load Balancer type object.
GET /load_balancer_types/{id}ID of the Load Balancer Type.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/load_balancer_types/$ID"1Content-Type: application/json
2Status: 2001{
2 "load_balancer_type": {
3 "deprecated": "2016-01-30T23:50:00+00:00",
4 "description": "LB11",
5 "id": 1,
6 "max_assigned_certificates": 10,
7 "max_connections": 20000,
8 "max_services": 5,
9 "max_targets": 25,
10 "name": "lb11",
11 "prices": [
12 {
13 "included_traffic": 654321,
14 "location": "fsn1",
15 "price_hourly": {
16 "gross": "1.1900",
17 "net": "1.0000"
18 },
19 "price_monthly": {
20 "gross": "1.1900",
21 "net": "1.0000"
22 },
23 "price_per_tb_traffic": {
24 "gross": "1.1900",
25 "net": "1.0000"
26 }
27 }
28 ]
29 }
30}Datacenters are organized by Locations. Datacenters in the same Location are connected with very low latency links.
Returns all Locations.
Use the provided URI parameters to modify the result.
GET /locationsFilter 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 Locations.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/locations"1Content-Type: application/json
2Status: 2001{
2 "locations": [
3 {
4 "city": "Falkenstein",
5 "country": "DE",
6 "description": "Falkenstein DC Park 1",
7 "id": 42,
8 "latitude": 50.47612,
9 "longitude": 12.370071,
10 "name": "fsn1",
11 "network_zone": "eu-central"
12 }
13 ],
14 "meta": {
15 "pagination": {
16 "last_page": 4,
17 "next_page": 4,
18 "page": 3,
19 "per_page": 25,
20 "previous_page": 2,
21 "total_entries": 100
22 }
23 }
24}Returns a Location.
GET /locations/{id}ID of the Location.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/locations/$ID"1Content-Type: application/json
2Status: 2001{
2 "location": {
3 "city": "Falkenstein",
4 "country": "DE",
5 "description": "Falkenstein DC Park 1",
6 "id": 42,
7 "latitude": 50.47612,
8 "longitude": 12.370071,
9 "name": "fsn1",
10 "network_zone": "eu-central"
11 }
12}Networks is a private networks feature. These Networks are optional and they coexist with the public network that every Server has by default.
They allow Servers to talk to each other over a dedicated network interface using private IP addresses not available publicly.
The IP addresses are allocated and managed via the API, they must conform to RFC1918 standard. IPs and network interfaces defined under Networks do not provide public internet connectivity, you will need to use the already existing public network interface for that.
Each network has a user selected ip_range which defines all available IP addresses which can be used for Subnets within the Network.
To assign individual IPs to Servers you will need to create Network Subnets, described below.
Currently Networks support IPv4 only.
Subnets divide the ip_range from the parent Network object into multiple Subnetworks that you can use for different specific purposes.
For each subnet you need to specify its own ip_range which must be contained within the parent Network’s ip_range. Additionally each subnet must belong to one of the available Network Zones described below. Subnets can not have overlapping IP ranges.
Currently there are three types of subnet:
cloud is used to connect cloud Resources into your Network.server was used to connect only cloud Servers into your Network. This type is deprecated and is replaced by type cloud.vswitch allows you to connect Dedicated Server vSwitch - and all Dedicated Servers attached to it - into your NetworkSubnets of type vswitch must set a vswitch_id which is the ID of the existing vSwitch in Hetzner Robot that should be coupled.
Network Zones are groups of Locations which have special high-speed network connections between them. The Location object contains the network_zone property each Location belongs to. Currently these network zones exist:
| Network Zone | Contains Locations |
|---|---|
| eu-central | nbg1, fsn1, hel1 |
| us-east | ash |
| us-west | hil |
| ap-southeast | sin |
When a cloud Server is attached to a network without the user specifying an IP it automatically gets an IP address assigned from a subnet of type server in the same network zone. If you specify the optional ip parameter when attaching then we will try to assign that IP. Keep in mind that the Server’s location must be covered by the Subnet’s Network Zone if you specify an IP, or that at least one Subnet with the zone covering Server’s location must exist.
A cloud Server can also have more than one IP address in a Network by specifying aliases. For details see the attach to network action.
The following IP addresses are reserved in networks and can not be used:
ip_range as it will be used as a default gateway for the private Network interface.172.31.1.1 as it is being used as default gateway for our public Network interfaces.By using subnets of type vswitch you can couple the Cloud Networks with an existing Dedicated Server vSwitch and enable dedicated and cloud servers to
talk to each other over the Network.
In order for this to work the dedicated servers may only use IPs from the subnet and must have a special network configuration. Please refer to FAQ. vSwitch Layer 2 features are not supported.
Networks also support the notion of routes which are automatically applied to private traffic. A route makes sure that all packets for a given destination IP prefix will be sent to the address specified in its gateway.
List multiple Networks.
Use the provided URI parameters to modify the result.
GET /networksFilter 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/networks"1Content-Type: application/json
2Status: 2001{
2 "meta": {
3 "pagination": {
4 "last_page": 4,
5 "next_page": 4,
6 "page": 3,
7 "per_page": 25,
8 "previous_page": 2,
9 "total_entries": 100
10 }
11 },
12 "networks": [
13 {
14 "created": "2016-01-30T23:55:00+00:00",
15 "expose_routes_to_vswitch": false,
16 "id": 4711,
17 "ip_range": "10.0.0.0/16",
18 "labels": {
19 "environment": "prod",
20 "example.com/my": "label",
21 "just-a-key": ""
22 },
23 "load_balancers": [
24 42
25 ],
26 "name": "mynet",
27 "protection": {
28 "delete": false
29 },
30 "routes": [
31 {
32 "destination": "10.100.1.0/24",
33 "gateway": "10.0.1.1"
34 }
35 ],
36 "servers": [
37 42
38 ],
39 "subnets": [
40 {
41 "gateway": "10.0.0.1",
42 "ip_range": "10.0.1.0/24",
43 "network_zone": "eu-central",
44 "type": "cloud",
45 "vswitch_id": 1000
46 }
47 ]
48 }
49 ]
50}Creates a Network.
The provided ip_range can only be extended later on, but not reduced.
Subnets can be added now or later on using the add subnet action. If you do not specify an ip_range for the subnet the first available /24 range will be used.
Routes can be added now or later by using the add route action.
POST /networksToggle to expose routes to the Networks vSwitch.
Indicates if the routes from this Network should be exposed to the vSwitch in this Network. Only takes effect if a vSwitch is setup in this Network.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Name of the Network.
Array of routes set in this Network.
Array of subnets to allocate.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"expose_routes_to_vswitch":false,"ip_range":"10.0.0.0/16","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"mynet","routes":[{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}],"subnets":[{"ip_range":"10.0.1.0/24","network_zone":"eu-central","type":"cloud","vswitch_id":1000}]}' \
6 "https://api.hetzner.cloud/v1/networks"1{
2 "expose_routes_to_vswitch": false,
3 "ip_range": "10.0.0.0/16",
4 "labels": {
5 "environment": "prod",
6 "example.com/my": "label",
7 "just-a-key": ""
8 },
9 "name": "mynet",
10 "routes": [
11 {
12 "destination": "10.100.1.0/24",
13 "gateway": "10.0.1.1"
14 }
15 ],
16 "subnets": [
17 {
18 "ip_range": "10.0.1.0/24",
19 "network_zone": "eu-central",
20 "type": "cloud",
21 "vswitch_id": 1000
22 }
23 ]
24}1Content-Type: application/json
2Status: 2011{
2 "network": {
3 "created": "2016-01-30T23:55:00+00:00",
4 "expose_routes_to_vswitch": false,
5 "id": 4711,
6 "ip_range": "10.0.0.0/16",
7 "labels": {
8 "environment": "prod",
9 "example.com/my": "label",
10 "just-a-key": ""
11 },
12 "load_balancers": [
13 42
14 ],
15 "name": "mynet",
16 "protection": {
17 "delete": false
18 },
19 "routes": [
20 {
21 "destination": "10.100.1.0/24",
22 "gateway": "10.0.1.1"
23 }
24 ],
25 "servers": [
26 42
27 ],
28 "subnets": [
29 {
30 "gateway": "10.0.0.1",
31 "ip_range": "10.0.1.0/24",
32 "network_zone": "eu-central",
33 "type": "cloud",
34 "vswitch_id": 1000
35 }
36 ]
37 }
38}Deletes a Network.
Attached resources will be detached automatically.
DELETE /networks/{id}ID of the Network.
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/networks/$ID"1Status: 204Get a specific Network.
GET /networks/{id}ID of the Network.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/networks/$ID"1Content-Type: application/json
2Status: 2001{
2 "network": {
3 "created": "2016-01-30T23:55:00+00:00",
4 "expose_routes_to_vswitch": false,
5 "id": 4711,
6 "ip_range": "10.0.0.0/16",
7 "labels": {
8 "environment": "prod",
9 "example.com/my": "label",
10 "just-a-key": ""
11 },
12 "load_balancers": [
13 42
14 ],
15 "name": "mynet",
16 "protection": {
17 "delete": false
18 },
19 "routes": [
20 {
21 "destination": "10.100.1.0/24",
22 "gateway": "10.0.1.1"
23 }
24 ],
25 "servers": [
26 42
27 ],
28 "subnets": [
29 {
30 "gateway": "10.0.0.1",
31 "ip_range": "10.0.1.0/24",
32 "network_zone": "eu-central",
33 "type": "cloud",
34 "vswitch_id": 1000
35 }
36 ]
37 }
38}Update a Network.
Note that when updating Labels, the Networks 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.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
PUT /networks/{id}ID of the Network.
Toggle to expose routes to the Networks vSwitch.
Indicates if the routes from this Network should be exposed to the vSwitch in this Network. Only takes effect if a vSwitch is setup in this Network.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
New Network name.
1curl \
2 -X PUT \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"expose_routes_to_vswitch":false,"labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"new-name"}' \
6 "https://api.hetzner.cloud/v1/networks/$ID"1{
2 "expose_routes_to_vswitch": false,
3 "labels": {
4 "environment": "prod",
5 "example.com/my": "label",
6 "just-a-key": ""
7 },
8 "name": "new-name"
9}1Content-Type: application/json
2Status: 2001{
2 "network": {
3 "created": "2016-01-30T23:50:00+00:00",
4 "expose_routes_to_vswitch": true,
5 "id": 4711,
6 "ip_range": "10.0.0.0/16",
7 "labels": {
8 "labelkey": "value"
9 },
10 "load_balancers": [
11 42
12 ],
13 "name": "new-name",
14 "protection": {
15 "delete": false
16 },
17 "routes": [
18 {
19 "destination": "10.100.1.0/24",
20 "gateway": "10.0.1.1"
21 }
22 ],
23 "servers": [
24 42
25 ],
26 "subnets": [
27 {
28 "gateway": "10.0.0.1",
29 "ip_range": "10.0.1.0/24",
30 "network_zone": "eu-central",
31 "type": "cloud"
32 }
33 ]
34 }
35}Lists multiple Actions.
Use the provided URI parameters to modify the result.
GET /networks/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/networks/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 /networks/actions/{id}ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/networks/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 /networks/{id}/actionsID of the Network.
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/networks/$ID/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "add_subnet",
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": 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": 1,
25 "next_page": null,
26 "page": 1,
27 "per_page": 25,
28 "previous_page": null,
29 "total_entries": 21
30 }
31 }
32}Adds a route entry to a Network.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
POST /networks/{id}/actions/add_routeID of the Network.
Destination network or host of the route.
Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway.
Must be one of
0.0.0.0/0.Must not overlap with
172.31.1.1.172.31.1.1 is being used as a gateway for the public network interface of Servers.
Gateway of the route.
Packages addressed for the specified destination will be send to this IP address.
Cannot be
172.31.1.1.172.31.1.1 is being used as a gateway for the public network interface of Servers.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}' \
6 "https://api.hetzner.cloud/v1/networks/$ID/actions/add_route"1{
2 "destination": "10.100.1.0/24",
3 "gateway": "10.0.1.1"
4}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "add_route",
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": 4711,
14 "type": "network"
15 }
16 ],
17 "started": "2016-01-30T23:50:00+00:00",
18 "status": "running"
19 }
20}Adds a new subnet to the Network.
If the subnet ip_range is not provided, the first available /24 IP range will be used.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
POST /networks/{id}/actions/add_subnetID of the Network.
IP range of the subnet.
Uses CIDR notation.
Must be a subnet of the parent Networks ip_range.
Must not overlap with any other subnets or with any destinations in routes.
Minimum network size is /30. We highly recommend that you pick a larger subnet with a /24 netmask.
Name of the Network Zone.
The Location contains the network_zone it belongs to.
cloud server vswitchType of subnet.
cloud - Used to connect cloud Servers and Load Balancers.server - Same as the cloud type. Deprecated, use the cloud type instead.vswitch - Used to connect cloud Servers and Load Balancers with dedicated Servers.ID of the robot vSwitch.
Must be supplied if the subnet is of type vswitch.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"ip_range":"10.0.1.0/24","network_zone":"eu-central","type":"cloud","vswitch_id":1000}' \
6 "https://api.hetzner.cloud/v1/networks/$ID/actions/add_subnet"1{
2 "ip_range": "10.0.1.0/24",
3 "network_zone": "eu-central",
4 "type": "cloud",
5 "vswitch_id": 1000
6}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "add_subnet",
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": 4711,
14 "type": "network"
15 }
16 ],
17 "started": "2016-01-30T23:50:00+00:00",
18 "status": "running"
19 }
20}Changes the IP range of a Network.
The following restrictions apply to changing the IP range:
To update the routes on the connected Servers, they need to be rebooted or the routes to be updated manually.
For example if the Network has a range of 10.0.0.0/16 to extend it the new range has to start with the IP 10.0.0.0 as well. The netmask /16 can be changed to a smaller one then 16 therefore increasing the IP range. A valid entry would be 10.0.0.0/15, 10.0.0.0/14 or 10.0.0.0/13 and so on.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
POST /networks/{id}/actions/change_ip_rangeID of the Network.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"ip_range":"10.0.0.0/16"}' \
6 "https://api.hetzner.cloud/v1/networks/$ID/actions/change_ip_range"1{
2 "ip_range": "10.0.0.0/16"
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "change_ip_range",
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": "network"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Changes the protection settings of a Network.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
POST /networks/{id}/actions/change_protectionID of the Network.
Delete protection setting.
If true, prevents the Network 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/networks/$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": "network"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Delete a route entry from a Network.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
POST /networks/{id}/actions/delete_routeID of the Network.
Destination network or host of the route.
Packages addressed for IPs matching the destination IP prefix will be send to the specified gateway.
Must be one of
0.0.0.0/0.Must not overlap with
172.31.1.1.172.31.1.1 is being used as a gateway for the public network interface of Servers.
Gateway of the route.
Packages addressed for the specified destination will be send to this IP address.
Cannot be
172.31.1.1.172.31.1.1 is being used as a gateway for the public network interface of Servers.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}' \
6 "https://api.hetzner.cloud/v1/networks/$ID/actions/delete_route"1{
2 "destination": "10.100.1.0/24",
3 "gateway": "10.0.1.1"
4}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "delete_route",
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": 4711,
14 "type": "network"
15 }
16 ],
17 "started": "2016-01-30T23:50:00+00:00",
18 "status": "running"
19 }
20}Deletes a single subnet entry from a Network.
Subnets containing attached resources can not be deleted, they must be detached beforehand.
If a change is currently being performed on this Network, a error response with code conflict will be returned.
POST /networks/{id}/actions/delete_subnetID of the Network.
IP range in CIDR block notation of the subnet to delete.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"ip_range":"10.0.1.0/24"}' \
6 "https://api.hetzner.cloud/v1/networks/$ID/actions/delete_subnet"1{
2 "ip_range": "10.0.1.0/24"
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "delete_subnet",
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": 4711,
14 "type": "network"
15 }
16 ],
17 "started": "2016-01-30T23:50:00+00:00",
18 "status": "running"
19 }
20}GET /networks/{id}/actions/{action_id}ID of the Network.
ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/networks/$ID/actions/$ACTION_ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "add_subnet",
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": "network"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Placement groups are used to influence the location of interdependent virtual servers in our data centers. The distribution of the different instances within a group is based on a pattern specified in the type. By enforcing certain rules on the placement of instances within our infrastructure, availability can be influenced in a way that fits your needs best.
In spread placement groups, all virtual servers will run on different physical servers. This decreases the probability that some instances might fail together.
Returns all PlacementGroup objects.
GET /placement_groupsid 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".
spreadCan be used multiple times. The response will only contain PlacementGroups 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/placement_groups"1Content-Type: application/json
2Status: 2001{
2 "meta": {
3 "pagination": {
4 "last_page": 1,
5 "next_page": null,
6 "page": 1,
7 "per_page": 25,
8 "previous_page": null,
9 "total_entries": 21
10 }
11 },
12 "placement_groups": [
13 {
14 "created": "2019-01-08T12:10:00+00:00",
15 "id": 897,
16 "labels": {
17 "key": "value"
18 },
19 "name": "my Placement Group",
20 "servers": [
21 4711,
22 4712
23 ],
24 "type": "spread"
25 }
26 ]
27}Creates a new PlacementGroup.
POST /placement_groupsUser-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Name of the PlacementGroup
spreadDefine the Placement Group Type.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"name":"my Placement Group","type":"spread"}' \
6 "https://api.hetzner.cloud/v1/placement_groups"1{
2 "name": "my Placement Group",
3 "type": "spread"
4}1Content-Type: application/json
2Status: 2011{
2 "placement_group": {
3 "created": "2019-01-08T12:10:00+00:00",
4 "id": 897,
5 "labels": {
6 "key": "value"
7 },
8 "name": "my Placement Group",
9 "servers": [],
10 "type": "spread"
11 }
12}Deletes a PlacementGroup.
DELETE /placement_groups/{id}ID of the Placement Group.
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/placement_groups/$ID"1Status: 204Gets a specific PlacementGroup object.
GET /placement_groups/{id}ID of the Placement Group.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/placement_groups/$ID"1Content-Type: application/json
2Status: 2001{
2 "placement_group": {
3 "created": "2019-01-08T12:10:00+00:00",
4 "id": 897,
5 "labels": {
6 "key": "value"
7 },
8 "name": "my Placement Group",
9 "servers": [
10 4711,
11 4712
12 ],
13 "type": "spread"
14 }
15}Updates the PlacementGroup properties.
Note that when updating labels, the PlacementGroup’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.
Note: if the PlacementGroup object changes during the request, the response will be a “conflict” error.
PUT /placement_groups/{id}ID of the Placement Group.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
New PlacementGroup 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 Placement Group"}' \
6 "https://api.hetzner.cloud/v1/placement_groups/$ID"1{
2 "labels": {
3 "environment": "prod",
4 "example.com/my": "label",
5 "just-a-key": ""
6 },
7 "name": "my Placement Group"
8}1Content-Type: application/json
2Status: 2001{
2 "placement_group": {
3 "created": "2019-01-08T12:10:00+00:00",
4 "id": 897,
5 "labels": {
6 "key": "value"
7 },
8 "name": "my Placement Group",
9 "servers": [
10 4711,
11 4712
12 ],
13 "type": "spread"
14 }
15}Returns prices for resources.
Returns prices for all resources available on the platform. VAT and currency of the Project owner are used for calculations.
Both net and gross prices are included in the response.
GET /pricing1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/pricing"1Content-Type: application/json
2Status: 2001{
2 "pricing": {
3 "currency": "EUR",
4 "floating_ip": {
5 "price_monthly": {
6 "gross": "1.1900",
7 "net": "1.0000"
8 }
9 },
10 "floating_ips": [
11 {
12 "prices": [
13 {
14 "location": "fsn1",
15 "price_monthly": {
16 "gross": "1.1900",
17 "net": "1.0000"
18 }
19 }
20 ],
21 "type": "ipv4"
22 }
23 ],
24 "image": {
25 "price_per_gb_month": {
26 "gross": "1.1900",
27 "net": "1.0000"
28 }
29 },
30 "load_balancer_types": [
31 {
32 "id": 1,
33 "name": "lb11",
34 "prices": [
35 {
36 "included_traffic": 654321,
37 "location": "fsn1",
38 "price_hourly": {
39 "gross": "1.1900",
40 "net": "1.0000"
41 },
42 "price_monthly": {
43 "gross": "1.1900",
44 "net": "1.0000"
45 },
46 "price_per_tb_traffic": {
47 "gross": "1.1900",
48 "net": "1.0000"
49 }
50 }
51 ]
52 }
53 ],
54 "primary_ips": [
55 {
56 "prices": [
57 {
58 "location": "fsn1",
59 "price_hourly": {
60 "gross": "1.1900",
61 "net": "1.0000"
62 },
63 "price_monthly": {
64 "gross": "1.1900",
65 "net": "1.0000"
66 }
67 }
68 ],
69 "type": "ipv4"
70 }
71 ],
72 "server_backup": {
73 "percentage": "20.00"
74 },
75 "server_types": [
76 {
77 "id": 104,
78 "name": "cpx11",
79 "prices": [
80 {
81 "included_traffic": 654321,
82 "location": "fsn1",
83 "price_hourly": {
84 "gross": "1.1900",
85 "net": "1.0000"
86 },
87 "price_monthly": {
88 "gross": "1.1900",
89 "net": "1.0000"
90 },
91 "price_per_tb_traffic": {
92 "gross": "1.1900",
93 "net": "1.0000"
94 }
95 }
96 ]
97 }
98 ],
99 "vat_rate": "19.00",
100 "volume": {
101 "price_per_gb_month": {
102 "gross": "1.1900",
103 "net": "1.0000"
104 }
105 }
106 }
107}Primary IPs help you to create more flexible networking setups. You can assign at most one Primary IP of type ipv4 and one of type ipv6 per Server. This Server then uses these IPs.
You can only unassign a Primary IP from a Server when it's powered off. This Primary IP can then be assigned to a different powered off Server, or you can keep it around for later use.
Primary IPs are bound to a specific Datacenter. You can not assign a Primary IP from one Datacenter to a Server in a different Datacenter. If you need this capability use Floating IPs instead.
If your Server's operating system supports cloud-init there is no further configuration needed to make Primary IPs work.
Primary IPs of type ipv4 use a single IPv4 address as their ip property. Primary IPs of type ipv6 use a /64 network such as fc00::/64 as their ip property. Any IP address within that network can be used on your host.
Primary IPs are billed on an hourly basis.
List multiple Primary IPs.
Use the provided URI parameters to modify the result.
GET /primary_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".
Filter results by IP address.
25Maximum number of entries returned per page. For more information, see "Pagination".
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".
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/primary_ips"1Content-Type: application/json
2Status: 2001{
2 "meta": {
3 "pagination": {
4 "last_page": 4,
5 "next_page": 4,
6 "page": 3,
7 "per_page": 25,
8 "previous_page": 2,
9 "total_entries": 100
10 }
11 },
12 "primary_ips": [
13 {
14 "assignee_id": 17,
15 "assignee_type": "server",
16 "auto_delete": true,
17 "blocked": false,
18 "created": "2016-01-30T23:55:00+00:00",
19 "datacenter": {
20 "description": "Falkenstein DC Park 8",
21 "id": 42,
22 "location": {
23 "city": "Falkenstein",
24 "country": "DE",
25 "description": "Falkenstein DC Park 1",
26 "id": 42,
27 "latitude": 50.47612,
28 "longitude": 12.370071,
29 "name": "fsn1",
30 "network_zone": "eu-central"
31 },
32 "name": "fsn1-dc8",
33 "server_types": {
34 "available": [
35 1,
36 2,
37 3
38 ],
39 "available_for_migration": [
40 1,
41 2,
42 3
43 ],
44 "supported": [
45 1,
46 2,
47 3
48 ]
49 }
50 },
51 "dns_ptr": [
52 {
53 "dns_ptr": "server.example.com",
54 "ip": "2001:db8::1"
55 }
56 ],
57 "id": 42,
58 "ip": "131.232.99.1",
59 "labels": {
60 "environment": "prod",
61 "example.com/my": "label",
62 "just-a-key": ""
63 },
64 "name": "my-resource",
65 "protection": {
66 "delete": false
67 },
68 "type": "ipv4"
69 }
70 ]
71}Create a new Primary IP.
Can optionally be assigned to a resource by providing an assignee_id and assignee_type.
If not assigned to a resource the datacenter key needs to be provided. This can be either the ID or the name of the Datacenter this Primary IP shall be created in.
A Primary IP can only be assigned to resource in the same Datacenter later on.
| Code | Description |
|---|---|
server_not_stopped |
The specified Server is running, but needs to be powered off |
server_has_ipv4 |
The Server already has an ipv4 address |
server_has_ipv6 |
The Server already has an ipv6 address |
POST /primary_ipsRequest Body for creating a new Primary IP.
The datacenter and assignee_id/assignee_type attributes are mutually exclusive.
ID of resource to assign the Primary IP to.
Omitted if the Primary IP should not get assigned.
serverType of resource the Primary IP can get assigned to.
Currently Primary IPs can only be assigned to Servers,
therefore this field must be set to server.
falseAuto deletion state.
If enabled the Primary IP will be deleted once the assigned resource gets deleted.
Datacenter ID or name.
The Primary IP will be bound to this Datacenter. Omit if assignee_id/assignee_type is provided.
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 POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"assignee_id":17,"assignee_type":"server","auto_delete":false,"datacenter":"fsn1-dc8","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"my-resource","type":"ipv4"}' \
6 "https://api.hetzner.cloud/v1/primary_ips"1{
2 "assignee_id": 17,
3 "assignee_type": "server",
4 "auto_delete": false,
5 "datacenter": "fsn1-dc8",
6 "labels": {
7 "environment": "prod",
8 "example.com/my": "label",
9 "just-a-key": ""
10 },
11 "name": "my-resource",
12 "type": "ipv4"
13}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "create_primary_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": 17,
14 "type": "server"
15 }
16 ],
17 "started": "2016-01-30T23:50:00+00:00",
18 "status": "running"
19 },
20 "primary_ip": {
21 "assignee_id": 17,
22 "assignee_type": "server",
23 "auto_delete": true,
24 "blocked": false,
25 "created": "2016-01-30T23:50:00+00:00",
26 "datacenter": {
27 "description": "Falkenstein DC Park 8",
28 "id": 42,
29 "location": {
30 "city": "Falkenstein",
31 "country": "DE",
32 "description": "Falkenstein DC Park 1",
33 "id": 1,
34 "latitude": 50.47612,
35 "longitude": 12.370071,
36 "name": "fsn1",
37 "network_zone": "eu-central"
38 },
39 "name": "fsn1-dc8",
40 "server_types": {
41 "available": [
42 1,
43 2,
44 3
45 ],
46 "available_for_migration": [
47 1,
48 2,
49 3
50 ],
51 "supported": [
52 1,
53 2,
54 3
55 ]
56 }
57 },
58 "dns_ptr": [
59 {
60 "dns_ptr": "server.example.com",
61 "ip": "2001:db8::1"
62 }
63 ],
64 "id": 42,
65 "ip": "131.232.99.1",
66 "labels": {
67 "labelkey": "value"
68 },
69 "name": "my-ip",
70 "protection": {
71 "delete": false
72 },
73 "type": "ipv4"
74 }
75}Deletes a Primary IP.
If assigned to a Server the Primary IP will be unassigned automatically. The Server must be powered off (status off) in order for this operation to succeed.
DELETE /primary_ips/{id}ID of the Primary IP.
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/primary_ips/$ID"1Status: 204Returns a Primary IP.
GET /primary_ips/{id}ID of the Primary IP.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/primary_ips/$ID"1Content-Type: application/json
2Status: 2001{
2 "primary_ip": {
3 "assignee_id": 17,
4 "assignee_type": "server",
5 "auto_delete": true,
6 "blocked": false,
7 "created": "2016-01-30T23:55:00+00:00",
8 "datacenter": {
9 "description": "Falkenstein DC Park 8",
10 "id": 42,
11 "location": {
12 "city": "Falkenstein",
13 "country": "DE",
14 "description": "Falkenstein DC Park 1",
15 "id": 42,
16 "latitude": 50.47612,
17 "longitude": 12.370071,
18 "name": "fsn1",
19 "network_zone": "eu-central"
20 },
21 "name": "fsn1-dc8",
22 "server_types": {
23 "available": [
24 1,
25 2,
26 3
27 ],
28 "available_for_migration": [
29 1,
30 2,
31 3
32 ],
33 "supported": [
34 1,
35 2,
36 3
37 ]
38 }
39 },
40 "dns_ptr": [
41 {
42 "dns_ptr": "server.example.com",
43 "ip": "2001:db8::1"
44 }
45 ],
46 "id": 42,
47 "ip": "131.232.99.1",
48 "labels": {
49 "environment": "prod",
50 "example.com/my": "label",
51 "just-a-key": ""
52 },
53 "name": "my-resource",
54 "protection": {
55 "delete": false
56 },
57 "type": "ipv4"
58 }
59}Update the Primary IP.
Note that when updating Labels, the Primary 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.
If another change is concurrently performed on this Primary IP, a error response with code conflict will be returned.
PUT /primary_ips/{id}ID of the Primary IP.
falseAuto deletion state.
If enabled the Primary IP will be deleted once the assigned resource gets deleted.
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 '{"auto_delete":true,"labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"my-resource"}' \
6 "https://api.hetzner.cloud/v1/primary_ips/$ID"1{
2 "auto_delete": true,
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 "primary_ip": {
3 "assignee_id": 17,
4 "assignee_type": "server",
5 "auto_delete": true,
6 "blocked": false,
7 "created": "2016-01-30T23:55:00+00:00",
8 "datacenter": {
9 "description": "Falkenstein DC Park 8",
10 "id": 42,
11 "location": {
12 "city": "Falkenstein",
13 "country": "DE",
14 "description": "Falkenstein DC Park 1",
15 "id": 42,
16 "latitude": 50.47612,
17 "longitude": 12.370071,
18 "name": "fsn1",
19 "network_zone": "eu-central"
20 },
21 "name": "fsn1-dc8",
22 "server_types": {
23 "available": [
24 1,
25 2,
26 3
27 ],
28 "available_for_migration": [
29 1,
30 2,
31 3
32 ],
33 "supported": [
34 1,
35 2,
36 3
37 ]
38 }
39 },
40 "dns_ptr": [
41 {
42 "dns_ptr": "server.example.com",
43 "ip": "2001:db8::1"
44 }
45 ],
46 "id": 42,
47 "ip": "131.232.99.1",
48 "labels": {
49 "environment": "prod",
50 "example.com/my": "label",
51 "just-a-key": ""
52 },
53 "name": "my-resource",
54 "protection": {
55 "delete": false
56 },
57 "type": "ipv4"
58 }
59}Lists multiple Actions.
Use the provided URI parameters to modify the result.
GET /primary_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/primary_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 /primary_ips/actions/{id}ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/primary_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}Assign a Primary IP to a resource.
A Server can only have one Primary IP of type ipv4 and one of type ipv6 assigned. If you need more IPs use Floating IPs.
A Server must be powered off (status off) in order for this operation to succeed.
| Code | Description |
|---|---|
server_not_stopped |
The Server is running, but needs to be powered off |
primary_ip_already_assigned |
Primary IP is already assigned to a different Server |
server_has_ipv4 |
The Server already has an IPv4 address |
server_has_ipv6 |
The Server already has an IPv6 address |
POST /primary_ips/{id}/actions/assignID of the Primary IP.
ID of a resource of type assignee_type
serverType of resource assigning the Primary IP to
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"assignee_id":4711,"assignee_type":"server"}' \
6 "https://api.hetzner.cloud/v1/primary_ips/$ID/actions/assign"1{
2 "assignee_id": 4711,
3 "assignee_type": "server"
4}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "assign_primary_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 "id": 4711,
18 "type": "primary_ip"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Change the reverse DNS records for this Primary IP.
Allows to modify the PTR records set for the IP address.
POST /primary_ips/{id}/actions/change_dns_ptrID of the Primary IP.
The ip attributes specifies for which IP address the record is set. For IPv4 addresses this must be the exact address of the Primary IP. For IPv6 addresses this must be a single address within the /64 subnet of the Primary IP.
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/primary_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": "primary_ip"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Changes the protection configuration of a Primary IP.
A Primary IPs deletion protection can only be enabled if its auto_delete property is set to false.
POST /primary_ips/{id}/actions/change_protectionID of the Primary 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/primary_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": "primary_ip"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Unassign a Primary IP from a resource.
A Server must be powered off (status off) in order for this operation to succeed.
A Server requires at least one network interface (public or private) to be powered on.
| Code | Description |
|---|---|
server_not_stopped |
The Server is running, but needs to be powered off |
server_is_load_balancer_target |
The Server IPv4 address is a loadbalancer target |
POST /primary_ips/{id}/actions/unassignID of the Primary IP.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/primary_ips/$ID/actions/unassign"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "unassign_primary_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 "id": 4711,
18 "type": "primary_ip"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Servers are virtual machines that can be provisioned.
Returns all existing Server objects
GET /serversFilter 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 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".
initializing starting running stopping off deleting rebuilding migrating unknownCan be used multiple times. The response will only contain Server matching the status
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/servers"1Content-Type: application/json
2Status: 2001{
2 "meta": {
3 "pagination": {
4 "last_page": 4,
5 "next_page": 4,
6 "page": 3,
7 "per_page": 25,
8 "previous_page": 2,
9 "total_entries": 100
10 }
11 },
12 "servers": [
13 {
14 "backup_window": "22-02",
15 "created": "2016-01-30T23:55:00+00:00",
16 "datacenter": {
17 "description": "Falkenstein DC Park 8",
18 "id": 42,
19 "location": {
20 "city": "Falkenstein",
21 "country": "DE",
22 "description": "Falkenstein DC Park 1",
23 "id": 42,
24 "latitude": 50.47612,
25 "longitude": 12.370071,
26 "name": "fsn1",
27 "network_zone": "eu-central"
28 },
29 "name": "fsn1-dc8",
30 "server_types": {
31 "available": [
32 1,
33 2,
34 3
35 ],
36 "available_for_migration": [
37 1,
38 2,
39 3
40 ],
41 "supported": [
42 1,
43 2,
44 3
45 ]
46 }
47 },
48 "id": 42,
49 "image": {
50 "architecture": "x86",
51 "bound_to": null,
52 "created": "2016-01-30T23:55:00+00:00",
53 "created_from": {
54 "id": 1,
55 "name": "Server"
56 },
57 "deleted": null,
58 "deprecated": "2018-02-28T00:00:00+00:00",
59 "description": "Ubuntu 20.04 Standard 64 bit",
60 "disk_size": 10,
61 "id": 42,
62 "image_size": 2.3,
63 "labels": {
64 "environment": "prod",
65 "example.com/my": "label",
66 "just-a-key": ""
67 },
68 "name": "ubuntu-20.04",
69 "os_flavor": "ubuntu",
70 "os_version": "20.04",
71 "protection": {
72 "delete": false
73 },
74 "rapid_deploy": false,
75 "status": "available",
76 "type": "snapshot"
77 },
78 "included_traffic": 654321,
79 "ingoing_traffic": 123456,
80 "iso": {
81 "architecture": "x86",
82 "deprecation": {
83 "announced": "2023-06-01T00:00:00+00:00",
84 "unavailable_after": "2023-09-01T00:00:00+00:00"
85 },
86 "description": "FreeBSD 11.0 x64",
87 "id": 42,
88 "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
89 "type": "public"
90 },
91 "labels": {
92 "environment": "prod",
93 "example.com/my": "label",
94 "just-a-key": ""
95 },
96 "load_balancers": [
97 0
98 ],
99 "locked": false,
100 "name": "my-resource",
101 "outgoing_traffic": 123456,
102 "placement_group": {
103 "created": "2016-01-30T23:55:00+00:00",
104 "id": 42,
105 "labels": {
106 "environment": "prod",
107 "example.com/my": "label",
108 "just-a-key": ""
109 },
110 "name": "my-resource",
111 "servers": [
112 42
113 ],
114 "type": "spread"
115 },
116 "primary_disk_size": 50,
117 "private_net": [
118 {
119 "alias_ips": [
120 "10.0.0.3",
121 "10.0.0.4"
122 ],
123 "ip": "10.0.0.2",
124 "mac_address": "86:00:ff:2a:7d:e1",
125 "network": 4711
126 }
127 ],
128 "protection": {
129 "delete": false,
130 "rebuild": false
131 },
132 "public_net": {
133 "firewalls": [
134 {
135 "id": 42,
136 "status": "applied"
137 }
138 ],
139 "floating_ips": [
140 478
141 ],
142 "ipv4": {
143 "blocked": false,
144 "dns_ptr": "server01.example.com",
145 "id": 42,
146 "ip": "1.2.3.4"
147 },
148 "ipv6": {
149 "blocked": false,
150 "dns_ptr": [
151 {
152 "dns_ptr": "server.example.com",
153 "ip": "2001:db8::1"
154 }
155 ],
156 "id": 42,
157 "ip": "2001:db8::/64"
158 }
159 },
160 "rescue_enabled": false,
161 "server_type": {
162 "architecture": "x86",
163 "cores": 2,
164 "cpu_type": "shared",
165 "deprecated": false,
166 "deprecation": {
167 "announced": "2023-06-01T00:00:00+00:00",
168 "unavailable_after": "2023-09-01T00:00:00+00:00"
169 },
170 "description": "CPX11",
171 "disk": 40,
172 "id": 1,
173 "memory": 2,
174 "name": "cpx11",
175 "prices": [
176 {
177 "included_traffic": 654321,
178 "location": "fsn1",
179 "price_hourly": {
180 "gross": "1.1900",
181 "net": "1.0000"
182 },
183 "price_monthly": {
184 "gross": "1.1900",
185 "net": "1.0000"
186 },
187 "price_per_tb_traffic": {
188 "gross": "1.1900",
189 "net": "1.0000"
190 }
191 }
192 ],
193 "storage_type": "local"
194 },
195 "status": "running",
196 "volumes": [
197 0
198 ]
199 }
200 ]
201}Creates a new Server. Returns preliminary information about the Server as well as an Action that covers progress of creation.
POST /serversPlease note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes).
For server_type you can either use the ID as listed in /server_types or its name.
For image you can either use the ID as listed in /images or its name.
If you want to create the Server in a Location, you must set location to the ID or name as listed in /locations. This is the recommended way. You can be even more specific by setting datacenter to the ID or name as listed in /datacenters. However we only recommend this if you want to assign a specific Primary IP to the Server which is located in the specified Datacenter.
Some properties like start_after_create or automount will trigger Actions after the Server is created. Those Actions are listed in the next_actions field in the response.
For accessing your Server we strongly recommend to use SSH keys by passing the respective key IDs in ssh_keys. If you do not specify any ssh_keys we will generate a root password for you and return it in the response.
Please note that provided user-data is stored in our systems. While we take measures to protect it we highly recommend that you don’t use it to store passwords or other sensitive information.
| Code | Description |
|---|---|
placement_error |
An error during the placement occurred |
primary_ip_assigned |
The specified Primary IP is already assigned to a server |
primary_ip_datacenter_mismatch |
The specified Primary IP is in a different datacenter |
primary_ip_version_mismatch |
The specified Primary IP has the wrong IP Version |
Auto-mount Volumes after attach
ID or name of Datacenter to create Server in (must not be used together with location)
Firewalls which should be applied on the Server's public network interface at creation time
ID or name of the Image the Server is created from
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
ID or name of Location to create Server in (must not be used together with datacenter)
Name of the Server to create (must be unique per Project and a valid hostname as per RFC 1123)
Network IDs which should be attached to the Server private network interface at the creation time
ID of the Placement Group the server should be in
Public Network options
ID or name of the Server type this Server should be created with
SSH key IDs (integer) or names (string) which should be injected into the Server at creation time
trueThis automatically triggers a Power on a Server-Server Action after the creation is finished and is returned in the next_actions response object.
Cloud-Init user data to use during Server creation. This field is limited to 32KiB.
Volume IDs which should be attached to the Server at the creation time. Volumes must be in the same Location.
Root password when no SSH keys have been specified
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"automount":false,"datacenter":"nbg1-dc3","firewalls":[{"firewall":38}],"image":"ubuntu-20.04","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"location":"nbg1","name":"my-server","networks":[456],"placement_group":1,"public_net":{"enable_ipv4":false,"enable_ipv6":false,"ipv4":null,"ipv6":null},"server_type":"cpx11","ssh_keys":["my-ssh-key"],"start_after_create":true,"user_data":"#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n","volumes":[123]}' \
6 "https://api.hetzner.cloud/v1/servers"1{
2 "automount": false,
3 "datacenter": "nbg1-dc3",
4 "firewalls": [
5 {
6 "firewall": 38
7 }
8 ],
9 "image": "ubuntu-20.04",
10 "labels": {
11 "environment": "prod",
12 "example.com/my": "label",
13 "just-a-key": ""
14 },
15 "location": "nbg1",
16 "name": "my-server",
17 "networks": [
18 456
19 ],
20 "placement_group": 1,
21 "public_net": {
22 "enable_ipv4": false,
23 "enable_ipv6": false,
24 "ipv4": null,
25 "ipv6": null
26 },
27 "server_type": "cpx11",
28 "ssh_keys": [
29 "my-ssh-key"
30 ],
31 "start_after_create": true,
32 "user_data": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n",
33 "volumes": [
34 123
35 ]
36}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "create_server",
4 "error": {
5 "code": "action_failed",
6 "message": "Action failed"
7 },
8 "finished": null,
9 "id": 1,
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 "next_actions": [
21 {
22 "command": "start_server",
23 "error": {
24 "code": "action_failed",
25 "message": "Action failed"
26 },
27 "finished": null,
28 "id": 13,
29 "progress": 0,
30 "resources": [
31 {
32 "id": 42,
33 "type": "server"
34 }
35 ],
36 "started": "2016-01-30T23:50:00+00:00",
37 "status": "running"
38 }
39 ],
40 "root_password": "YItygq1v3GYjjMomLaKc",
41 "server": {
42 "backup_window": "22-02",
43 "created": "2016-01-30T23:50:00+00:00",
44 "datacenter": {
45 "description": "Falkenstein 1 DC 8",
46 "id": 1,
47 "location": {
48 "city": "Falkenstein",
49 "country": "DE",
50 "description": "Falkenstein DC Park 1",
51 "id": 1,
52 "latitude": 50.47612,
53 "longitude": 12.370071,
54 "name": "fsn1",
55 "network_zone": "eu-central"
56 },
57 "name": "fsn1-dc8",
58 "server_types": {
59 "available": [
60 1,
61 2,
62 3
63 ],
64 "available_for_migration": [
65 1,
66 2,
67 3
68 ],
69 "supported": [
70 1,
71 2,
72 3
73 ]
74 }
75 },
76 "id": 42,
77 "image": {
78 "architecture": "x86",
79 "bound_to": null,
80 "created": "2016-01-30T23:50:00+00:00",
81 "created_from": {
82 "id": 1,
83 "name": "Server"
84 },
85 "deleted": null,
86 "deprecated": "2018-02-28T00:00:00+00:00",
87 "description": "Ubuntu 20.04 Standard 64 bit",
88 "disk_size": 10,
89 "id": 4711,
90 "image_size": 2.3,
91 "labels": {
92 "env": "dev"
93 },
94 "name": "ubuntu-20.04",
95 "os_flavor": "ubuntu",
96 "os_version": "20.04",
97 "protection": {
98 "delete": false
99 },
100 "rapid_deploy": false,
101 "status": "available",
102 "type": "snapshot"
103 },
104 "included_traffic": 654321,
105 "ingoing_traffic": 123456,
106 "iso": {
107 "architecture": "x86",
108 "deprecation": {
109 "announced": "2018-02-28T00:00:00+00:00",
110 "unavailable_after": "2018-05-31T00:00:00+00:00"
111 },
112 "description": "FreeBSD 11.0 x64",
113 "id": 4711,
114 "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
115 "type": "public"
116 },
117 "labels": {
118 "env": "dev"
119 },
120 "load_balancers": [],
121 "locked": false,
122 "name": "my-server",
123 "outgoing_traffic": 123456,
124 "primary_disk_size": 50,
125 "private_net": [
126 {
127 "alias_ips": [],
128 "ip": "10.0.0.2",
129 "mac_address": "86:00:ff:2a:7d:e1",
130 "network": 4711
131 }
132 ],
133 "protection": {
134 "delete": false,
135 "rebuild": false
136 },
137 "public_net": {
138 "firewalls": [
139 {
140 "id": 38,
141 "status": "applied"
142 }
143 ],
144 "floating_ips": [
145 478
146 ],
147 "ipv4": {
148 "blocked": false,
149 "dns_ptr": "server01.example.com",
150 "ip": "1.2.3.4"
151 },
152 "ipv6": {
153 "blocked": false,
154 "dns_ptr": [
155 {
156 "dns_ptr": "server.example.com",
157 "ip": "2001:db8::1"
158 }
159 ],
160 "ip": "2001:db8::/64"
161 }
162 },
163 "rescue_enabled": false,
164 "server_type": {
165 "architecture": "x86",
166 "cores": 2,
167 "cpu_type": "shared",
168 "deprecated": true,
169 "description": "CPX11",
170 "disk": 40,
171 "id": 1,
172 "memory": 2,
173 "name": "cpx11",
174 "prices": [
175 {
176 "included_traffic": 21990232555520,
177 "location": "fsn1",
178 "price_hourly": {
179 "gross": "1.1900000000000000",
180 "net": "1.0000000000"
181 },
182 "price_monthly": {
183 "gross": "1.1900000000000000",
184 "net": "1.0000000000"
185 },
186 "price_per_tb_traffic": {
187 "gross": "1.1900000000000000",
188 "net": "1.0000000000"
189 }
190 }
191 ],
192 "storage_type": "local"
193 },
194 "status": "initializing",
195 "volumes": []
196 }
197}Deletes a Server. This immediately removes the Server from your account, and it is no longer accessible. Any resources attached to the server (like Volumes, Primary IPs, Floating IPs, Firewalls, Placement Groups) are detached while the server is deleted.
DELETE /servers/{id}ID of the Server.
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$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 a specific Server object. The Server must exist inside the Project
GET /servers/{id}ID of the Server.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/servers/$ID"1Content-Type: application/json
2Status: 2001{
2 "server": {
3 "backup_window": "22-02",
4 "created": "2016-01-30T23:55:00+00:00",
5 "datacenter": {
6 "description": "Falkenstein DC Park 8",
7 "id": 42,
8 "location": {
9 "city": "Falkenstein",
10 "country": "DE",
11 "description": "Falkenstein DC Park 1",
12 "id": 42,
13 "latitude": 50.47612,
14 "longitude": 12.370071,
15 "name": "fsn1",
16 "network_zone": "eu-central"
17 },
18 "name": "fsn1-dc8",
19 "server_types": {
20 "available": [
21 1,
22 2,
23 3
24 ],
25 "available_for_migration": [
26 1,
27 2,
28 3
29 ],
30 "supported": [
31 1,
32 2,
33 3
34 ]
35 }
36 },
37 "id": 42,
38 "image": {
39 "architecture": "x86",
40 "bound_to": null,
41 "created": "2016-01-30T23:55:00+00:00",
42 "created_from": {
43 "id": 1,
44 "name": "Server"
45 },
46 "deleted": null,
47 "deprecated": "2018-02-28T00:00:00+00:00",
48 "description": "Ubuntu 20.04 Standard 64 bit",
49 "disk_size": 10,
50 "id": 42,
51 "image_size": 2.3,
52 "labels": {
53 "environment": "prod",
54 "example.com/my": "label",
55 "just-a-key": ""
56 },
57 "name": "ubuntu-20.04",
58 "os_flavor": "ubuntu",
59 "os_version": "20.04",
60 "protection": {
61 "delete": false
62 },
63 "rapid_deploy": false,
64 "status": "available",
65 "type": "snapshot"
66 },
67 "included_traffic": 654321,
68 "ingoing_traffic": 123456,
69 "iso": {
70 "architecture": "x86",
71 "deprecation": {
72 "announced": "2023-06-01T00:00:00+00:00",
73 "unavailable_after": "2023-09-01T00:00:00+00:00"
74 },
75 "description": "FreeBSD 11.0 x64",
76 "id": 42,
77 "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
78 "type": "public"
79 },
80 "labels": {
81 "environment": "prod",
82 "example.com/my": "label",
83 "just-a-key": ""
84 },
85 "load_balancers": [
86 0
87 ],
88 "locked": false,
89 "name": "my-resource",
90 "outgoing_traffic": 123456,
91 "placement_group": {
92 "created": "2016-01-30T23:55:00+00:00",
93 "id": 42,
94 "labels": {
95 "environment": "prod",
96 "example.com/my": "label",
97 "just-a-key": ""
98 },
99 "name": "my-resource",
100 "servers": [
101 42
102 ],
103 "type": "spread"
104 },
105 "primary_disk_size": 50,
106 "private_net": [
107 {
108 "alias_ips": [
109 "10.0.0.3",
110 "10.0.0.4"
111 ],
112 "ip": "10.0.0.2",
113 "mac_address": "86:00:ff:2a:7d:e1",
114 "network": 4711
115 }
116 ],
117 "protection": {
118 "delete": false,
119 "rebuild": false
120 },
121 "public_net": {
122 "firewalls": [
123 {
124 "id": 42,
125 "status": "applied"
126 }
127 ],
128 "floating_ips": [
129 478
130 ],
131 "ipv4": {
132 "blocked": false,
133 "dns_ptr": "server01.example.com",
134 "id": 42,
135 "ip": "1.2.3.4"
136 },
137 "ipv6": {
138 "blocked": false,
139 "dns_ptr": [
140 {
141 "dns_ptr": "server.example.com",
142 "ip": "2001:db8::1"
143 }
144 ],
145 "id": 42,
146 "ip": "2001:db8::/64"
147 }
148 },
149 "rescue_enabled": false,
150 "server_type": {
151 "architecture": "x86",
152 "cores": 2,
153 "cpu_type": "shared",
154 "deprecated": false,
155 "deprecation": {
156 "announced": "2023-06-01T00:00:00+00:00",
157 "unavailable_after": "2023-09-01T00:00:00+00:00"
158 },
159 "description": "CPX11",
160 "disk": 40,
161 "id": 1,
162 "memory": 2,
163 "name": "cpx11",
164 "prices": [
165 {
166 "included_traffic": 654321,
167 "location": "fsn1",
168 "price_hourly": {
169 "gross": "1.1900",
170 "net": "1.0000"
171 },
172 "price_monthly": {
173 "gross": "1.1900",
174 "net": "1.0000"
175 },
176 "price_per_tb_traffic": {
177 "gross": "1.1900",
178 "net": "1.0000"
179 }
180 }
181 ],
182 "storage_type": "local"
183 },
184 "status": "running",
185 "volumes": [
186 0
187 ]
188 }
189}Updates a Server. You can update a Server’s name and a Server’s labels. Please note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes). Also note that when updating labels, the Server’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.
PUT /servers/{id}ID of the Server.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
New name to set
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-server"}' \
6 "https://api.hetzner.cloud/v1/servers/$ID"1{
2 "labels": {
3 "environment": "prod",
4 "example.com/my": "label",
5 "just-a-key": ""
6 },
7 "name": "my-server"
8}1Content-Type: application/json
2Status: 2001{
2 "server": {
3 "backup_window": "22-02",
4 "created": "2016-01-30T23:55:00+00:00",
5 "datacenter": {
6 "description": "Falkenstein DC Park 8",
7 "id": 42,
8 "location": {
9 "city": "Falkenstein",
10 "country": "DE",
11 "description": "Falkenstein DC Park 1",
12 "id": 42,
13 "latitude": 50.47612,
14 "longitude": 12.370071,
15 "name": "fsn1",
16 "network_zone": "eu-central"
17 },
18 "name": "fsn1-dc8",
19 "server_types": {
20 "available": [
21 1,
22 2,
23 3
24 ],
25 "available_for_migration": [
26 1,
27 2,
28 3
29 ],
30 "supported": [
31 1,
32 2,
33 3
34 ]
35 }
36 },
37 "id": 42,
38 "image": {
39 "architecture": "x86",
40 "bound_to": null,
41 "created": "2016-01-30T23:55:00+00:00",
42 "created_from": {
43 "id": 1,
44 "name": "Server"
45 },
46 "deleted": null,
47 "deprecated": "2018-02-28T00:00:00+00:00",
48 "description": "Ubuntu 20.04 Standard 64 bit",
49 "disk_size": 10,
50 "id": 42,
51 "image_size": 2.3,
52 "labels": {
53 "environment": "prod",
54 "example.com/my": "label",
55 "just-a-key": ""
56 },
57 "name": "ubuntu-20.04",
58 "os_flavor": "ubuntu",
59 "os_version": "20.04",
60 "protection": {
61 "delete": false
62 },
63 "rapid_deploy": false,
64 "status": "available",
65 "type": "snapshot"
66 },
67 "included_traffic": 654321,
68 "ingoing_traffic": 123456,
69 "iso": {
70 "architecture": "x86",
71 "deprecation": {
72 "announced": "2023-06-01T00:00:00+00:00",
73 "unavailable_after": "2023-09-01T00:00:00+00:00"
74 },
75 "description": "FreeBSD 11.0 x64",
76 "id": 42,
77 "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
78 "type": "public"
79 },
80 "labels": {
81 "environment": "prod",
82 "example.com/my": "label",
83 "just-a-key": ""
84 },
85 "load_balancers": [
86 0
87 ],
88 "locked": false,
89 "name": "my-resource",
90 "outgoing_traffic": 123456,
91 "placement_group": {
92 "created": "2016-01-30T23:55:00+00:00",
93 "id": 42,
94 "labels": {
95 "environment": "prod",
96 "example.com/my": "label",
97 "just-a-key": ""
98 },
99 "name": "my-resource",
100 "servers": [
101 42
102 ],
103 "type": "spread"
104 },
105 "primary_disk_size": 50,
106 "private_net": [
107 {
108 "alias_ips": [
109 "10.0.0.3",
110 "10.0.0.4"
111 ],
112 "ip": "10.0.0.2",
113 "mac_address": "86:00:ff:2a:7d:e1",
114 "network": 4711
115 }
116 ],
117 "protection": {
118 "delete": false,
119 "rebuild": false
120 },
121 "public_net": {
122 "firewalls": [
123 {
124 "id": 42,
125 "status": "applied"
126 }
127 ],
128 "floating_ips": [
129 478
130 ],
131 "ipv4": {
132 "blocked": false,
133 "dns_ptr": "server01.example.com",
134 "id": 42,
135 "ip": "1.2.3.4"
136 },
137 "ipv6": {
138 "blocked": false,
139 "dns_ptr": [
140 {
141 "dns_ptr": "server.example.com",
142 "ip": "2001:db8::1"
143 }
144 ],
145 "id": 42,
146 "ip": "2001:db8::/64"
147 }
148 },
149 "rescue_enabled": false,
150 "server_type": {
151 "architecture": "x86",
152 "cores": 2,
153 "cpu_type": "shared",
154 "deprecated": false,
155 "deprecation": {
156 "announced": "2023-06-01T00:00:00+00:00",
157 "unavailable_after": "2023-09-01T00:00:00+00:00"
158 },
159 "description": "CPX11",
160 "disk": 40,
161 "id": 1,
162 "memory": 2,
163 "name": "cpx11",
164 "prices": [
165 {
166 "included_traffic": 654321,
167 "location": "fsn1",
168 "price_hourly": {
169 "gross": "1.1900",
170 "net": "1.0000"
171 },
172 "price_monthly": {
173 "gross": "1.1900",
174 "net": "1.0000"
175 },
176 "price_per_tb_traffic": {
177 "gross": "1.1900",
178 "net": "1.0000"
179 }
180 }
181 ],
182 "storage_type": "local"
183 },
184 "status": "running",
185 "volumes": [
186 0
187 ]
188 }
189}Get Metrics for specified Server.
You must specify the type of metric to get: cpu, disk or network. You can also specify more than one type by comma separation, e.g. cpu,disk.
Depending on the type you will get different time series data
| Type | Timeseries | Unit | Description |
|---|---|---|---|
| cpu | cpu | percent | Percent CPU usage |
| disk | disk.0.iops.read | iop/s | Number of read IO operations per second |
| disk.0.iops.write | iop/s | Number of write IO operations per second | |
| disk.0.bandwidth.read | bytes/s | Bytes read per second | |
| disk.0.bandwidth.write | bytes/s | Bytes written per second | |
| network | network.0.pps.in | packets/s | Public Network interface packets per second received |
| network.0.pps.out | packets/s | Public Network interface packets per second sent | |
| network.0.bandwidth.in | bytes/s | Public Network interface bytes/s received | |
| network.0.bandwidth.out | bytes/s | Public Network interface bytes/s sent |
Metrics are available for the last 30 days only.
If you do not provide the step argument we will automatically adjust it so that a maximum of 200 samples are returned.
We limit the number of samples returned to a maximum of 500 and will adjust the step parameter accordingly.
GET /servers/{id}/metricsID of the Server.
cpu disk networkType of metrics to get
Start of period to get Metrics for (in ISO-8601 format)
End of period to get Metrics for (in ISO-8601 format)
Resolution of results in seconds
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/servers/$ID/metrics?type=$TYPE&start=$START&end=$END"1Content-Type: application/json
2Status: 2001{
2 "metrics": {
3 "end": "2017-01-01T23:00:00+00:00",
4 "start": "2017-01-01T00:00:00+00:00",
5 "step": 60,
6 "time_series": {
7 "name_of_timeseries": {
8 "values": [
9 [
10 1435781470.622,
11 "42"
12 ],
13 [
14 1435781471.622,
15 "43"
16 ]
17 ]
18 }
19 }
20 }
21}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 /servers/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/servers/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 /servers/actions/{id}ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/servers/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 Server. You can sort the results by using the sort URI parameter, and filter them with the status parameter.
GET /servers/{id}/actionsID of the Server.
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/servers/$ID/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "start_server",
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": 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": 1,
25 "next_page": null,
26 "page": 1,
27 "per_page": 25,
28 "previous_page": null,
29 "total_entries": 21
30 }
31 }
32}Adds a Server to a Placement Group.
Server must be powered off for this command to succeed.
| Code | Description |
|---|---|
server_not_stopped |
The action requires a stopped server |
POST /servers/{id}/actions/add_to_placement_groupID of the Server.
ID of Placement Group the Server should be added to
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"placement_group":1}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/add_to_placement_group"1{
2 "placement_group": 1
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "add_to_placement_group",
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}Attaches an ISO to a Server. The Server will immediately see it as a new disk. An already attached ISO will automatically be detached before the new ISO is attached.
Servers with attached ISOs have a modified boot order: They will try to boot from the ISO first before falling back to hard disk.
POST /servers/{id}/actions/attach_isoID of the Server.
ID or name of ISO to attach to the Server as listed in GET /isos
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"iso":"FreeBSD-11.0-RELEASE-amd64-dvd1"}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/attach_iso"1{
2 "iso": "FreeBSD-11.0-RELEASE-amd64-dvd1"
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "attach_iso",
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}Attaches a Server to a network. This will complement the fixed public Server interface by adding an additional ethernet interface to the Server which is connected to the specified network.
The Server will get an IP auto assigned from a subnet of type server in the same network_zone.
Using the alias_ips attribute you can also define one or more additional IPs to the Servers. Please note that you will have to configure these IPs by hand on your Server since only the primary IP will be given out by DHCP.
Call specific error codes
| Code | Description |
|---|---|
server_already_attached |
The server is already attached to the network |
ip_not_available |
The provided Network IP is not available |
no_subnet_available |
No Subnet or IP is available for the Server within the network |
networks_overlap |
The network IP range overlaps with one of the server networks |
POST /servers/{id}/actions/attach_to_networkID of the Server.
Additional IPs to be assigned to this Server
IP to request to be assigned to this Server; if you do not provide this then you will be auto assigned an IP address
ID of an existing network to attach the Server to
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"alias_ips":["10.0.1.2"],"ip":"10.0.1.1","network":4711}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/attach_to_network"1{
2 "alias_ips": [
3 "10.0.1.2"
4 ],
5 "ip": "10.0.1.1",
6 "network": 4711
7}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "attach_to_network",
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 "id": 4711,
18 "type": "network"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Changes the alias IPs of an already attached Network. Note that the existing aliases for the specified Network will be replaced with these provided in the request body. So if you want to add an alias IP, you have to provide the existing ones from the Network plus the new alias IP in the request body.
POST /servers/{id}/actions/change_alias_ipsID of the Server.
New alias IPs to set for this Server
ID of an existing Network already attached to the Server
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"alias_ips":["10.0.1.2"],"network":4711}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/change_alias_ips"1{
2 "alias_ips": [
3 "10.0.1.2"
4 ],
5 "network": 4711
6}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "change_alias_ips",
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 "id": 4711,
18 "type": "network"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Changes the hostname that will appear when getting the hostname belonging to the primary IPs (IPv4 and IPv6) of this Server.
Floating IPs assigned to the Server are not affected by this.
POST /servers/{id}/actions/change_dns_ptrID of the Server.
Select the IP address for which to change the DNS entry by passing ip. It can be either IPv4 or IPv6. The target hostname is set by passing dns_ptr.
Hostname to set as a reverse DNS PTR entry, reset to original value if null
Primary IP address for which the reverse DNS entry should be set
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"dns_ptr":"server01.example.com","ip":"1.2.3.4"}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/change_dns_ptr"1{
2 "dns_ptr": "server01.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": 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}Changes the protection configuration of the Server.
POST /servers/{id}/actions/change_protectionID of the Server.
If true, prevents the Server from being deleted (currently delete and rebuild attribute needs to have the same value)
If true, prevents the Server from being rebuilt (currently delete and rebuild attribute needs to have the same value)
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"delete":true,"rebuild":true}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/change_protection"1{
2 "delete": true,
3 "rebuild": true
4}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": 42,
14 "type": "server"
15 }
16 ],
17 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Changes the type (Cores, RAM and disk sizes) of a Server.
Server must be powered off for this command to succeed.
This copies the content of its disk, and starts it again.
You can only migrate to Server types with the same storage_type and equal or bigger disks. Shrinking disks is not possible as it might destroy data.
If the disk gets upgraded, the Server type can not be downgraded any more. If you plan to downgrade the Server type, set upgrade_disk to false.
| Code | Description |
|---|---|
invalid_server_type |
The server type does not fit for the given server or is deprecated |
server_not_stopped |
The action requires a stopped server |
POST /servers/{id}/actions/change_typeID of the Server.
ID or name of Server type the Server should migrate to
If false, do not upgrade the disk (this allows downgrading the Server type later)
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"server_type":"cpx11","upgrade_disk":true}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/change_type"1{
2 "server_type": "cpx11",
3 "upgrade_disk": true
4}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "change_server_type",
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}Creates an Image (snapshot) from a Server by copying the contents of its disks. This creates a snapshot of the current state of the disk and copies it into an Image. If the Server is currently running you must make sure that its disk content is consistent. Otherwise, the created Image may not be readable.
To make sure disk content is consistent, we recommend to shut down the Server prior to creating an Image.
You can either create a backup Image that is bound to the Server and therefore will be deleted when the Server is deleted, or you can create a snapshot Image which is completely independent of the Server it was created from and will survive Server deletion. Backup Images are only available when the backup option is enabled for the Server. Snapshot Images are billed on a per GB basis.
POST /servers/{id}/actions/create_imageID of the Server.
Description of the Image, will be auto-generated if not set
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
snapshot backupDefault: snapshotType of Image to create.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"description":"my image","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"type":"snapshot"}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/create_image"1{
2 "description": "my image",
3 "labels": {
4 "environment": "prod",
5 "example.com/my": "label",
6 "just-a-key": ""
7 },
8 "type": "snapshot"
9}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "create_image",
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 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 },
20 "image": {
21 "architecture": "x86",
22 "bound_to": null,
23 "created": "2016-01-30T23:50:00+00:00",
24 "created_from": {
25 "id": 1,
26 "name": "Server"
27 },
28 "deleted": null,
29 "deprecated": "2018-02-28T00:00:00+00:00",
30 "description": "my image",
31 "disk_size": 10,
32 "id": 4711,
33 "image_size": 2.3,
34 "labels": {
35 "env": "dev"
36 },
37 "name": null,
38 "os_flavor": "ubuntu",
39 "os_version": "20.04",
40 "protection": {
41 "delete": false
42 },
43 "rapid_deploy": false,
44 "status": "creating",
45 "type": "snapshot"
46 }
47}Detaches a Server from a network. The interface for this network will vanish.
POST /servers/{id}/actions/detach_from_networkID of the Server.
ID of an existing network to detach the Server from
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"network":4711}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/detach_from_network"1{
2 "network": 4711
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "detach_from_network",
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 "id": 4711,
18 "type": "network"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Detaches an ISO from a Server. In case no ISO Image is attached to the Server, the status of the returned Action is immediately set to success
POST /servers/{id}/actions/detach_isoID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/detach_iso"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "detach_iso",
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}Disables the automatic backup option and deletes all existing Backups for a Server. No more additional charges for backups will be made.
Caution: This immediately removes all existing backups for the Server!
POST /servers/{id}/actions/disable_backupID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/disable_backup"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "disable_backup",
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 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Disables the Hetzner Rescue System for a Server. This makes a Server start from its disks on next reboot.
Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.
Disabling rescue mode will not reboot your Server — you will have to do this yourself.
POST /servers/{id}/actions/disable_rescueID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/disable_rescue"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "disable_rescue",
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}Enables and configures the automatic daily backup option for the Server. Enabling automatic backups will increase the price of the Server by 20%. In return, you will get seven slots where Images of type backup can be stored.
Backups are automatically created daily.
POST /servers/{id}/actions/enable_backupID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/enable_backup"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "enable_backup",
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 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Enable the Hetzner Rescue System for this Server. The next time a Server with enabled rescue mode boots it will start a special minimal Linux distribution designed for repair and reinstall.
In case a Server cannot boot on its own you can use this to access a Server’s disks.
Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.
Enabling rescue mode will not reboot your Server — you will have to do this yourself.
POST /servers/{id}/actions/enable_rescueID of the Server.
Array of SSH key IDs which should be injected into the rescue system.
linux64Default: linux64Type of rescue system to boot.
Password that will be set for this Server once the Action succeeds
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"ssh_keys":[2323],"type":"linux64"}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/enable_rescue"1{
2 "ssh_keys": [
3 2323
4 ],
5 "type": "linux64"
6}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "enable_rescue",
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 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 },
20 "root_password": "zCWbFhnu950dUTko5f40"
21}Cuts power to the Server. This forcefully stops it without giving the Server operating system time to gracefully stop. May lead to data loss, equivalent to pulling the power cord. Power off should only be used when shutdown does not work.
POST /servers/{id}/actions/poweroffID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/poweroff"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "stop_server",
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}Starts a Server by turning its power on.
POST /servers/{id}/actions/poweronID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/poweron"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "start_server",
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}Reboots a Server gracefully by sending an ACPI request. The Server operating system must support ACPI and react to the request, otherwise the Server will not reboot.
POST /servers/{id}/actions/rebootID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/reboot"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "reboot_server",
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}Rebuilds a Server overwriting its disk with the content of an Image, thereby destroying all data on the target Server
The Image can either be one you have created earlier (backup or snapshot Image) or it can be a completely fresh system Image provided by us. You can get a list of all available Images with GET /images.
Your Server will automatically be powered off before the rebuild command executes.
POST /servers/{id}/actions/rebuildID of the Server.
To select which Image to rebuild from you can either pass an ID or a name as the image argument. Passing a name only works for system Images since the other Image types do not have a name set.
ID or name of Image to rebuilt from.
New root password when not using SSH keys
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"image":"ubuntu-20.04"}' \
6 "https://api.hetzner.cloud/v1/servers/$ID/actions/rebuild"1{
2 "image": "ubuntu-20.04"
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "rebuild_server",
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 "root_password": null
21}Removes a Server from a Placement Group.
POST /servers/{id}/actions/remove_from_placement_groupID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/remove_from_placement_group"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "remove_from_placement_group",
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 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Requests credentials for remote access via VNC over websocket to keyboard, monitor, and mouse for a Server. The provided URL is valid for 1 minute, after this period a new url needs to be created to connect to the Server. How long the connection is open after the initial connect is not subject to this timeout.
POST /servers/{id}/actions/request_consoleID of the Server.
VNC password to use for this connection (this password only works in combination with a wss_url with valid token)
URL of websocket proxy to use; this includes a token which is valid for a limited time only
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/request_console"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "request_console",
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 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 },
20 "password": "9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x",
21 "wss_url": "wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c"
22}Cuts power to a Server and starts it again. This forcefully stops it without giving the Server operating system time to gracefully stop. This may lead to data loss, it’s equivalent to pulling the power cord and plugging it in again. Reset should only be used when reboot does not work.
POST /servers/{id}/actions/resetID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/reset"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "reset_server",
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}Resets the root password. Only works for Linux systems that are running the qemu guest agent. Server must be powered on (status running) in order for this operation to succeed.
This will generate a new password for this Server and return it.
If this does not succeed you can use the rescue system to netboot the Server and manually change your Server password by hand.
POST /servers/{id}/actions/reset_passwordID of the Server.
Password that will be set for this Server once the Action succeeds
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/reset_password"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "reset_password",
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 "root_password": "zCWbFhnu950dUTko5f40"
21}Shuts down a Server gracefully by sending an ACPI shutdown request. The Server operating system must support ACPI
and react to the request, otherwise the Server will not shut down. Please note that the action status in this case
only reflects whether the action was sent to the server. It does not mean that the server actually shut down
successfully. If you need to ensure that the server is off, use the poweroff action
POST /servers/{id}/actions/shutdownID of the Server.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/servers/$ID/actions/shutdown"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "shutdown_server",
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}Returns a specific Action object for a Server.
GET /servers/{id}/actions/{action_id}ID of the Server.
ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/servers/$ID/actions/$ACTION_ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "start_server",
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 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}Server types define kinds of Servers offered. Each type has an hourly and a monthly cost. You will pay whichever cost is lower for your usage of this specific Server. Costs may differ between Locations.
Currency for all amounts is €. All prices exclude VAT.
Gets all Server type objects.
GET /server_typesFilter resources by their name. The response will only contain the resources matching the specified name.
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/server_types"1Content-Type: application/json
2Status: 2001{
2 "meta": {
3 "pagination": {
4 "last_page": 4,
5 "next_page": 4,
6 "page": 3,
7 "per_page": 25,
8 "previous_page": 2,
9 "total_entries": 100
10 }
11 },
12 "server_types": [
13 {
14 "architecture": "x86",
15 "cores": 2,
16 "cpu_type": "shared",
17 "deprecated": false,
18 "deprecation": {
19 "announced": "2023-06-01T00:00:00+00:00",
20 "unavailable_after": "2023-09-01T00:00:00+00:00"
21 },
22 "description": "CPX11",
23 "disk": 40,
24 "id": 1,
25 "memory": 2,
26 "name": "cpx11",
27 "prices": [
28 {
29 "included_traffic": 654321,
30 "location": "fsn1",
31 "price_hourly": {
32 "gross": "1.1900",
33 "net": "1.0000"
34 },
35 "price_monthly": {
36 "gross": "1.1900",
37 "net": "1.0000"
38 },
39 "price_per_tb_traffic": {
40 "gross": "1.1900",
41 "net": "1.0000"
42 }
43 }
44 ],
45 "storage_type": "local"
46 }
47 ]
48}Gets a specific Server type object.
GET /server_types/{id}ID of the Server Type.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/server_types/$ID"1Content-Type: application/json
2Status: 2001{
2 "server_type": {
3 "architecture": "x86",
4 "cores": 2,
5 "cpu_type": "shared",
6 "deprecated": false,
7 "deprecation": {
8 "announced": "2023-06-01T00:00:00+00:00",
9 "unavailable_after": "2023-09-01T00:00:00+00:00"
10 },
11 "description": "CPX11",
12 "disk": 40,
13 "id": 1,
14 "memory": 2,
15 "name": "cpx11",
16 "prices": [
17 {
18 "included_traffic": 654321,
19 "location": "fsn1",
20 "price_hourly": {
21 "gross": "1.1900",
22 "net": "1.0000"
23 },
24 "price_monthly": {
25 "gross": "1.1900",
26 "net": "1.0000"
27 },
28 "price_per_tb_traffic": {
29 "gross": "1.1900",
30 "net": "1.0000"
31 }
32 }
33 ],
34 "storage_type": "local"
35 }
36}SSH keys are public keys you provide to the cloud system. They can be injected into Servers at creation time. We highly recommend that you use keys instead of passwords to manage your Servers.
Returns all SSH key objects.
GET /ssh_keysid id:asc id:desc name name:asc name: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.
Can be used to filter SSH keys by their fingerprint. The response will only contain the SSH key matching the specified fingerprint.
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/ssh_keys"1Content-Type: application/json
2Status: 2001{
2 "meta": {
3 "pagination": {
4 "last_page": 4,
5 "next_page": 4,
6 "page": 3,
7 "per_page": 25,
8 "previous_page": 2,
9 "total_entries": 100
10 }
11 },
12 "ssh_keys": [
13 {
14 "created": "2016-01-30T23:55:00+00:00",
15 "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
16 "id": 42,
17 "labels": {
18 "environment": "prod",
19 "example.com/my": "label",
20 "just-a-key": ""
21 },
22 "name": "my-resource",
23 "public_key": "ssh-rsa AAAjjk76kgf...Xt"
24 }
25 ]
26}Creates a new SSH key with the given name and public_key. Once an SSH key is created, it can be used in other calls such as creating Servers.
POST /ssh_keysUser-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Name of the SSH key
Public key
1curl \
2 -X POST \
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 ssh key","public_key":"ssh-rsa AAAjjk76kgf...Xt"}' \
6 "https://api.hetzner.cloud/v1/ssh_keys"1{
2 "labels": {
3 "environment": "prod",
4 "example.com/my": "label",
5 "just-a-key": ""
6 },
7 "name": "My ssh key",
8 "public_key": "ssh-rsa AAAjjk76kgf...Xt"
9}1Content-Type: application/json
2Status: 2011{
2 "ssh_key": {
3 "created": "2016-01-30T23:55:00+00:00",
4 "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
5 "id": 42,
6 "labels": {
7 "environment": "prod",
8 "example.com/my": "label",
9 "just-a-key": ""
10 },
11 "name": "my-resource",
12 "public_key": "ssh-rsa AAAjjk76kgf...Xt"
13 }
14}Deletes an SSH key. It cannot be used anymore.
DELETE /ssh_keys/{id}ID of the SSH Key.
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/ssh_keys/$ID"1Status: 204Returns a specific SSH key object.
GET /ssh_keys/{id}ID of the SSH Key.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/ssh_keys/$ID"1Content-Type: application/json
2Status: 2001{
2 "ssh_key": {
3 "created": "2016-01-30T23:55:00+00:00",
4 "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
5 "id": 42,
6 "labels": {
7 "environment": "prod",
8 "example.com/my": "label",
9 "just-a-key": ""
10 },
11 "name": "my-resource",
12 "public_key": "ssh-rsa AAAjjk76kgf...Xt"
13 }
14}Updates an SSH key. You can update an SSH key name and an SSH key labels.
Please note that when updating labels, the SSH key current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.
PUT /ssh_keys/{id}ID of the SSH Key.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
New name Name to set
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 ssh key"}' \
6 "https://api.hetzner.cloud/v1/ssh_keys/$ID"1{
2 "labels": {
3 "environment": "prod",
4 "example.com/my": "label",
5 "just-a-key": ""
6 },
7 "name": "My ssh key"
8}1Content-Type: application/json
2Status: 2001{
2 "ssh_key": {
3 "created": "2016-01-30T23:50:00+00:00",
4 "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
5 "id": 2323,
6 "labels": {
7 "labelkey": "value"
8 },
9 "name": "My ssh key",
10 "public_key": "ssh-rsa AAAjjk76kgf...Xt"
11 }
12}A Volume is a highly-available, scalable, and SSD-based block storage for Servers.
Pricing for Volumes depends on the Volume size and Location, not the actual used storage.
Please see Hetzner Docs for more details about Volumes.
Gets all existing Volumes that you have available.
GET /volumesavailable creatingCan be used multiple times. The response will only contain Volumes matching the status.
id 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/volumes"1Content-Type: application/json
2Status: 2001{
2 "meta": {
3 "pagination": {
4 "last_page": 4,
5 "next_page": 4,
6 "page": 3,
7 "per_page": 25,
8 "previous_page": 2,
9 "total_entries": 100
10 }
11 },
12 "volumes": [
13 {
14 "created": "2016-01-30T23:55:00+00:00",
15 "format": "xfs",
16 "id": 42,
17 "labels": {
18 "environment": "prod",
19 "example.com/my": "label",
20 "just-a-key": ""
21 },
22 "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
23 "location": {
24 "city": "Falkenstein",
25 "country": "DE",
26 "description": "Falkenstein DC Park 1",
27 "id": 42,
28 "latitude": 50.47612,
29 "longitude": 12.370071,
30 "name": "fsn1",
31 "network_zone": "eu-central"
32 },
33 "name": "my-resource",
34 "protection": {
35 "delete": false
36 },
37 "server": 12,
38 "size": 42,
39 "status": "available"
40 }
41 ]
42}Creates a new Volume attached to a Server. If you want to create a Volume that is not attached to a Server, you need to provide the location key instead of server. This can be either the ID or the name of the Location this Volume will be created in. Note that a Volume can be attached to a Server only in the same Location as the Volume itself.
Specifying the Server during Volume creation will automatically attach the Volume to that Server after it has been initialized. In that case, the next_actions key in the response is an array which contains a single attach_volume action.
The minimum Volume size is 10GB and the maximum size is 10TB (10240GB).
A volume’s name can consist of alphanumeric characters, dashes, underscores, and dots, but has to start and end with an alphanumeric character. The total length is limited to 64 characters. Volume names must be unique per Project.
| Code | Description |
|---|---|
no_space_left_in_location |
There is no volume space left in the given location |
POST /volumesAuto-mount Volume after attach. server must be provided.
Format Volume after creation. One of: xfs, ext4
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Location to create the Volume in (can be omitted if Server is specified)
Name of the volume
Server to which to attach the Volume once it's created (Volume will be created in the same Location as the server)
Size of the Volume in GB
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"automount":false,"format":"xfs","labels":{"labelkey":"value"},"location":"nbg1","name":"test-database","size":42}' \
6 "https://api.hetzner.cloud/v1/volumes"1{
2 "automount": false,
3 "format": "xfs",
4 "labels": {
5 "labelkey": "value"
6 },
7 "location": "nbg1",
8 "name": "test-database",
9 "size": 42
10}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "create_volume",
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 "id": 554,
18 "type": "volume"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 },
24 "next_actions": [
25 {
26 "command": "attach_volume",
27 "error": {
28 "code": "action_failed",
29 "message": "Action failed"
30 },
31 "finished": null,
32 "id": 13,
33 "progress": 0,
34 "resources": [
35 {
36 "id": 42,
37 "type": "server"
38 },
39 {
40 "id": 554,
41 "type": "volume"
42 }
43 ],
44 "started": "2016-01-30T23:50:00+00:00",
45 "status": "running"
46 }
47 ],
48 "volume": {
49 "created": "2016-01-30T23:50:11+00:00",
50 "format": "xfs",
51 "id": 4711,
52 "labels": {
53 "env": "dev"
54 },
55 "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
56 "location": {
57 "city": "Falkenstein",
58 "country": "DE",
59 "description": "Falkenstein DC Park 1",
60 "id": 1,
61 "latitude": 50.47612,
62 "longitude": 12.370071,
63 "name": "fsn1",
64 "network_zone": "eu-central"
65 },
66 "name": "database-storage",
67 "protection": {
68 "delete": false
69 },
70 "server": 12,
71 "size": 42,
72 "status": "available"
73 }
74}Deletes a volume. All Volume data is irreversibly destroyed. The Volume must not be attached to a Server and it must not have delete protection enabled.
DELETE /volumes/{id}ID of the Volume.
1curl \
2 -X DELETE \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/volumes/$ID"1Status: 204Gets a specific Volume object.
GET /volumes/{id}ID of the Volume.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/volumes/$ID"1Content-Type: application/json
2Status: 2001{
2 "volume": {
3 "created": "2016-01-30T23:55:00+00:00",
4 "format": "xfs",
5 "id": 42,
6 "labels": {
7 "environment": "prod",
8 "example.com/my": "label",
9 "just-a-key": ""
10 },
11 "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
12 "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 "name": "my-resource",
23 "protection": {
24 "delete": false
25 },
26 "server": 12,
27 "size": 42,
28 "status": "available"
29 }
30}Updates the Volume properties.
Note that when updating labels, the volume’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.
PUT /volumes/{id}ID of the Volume.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
New Volume 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":"database-storage"}' \
6 "https://api.hetzner.cloud/v1/volumes/$ID"1{
2 "labels": {
3 "environment": "prod",
4 "example.com/my": "label",
5 "just-a-key": ""
6 },
7 "name": "database-storage"
8}1Content-Type: application/json
2Status: 2001{
2 "volume": {
3 "created": "2016-01-30T23:50:11+00:00",
4 "format": "xfs",
5 "id": 4711,
6 "labels": {
7 "labelkey": "value"
8 },
9 "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
10 "location": {
11 "city": "Falkenstein",
12 "country": "DE",
13 "description": "Falkenstein DC Park 1",
14 "id": 1,
15 "latitude": 50.47612,
16 "longitude": 12.370071,
17 "name": "fsn1",
18 "network_zone": "eu-central"
19 },
20 "name": "database-storage",
21 "protection": {
22 "delete": false
23 },
24 "server": 12,
25 "size": 42,
26 "status": "available"
27 }
28}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 /volumes/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/volumes/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 /volumes/actions/{id}ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/volumes/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 Volume. You can sort the results by using the sort URI parameter, and filter them with the status parameter.
GET /volumes/{id}/actionsID of the Volume.
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/volumes/$ID/actions"1Content-Type: application/json
2Status: 2001{
2 "actions": [
3 {
4 "command": "attach_volume",
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": 42,
15 "type": "server"
16 },
17 {
18 "id": 13,
19 "type": "volume"
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}Attaches a Volume to a Server. Works only if the Server is in the same Location as the Volume.
POST /volumes/{id}/actions/attachID of the Volume.
Auto-mount the Volume after attaching it
ID of the Server the Volume will be attached to
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"automount":false,"server":43}' \
6 "https://api.hetzner.cloud/v1/volumes/$ID/actions/attach"1{
2 "automount": false,
3 "server": 43
4}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "attach_volume",
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": 43,
14 "type": "server"
15 },
16 {
17 "id": 554,
18 "type": "volume"
19 }
20 ],
21 "started": "2016-01-30T23:50:00+00:00",
22 "status": "running"
23 }
24}Changes the protection configuration of a Volume.
POST /volumes/{id}/actions/change_protectionID of the Volume.
If true, prevents the Volume 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/volumes/$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": 42,
14 "type": "server"
15 },
16 {
17 "id": 554,
18 "type": "volume"
19 }
20 ],
21 "started": "2016-01-30T23:55:00+00:00",
22 "status": "success"
23 }
24}Detaches a Volume from the Server it’s attached to. You may attach it to a Server again at a later time.
POST /volumes/{id}/actions/detachID of the Volume.
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 "https://api.hetzner.cloud/v1/volumes/$ID/actions/detach"1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "detach_volume",
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}Changes the size of a Volume. Note that downsizing a Volume is not possible.
POST /volumes/{id}/actions/resizeID of the Volume.
New Volume size in GB (must be greater than current size)
1curl \
2 -X POST \
3 -H "Authorization: Bearer $API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{"size":50}' \
6 "https://api.hetzner.cloud/v1/volumes/$ID/actions/resize"1{
2 "size": 50
3}1Content-Type: application/json
2Status: 2011{
2 "action": {
3 "command": "resize_volume",
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": 554,
14 "type": "volume"
15 }
16 ],
17 "started": "2016-01-30T23:50:00+00:00",
18 "status": "running"
19 }
20}Returns a specific Action for a Volume.
GET /volumes/{id}/actions/{action_id}ID of the Volume.
ID of the Action.
1curl \
2 -H "Authorization: Bearer $API_TOKEN" \
3 "https://api.hetzner.cloud/v1/volumes/$ID/actions/$ACTION_ID"1Content-Type: application/json
2Status: 2001{
2 "action": {
3 "command": "attach_volume",
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 "started": "2016-01-30T23:55:00+00:00",
18 "status": "success"
19 }
20}