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:
You can find even more libraries, tools and integrations on our Awesome List on GitHub.
If you are developing an open-source project that supports or intends to add support for Hetzner APIs, you may be eligible for a free one-time credit of up to € 50 / $ 50 on your account. Please contact us via 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.
curl -H "Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj" \
https://api.hetzner.cloud/v1/servers{
"servers": [],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 0
}
}
}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.
Authorization: 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 |
deprecated_api_endpoint |
The request can not be answered because the API functionality was removed |
timeout |
The request could not be answered in time, please retry |
{
"error": {
"code": "invalid_input",
"message": "invalid input in field 'broken_field': is too long",
"details": {
"fields": [
{
"name": "broken_field",
"messages": ["is too long"]
}
]
}
}
}{
"error": {
"code": "invalid_input",
"message": "invalid input in field 'broken_field': is too long",
"details": {
"fields": [
{
"name": "broken_field",
"messages": ["is too long"]
}
]
}
}
}{
"error": {
"code": "uniqueness_error",
"message": "SSH key with the same fingerprint already exists",
"details": {
"fields": [
{
"name": "public_key"
}
]
}
}
}{
"error": {
"code": "resource_limit_exceeded",
"message": "project limit exceeded",
"details": {
"limits": [
{
"name": "project_limit"
}
]
}
}
}{
"error": {
"code": "deprecated_api_endpoint",
"message": "API functionality was removed",
"details": {
"announcement": "https://docs.hetzner.cloud/changelog#2023-07-20-foo-endpoint-is-deprecated"
}
}
}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.
{
"labels": {
"environment": "development",
"service": "backend",
"example.com/my": "label",
"just-a-key": ""
}
}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.
{
"servers": [...],
"meta": {
"pagination": {
"page": 2,
"per_page": 25,
"previous_page": 1,
"next_page": 3,
"last_page": 4,
"total_entries": 100
}
}
}Link: <https://api.hetzner.cloud/v1/actions?page=2&per_page=5>; rel="prev",
<https://api.hetzner.cloud/v1/actions?page=4&per_page=5>; rel="next",
<https://api.hetzner.cloud/v1/actions?page=6&per_page=5>; rel="last"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 several 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 |
$ curl http://169.254.169.254/hetzner/v1/metadataavailability-zone: hel1-dc2
hostname: my-server
instance-id: 42
public-ipv4: 1.2.3.4
region: eu-central$ curl http://169.254.169.254/hetzner/v1/metadata/hostname
my-server$ curl http://169.254.169.254/hetzner/v1/metadata/instance-id
42$ curl http://169.254.169.254/hetzner/v1/metadata/public-ipv4
1.2.3.4$ curl http://169.254.169.254/hetzner/v1/metadata/private-networks- ip: 10.0.0.2
alias_ips: [10.0.0.3, 10.0.0.4]
interface_num: 1
mac_address: 86:00:00:2a:7d:e0
network_id: 1234
network_name: nw-test1
network: 10.0.0.0/8
subnet: 10.0.0.0/24
gateway: 10.0.0.1
- ip: 192.168.0.2
alias_ips: []
interface_num: 2
mac_address: 86:00:00:2a:7d:e1
network_id: 4321
network_name: nw-test2
network: 192.168.0.0/16
subnet: 192.168.0.0/24
gateway: 192.168.0.1$ curl http://169.254.169.254/hetzner/v1/metadata/availability-zone
hel1-dc2$ curl http://169.254.169.254/hetzner/v1/metadata/region
eu-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.
https://api.hetzner.cloud/v1/actions?sort=status:asc
https://api.hetzner.cloud/v1/actions?sort=status:desc
https://api.hetzner.cloud/v1/actions?sort=status:asc&sort=command:descYou can find all announced deprecations in our Changelog.
Actions show the results and progress of asynchronous requests to the API.
Returns multiple Action objects specified by the id parameter.
Note: This endpoint previously allowed listing all actions in the project. This functionality was deprecated in July 2023 and removed on 30 January 2025.
GET /actionsFilter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/actions?id=$ID"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
]
}Returns a specific Action object.
GET /actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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 exactly the specified name.
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
uploaded managedFilter resources by type. Can be used multiple times. The response will only contain the resources with the specified type.
25Maximum number of entries returned per page. For more information, see "Pagination".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/certificates"Content-Type: application/json
Status: 200{
"certificates": [
{
"id": 897,
"name": "my website cert",
"labels": {
"key": "value"
},
"type": "uploaded",
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00+00:00",
"not_valid_before": "2019-01-08T10:00:00+00:00",
"not_valid_after": "2019-07-08T09:59:59+00:00",
"domain_names": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
"status": null,
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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 /certificatesName of the Certificate.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
uploaded managedDefault: uploadedChoose between uploading a Certificate in PEM format or requesting a managed Let's Encrypt Certificate.
Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. Required for type uploaded Certificates.
Certificate key in PEM format. 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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my website cert","type":"uploaded","certificate":"-----BEGIN CERTIFICATE-----\n...","private_key":"-----BEGIN PRIVATE KEY-----\n..."}' \
"https://api.hetzner.cloud/v1/certificates"{
"name": "my website cert",
"type": "uploaded",
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"private_key": "-----BEGIN PRIVATE KEY-----\n..."
}Content-Type: application/json
Status: 201{
"certificate": {
"id": 897,
"name": "my website cert",
"labels": {
"key": "value"
},
"type": "uploaded",
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00+00:00",
"not_valid_before": "2019-01-08T10:00:00+00:00",
"not_valid_after": "2019-07-08T09:59:59+00:00",
"domain_names": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
"status": null,
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
},
"action": null
}Gets a specific Certificate object.
GET /certificates/{id}ID of the Certificate.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/certificates/$ID"Content-Type: application/json
Status: 200{
"certificate": {
"id": 897,
"name": "my website cert",
"labels": {
"key": "value"
},
"type": "uploaded",
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00+00:00",
"not_valid_before": "2019-01-08T10:00:00+00:00",
"not_valid_after": "2019-07-08T09:59:59+00:00",
"domain_names": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
"status": null,
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}Updates the Certificate properties.
Note: if the Certificate object changes during the request, the response will be a “conflict” error.
PUT /certificates/{id}ID of the Certificate.
New Certificate name.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my website cert","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/certificates/$ID"{
"name": "my website cert",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"certificate": {
"id": 897,
"name": "my website cert",
"labels": {
"key": "value"
},
"type": "uploaded",
"certificate": "-----BEGIN CERTIFICATE-----\n...",
"created": "2019-01-08T12:10:00+00:00",
"not_valid_before": "2019-01-08T10:00:00+00:00",
"not_valid_after": "2019-07-08T09:59:59+00:00",
"domain_names": [
"example.com",
"webmail.example.com",
"www.example.com"
],
"fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
"status": null,
"used_by": [
{
"id": 4711,
"type": "load_balancer"
}
]
}
}Deletes a Certificate.
DELETE /certificates/{id}ID of the Certificate.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/certificates/$ID"Status: 204Returns 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/certificates/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a specific Action object.
GET /certificates/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/certificates/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/certificates/$ID/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 14,
"command": "issue_certificate",
"status": "success",
"progress": 100,
"started": "2021-01-30T23:55:00+00:00",
"finished": "2021-01-30T23:57:00+00:00",
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/certificates/$ID/actions/retry"Content-Type: application/json
Status: 201{
"action": {
"id": 14,
"command": "issue_certificate",
"status": "success",
"progress": 100,
"started": "2021-01-30T23:55:00+00:00",
"finished": "2021-01-30T23:57:00+00:00",
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/certificates/$ID/actions/$ACTION_ID"Content-Type: application/json
Status: 200{
"action": {
"id": 14,
"command": "issue_certificate",
"status": "success",
"progress": 100,
"started": "2021-01-30T23:55:00+00:00",
"finished": "2021-01-30T23:57:00+00:00",
"resources": [
{
"id": 896,
"type": "certificate"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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 exactly 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/ssh_keys"Content-Type: application/json
Status: 200{
"ssh_keys": [
{
"id": 42,
"name": "my-resource",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"public_key": "ssh-rsa AAAjjk76kgf...Xt",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00"
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}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_keysName of the SSH key.
Public key.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"My ssh key","public_key":"ssh-rsa AAAjjk76kgf...Xt","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/ssh_keys"{
"name": "My ssh key",
"public_key": "ssh-rsa AAAjjk76kgf...Xt",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 201{
"ssh_key": {
"id": 42,
"name": "my-resource",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"public_key": "ssh-rsa AAAjjk76kgf...Xt",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00"
}
}Returns a specific SSH key object.
GET /ssh_keys/{id}ID of the SSH Key.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/ssh_keys/$ID"Content-Type: application/json
Status: 200{
"ssh_key": {
"id": 42,
"name": "my-resource",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"public_key": "ssh-rsa AAAjjk76kgf...Xt",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00"
}
}Updates an SSH key. You can update an SSH key name and an SSH key labels.
PUT /ssh_keys/{id}ID of the SSH Key.
New name Name to set.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"My ssh key","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/ssh_keys/$ID"{
"name": "My ssh key",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"ssh_key": {
"id": 2323,
"name": "My ssh key",
"fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
"public_key": "ssh-rsa AAAjjk76kgf...Xt",
"labels": {
"key": "value"
},
"created": "2016-01-30T23:50:00+00:00"
}
}Deletes an SSH key. It cannot be used anymore.
DELETE /ssh_keys/{id}ID of the SSH Key.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/ssh_keys/$ID"Status: 204Datacenters 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 exactly 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.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/locations"Content-Type: application/json
Status: 200{
"locations": [
{
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a Location.
GET /locations/{id}ID of the Location.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/locations/$ID"Content-Type: application/json
Status: 200{
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
}
}Each Datacenter represents a virtual Datacenter which is made up of possible many physical Datacenters where Servers are hosted.
See the Hetzner Locations Docs for more details about Datacenters.
Returns all Datacenters.
GET /datacentersFilter resources by their name. The response will only contain the resources matching exactly 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.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/datacenters"Content-Type: application/json
Status: 200{
"datacenters": [
{
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
}
],
"recommendation": 1,
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a single Datacenter.
GET /datacenters/{id}ID of the Datacenter.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/datacenters/$ID"Content-Type: application/json
Status: 200{
"datacenter": {
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
}
}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 exactly 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/firewalls"Content-Type: application/json
Status: 200{
"firewalls": [
{
"id": 42,
"name": "new-name",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"rules": [
{
"description": null,
"direction": "in",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"destination_ips": [],
"protocol": "tcp",
"port": "80"
}
],
"applied_to": [
{
"type": "server",
"server": {
"id": 42
},
"label_selector": {
"selector": "env=prod"
},
"applied_to_resources": [
{
"type": "server",
"server": {
"id": 42
}
}
]
}
]
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}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 /firewallsUser-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.
Resources to apply the Firewall to.
Resources added directly are taking precedence over those added via a Label Selector.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Corporate Intranet Protection","labels":{"key":"value"},"rules":[{"description":"Allow port 80","direction":"in","source_ips":["28.239.13.1/32","28.239.14.0/24","ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"],"protocol":"tcp","port":"80"}],"apply_to":[{"type":"server","server":{"id":42}}]}' \
"https://api.hetzner.cloud/v1/firewalls"{
"name": "Corporate Intranet Protection",
"labels": {
"key": "value"
},
"rules": [
{
"description": "Allow port 80",
"direction": "in",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"protocol": "tcp",
"port": "80"
}
],
"apply_to": [
{
"type": "server",
"server": {
"id": 42
}
}
]
}Content-Type: application/json
Status: 201{
"firewall": {
"id": 42,
"name": "new-name",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"rules": [
{
"description": null,
"direction": "in",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"destination_ips": [],
"protocol": "tcp",
"port": "80"
}
],
"applied_to": [
{
"type": "server",
"server": {
"id": 42
},
"label_selector": {
"selector": "env=prod"
},
"applied_to_resources": [
{
"type": "server",
"server": {
"id": 42
}
}
]
}
]
},
"actions": [
{
"id": 13,
"command": "set_firewall_rules",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
},
{
"id": 14,
"command": "apply_firewall",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
]
}Returns a single Firewall.
GET /firewalls/{id}ID of the Firewall.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/firewalls/$ID"Content-Type: application/json
Status: 200{
"firewall": {
"id": 42,
"name": "new-name",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"rules": [
{
"description": null,
"direction": "in",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"destination_ips": [],
"protocol": "tcp",
"port": "80"
}
],
"applied_to": [
{
"type": "server",
"server": {
"id": 42
},
"label_selector": {
"selector": "env=prod"
},
"applied_to_resources": [
{
"type": "server",
"server": {
"id": 42
}
}
]
}
]
}
}Update a Firewall.
In case of a parallel running change on the Firewall a conflict error will be returned.
PUT /firewalls/{id}ID of the Firewall.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"new-name","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/firewalls/$ID"{
"name": "new-name",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"firewall": {
"id": 42,
"name": "new-name",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"rules": [
{
"description": null,
"direction": "in",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"destination_ips": [],
"protocol": "tcp",
"port": "80"
}
],
"applied_to": [
{
"type": "server",
"server": {
"id": 42
},
"label_selector": {
"selector": "env=prod"
},
"applied_to_resources": [
{
"type": "server",
"server": {
"id": 42
}
}
]
}
]
}
}Deletes the Firewall.
| Code | Description |
|---|---|
resource_in_use |
Firewall still applied to a resource |
DELETE /firewalls/{id}ID of the Firewall.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/firewalls/$ID"Status: 204GET /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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/firewalls/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns the specific Action.
GET /firewalls/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/firewalls/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/firewalls/$ID/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 13,
"command": "set_firewall_rules",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"apply_to":[{"type":"server","server":{"id":42}}]}' \
"https://api.hetzner.cloud/v1/firewalls/$ID/actions/apply_to_resources"{
"apply_to": [
{
"type": "server",
"server": {
"id": 42
}
}
]
}Content-Type: application/json
Status: 201{
"actions": [
{
"id": 14,
"command": "apply_firewall",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
]
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"remove_from":[{"type":"server","server":{"id":42}}]}' \
"https://api.hetzner.cloud/v1/firewalls/$ID/actions/remove_from_resources"{
"remove_from": [
{
"type": "server",
"server": {
"id": 42
}
}
]
}Content-Type: application/json
Status: 201{
"actions": [
{
"id": 14,
"command": "remove_firewall",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 38,
"type": "firewall"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
]
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"rules":[{"description":"Allow port 80","direction":"in","source_ips":["28.239.13.1/32","28.239.14.0/24","ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"],"protocol":"tcp","port":"80"}]}' \
"https://api.hetzner.cloud/v1/firewalls/$ID/actions/set_rules"{
"rules": [
{
"description": "Allow port 80",
"direction": "in",
"source_ips": [
"28.239.13.1/32",
"28.239.14.0/24",
"ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
],
"protocol": "tcp",
"port": "80"
}
]
}Content-Type: application/json
Status: 201{
"actions": [
{
"id": 13,
"command": "set_firewall_rules",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
},
{
"id": 14,
"command": "apply_firewall",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 38,
"type": "firewall"
},
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
]
}GET /firewalls/{id}/actions/{action_id}ID of the Firewall.
ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/firewalls/$ID/actions/$ACTION_ID"Content-Type: application/json
Status: 200{
"action": {
"id": 13,
"command": "set_firewall_rules",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 38,
"type": "firewall"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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 exactly 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/floating_ips"Content-Type: application/json
Status: 200{
"floating_ips": [
{
"id": 42,
"name": "my-resource",
"description": "This describes my resource",
"ip": "2001:db8::/64",
"type": "ipv6",
"server": 42,
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
],
"home_location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"blocked": false,
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00"
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}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.
ipv4 ipv6The Floating IP type.
Server the Floating IP is assigned to.
null if not assigned.
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.
Description of the Resource.
Name of the Resource. Must be unique per Project.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"ipv6","server":42,"home_location":"fsn1","description":"This describes my resource","name":"my-resource","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/floating_ips"{
"type": "ipv6",
"server": 42,
"home_location": "fsn1",
"description": "This describes my resource",
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 201{
"floating_ip": {
"id": 4711,
"name": "Web Frontend",
"description": "Web Frontend",
"ip": "2001:db8::/64",
"type": "ipv6",
"server": 42,
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
],
"home_location": {
"id": 1,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"blocked": false,
"protection": {
"delete": false
},
"labels": {
"key": "value"
},
"created": "2016-01-30T23:50:00+00:00"
},
"action": {
"id": 13,
"command": "create_floating_ip",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Returns a single Floating IP.
GET /floating_ips/{id}ID of the Floating IP.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/floating_ips/$ID"Content-Type: application/json
Status: 200{
"floating_ip": {
"id": 42,
"name": "my-resource",
"description": "This describes my resource",
"ip": "2001:db8::/64",
"type": "ipv6",
"server": 42,
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
],
"home_location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"blocked": false,
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00"
}
}Update a Floating IP.
PUT /floating_ips/{id}ID of the Floating IP.
Description of the Resource.
Name of the Resource. Must be unique per Project.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"This describes my resource","name":"my-resource","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/floating_ips/$ID"{
"description": "This describes my resource",
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"floating_ip": {
"id": 4711,
"name": "Web Frontend",
"description": "Web Frontend",
"ip": "2001:db8::/64",
"type": "ipv6",
"server": 42,
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
],
"home_location": {
"id": 1,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"blocked": false,
"protection": {
"delete": false
},
"labels": {
"key": "value"
},
"created": "2016-01-30T23:50:00+00:00"
}
}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.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/floating_ips/$ID"Status: 204Lists 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/floating_ips/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a single Action.
GET /floating_ips/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/floating_ips/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/floating_ips/$ID/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 13,
"command": "assign_floating_ip",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "server"
},
{
"id": 4712,
"type": "floating_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"server":42}' \
"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/assign"{
"server": 42
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "assign_floating_ip",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
Single IPv4 or IPv6 address to create pointer for.
Domain Name to point to.
PTR record content used for reverse DNS.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip":"2001:db8::1","dns_ptr":"server.example.com"}' \
"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/change_dns_ptr"{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_dns_ptr",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "floating_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"delete":false}' \
"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/change_protection"{
"delete": false
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "floating_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/unassign"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "unassign_floating_ip",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Returns a specific Action for a Floating IP.
GET /floating_ips/{id}/actions/{action_id}ID of the Floating IP.
ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/$ACTION_ID"Content-Type: application/json
Status: 200{
"action": {
"id": 13,
"command": "assign_floating_ip",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "floating_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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 exactly 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".
running initializing starting stopping off deleting migrating rebuilding unknownFilter resources by status. Can be used multiple times. The response will only contain the resources with the specified status.
25Maximum number of entries returned per page. For more information, see "Pagination".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers"Content-Type: application/json
Status: 200{
"servers": [
{
"id": 42,
"name": "my-resource",
"status": "running",
"created": "2016-01-30T23:55:00+00:00",
"public_net": {
"ipv4": {
"id": 42,
"ip": "1.2.3.4",
"blocked": false,
"dns_ptr": "server01.example.com"
},
"ipv6": {
"id": 42,
"ip": "2001:db8::/64",
"blocked": false,
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
]
},
"floating_ips": [
478
],
"firewalls": [
{
"id": 42,
"status": "applied"
}
]
},
"private_net": [
{
"network": 4711,
"ip": "10.0.0.2",
"alias_ips": [
"10.0.0.3",
"10.0.0.4"
],
"mac_address": "86:00:ff:2a:7d:e1"
}
],
"server_type": {
"id": 1,
"name": "cpx11",
"description": "CPX11",
"cores": 2,
"memory": 2,
"disk": 40,
"deprecated": false,
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
],
"storage_type": "local",
"cpu_type": "shared",
"architecture": "x86",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
}
},
"datacenter": {
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
},
"image": {
"id": 42,
"type": "snapshot",
"status": "available",
"name": "ubuntu-20.04",
"description": "Ubuntu 20.04 Standard 64 bit",
"image_size": 2.3,
"disk_size": 10,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"bound_to": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"rapid_deploy": false,
"protection": {
"delete": false
},
"deprecated": "2018-02-28T00:00:00+00:00",
"deleted": null,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"architecture": "x86"
},
"iso": {
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"description": "FreeBSD 11.0 x64",
"type": "public",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
},
"architecture": "x86"
},
"rescue_enabled": false,
"locked": false,
"backup_window": "22-02",
"outgoing_traffic": 123456,
"ingoing_traffic": 123456,
"included_traffic": 654321,
"protection": {
"delete": false,
"rebuild": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"volumes": [
0
],
"load_balancers": [
0
],
"primary_disk_size": 50,
"placement_group": {
"id": 42,
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"type": "spread",
"created": "2016-01-30T23:55:00+00:00",
"servers": [
42
]
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}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 |
Name of the Server to create (must be unique per Project and a valid hostname as per RFC 1123).
ID or name of Location to create Server in (must not be used together with datacenter).
ID or name of Datacenter to create Server in (must not be used together with location).
ID or name of the Server type this Server should be created with.
trueThis automatically triggers a Power on a Server-Server Action after the creation is finished and is returned in the next_actions response object.
ID or name of the Image the Server is created from.
ID of the Placement Group the Server should be in.
SSH key IDs (integer) or names (string) which should be injected into the Server at creation time.
Volume IDs which should be attached to the Server at the creation time. Volumes must be in the same Location.
Network IDs which should be attached to the Server private network interface at the creation time.
Firewalls which should be applied on the Server's public network interface at creation time.
Cloud-Init user data to use during Server creation. This field is limited to 32KiB.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Auto-mount Volumes after attach.
Public Network options.
Root password when no SSH keys have been specified.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my-server","location":"nbg1","datacenter":"nbg1-dc3","server_type":"cpx11","start_after_create":true,"image":"ubuntu-20.04","placement_group":1,"ssh_keys":["my-ssh-key"],"volumes":[123],"networks":[456],"firewalls":[{"firewall":38}],"user_data":"#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"automount":false,"public_net":{"enable_ipv4":false,"enable_ipv6":false,"ipv4":null,"ipv6":null}}' \
"https://api.hetzner.cloud/v1/servers"{
"name": "my-server",
"location": "nbg1",
"datacenter": "nbg1-dc3",
"server_type": "cpx11",
"start_after_create": true,
"image": "ubuntu-20.04",
"placement_group": 1,
"ssh_keys": [
"my-ssh-key"
],
"volumes": [
123
],
"networks": [
456
],
"firewalls": [
{
"firewall": 38
}
],
"user_data": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"automount": false,
"public_net": {
"enable_ipv4": false,
"enable_ipv6": false,
"ipv4": null,
"ipv6": null
}
}Content-Type: application/json
Status: 201{
"server": {
"id": 42,
"name": "my-server",
"status": "initializing",
"created": "2016-01-30T23:50:00+00:00",
"public_net": {
"ipv4": {
"ip": "1.2.3.4",
"blocked": false,
"dns_ptr": "server01.example.com"
},
"ipv6": {
"ip": "2001:db8::/64",
"blocked": false,
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
]
},
"floating_ips": [
478
],
"firewalls": [
{
"id": 38,
"status": "applied"
}
]
},
"private_net": [
{
"network": 4711,
"ip": "10.0.0.2",
"alias_ips": [],
"mac_address": "86:00:ff:2a:7d:e1"
}
],
"server_type": {
"id": 1,
"name": "cpx11",
"description": "CPX11",
"cores": 2,
"memory": 2,
"disk": 40,
"deprecated": true,
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
},
"price_monthly": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
},
"included_traffic": 21990232555520,
"price_per_tb_traffic": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
}
}
],
"storage_type": "local",
"cpu_type": "shared",
"architecture": "x86"
},
"datacenter": {
"id": 1,
"name": "fsn1-dc8",
"description": "Falkenstein 1 DC 8",
"location": {
"id": 1,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
},
"image": {
"id": 4711,
"type": "snapshot",
"status": "available",
"name": "ubuntu-20.04",
"description": "Ubuntu 20.04 Standard 64 bit",
"image_size": 2.3,
"disk_size": 10,
"created": "2016-01-30T23:50:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"bound_to": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"rapid_deploy": false,
"protection": {
"delete": false
},
"deprecated": "2018-02-28T00:00:00+00:00",
"deleted": null,
"labels": {
"key": "value"
},
"architecture": "x86"
},
"iso": {
"id": 4711,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"description": "FreeBSD 11.0 x64",
"type": "public",
"deprecation": {
"announced": "2018-02-28T00:00:00+00:00",
"unavailable_after": "2018-05-31T00:00:00+00:00"
},
"architecture": "x86"
},
"rescue_enabled": false,
"locked": false,
"backup_window": "22-02",
"outgoing_traffic": 123456,
"ingoing_traffic": 123456,
"included_traffic": 654321,
"protection": {
"delete": false,
"rebuild": false
},
"labels": {
"key": "value"
},
"volumes": [],
"load_balancers": [],
"primary_disk_size": 50
},
"action": {
"id": 1,
"command": "create_server",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
},
"next_actions": [
{
"id": 13,
"command": "start_server",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"root_password": "YItygq1v3GYjjMomLaKc"
}Returns a specific Server object. The Server must exist inside the Project.
GET /servers/{id}ID of the Server.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID"Content-Type: application/json
Status: 200{
"server": {
"id": 42,
"name": "my-resource",
"status": "running",
"created": "2016-01-30T23:55:00+00:00",
"public_net": {
"ipv4": {
"id": 42,
"ip": "1.2.3.4",
"blocked": false,
"dns_ptr": "server01.example.com"
},
"ipv6": {
"id": 42,
"ip": "2001:db8::/64",
"blocked": false,
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
]
},
"floating_ips": [
478
],
"firewalls": [
{
"id": 42,
"status": "applied"
}
]
},
"private_net": [
{
"network": 4711,
"ip": "10.0.0.2",
"alias_ips": [
"10.0.0.3",
"10.0.0.4"
],
"mac_address": "86:00:ff:2a:7d:e1"
}
],
"server_type": {
"id": 1,
"name": "cpx11",
"description": "CPX11",
"cores": 2,
"memory": 2,
"disk": 40,
"deprecated": false,
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
],
"storage_type": "local",
"cpu_type": "shared",
"architecture": "x86",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
}
},
"datacenter": {
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
},
"image": {
"id": 42,
"type": "snapshot",
"status": "available",
"name": "ubuntu-20.04",
"description": "Ubuntu 20.04 Standard 64 bit",
"image_size": 2.3,
"disk_size": 10,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"bound_to": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"rapid_deploy": false,
"protection": {
"delete": false
},
"deprecated": "2018-02-28T00:00:00+00:00",
"deleted": null,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"architecture": "x86"
},
"iso": {
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"description": "FreeBSD 11.0 x64",
"type": "public",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
},
"architecture": "x86"
},
"rescue_enabled": false,
"locked": false,
"backup_window": "22-02",
"outgoing_traffic": 123456,
"ingoing_traffic": 123456,
"included_traffic": 654321,
"protection": {
"delete": false,
"rebuild": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"volumes": [
0
],
"load_balancers": [
0
],
"primary_disk_size": 50,
"placement_group": {
"id": 42,
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"type": "spread",
"created": "2016-01-30T23:55:00+00:00",
"servers": [
42
]
}
}
}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).
PUT /servers/{id}ID of the Server.
New name to set.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my-server","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/servers/$ID"{
"name": "my-server",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"server": {
"id": 42,
"name": "my-resource",
"status": "running",
"created": "2016-01-30T23:55:00+00:00",
"public_net": {
"ipv4": {
"id": 42,
"ip": "1.2.3.4",
"blocked": false,
"dns_ptr": "server01.example.com"
},
"ipv6": {
"id": 42,
"ip": "2001:db8::/64",
"blocked": false,
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
]
},
"floating_ips": [
478
],
"firewalls": [
{
"id": 42,
"status": "applied"
}
]
},
"private_net": [
{
"network": 4711,
"ip": "10.0.0.2",
"alias_ips": [
"10.0.0.3",
"10.0.0.4"
],
"mac_address": "86:00:ff:2a:7d:e1"
}
],
"server_type": {
"id": 1,
"name": "cpx11",
"description": "CPX11",
"cores": 2,
"memory": 2,
"disk": 40,
"deprecated": false,
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
],
"storage_type": "local",
"cpu_type": "shared",
"architecture": "x86",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
}
},
"datacenter": {
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
},
"image": {
"id": 42,
"type": "snapshot",
"status": "available",
"name": "ubuntu-20.04",
"description": "Ubuntu 20.04 Standard 64 bit",
"image_size": 2.3,
"disk_size": 10,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"bound_to": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"rapid_deploy": false,
"protection": {
"delete": false
},
"deprecated": "2018-02-28T00:00:00+00:00",
"deleted": null,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"architecture": "x86"
},
"iso": {
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"description": "FreeBSD 11.0 x64",
"type": "public",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
},
"architecture": "x86"
},
"rescue_enabled": false,
"locked": false,
"backup_window": "22-02",
"outgoing_traffic": 123456,
"ingoing_traffic": 123456,
"included_traffic": 654321,
"protection": {
"delete": false,
"rebuild": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"volumes": [
0
],
"load_balancers": [
0
],
"primary_disk_size": 50,
"placement_group": {
"id": 42,
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"type": "spread",
"created": "2016-01-30T23:55:00+00:00",
"servers": [
42
]
}
}
}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.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/metrics?type=$TYPE&start=$START&end=$END"Content-Type: application/json
Status: 200{
"metrics": {
"start": "2017-01-01T00:00:00+00:00",
"end": "2017-01-01T23:00:00+00:00",
"step": 60,
"time_series": {
"name_of_timeseries": {
"values": [
[
1435781470.622,
"42"
],
[
1435781471.622,
"43"
]
]
}
}
}
}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 server 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 app snapshot backupFilter resources by type. Can be used multiple times. The response will only contain the resources with the specified type.
available creating unavailableFilter resources by status. Can be used multiple times. The response will only contain the resources with the specified 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 exactly the specified name.
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
x86 armFilter resources by cpu architecture. The response will only contain the resources with the specified cpu architecture.
25Maximum number of entries returned per page. For more information, see "Pagination".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/images"Content-Type: application/json
Status: 200{
"images": [
{
"id": 42,
"type": "snapshot",
"status": "available",
"name": "ubuntu-20.04",
"description": "Ubuntu 20.04 Standard 64 bit",
"image_size": 2.3,
"disk_size": 10,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"bound_to": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"rapid_deploy": false,
"protection": {
"delete": false
},
"deprecated": "2018-02-28T00:00:00+00:00",
"deleted": null,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"architecture": "x86"
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a specific Image object.
GET /images/{id}ID of the Image.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/images/$ID"Content-Type: application/json
Status: 200{
"image": {
"id": 42,
"type": "snapshot",
"status": "available",
"name": "ubuntu-20.04",
"description": "Ubuntu 20.04 Standard 64 bit",
"image_size": 2.3,
"disk_size": 10,
"created": "2016-01-30T23:55:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"bound_to": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"rapid_deploy": false,
"protection": {
"delete": false
},
"deprecated": "2018-02-28T00:00:00+00:00",
"deleted": null,
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"architecture": "x86"
}
}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.
PUT /images/{id}ID of the Image.
New description of Image.
snapshotDestination Image type to convert to.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"My new Image description","type":"snapshot","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/images/$ID"{
"description": "My new Image description",
"type": "snapshot",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"image": {
"id": 4711,
"type": "snapshot",
"status": "available",
"name": null,
"description": "My new Image description",
"image_size": 2.3,
"disk_size": 10,
"created": "2016-01-30T23:50:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"bound_to": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"rapid_deploy": false,
"protection": {
"delete": false
},
"deprecated": "2018-02-28T00:00:00+00:00",
"deleted": null,
"labels": {
"key": "value"
},
"architecture": "x86"
}
}Deletes an Image. Only Images of type snapshot and backup can be deleted.
DELETE /images/{id}ID of the Image.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/images/$ID"Status: 204Returns 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/images/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a specific Action object.
GET /images/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/images/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/images/$ID/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "image"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"delete":true}' \
"https://api.hetzner.cloud/v1/images/$ID/actions/change_protection"{
"delete": true
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "image"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Returns a specific Action for an Image.
GET /images/{id}/actions/{action_id}ID of the Image.
ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/images/$ID/actions/$ACTION_ID"Content-Type: application/json
Status: 200{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "image"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}ISOs 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 exactly the specified name.
x86 armFilter resources by cpu architecture. The response will only contain the resources with the specified cpu 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/isos"Content-Type: application/json
Status: 200{
"isos": [
{
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"description": "FreeBSD 11.0 x64",
"type": "public",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
},
"architecture": "x86"
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a specific ISO object.
GET /isos/{id}ID of the ISO.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/isos/$ID"Content-Type: application/json
Status: 200{
"iso": {
"id": 42,
"name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
"description": "FreeBSD 11.0 x64",
"type": "public",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
},
"architecture": "x86"
}
}Placement groups are used to influence the location of interdependent virtual servers in our data centers. The distribution of the different servers within a group is based on a pattern specified in the type. By enforcing certain rules on the placement of servers 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 servers might fail together.
Returns all Placement Group 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 exactly the specified name.
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
spreadFilter resources by type. Can be used multiple times. The response will only contain the resources with the specified type.
25Maximum number of entries returned per page. For more information, see "Pagination".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/placement_groups"Content-Type: application/json
Status: 200{
"placement_groups": [
{
"id": 897,
"name": "my Placement Group",
"labels": {
"key": "value"
},
"type": "spread",
"created": "2019-01-08T12:10:00+00:00",
"servers": [
4711,
4712
]
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}Creates a new Placement Group.
POST /placement_groupsName of the Placement Group.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
spreadDefine the Placement Group Type.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my Placement Group","type":"spread"}' \
"https://api.hetzner.cloud/v1/placement_groups"{
"name": "my Placement Group",
"type": "spread"
}Content-Type: application/json
Status: 201{
"placement_group": {
"id": 897,
"name": "my Placement Group",
"labels": {
"key": "value"
},
"type": "spread",
"created": "2019-01-08T12:10:00+00:00",
"servers": []
}
}Gets a specific Placement Group object.
GET /placement_groups/{id}ID of the Placement Group.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/placement_groups/$ID"Content-Type: application/json
Status: 200{
"placement_group": {
"id": 897,
"name": "my Placement Group",
"labels": {
"key": "value"
},
"type": "spread",
"created": "2019-01-08T12:10:00+00:00",
"servers": [
4711,
4712
]
}
}Updates the Placement Group properties.
Note: if the Placement Group object changes during the request, the response will be a “conflict” error.
PUT /placement_groups/{id}ID of the Placement Group.
New Placement Group name.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my Placement Group","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/placement_groups/$ID"{
"name": "my Placement Group",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"placement_group": {
"id": 897,
"name": "my Placement Group",
"labels": {
"key": "value"
},
"type": "spread",
"created": "2019-01-08T12:10:00+00:00",
"servers": [
4711,
4712
]
}
}Deletes a Placement Group.
DELETE /placement_groups/{id}ID of the Placement Group.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/placement_groups/$ID"Status: 204Primary 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 exactly 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/primary_ips"Content-Type: application/json
Status: 200{
"primary_ips": [
{
"id": 42,
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"blocked": false,
"datacenter": {
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
},
"ip": "2001:db8::/64",
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
],
"protection": {
"delete": false
},
"type": "ipv6",
"auto_delete": true,
"assignee_type": "server",
"assignee_id": 17
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}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.
Name of the Resource. Must be unique per Project.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Datacenter ID or name.
The Primary IP will be bound to this Datacenter. Omit if assignee_id/assignee_type is provided.
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.
ID of resource to assign the Primary IP to.
Omitted if the Primary IP should not get assigned.
falseAuto deletion state.
If enabled the Primary IP will be deleted once the assigned resource gets deleted.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my-resource","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"type":"ipv6","datacenter":"fsn1-dc8","assignee_type":"server","assignee_id":17,"auto_delete":false}' \
"https://api.hetzner.cloud/v1/primary_ips"{
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"type": "ipv6",
"datacenter": "fsn1-dc8",
"assignee_type": "server",
"assignee_id": 17,
"auto_delete": false
}Content-Type: application/json
Status: 201{
"primary_ip": {
"id": 42,
"name": "my-ip",
"labels": {
"key": "value"
},
"created": "2016-01-30T23:50:00+00:00",
"blocked": false,
"datacenter": {
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 1,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
},
"ip": "2001:db8::/64",
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
],
"protection": {
"delete": false
},
"type": "ipv6",
"auto_delete": true,
"assignee_type": "server",
"assignee_id": 17
},
"action": {
"id": 13,
"command": "create_primary_ip",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 17,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Returns a Primary IP.
GET /primary_ips/{id}ID of the Primary IP.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/primary_ips/$ID"Content-Type: application/json
Status: 200{
"primary_ip": {
"id": 42,
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"blocked": false,
"datacenter": {
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
},
"ip": "2001:db8::/64",
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
],
"protection": {
"delete": false
},
"type": "ipv6",
"auto_delete": true,
"assignee_type": "server",
"assignee_id": 17
}
}Update a Primary IP.
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.
Name of the Resource. Must be unique per Project.
falseAuto deletion state.
If enabled the Primary IP will be deleted once the assigned resource gets deleted.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"my-resource","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"auto_delete":true}' \
"https://api.hetzner.cloud/v1/primary_ips/$ID"{
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"auto_delete": true
}Content-Type: application/json
Status: 200{
"primary_ip": {
"id": 42,
"name": "my-resource",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"blocked": false,
"datacenter": {
"id": 42,
"name": "fsn1-dc8",
"description": "Falkenstein DC Park 8",
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"server_types": {
"supported": [
1,
2,
3
],
"available": [
1,
2,
3
],
"available_for_migration": [
1,
2,
3
]
}
},
"ip": "2001:db8::/64",
"dns_ptr": [
{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}
],
"protection": {
"delete": false
},
"type": "ipv6",
"auto_delete": true,
"assignee_type": "server",
"assignee_id": 17
}
}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.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/primary_ips/$ID"Status: 204Lists 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/primary_ips/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a single Action.
GET /primary_ips/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/primary_ips/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
serverType of resource assigning the Primary IP to.
ID of a resource of type assignee_type.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"assignee_type":"server","assignee_id":4711}' \
"https://api.hetzner.cloud/v1/primary_ips/$ID/actions/assign"{
"assignee_type": "server",
"assignee_id": 4711
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "assign_primary_ip",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "primary_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
Single IPv4 or IPv6 address to create pointer for.
Domain Name to point to.
PTR record content used for reverse DNS.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip":"2001:db8::1","dns_ptr":"server.example.com"}' \
"https://api.hetzner.cloud/v1/primary_ips/$ID/actions/change_dns_ptr"{
"ip": "2001:db8::1",
"dns_ptr": "server.example.com"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_dns_ptr",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "primary_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"delete":false}' \
"https://api.hetzner.cloud/v1/primary_ips/$ID/actions/change_protection"{
"delete": false
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "primary_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/primary_ips/$ID/actions/unassign"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "unassign_primary_ip",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "primary_ip"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a specific Action object.
GET /servers/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 13,
"command": "start_server",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"placement_group":1}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/add_to_placement_group"{
"placement_group": 1
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "add_to_placement_group",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"iso":"FreeBSD-11.0-RELEASE-amd64-dvd1"}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/attach_iso"{
"iso": "FreeBSD-11.0-RELEASE-amd64-dvd1"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "attach_iso",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
ID of an existing network to attach the Server to.
IP to request to be assigned to this Server; if you do not provide this then you will be auto assigned an IP address.
Additional IPs to be assigned to this Server.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"network":4711,"ip":"10.0.1.1","alias_ips":["10.0.1.2"]}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/attach_to_network"{
"network": 4711,
"ip": "10.0.1.1",
"alias_ips": [
"10.0.1.2"
]
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "attach_to_network",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
ID of an existing Network already attached to the Server.
New alias IPs to set for this Server.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"network":4711,"alias_ips":["10.0.1.2"]}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/change_alias_ips"{
"network": 4711,
"alias_ips": [
"10.0.1.2"
]
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_alias_ips",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
Primary IP address for which the reverse DNS entry should be set.
Hostname to set as a reverse DNS PTR entry, reset to original value if null.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip":"1.2.3.4","dns_ptr":"server01.example.com"}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/change_dns_ptr"{
"ip": "1.2.3.4",
"dns_ptr": "server01.example.com"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_dns_ptr",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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).
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"delete":true,"rebuild":true}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/change_protection"{
"delete": true,
"rebuild": true
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
If false, do not upgrade the disk (this allows downgrading the Server type later).
ID or name of Server type the Server should migrate to.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"upgrade_disk":true,"server_type":"cpx11"}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/change_type"{
"upgrade_disk": true,
"server_type": "cpx11"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_server_type",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
snapshot backupDefault: snapshotType of Image to create.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"description":"my image","type":"snapshot","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/create_image"{
"description": "my image",
"type": "snapshot",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 201{
"image": {
"id": 4711,
"type": "snapshot",
"status": "creating",
"name": null,
"description": "my image",
"image_size": 2.3,
"disk_size": 10,
"created": "2016-01-30T23:50:00+00:00",
"created_from": {
"id": 1,
"name": "Server"
},
"bound_to": null,
"os_flavor": "ubuntu",
"os_version": "20.04",
"rapid_deploy": false,
"protection": {
"delete": false
},
"deprecated": "2018-02-28T00:00:00+00:00",
"deleted": null,
"labels": {
"key": "value"
},
"architecture": "x86"
},
"action": {
"id": 13,
"command": "create_image",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"network":4711}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/detach_from_network"{
"network": 4711
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "detach_from_network",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/detach_iso"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "detach_iso",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/disable_backup"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "disable_backup",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/disable_rescue"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "disable_rescue",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/enable_backup"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "enable_backup",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
linux64Default: linux64Type of rescue system to boot.
Array of SSH key IDs which should be injected into the rescue system.
Password that will be set for this Server once the Action succeeds.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"linux64","ssh_keys":[2323]}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/enable_rescue"{
"type": "linux64",
"ssh_keys": [
2323
]
}Content-Type: application/json
Status: 201{
"root_password": "zCWbFhnu950dUTko5f40",
"action": {
"id": 13,
"command": "enable_rescue",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/poweroff"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "stop_server",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Starts a Server by turning its power on.
POST /servers/{id}/actions/poweronID of the Server.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/poweron"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "start_server",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/reboot"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "reboot_server",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"image":"ubuntu-20.04"}' \
"https://api.hetzner.cloud/v1/servers/$ID/actions/rebuild"{
"image": "ubuntu-20.04"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "rebuild_server",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
},
"root_password": null
}Removes a Server from a Placement Group.
POST /servers/{id}/actions/remove_from_placement_groupID of the Server.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/remove_from_placement_group"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "remove_from_placement_group",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
URL of websocket proxy to use; this includes a token which is valid for a limited time only.
VNC password to use for this connection (this password only works in combination with a wss_url with valid token).
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/request_console"Content-Type: application/json
Status: 201{
"wss_url": "wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c",
"password": "9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x",
"action": {
"id": 13,
"command": "request_console",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/reset"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "reset_server",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/reset_password"Content-Type: application/json
Status: 201{
"root_password": "zCWbFhnu950dUTko5f40",
"action": {
"id": 13,
"command": "reset_password",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/shutdown"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "shutdown_server",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Returns a specific Action object for a Server.
GET /servers/{id}/actions/{action_id}ID of the Server.
ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/servers/$ID/actions/$ACTION_ID"Content-Type: application/json
Status: 200{
"action": {
"id": 13,
"command": "start_server",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
All prices are displayed in the currency of the project owner's account.
Gets all Server type objects.
GET /server_typesFilter resources by their name. The response will only contain the resources matching exactly the specified name.
25Maximum number of entries returned per page. For more information, see "Pagination".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/server_types"Content-Type: application/json
Status: 200{
"server_types": [
{
"id": 1,
"name": "cpx11",
"description": "CPX11",
"cores": 2,
"memory": 2,
"disk": 40,
"deprecated": false,
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
],
"storage_type": "local",
"cpu_type": "shared",
"architecture": "x86",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Gets a specific Server type object.
GET /server_types/{id}ID of the Server Type.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/server_types/$ID"Content-Type: application/json
Status: 200{
"server_type": {
"id": 1,
"name": "cpx11",
"description": "CPX11",
"cores": 2,
"memory": 2,
"disk": 40,
"deprecated": false,
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
],
"storage_type": "local",
"cpu_type": "shared",
"architecture": "x86",
"deprecation": {
"unavailable_after": "2023-09-01T00:00:00+00:00",
"announced": "2023-06-01T00:00:00+00:00"
}
}
}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 exactly 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers"Content-Type: application/json
Status: 200{
"load_balancers": [
{
"id": 42,
"name": "my-resource",
"public_net": {
"enabled": false,
"ipv4": {
"ip": "1.2.3.4",
"dns_ptr": "lb1.example.com"
},
"ipv6": {
"ip": "2001:db8::1",
"dns_ptr": "lb1.example.com"
}
},
"private_net": [
{
"network": 4711,
"ip": "10.0.0.2"
}
],
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"load_balancer_type": {
"id": 1,
"name": "lb11",
"description": "LB11",
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"max_assigned_certificates": 10,
"deprecated": "2016-01-30T23:50:00+00:00",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
]
},
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"services": [
{
"protocol": "https",
"listen_port": 443,
"destination_port": 80,
"proxyprotocol": false,
"health_check": {
"protocol": "http",
"port": 4711,
"interval": 15,
"timeout": 10,
"retries": 3,
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
}
},
"http": {
"cookie_name": "HCLBSTICKY",
"cookie_lifetime": 300,
"certificates": [
897
],
"redirect_http": true,
"sticky_sessions": true
}
}
],
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"label_selector": {
"selector": "env=prod"
},
"ip": {
"ip": "203.0.113.1"
},
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"use_private_ip": false,
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"use_private_ip": false
}
]
}
],
"algorithm": {
"type": "round_robin"
},
"outgoing_traffic": null,
"ingoing_traffic": null,
"included_traffic": 10000
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}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_balancersName of the Load Balancer.
ID or name of the Load Balancer type this Load Balancer should be created with.
Algorithm of the Load Balancer.
Array of services.
Array of targets.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Enable or disable the public interface of the Load Balancer.
ID of the network the Load Balancer should be attached to on creation.
Name of network zone.
ID or name of Location to create Load Balancer in.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Web Frontend","load_balancer_type":"lb11","algorithm":{"type":"round_robin"},"services":[{"protocol":"https","listen_port":443,"destination_port":80,"proxyprotocol":false,"health_check":{"protocol":"http","port":4711,"interval":15,"timeout":10,"retries":3,"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false}},"http":{"cookie_name":"HCLBSTICKY","cookie_lifetime":300,"certificates":[897],"redirect_http":true,"sticky_sessions":true}}],"targets":[{"type":"server","server":{"id":80},"use_private_ip":true,"label_selector":{"selector":"env=prod"},"ip":{"ip":"203.0.113.1"}}],"labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"public_interface":true,"network":123,"network_zone":"eu-central","location":"fsn1"}' \
"https://api.hetzner.cloud/v1/load_balancers"{
"name": "Web Frontend",
"load_balancer_type": "lb11",
"algorithm": {
"type": "round_robin"
},
"services": [
{
"protocol": "https",
"listen_port": 443,
"destination_port": 80,
"proxyprotocol": false,
"health_check": {
"protocol": "http",
"port": 4711,
"interval": 15,
"timeout": 10,
"retries": 3,
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
}
},
"http": {
"cookie_name": "HCLBSTICKY",
"cookie_lifetime": 300,
"certificates": [
897
],
"redirect_http": true,
"sticky_sessions": true
}
}
],
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"use_private_ip": true,
"label_selector": {
"selector": "env=prod"
},
"ip": {
"ip": "203.0.113.1"
}
}
],
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"public_interface": true,
"network": 123,
"network_zone": "eu-central",
"location": "fsn1"
}Content-Type: application/json
Status: 201{
"load_balancer": {
"id": 4711,
"name": "Web Frontend",
"public_net": {
"enabled": false,
"ipv4": {
"ip": "1.2.3.4"
},
"ipv6": {
"ip": "2001:db8::1"
}
},
"private_net": [
{
"network": 4711,
"ip": "10.0.0.2"
}
],
"location": {
"id": 1,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"load_balancer_type": {
"id": 1,
"name": "lb11",
"description": "LB11",
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"max_assigned_certificates": 10,
"deprecated": "2016-01-30T23:50:00+00:00",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
},
"price_monthly": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
}
}
]
},
"protection": {
"delete": false
},
"labels": {
"key": "value"
},
"created": "2016-01-30T23:50:00+00:00",
"services": [
{
"protocol": "http",
"listen_port": 443,
"destination_port": 80,
"proxyprotocol": false,
"health_check": {
"protocol": "http",
"port": 4711,
"interval": 15,
"timeout": 10,
"retries": 3,
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??,3??"
],
"tls": false
}
},
"http": {
"cookie_name": "HCLBSTICKY",
"cookie_lifetime": 300,
"certificates": [
897
],
"redirect_http": true,
"sticky_sessions": true
}
}
],
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"use_private_ip": true,
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"use_private_ip": true
}
]
}
],
"algorithm": {
"type": "round_robin"
},
"outgoing_traffic": 123456,
"ingoing_traffic": 123456,
"included_traffic": 654321
},
"action": {
"id": 13,
"command": "create_load_balancer",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Gets a specific Load Balancer object.
GET /load_balancers/{id}ID of the Load Balancer.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/$ID"Content-Type: application/json
Status: 200{
"load_balancer": {
"id": 42,
"name": "my-resource",
"public_net": {
"enabled": false,
"ipv4": {
"ip": "1.2.3.4",
"dns_ptr": "lb1.example.com"
},
"ipv6": {
"ip": "2001:db8::1",
"dns_ptr": "lb1.example.com"
}
},
"private_net": [
{
"network": 4711,
"ip": "10.0.0.2"
}
],
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"load_balancer_type": {
"id": 1,
"name": "lb11",
"description": "LB11",
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"max_assigned_certificates": 10,
"deprecated": "2016-01-30T23:50:00+00:00",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
]
},
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"services": [
{
"protocol": "https",
"listen_port": 443,
"destination_port": 80,
"proxyprotocol": false,
"health_check": {
"protocol": "http",
"port": 4711,
"interval": 15,
"timeout": 10,
"retries": 3,
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
}
},
"http": {
"cookie_name": "HCLBSTICKY",
"cookie_lifetime": 300,
"certificates": [
897
],
"redirect_http": true,
"sticky_sessions": true
}
}
],
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"label_selector": {
"selector": "env=prod"
},
"ip": {
"ip": "203.0.113.1"
},
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"use_private_ip": false,
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"use_private_ip": false
}
]
}
],
"algorithm": {
"type": "round_robin"
},
"outgoing_traffic": null,
"ingoing_traffic": null,
"included_traffic": 10000
}
}Updates a Load Balancer. You can update a Load Balancer’s name and a Load Balancer’s labels.
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.
New Load Balancer name.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"new-name","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID"{
"name": "new-name",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"load_balancer": {
"id": 4711,
"name": "new-name",
"public_net": {
"enabled": false,
"ipv4": {
"ip": "1.2.3.4"
},
"ipv6": {
"ip": "2001:db8::1"
}
},
"private_net": [
{
"network": 4711,
"ip": "10.0.0.2"
}
],
"location": {
"id": 1,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"load_balancer_type": {
"id": 1,
"name": "lb11",
"description": "LB11",
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"max_assigned_certificates": 10,
"deprecated": "2016-01-30T23:50:00+00:00",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
},
"price_monthly": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000000000",
"gross": "1.1900000000000000"
}
}
]
},
"protection": {
"delete": false
},
"labels": {
"key": "value"
},
"created": "2016-01-30T23:50:00+00:00",
"services": [
{
"protocol": "http",
"listen_port": 443,
"destination_port": 80,
"proxyprotocol": false,
"health_check": {
"protocol": "http",
"port": 4711,
"interval": 15,
"timeout": 10,
"retries": 3,
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??,3??"
],
"tls": false
}
},
"http": {
"cookie_name": "HCLBSTICKY",
"cookie_lifetime": 300,
"certificates": [
897
],
"redirect_http": true,
"sticky_sessions": true
}
}
],
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"use_private_ip": true,
"label_selector": {
"selector": "env=prod"
},
"ip": {
"ip": "203.0.113.1"
},
"targets": [
{
"type": "server",
"server": {
"id": 80
},
"health_status": [
{
"listen_port": 443,
"status": "healthy"
}
],
"use_private_ip": true
}
]
}
],
"algorithm": {
"type": "round_robin"
},
"outgoing_traffic": 123456,
"ingoing_traffic": 123456,
"included_traffic": 654321
}
}Deletes a Load Balancer.
DELETE /load_balancers/{id}ID of the Load Balancer.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/$ID"Status: 204You 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.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/$ID/metrics?type=$TYPE&start=$START&end=$END"Content-Type: application/json
Status: 200{
"metrics": {
"start": "2017-01-01T00:00:00+00:00",
"end": "2017-01-01T23:00:00+00:00",
"step": 60,
"time_series": {
"name_of_timeseries": {
"values": [
[
1435781470.622,
"42"
],
[
1435781471.622,
"43"
]
]
}
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a specific Action object.
GET /load_balancers/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 13,
"command": "add_service",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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.
tcp http httpsProtocol of the Load Balancer.
Port the Load Balancer listens on.
Port the Load Balancer will balance to.
Is Proxyprotocol enabled or not.
Service health check.
Configuration option for protocols http and https.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"protocol":"https","listen_port":443,"destination_port":80,"proxyprotocol":false,"health_check":{"protocol":"http","port":4711,"interval":15,"timeout":10,"retries":3,"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false}},"http":{"cookie_name":"HCLBSTICKY","cookie_lifetime":300,"certificates":[897],"redirect_http":true,"sticky_sessions":true}}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/add_service"{
"protocol": "https",
"listen_port": 443,
"destination_port": 80,
"proxyprotocol": false,
"health_check": {
"protocol": "http",
"port": 4711,
"interval": 15,
"timeout": 10,
"retries": 3,
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
}
},
"http": {
"cookie_name": "HCLBSTICKY",
"cookie_lifetime": 300,
"certificates": [
897
],
"redirect_http": true,
"sticky_sessions": true
}
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "add_service",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
server label_selector ipType of the resource.
Configuration for type Server, only valid and required if type is server.
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.
Configuration for label selector targets, only valid and required if type is label_selector.
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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"server","server":{"id":80},"use_private_ip":true,"label_selector":{"selector":"env=prod"},"ip":{"ip":"203.0.113.1"}}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/add_target"{
"type": "server",
"server": {
"id": 80
},
"use_private_ip": true,
"label_selector": {
"selector": "env=prod"
},
"ip": {
"ip": "203.0.113.1"
}
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "add_target",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
ID of an existing network to attach the Load Balancer to.
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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"network":4711,"ip":"10.0.1.1"}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/attach_to_network"{
"network": 4711,
"ip": "10.0.1.1"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "attach_to_network",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"round_robin"}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/change_algorithm"{
"type": "round_robin"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_algorithm",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
Public IP address for which the reverse DNS entry should be set.
Hostname to set as a reverse DNS PTR entry.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip":"1.2.3.4","dns_ptr":"lb1.example.com"}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/change_dns_ptr"{
"ip": "1.2.3.4",
"dns_ptr": "lb1.example.com"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_dns_ptr",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"delete":true}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/change_protection"{
"delete": true
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"load_balancer_type":"lb21"}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/change_type"{
"load_balancer_type": "lb21"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_load_balancer_type",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"listen_port":443}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/delete_service"{
"listen_port": 443
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "delete_service",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"network":4711}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/detach_from_network"{
"network": 4711
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "detach_from_network",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/disable_public_interface"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "disable_public_interface",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/enable_public_interface"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "enable_public_interface",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Removes a target from a Load Balancer.
POST /load_balancers/{id}/actions/remove_targetID of the Load Balancer.
server label_selector ipType of the resource.
Configuration for type Server, required if type is server.
Configuration for label selector targets, required if type is label_selector.
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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"server","server":{"id":80},"label_selector":{"selector":"env=prod"},"ip":{"ip":"203.0.113.1"}}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/remove_target"{
"type": "server",
"server": {
"id": 80
},
"label_selector": {
"selector": "env=prod"
},
"ip": {
"ip": "203.0.113.1"
}
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "remove_target",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
tcp http httpsProtocol of the Load Balancer.
Port the Load Balancer listens on.
Port the Load Balancer will balance to.
Is Proxyprotocol enabled or not.
Service health check.
Configuration option for protocols http and https.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"protocol":"https","listen_port":443,"destination_port":80,"proxyprotocol":false,"health_check":{"protocol":"http","port":4711,"interval":15,"timeout":10,"retries":3,"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false}},"http":{"cookie_name":"HCLBSTICKY","cookie_lifetime":300,"certificates":[897],"redirect_http":true,"sticky_sessions":true}}' \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/update_service"{
"protocol": "https",
"listen_port": 443,
"destination_port": 80,
"proxyprotocol": false,
"health_check": {
"protocol": "http",
"port": 4711,
"interval": 15,
"timeout": 10,
"retries": 3,
"http": {
"domain": "example.com",
"path": "/",
"response": "{\"status\": \"ok\"}",
"status_codes": [
"2??",
"3??"
],
"tls": false
}
},
"http": {
"cookie_name": "HCLBSTICKY",
"cookie_lifetime": 300,
"certificates": [
897
],
"redirect_http": true,
"sticky_sessions": true
}
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "update_service",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Returns a specific Action for a Load Balancer.
GET /load_balancers/{id}/actions/{action_id}ID of the Load Balancer.
ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancers/$ID/actions/$ACTION_ID"Content-Type: application/json
Status: 200{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "load_balancer"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Load Balancer types 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.
All prices are displayed in the currency of the project owner's account.
Gets all Load Balancer type objects.
GET /load_balancer_typesFilter resources by their name. The response will only contain the resources matching exactly the specified name.
25Maximum number of entries returned per page. For more information, see "Pagination".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancer_types"Content-Type: application/json
Status: 200{
"load_balancer_types": [
{
"id": 1,
"name": "lb11",
"description": "LB11",
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"max_assigned_certificates": 10,
"deprecated": "2016-01-30T23:50:00+00:00",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
]
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Gets a specific Load Balancer type object.
GET /load_balancer_types/{id}ID of the Load Balancer Type.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/load_balancer_types/$ID"Content-Type: application/json
Status: 200{
"load_balancer_type": {
"id": 1,
"name": "lb11",
"description": "LB11",
"max_connections": 20000,
"max_services": 5,
"max_targets": 25,
"max_assigned_certificates": 10,
"deprecated": "2016-01-30T23:50:00+00:00",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
]
}
}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 /networksid 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 exactly 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/networks"Content-Type: application/json
Status: 200{
"networks": [
{
"id": 4711,
"name": "mynet",
"ip_range": "10.0.0.0/16",
"subnets": [
{
"type": "cloud",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"gateway": "10.0.0.1",
"vswitch_id": 1000
}
],
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"load_balancers": [
42
],
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"expose_routes_to_vswitch": false
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}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 /networksName of the Network.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Array of subnets to allocate.
Array of routes set in this 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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"mynet","ip_range":"10.0.0.0/16","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"subnets":[{"type":"cloud","ip_range":"10.0.1.0/24","network_zone":"eu-central","vswitch_id":1000}],"routes":[{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}],"expose_routes_to_vswitch":false}' \
"https://api.hetzner.cloud/v1/networks"{
"name": "mynet",
"ip_range": "10.0.0.0/16",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"subnets": [
{
"type": "cloud",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"vswitch_id": 1000
}
],
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"expose_routes_to_vswitch": false
}Content-Type: application/json
Status: 201{
"network": {
"id": 4711,
"name": "mynet",
"ip_range": "10.0.0.0/16",
"subnets": [
{
"type": "cloud",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"gateway": "10.0.0.1",
"vswitch_id": 1000
}
],
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"load_balancers": [
42
],
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"expose_routes_to_vswitch": false
}
}Get a specific Network.
GET /networks/{id}ID of the Network.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/networks/$ID"Content-Type: application/json
Status: 200{
"network": {
"id": 4711,
"name": "mynet",
"ip_range": "10.0.0.0/16",
"subnets": [
{
"type": "cloud",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"gateway": "10.0.0.1",
"vswitch_id": 1000
}
],
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"load_balancers": [
42
],
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"created": "2016-01-30T23:55:00+00:00",
"expose_routes_to_vswitch": false
}
}Update a Network.
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.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"new-name","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"expose_routes_to_vswitch":false}' \
"https://api.hetzner.cloud/v1/networks/$ID"{
"name": "new-name",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"expose_routes_to_vswitch": false
}Content-Type: application/json
Status: 200{
"network": {
"id": 4711,
"name": "new-name",
"ip_range": "10.0.0.0/16",
"subnets": [
{
"type": "cloud",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"gateway": "10.0.0.1"
}
],
"routes": [
{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}
],
"servers": [
42
],
"load_balancers": [
42
],
"protection": {
"delete": false
},
"labels": {
"key": "value"
},
"created": "2016-01-30T23:50:00+00:00",
"expose_routes_to_vswitch": true
}
}Deletes a Network.
Attached resources will be detached automatically.
DELETE /networks/{id}ID of the Network.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/networks/$ID"Status: 204Lists 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/networks/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a single Action.
GET /networks/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/networks/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/networks/$ID/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 13,
"command": "add_subnet",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}' \
"https://api.hetzner.cloud/v1/networks/$ID/actions/add_route"{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "add_route",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
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.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.
ID of the robot vSwitch.
Must be supplied if the subnet is of type vswitch.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type":"cloud","ip_range":"10.0.1.0/24","network_zone":"eu-central","vswitch_id":1000}' \
"https://api.hetzner.cloud/v1/networks/$ID/actions/add_subnet"{
"type": "cloud",
"ip_range": "10.0.1.0/24",
"network_zone": "eu-central",
"vswitch_id": 1000
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "add_subnet",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip_range":"10.0.0.0/16"}' \
"https://api.hetzner.cloud/v1/networks/$ID/actions/change_ip_range"{
"ip_range": "10.0.0.0/16"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_ip_range",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"delete":true}' \
"https://api.hetzner.cloud/v1/networks/$ID/actions/change_protection"{
"delete": true
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}' \
"https://api.hetzner.cloud/v1/networks/$ID/actions/delete_route"{
"destination": "10.100.1.0/24",
"gateway": "10.0.1.1"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "delete_route",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"ip_range":"10.0.1.0/24"}' \
"https://api.hetzner.cloud/v1/networks/$ID/actions/delete_subnet"{
"ip_range": "10.0.1.0/24"
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "delete_subnet",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}GET /networks/{id}/actions/{action_id}ID of the Network.
ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/networks/$ID/actions/$ACTION_ID"Content-Type: application/json
Status: 200{
"action": {
"id": 13,
"command": "add_subnet",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 4711,
"type": "network"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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 /pricingcurl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/pricing"Content-Type: application/json
Status: 200{
"pricing": {
"currency": "EUR",
"vat_rate": "19.00",
"primary_ips": [
{
"type": "ipv4",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
}
}
]
}
],
"floating_ips": [
{
"type": "ipv4",
"prices": [
{
"location": "fsn1",
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
}
}
]
}
],
"image": {
"price_per_gb_month": {
"net": "1.0000",
"gross": "1.1900"
}
},
"volume": {
"price_per_gb_month": {
"net": "1.0000",
"gross": "1.1900"
}
},
"server_backup": {
"percentage": "20.00"
},
"server_types": [
{
"id": 104,
"name": "cpx11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
]
}
],
"load_balancer_types": [
{
"id": 1,
"name": "lb11",
"prices": [
{
"location": "fsn1",
"price_hourly": {
"net": "1.0000",
"gross": "1.1900"
},
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
},
"included_traffic": 654321,
"price_per_tb_traffic": {
"net": "1.0000",
"gross": "1.1900"
}
}
]
}
],
"floating_ip": {
"price_monthly": {
"net": "1.0000",
"gross": "1.1900"
}
}
}
}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 creatingFilter resources by status. Can be used multiple times. The response will only contain the resources with the specified 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 exactly 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/volumes"Content-Type: application/json
Status: 200{
"volumes": [
{
"id": 42,
"created": "2016-01-30T23:55:00+00:00",
"name": "my-resource",
"server": 12,
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"size": 42,
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"status": "available",
"format": "xfs"
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}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 /volumesSize of the Volume in GB.
Name of the volume.
User-defined labels (key/value pairs) for the Resource.
For more information, see "Labels".
Auto-mount Volume after attach. server must be provided.
Format Volume after creation. One of: xfs, ext4.
Location to create the Volume in (can be omitted if Server is specified).
Server to which to attach the Volume once it's created (Volume will be created in the same Location as the server).
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"size":42,"name":"test-database","labels":{"key":"value"},"location":"nbg1","automount":false,"format":"xfs"}' \
"https://api.hetzner.cloud/v1/volumes"{
"size": 42,
"name": "test-database",
"labels": {
"key": "value"
},
"location": "nbg1",
"automount": false,
"format": "xfs"
}Content-Type: application/json
Status: 201{
"volume": {
"id": 4711,
"created": "2016-01-30T23:50:11+00:00",
"name": "database-storage",
"server": 12,
"location": {
"id": 1,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"size": 42,
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"protection": {
"delete": false
},
"labels": {
"key": "value"
},
"status": "available",
"format": "xfs"
},
"action": {
"id": 13,
"command": "create_volume",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
},
"next_actions": [
{
"id": 13,
"command": "attach_volume",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
]
}Gets a specific Volume object.
GET /volumes/{id}ID of the Volume.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/volumes/$ID"Content-Type: application/json
Status: 200{
"volume": {
"id": 42,
"created": "2016-01-30T23:55:00+00:00",
"name": "my-resource",
"server": 12,
"location": {
"id": 42,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"size": 42,
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"protection": {
"delete": false
},
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
},
"status": "available",
"format": "xfs"
}
}Updates the Volume properties.
PUT /volumes/{id}ID of the Volume.
New Volume name.
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"database-storage","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
"https://api.hetzner.cloud/v1/volumes/$ID"{
"name": "database-storage",
"labels": {
"environment": "prod",
"example.com/my": "label",
"just-a-key": ""
}
}Content-Type: application/json
Status: 200{
"volume": {
"id": 4711,
"created": "2016-01-30T23:50:11+00:00",
"name": "database-storage",
"server": 12,
"location": {
"id": 1,
"name": "fsn1",
"description": "Falkenstein DC Park 1",
"country": "DE",
"city": "Falkenstein",
"latitude": 50.47612,
"longitude": 12.370071,
"network_zone": "eu-central"
},
"size": 42,
"linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
"protection": {
"delete": false
},
"labels": {
"key": "value"
},
"status": "available",
"format": "xfs"
}
}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.
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/volumes/$ID"Status: 204Returns 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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/volumes/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 3,
"per_page": 25,
"previous_page": 2,
"next_page": 4,
"last_page": 4,
"total_entries": 100
}
}
}Returns a specific Action object.
GET /volumes/actions/{id}ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/volumes/actions/$ID"Content-Type: application/json
Status: 200{
"action": {
"id": 42,
"command": "start_resource",
"status": "running",
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:55:00+00:00",
"progress": 100,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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".
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/volumes/$ID/actions"Content-Type: application/json
Status: 200{
"actions": [
{
"id": 13,
"command": "attach_volume",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 13,
"type": "volume"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
],
"meta": {
"pagination": {
"page": 1,
"per_page": 25,
"previous_page": null,
"next_page": null,
"last_page": 1,
"total_entries": 21
}
}
}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.
ID of the Server the Volume will be attached to.
Auto-mount the Volume after attaching it.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"server":43,"automount":false}' \
"https://api.hetzner.cloud/v1/volumes/$ID/actions/attach"{
"server": 43,
"automount": false
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "attach_volume",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 43,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Changes the protection configuration of a Volume.
POST /volumes/{id}/actions/change_protectionID of the Volume.
If true, prevents the Volume from being deleted.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"delete":true}' \
"https://api.hetzner.cloud/v1/volumes/$ID/actions/change_protection"{
"delete": true
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "change_protection",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
},
{
"id": 554,
"type": "volume"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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.
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/volumes/$ID/actions/detach"Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "detach_volume",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}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).
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"size":50}' \
"https://api.hetzner.cloud/v1/volumes/$ID/actions/resize"{
"size": 50
}Content-Type: application/json
Status: 201{
"action": {
"id": 13,
"command": "resize_volume",
"status": "running",
"progress": 0,
"started": "2016-01-30T23:50:00+00:00",
"finished": null,
"resources": [
{
"id": 554,
"type": "volume"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}Returns a specific Action for a Volume.
GET /volumes/{id}/actions/{action_id}ID of the Volume.
ID of the Action.
curl \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.hetzner.cloud/v1/volumes/$ID/actions/$ACTION_ID"Content-Type: application/json
Status: 200{
"action": {
"id": 13,
"command": "attach_volume",
"status": "success",
"progress": 100,
"started": "2016-01-30T23:55:00+00:00",
"finished": "2016-01-30T23:56:00+00:00",
"resources": [
{
"id": 42,
"type": "server"
}
],
"error": {
"code": "action_failed",
"message": "Action failed"
}
}
}