Hetzner Cloud API

This is the official documentation for the Hetzner Cloud API.

Introduction

The Hetzner Cloud API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.

As an alternative to working directly with our API you may also consider to use:

Also you can find a list of libraries, tools, and integrations on GitHub.

If you are developing integrations based on our API and your product is Open Source you may be eligible for a free one time €50 (excl. VAT) credit on your account. Please contact us via the the support page on your Cloud Console and let us know the following:

  • The type of integration you would like to develop
  • Link to the GitHub repo you will use for the Project
  • Link to some other Open Source work you have already done (if you have done so)

Getting Started

To get started using the API you first need an API token. Sign in into the Hetzner Cloud Console choose a Project, go to SecurityAPI 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.

Example Request

1curl -H "Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj" \
2  https://api.hetzner.cloud/v1/servers

Example Response

1{
2  "servers": [],
3  "meta": {
4    "pagination": {
5      "page": 1,
6      "per_page": 25,
7      "previous_page": null,
8      "next_page": null,
9      "last_page": 1,
10      "total_entries": 0
11    }
12  }
13}

Authentication

All requests to the Hetzner Cloud API must be authenticated via a API token. Include your secret API token in every request you send to the API with the Authorization HTTP header.

To create a new API token for your Project, switch into the Hetzner Cloud Console choose a Project, go to SecurityAPI Tokens , and generate a new token.

Example Authorization header

1Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj

Errors

Errors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code.

The error response contains the following keys:

Keys Meaning
code Short string indicating the type of error (machine-parsable)
message Textual description on what has gone wrong
details An object providing for details on the error (schema depends on code)

Error Codes

Code Description
forbidden Insufficient permissions for this request
unauthorized Request was made with an invalid or unknown token
invalid_input Error while parsing or processing the input
json_error Invalid JSON input in your request
locked The item you are trying to access is locked (there is already an Action running)
not_found Entity not found
rate_limit_exceeded Error when sending too many requests
resource_limit_exceeded Error when exceeding the maximum quantity of a resource for an account
resource_unavailable The requested resource is currently unavailable
server_error Error within the API backend
service_error Error within a service
uniqueness_error One or more of the objects fields must be unique
protected The Action you are trying to start is protected for this resource
maintenance Cannot perform operation due to maintenance
conflict The resource has changed during the request, please retry
unsupported_error The corresponding resource does not support the Action
token_readonly The token is only allowed to perform GET requests
unavailable A service or product is currently not available

Example response

1{
2  "error": {
3    "code": "invalid_input",
4    "message": "invalid input in field 'broken_field': is too long",
5    "details": {
6      "fields": [
7        {
8          "name": "broken_field",
9          "messages": ["is too long"]
10        }
11      ]
12    }
13  }
14}

invalid_input

1{
2  "error": {
3    "code": "invalid_input",
4    "message": "invalid input in field 'broken_field': is too long",
5    "details": {
6      "fields": [
7        {
8          "name": "broken_field",
9          "messages": ["is too long"]
10        }
11      ]
12    }
13  }
14}

uniqueness_error

1{
2  "error": {
3    "code": "uniqueness_error",
4    "message": "SSH key with the same fingerprint already exists",
5    "details": {
6      "fields": [
7        {
8          "name": "public_key"
9        }
10      ]
11    }
12  }
13}

resource_limit_exceeded

1{
2  "error": {
3    "code": "resource_limit_exceeded",
4    "message": "project limit exceeded",
5    "details": {
6      "limits": [
7        {
8          "name": "project_limit"
9        }
10      ]
11    }
12  }
13}

Labels

Labels are key/value pairs that can be attached to all resources.

Valid label keys have two segments: an optional prefix and name, separated by a slash ( / ). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character ( [a-z0-9A-Z] ) with dashes ( - ), underscores ( _ ), dots ( . ), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots ( . ), not longer than 253 characters in total, followed by a slash ( / ).

Valid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character ( [a-z0-9A-Z] ) with dashes ( - ), underscores ( _ ), dots ( . ), and alphanumerics between.

The hetzner.cloud/ prefix is reserved and cannot be used.

Example Labels

1{
2  "labels": {
3    "environment": "development",
4    "service": "backend",
5    "example.com/my": "label",
6    "just-a-key": ""
7  }
8}

Label Selector

For resources with labels, you can filter resources by their labels using the label selector query language.

Expression Meaning
k==v / k=v Value of key k does equal value v
k!=v Value of key k does not equal value v
k Key k is present
!k Key k is not present
k in (v1,v2,v3) Value of key k is v1 , v2 , or v3
k notin (v1,v2,v3) Value of key k is neither v1 , nor v2 , nor v3
k1==v,!k2 Value of key k1 is v and key k2 is not present

Examples

  • Returns all resources that have a env=production label and that don't have 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

Pagination

Responses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:

  • A page parameter specifies the page to fetch. The number of the first page is 1.
  • A per_page parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation.

Responses contain a Link header with pagination information.

Additionally, if the response body is JSON and the root object is an object, that object has a pagination object inside the meta object with pagination information:

The keys previous_page , next_page , last_page , and total_entries may be null when on the first page, last page, or when the total number of entries is unknown.

Line breaks have been added for display purposes only and responses may only contain some of the above rel values.

Example Pagination

1{
2    "servers": [...],
3    "meta": {
4        "pagination": {
5            "page": 2,
6            "per_page": 25,
7            "previous_page": 1,
8            "next_page": 3,
9            "last_page": 4,
10            "total_entries": 100
11        }
12    }
13}

Example Pagination Link header

1Link: <https://api.hetzner.cloud/v1/actions?page=2&per_page=5>; rel="prev",
2      <https://api.hetzner.cloud/v1/actions?page=4&per_page=5>; rel="next",
3      <https://api.hetzner.cloud/v1/actions?page=6&per_page=5>; rel="last"

Rate Limiting

All requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a 429 Too Many Requests error. Burst requests are allowed. Responses contain serveral headers which provide information about your current rate limit status.

  • The RateLimit-Limit header contains the total number of requests you can perform per hour.
  • The RateLimit-Remaining header contains the number of requests remaining in the current rate limit time frame.
  • The RateLimit-Reset header contains a UNIX timestamp of the point in time when your rate limit will have recovered and you will have the full number of requests available again.

The default limit is 3600 requests per hour and per Project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second.

Server Metadata

Your Server can discover metadata about itself by doing a HTTP request to specific URLs. The following data is available:

Data Format Contents
hostname text Name of the Server as set in the api
instance-id number ID of the server
public-ipv4 text Primary public IPv4 address
private-networks yaml Details about the private networks the Server is attached to
availability-zone text Name of the availability zone that Server runs in
region text Network zone, e.g. eu-central

Example: Summary

1$ curl http://169.254.169.254/hetzner/v1/metadata

1availability-zone: hel1-dc2
2hostname: my-server
3instance-id: 42
4public-ipv4: 1.2.3.4
5region: eu-central

Example: Hostname

1$ curl http://169.254.169.254/hetzner/v1/metadata/hostname
2my-server

Example: Instance ID

1$ curl http://169.254.169.254/hetzner/v1/metadata/instance-id
242

Example: Public IPv4

1$ curl http://169.254.169.254/hetzner/v1/metadata/public-ipv4
21.2.3.4

Example: Private Networks

1$ curl http://169.254.169.254/hetzner/v1/metadata/private-networks

1- ip: 10.0.0.2
2  alias_ips: [10.0.0.3, 10.0.0.4]
3  interface_num: 1
4  mac_address: 86:00:00:2a:7d:e0
5  network_id: 1234
6  network_name: nw-test1
7  network: 10.0.0.0/8
8  subnet: 10.0.0.0/24
9  gateway: 10.0.0.1
10- ip: 192.168.0.2
11  alias_ips: []
12  interface_num: 2
13  mac_address: 86:00:00:2a:7d:e1
14  network_id: 4321
15  network_name: nw-test2
16  network: 192.168.0.0/16
17  subnet: 192.168.0.0/24
18  gateway: 192.168.0.1

Example: Availability Zone

1$ curl http://169.254.169.254/hetzner/v1/metadata/availability-zone
2hel1-dc2

Example: Region

1$ curl http://169.254.169.254/hetzner/v1/metadata/region
2eu-central

Sorting

Some responses which return multiple items support sorting. If they do support sorting the documentation states which fields can be used for sorting. You specify sorting with the sort query string parameter. You can sort by multiple fields. You can set the sort direction by appending :asc or :desc to the field name. By default, ascending sorting is used.

Example: Sorting

1https://api.hetzner.cloud/v1/actions?sort=status:asc
2https://api.hetzner.cloud/v1/actions?sort=status:desc
3https://api.hetzner.cloud/v1/actions?sort=status:asc&sort=command:desc

Deprecation Notices

You can find all announced deprecations in our Changelog.

Actions

Actions show the results and progress of asynchronous requests to the API.

Get all Actions

Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status parameter.

HTTP Request

GET /actions

Query Parameters

  • idinteger (int64)

    Can be used multiple times, the response will contain only Actions with specified IDs.

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "start_resource",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:55:00+00:00",
10      "id": 42,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 42,
15          "type": "server"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns a specific Action object.

HTTP Request

GET /actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Resource

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/actions/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "start_resource",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:55:00+00:00",
9    "id": 42,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Certificates

TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic.

Get all Certificates

Returns all Certificate objects.

HTTP Request

GET /certificates

Query Parameters

  • sortstring
    Possible enum values:
    idid:ascid:descnamename:ascname:desccreatedcreated:asccreated:desc

    Can be used multiple times.

  • namestring

    Can be used to filter resources by their name. The response will only contain the resources matching the specified name

  • label_selectorstring

    Can be used to filter resources by labels. The response will only contain resources matching the label selector.

  • typestring
    Possible enum values:
    uploadedmanaged

    Can be used multiple times. The response will only contain Certificates matching the type.

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/certificates"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "certificates": [
3    {
4      "certificate": "-----BEGIN CERTIFICATE-----\n...",
5      "created": "2019-01-08T12:10:00+00:00",
6      "domain_names": [
7        "example.com",
8        "webmail.example.com",
9        "www.example.com"
10      ],
11      "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
12      "id": 897,
13      "labels": {
14        "env": "dev"
15      },
16      "name": "my website cert",
17      "not_valid_after": "2019-07-08T09:59:59+00:00",
18      "not_valid_before": "2019-01-08T10:00:00+00:00",
19      "status": null,
20      "type": "uploaded",
21      "used_by": [
22        {
23          "id": 4711,
24          "type": "load_balancer"
25        }
26      ]
27    }
28  ]
29}

Create a Certificate

Creates a new Certificate.

The default type uploaded allows for uploading your existing certificate and private_key in PEM format. You have to monitor its expiration date and handle renewal yourself.

In contrast, type managed requests a new Certificate from Let's Encrypt for the specified domain_names . Only domains managed by Hetzner DNS are supported. We handle renewal and timely alert the project owner via email if problems occur.

For type managed Certificates the action key of the response contains the Action that allows for tracking the issuance process. For type uploaded Certificates the action is always null.

HTTP Request

POST /certificates

Request

  • certificatestring

    Certificate and chain in PEM format, in order so that each record directly certifies the one preceding. Required for type uploaded Certificates.

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring required

    Name of the Certificate

  • private_keystring

    Certificate key in PEM format. Required for type uploaded Certificates.

  • typestring
    Possible enum values:
    uploadedmanaged

    Choose between uploading a Certificate in PEM format or requesting a managed Let's Encrypt Certificate. If omitted defaults to uploaded .

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"domain_names":["example.com","webmail.example.com","www.example.com"],"name":"my website cert","type":"managed"}' \
6	"https://api.hetzner.cloud/v1/certificates"

Request

1{
2  "domain_names": [
3    "example.com",
4    "webmail.example.com",
5    "www.example.com"
6  ],
7  "name": "my website cert",
8  "type": "managed"
9}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "create_certificate",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": null,
9    "id": 13,
10    "progress": 0,
11    "resources": [
12      {
13        "id": 879,
14        "type": "certificate"
15      }
16    ],
17    "started": "2019-01-08T12:10:00+00:00",
18    "status": "running"
19  },
20  "certificate": {
21    "certificate": null,
22    "created": "2019-01-08T12:10:00+00:00",
23    "domain_names": [
24      "example.com",
25      "webmail.example.com",
26      "www.example.com"
27    ],
28    "fingerprint": null,
29    "id": 897,
30    "labels": {
31      "env": "dev"
32    },
33    "name": "my website cert",
34    "not_valid_after": null,
35    "not_valid_before": null,
36    "status": {
37      "error": null,
38      "issuance": "pending",
39      "renewal": "unavailable"
40    },
41    "type": "managed",
42    "used_by": [
43      {
44        "id": 4711,
45        "type": "load_balancer"
46      }
47    ]
48  }
49}

Delete a Certificate

Deletes a Certificate.

HTTP Request

DELETE /certificates/{id}

Path Parameters

  • idinteger (int64) required

    ID of the resource

Example curl

1curl \
2	-X DELETE \
3	-H "Authorization: Bearer $API_TOKEN" \
4	"https://api.hetzner.cloud/v1/certificates/$ID"

Response headers

1Status: 204

Get a Certificate

Gets a specific Certificate object.

HTTP Request

GET /certificates/{id}

Path Parameters

  • idinteger (int64) required

    ID of the resource

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/certificates/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "certificate": {
3    "certificate": "-----BEGIN CERTIFICATE-----\n...",
4    "created": "2019-01-08T12:10:00+00:00",
5    "domain_names": [
6      "example.com",
7      "webmail.example.com",
8      "www.example.com"
9    ],
10    "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
11    "id": 897,
12    "labels": {
13      "env": "dev"
14    },
15    "name": "my website cert",
16    "not_valid_after": "2019-07-08T09:59:59+00:00",
17    "not_valid_before": "2019-01-08T10:00:00+00:00",
18    "status": null,
19    "type": "uploaded",
20    "used_by": [
21      {
22        "id": 4711,
23        "type": "load_balancer"
24      }
25    ]
26  }
27}

Update a Certificate

Updates the Certificate properties.

Note that when updating labels, the Certificate’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

Note: if the Certificate object changes during the request, the response will be a “conflict” error.

HTTP Request

PUT /certificates/{id}

Path Parameters

  • idinteger (int64) required

    ID of the resource

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New Certificate name

Response

Example curl

1curl \
2	-X PUT \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"labels":{"labelkey":"value"},"name":"my website cert"}' \
6	"https://api.hetzner.cloud/v1/certificates/$ID"

Request

1{
2  "labels": {
3    "labelkey": "value"
4  },
5  "name": "my website cert"
6}

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "certificate": {
3    "certificate": "-----BEGIN CERTIFICATE-----\n...",
4    "created": "2019-01-08T12:10:00+00:00",
5    "domain_names": [
6      "example.com",
7      "webmail.example.com",
8      "www.example.com"
9    ],
10    "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
11    "id": 897,
12    "labels": {
13      "labelkey": "value"
14    },
15    "name": "my website cert",
16    "not_valid_after": "2019-07-08T09:59:59+00:00",
17    "not_valid_before": "2019-01-08T10:00:00+00:00",
18    "status": null,
19    "type": "uploaded",
20    "used_by": [
21      {
22        "id": 4711,
23        "type": "load_balancer"
24      }
25    ]
26  }
27}

Certificate Actions

Get all Actions

Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.

HTTP Request

GET /certificates/actions

Query Parameters

  • idinteger (int64)

    Can be used multiple times, the response will contain only Actions with specified IDs.

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/certificates/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "start_resource",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:55:00+00:00",
10      "id": 42,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 42,
15          "type": "server"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns a specific Action object.

HTTP Request

GET /certificates/actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Action.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/certificates/actions/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "start_resource",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:55:00+00:00",
9    "id": 42,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Get all Actions for a Certificate

Returns all Action objects for a Certificate. You can sort the results by using the sort URI parameter, and filter them with the status parameter.

Only type managed Certificates can have Actions. For type uploaded Certificates the actions key will always contain an empty array.

HTTP Request

GET /certificates/{id}/actions

Path Parameters

  • idinteger (int64) required

    ID of the Action.

Query Parameters

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/certificates/$ID/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "issue_certificate",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2021-01-30T23:57:00+00:00",
10      "id": 14,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 896,
15          "type": "certificate"
16        }
17      ],
18      "started": "2021-01-30T23:55:00+00:00",
19      "status": "success"
20    }
21  ]
22}

Retry Issuance or Renewal

Retry a failed Certificate issuance or renewal.

Only applicable if the type of the Certificate is managed and the issuance or renewal status is failed .

Call specific error codes

Code Description
caa_record_does_not_allow_ca CAA record does not allow certificate authority
ca_dns_validation_failed Certificate Authority: DNS validation failed
ca_too_many_authorizations_failed_recently Certificate Authority: Too many authorizations failed recently
ca_too_many_certificates_issued_for_registered_domain Certificate Authority: Too many certificates issued for registered domain
ca_too_many_duplicate_certificates Certificate Authority: Too many duplicate certificates
could_not_verify_domain_delegated_to_zone Could not verify domain delegated to zone
dns_zone_not_found DNS zone not found
dns_zone_is_secondary_zone DNS zone is a secondary zone

HTTP Request

POST /certificates/{id}/actions/retry

Path Parameters

  • idinteger (int64) required

    ID of the Certificate

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	"https://api.hetzner.cloud/v1/certificates/$ID/actions/retry"

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "issue_certificate",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2021-01-30T23:57:00+00:00",
9    "id": 14,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 896,
14        "type": "certificate"
15      }
16    ],
17    "started": "2021-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Get an Action for a Certificate

Returns a specific Action for a Certificate. Only type managed Certificates have Actions.

HTTP Request

GET /certificates/{id}/actions/{action_id}

Path Parameters

  • idinteger (int64) required

    ID of the Certificate

  • action_idinteger (int64) required

    ID of the Action

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/certificates/$ID/actions/$ACTION_ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "issue_certificate",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2021-01-30T23:57:00+00:00",
9    "id": 14,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 896,
14        "type": "certificate"
15      }
16    ],
17    "started": "2021-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Datacenters

Each Datacenter represents a virtual Datacenter which is made up of possible many physical Datacenters where Servers are hosted.

Datacenter names are composed from their Location and virtual Datacenter number, for example fsn1-dc14 means virtual Datacenter 14 in Location fsn1.

Right now there is only one Datacenter for each Location. The Datacenter numbers for fsn, nbg and hel are arbitrarily set to 14, 3 and 2 for historic reasons and do not represent real physical Hetzner datacenters.

Get all Datacenters

Returns all Datacenter objects.

HTTP Request

GET /datacenters

Query Parameters

  • namestring

    Can be used to filter Datacenters by their name. The response will only contain the Datacenter matching the specified name. When the name does not match the Datacenter name format, an invalid_input error is returned.

  • sortstring
    Possible enum values:
    idid:ascid:descnamename:ascname:desc

    Can be used multiple times.

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

  • recommendationinteger (int64) required

    The Datacenter which is recommended to be used to create new Servers.

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/datacenters"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "datacenters": [
3    {
4      "description": "Falkenstein DC Park 8",
5      "id": 42,
6      "location": {
7        "city": "Falkenstein",
8        "country": "DE",
9        "description": "Falkenstein DC Park 1",
10        "id": 1,
11        "latitude": 50.47612,
12        "longitude": 12.370071,
13        "name": "fsn1",
14        "network_zone": "eu-central"
15      },
16      "name": "fsn1-dc8",
17      "server_types": {
18        "available": [
19          1,
20          2,
21          3
22        ],
23        "available_for_migration": [
24          1,
25          2,
26          3
27        ],
28        "supported": [
29          1,
30          2,
31          3
32        ]
33      }
34    }
35  ],
36  "meta": {
37    "pagination": {
38      "last_page": 4,
39      "next_page": 4,
40      "page": 3,
41      "per_page": 25,
42      "previous_page": 2,
43      "total_entries": 100
44    }
45  },
46  "recommendation": 1
47}

Get a Datacenter

Returns a specific Datacenter object.

HTTP Request

GET /datacenters/{id}

Path Parameters

  • idinteger (int64) required

    ID of Datacenter

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/datacenters/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "datacenter": {
3    "description": "Falkenstein DC Park 8",
4    "id": 42,
5    "location": {
6      "city": "Falkenstein",
7      "country": "DE",
8      "description": "Falkenstein DC Park 1",
9      "id": 1,
10      "latitude": 50.47612,
11      "longitude": 12.370071,
12      "name": "fsn1",
13      "network_zone": "eu-central"
14    },
15    "name": "fsn1-dc8",
16    "server_types": {
17      "available": [
18        1,
19        2,
20        3
21      ],
22      "available_for_migration": [
23        1,
24        2,
25        3
26      ],
27      "supported": [
28        1,
29        2,
30        3
31      ]
32    }
33  }
34}

Firewalls

Firewalls can limit the network access to or from your resources.

  • When applying a firewall with no in rule all inbound traffic will be dropped. The default for in is DROP.
  • When applying a firewall with no out rule all outbound traffic will be accepted. The default for out is ACCEPT.

Get all Firewalls

Returns all Firewall objects.

HTTP Request

GET /firewalls

Query Parameters

  • sortstring
    Possible enum values:
    idid:ascid:descnamename:ascname:desccreatedcreated:asccreated:desc

    Can be used multiple times.

  • namestring

    Can be used to filter resources by their name. The response will only contain the resources matching the specified name

  • label_selectorstring

    Can be used to filter resources by labels. The response will only contain resources matching the label selector.

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/firewalls"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "firewalls": [
3    {
4      "applied_to": [
5        {
6          "applied_to_resources": [
7            {
8              "server": {
9                "id": 42
10              },
11              "type": "server"
12            }
13          ],
14          "label_selector": {
15            "selector": "env=prod"
16          },
17          "server": {
18            "id": 42
19          },
20          "type": "server"
21        }
22      ],
23      "created": "2016-01-30T23:55:00+00:00",
24      "id": 42,
25      "labels": {},
26      "name": "my-resource",
27      "rules": [
28        {
29          "description": null,
30          "destination_ips": [
31            "28.239.13.1/32",
32            "28.239.14.0/24",
33            "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
34          ],
35          "direction": "in",
36          "port": "80",
37          "protocol": "tcp",
38          "source_ips": [
39            "28.239.13.1/32",
40            "28.239.14.0/24",
41            "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
42          ]
43        }
44      ]
45    }
46  ],
47  "meta": {
48    "pagination": {
49      "last_page": 4,
50      "next_page": 4,
51      "page": 3,
52      "per_page": 25,
53      "previous_page": 2,
54      "total_entries": 100
55    }
56  }
57}

Create a Firewall

Creates a new Firewall.

Call specific error codes

Code Description
server_already_added Server added more than one time to resource
incompatible_network_type The Network type is incompatible for the given resource
firewall_resource_not_found The resource the Firewall should be attached to was not found

HTTP Request

POST /firewalls

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring required

    Name of the Firewall

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"apply_to":[{"server":{"id":42},"type":"server"}],"labels":{"env":"dev"},"name":"Corporate Intranet Protection","rules":[{"description":"Allow port 80","direction":"in","port":"80","protocol":"tcp","source_ips":["28.239.13.1/32","28.239.14.0/24","ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"]}]}' \
6	"https://api.hetzner.cloud/v1/firewalls"

Request

1{
2  "apply_to": [
3    {
4      "server": {
5        "id": 42
6      },
7      "type": "server"
8    }
9  ],
10  "labels": {
11    "env": "dev"
12  },
13  "name": "Corporate Intranet Protection",
14  "rules": [
15    {
16      "description": "Allow port 80",
17      "direction": "in",
18      "port": "80",
19      "protocol": "tcp",
20      "source_ips": [
21        "28.239.13.1/32",
22        "28.239.14.0/24",
23        "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
24      ]
25    }
26  ]
27}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "actions": [
3    {
4      "command": "set_firewall_rules",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:56:00+00:00",
10      "id": 13,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 38,
15          "type": "firewall"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    },
21    {
22      "command": "apply_firewall",
23      "error": {
24        "code": "action_failed",
25        "message": "Action failed"
26      },
27      "finished": "2016-01-30T23:56:00+00:00",
28      "id": 14,
29      "progress": 100,
30      "resources": [
31        {
32          "id": 42,
33          "type": "server"
34        },
35        {
36          "id": 38,
37          "type": "firewall"
38        }
39      ],
40      "started": "2016-01-30T23:55:00+00:00",
41      "status": "success"
42    }
43  ],
44  "firewall": {
45    "applied_to": [
46      {
47        "applied_to_resources": [
48          {
49            "server": {
50              "id": 42
51            },
52            "type": "server"
53          }
54        ],
55        "label_selector": {
56          "selector": "env=prod"
57        },
58        "server": {
59          "id": 42
60        },
61        "type": "server"
62      }
63    ],
64    "created": "2016-01-30T23:55:00+00:00",
65    "id": 42,
66    "labels": {},
67    "name": "my-resource",
68    "rules": [
69      {
70        "description": null,
71        "destination_ips": [
72          "28.239.13.1/32",
73          "28.239.14.0/24",
74          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
75        ],
76        "direction": "in",
77        "port": "80",
78        "protocol": "tcp",
79        "source_ips": [
80          "28.239.13.1/32",
81          "28.239.14.0/24",
82          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
83        ]
84      }
85    ]
86  }
87}

Delete a Firewall

Deletes a Firewall.

Call specific error codes

Code Description
resource_in_use Firewall must not be in use to be deleted

HTTP Request

DELETE /firewalls/{id}

Path Parameters

  • idinteger (int64) required

    ID of the resource

Example curl

1curl \
2	-X DELETE \
3	-H "Authorization: Bearer $API_TOKEN" \
4	"https://api.hetzner.cloud/v1/firewalls/$ID"

Response headers

1Status: 204

Get a Firewall

Gets a specific Firewall object.

HTTP Request

GET /firewalls/{id}

Path Parameters

  • idinteger (int64) required

    ID of the resource

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/firewalls/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "firewall": {
3    "applied_to": [
4      {
5        "applied_to_resources": [
6          {
7            "server": {
8              "id": 42
9            },
10            "type": "server"
11          }
12        ],
13        "label_selector": {
14          "selector": "env=prod"
15        },
16        "server": {
17          "id": 42
18        },
19        "type": "server"
20      }
21    ],
22    "created": "2016-01-30T23:55:00+00:00",
23    "id": 42,
24    "labels": {},
25    "name": "my-resource",
26    "rules": [
27      {
28        "description": null,
29        "destination_ips": [
30          "28.239.13.1/32",
31          "28.239.14.0/24",
32          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
33        ],
34        "direction": "in",
35        "port": "80",
36        "protocol": "tcp",
37        "source_ips": [
38          "28.239.13.1/32",
39          "28.239.14.0/24",
40          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
41        ]
42      }
43    ]
44  }
45}

Update a Firewall

Updates the Firewall.

Note that when updating labels, the Firewall's current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

Note: if the Firewall object changes during the request, the response will be a “conflict” error.

HTTP Request

PUT /firewalls/{id}

Path Parameters

  • idinteger (int64) required

    ID of the resource

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New Firewall name

Response

Example curl

1curl \
2	-X PUT \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"labels":{"labelkey":"value"},"name":"new-name"}' \
6	"https://api.hetzner.cloud/v1/firewalls/$ID"

Request

1{
2  "labels": {
3    "labelkey": "value"
4  },
5  "name": "new-name"
6}

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "firewall": {
3    "applied_to": [
4      {
5        "applied_to_resources": [
6          {
7            "server": {
8              "id": 42
9            },
10            "type": "server"
11          }
12        ],
13        "label_selector": {
14          "selector": "env=prod"
15        },
16        "server": {
17          "id": 42
18        },
19        "type": "server"
20      }
21    ],
22    "created": "2016-01-30T23:55:00+00:00",
23    "id": 42,
24    "labels": {},
25    "name": "my-resource",
26    "rules": [
27      {
28        "description": null,
29        "destination_ips": [
30          "28.239.13.1/32",
31          "28.239.14.0/24",
32          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
33        ],
34        "direction": "in",
35        "port": "80",
36        "protocol": "tcp",
37        "source_ips": [
38          "28.239.13.1/32",
39          "28.239.14.0/24",
40          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
41        ]
42      }
43    ]
44  }
45}

Firewall Actions

Get all Actions

Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.

HTTP Request

GET /firewalls/actions

Query Parameters

  • idinteger (int64)

    Can be used multiple times, the response will contain only Actions with specified IDs.

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/firewalls/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "start_resource",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:55:00+00:00",
10      "id": 42,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 42,
15          "type": "server"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns a specific Action object.

HTTP Request

GET /firewalls/actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Resource

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/firewalls/actions/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "start_resource",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:55:00+00:00",
9    "id": 42,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Get all Actions for a Firewall

Returns all Action objects for a Firewall. You can sort the results by using the sort URI parameter, and filter them with the status parameter.

HTTP Request

GET /firewalls/{id}/actions

Path Parameters

  • idinteger (int64) required

    ID of the Action.

Query Parameters

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/firewalls/$ID/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "set_firewall_rules",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:56:00+00:00",
10      "id": 13,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 38,
15          "type": "firewall"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    }
21  ]
22}

Apply to Resources

Applies one Firewall to multiple resources.

Currently servers (public network interface) and label selectors are supported.

Call specific error codes

Code Description
firewall_already_applied Firewall was already applied on resource
incompatible_network_type The Network type is incompatible for the given resource
firewall_resource_not_found The resource the Firewall should be attached to was not found

HTTP Request

POST /firewalls/{id}/actions/apply_to_resources

Path Parameters

  • idinteger (int64) required

    ID of the Firewall

Request

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"apply_to":[{"server":{"id":42},"type":"server"}]}' \
6	"https://api.hetzner.cloud/v1/firewalls/$ID/actions/apply_to_resources"

Request

1{
2  "apply_to": [
3    {
4      "server": {
5        "id": 42
6      },
7      "type": "server"
8    }
9  ]
10}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "actions": [
3    {
4      "command": "apply_firewall",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:56:00+00:00",
10      "id": 14,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 42,
15          "type": "server"
16        },
17        {
18          "id": 38,
19          "type": "firewall"
20        }
21      ],
22      "started": "2016-01-30T23:55:00+00:00",
23      "status": "success"
24    }
25  ]
26}

Remove from Resources

Removes one Firewall from multiple resources.

Currently only Servers (and their public network interfaces) are supported.

Call specific error codes

Code Description
firewall_already_removed Firewall was already removed from the resource
firewall_resource_not_found The resource the Firewall should be attached to was not found
firewall_managed_by_label_selector Firewall was applied via label selector and cannot be removed manually

HTTP Request

POST /firewalls/{id}/actions/remove_from_resources

Path Parameters

  • idinteger (int64) required

    ID of the Firewall

Request

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"remove_from":[{"server":{"id":42},"type":"server"}]}' \
6	"https://api.hetzner.cloud/v1/firewalls/$ID/actions/remove_from_resources"

Request

1{
2  "remove_from": [
3    {
4      "server": {
5        "id": 42
6      },
7      "type": "server"
8    }
9  ]
10}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "actions": [
3    {
4      "command": "remove_firewall",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:56:00+00:00",
10      "id": 14,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 42,
15          "type": "server"
16        },
17        {
18          "id": 38,
19          "type": "firewall"
20        }
21      ],
22      "started": "2016-01-30T23:55:00+00:00",
23      "status": "success"
24    }
25  ]
26}

Set Rules

Sets the rules of a Firewall.

All existing rules will be overwritten. Pass an empty rules array to remove all rules. The maximum amount of rules that can be defined is 50.

Call specific error codes

Code Description
firewall_resource_not_found The resource the Firewall should be attached to was not found

HTTP Request

POST /firewalls/{id}/actions/set_rules

Path Parameters

  • idinteger (int64) required

    ID of the Firewall

Request

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"rules":[{"description":"Allow port 80","direction":"in","port":"80","protocol":"tcp","source_ips":["28.239.13.1/32","28.239.14.0/24","ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"]}]}' \
6	"https://api.hetzner.cloud/v1/firewalls/$ID/actions/set_rules"

Request

1{
2  "rules": [
3    {
4      "description": "Allow port 80",
5      "direction": "in",
6      "port": "80",
7      "protocol": "tcp",
8      "source_ips": [
9        "28.239.13.1/32",
10        "28.239.14.0/24",
11        "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
12      ]
13    }
14  ]
15}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "actions": [
3    {
4      "command": "set_firewall_rules",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:56:00+00:00",
10      "id": 13,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 38,
15          "type": "firewall"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    },
21    {
22      "command": "apply_firewall",
23      "error": {
24        "code": "action_failed",
25        "message": "Action failed"
26      },
27      "finished": "2016-01-30T23:56:00+00:00",
28      "id": 14,
29      "progress": 100,
30      "resources": [
31        {
32          "id": 38,
33          "type": "firewall"
34        },
35        {
36          "id": 42,
37          "type": "server"
38        }
39      ],
40      "started": "2016-01-30T23:55:00+00:00",
41      "status": "success"
42    }
43  ]
44}

Get an Action for a Firewall

Returns a specific Action for a Firewall.

HTTP Request

GET /firewalls/{id}/actions/{action_id}

Path Parameters

  • idinteger (int64) required

    ID of the Firewall

  • action_idinteger (int64) required

    ID of the Action

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/firewalls/$ID/actions/$ACTION_ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "set_firewall_rules",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 38,
14        "type": "firewall"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Floating IPs

Floating IPs help you to create highly available setups. You can assign a Floating IP to any Server. The Server can then use this IP. You can reassign it to a different Server at any time, or you can choose to unassign the IP from Servers all together.

Floating IPs can be used globally. This means you can assign a Floating IP to a Server in one Location and later reassign it to a Server in a different Location. For optimal routing and latency Floating IPs should be used in the Location they were created in.

For Floating IPs to work with your Server, you must configure them inside your operation system.

Floating IPs of type ipv4 use a single IPv4 address as their ip property. Floating IPs of type ipv6 use a /64 network such as fc00::/64 as their ip property. Any IP address within that network can be used on your host.

Floating IPs are billed on a monthly basis.

Get all Floating IPs

Returns all Floating IP objects.

HTTP Request

GET /floating_ips

Query Parameters

  • namestring

    Can be used to filter Floating IPs by their name. The response will only contain the Floating IP matching the specified name.

  • label_selectorstring

    Can be used to filter Floating IPs by labels. The response will only contain Floating IPs matching the label selector.

  • sortstring
    Possible enum values:
    idid:ascid:desccreatedcreated:asccreated:desc

    Can be used multiple times. Choices id id:asc id:desc created created:asc created:desc

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/floating_ips"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "floating_ips": [
3    {
4      "blocked": false,
5      "created": "2016-01-30T23:55:00+00:00",
6      "description": "this describes my resource",
7      "dns_ptr": [
8        {
9          "dns_ptr": "server.example.com",
10          "ip": "2001:db8::1"
11        }
12      ],
13      "home_location": {
14        "city": "Falkenstein",
15        "country": "DE",
16        "description": "Falkenstein DC Park 1",
17        "id": 1,
18        "latitude": 50.47612,
19        "longitude": 12.370071,
20        "name": "fsn1",
21        "network_zone": "eu-central"
22      },
23      "id": 42,
24      "ip": "131.232.99.1",
25      "labels": {},
26      "name": "my-resource",
27      "protection": {
28        "delete": false
29      },
30      "server": 42,
31      "type": "ipv4"
32    }
33  ],
34  "meta": {
35    "pagination": {
36      "last_page": 4,
37      "next_page": 4,
38      "page": 3,
39      "per_page": 25,
40      "previous_page": 2,
41      "total_entries": 100
42    }
43  }
44}

Create a Floating IP

Creates a new Floating IP assigned to a Server. If you want to create a Floating IP that is not bound to a Server, you need to provide the home_location key instead of server . This can be either the ID or the name of the Location this IP shall be created in. Note that a Floating IP can be assigned to a Server in any Location later on. For optimal routing it is advised to use the Floating IP in the same Location it was created in.

HTTP Request

POST /floating_ips

Request

The type argument is required while home_location and server are mutually exclusive.

  • descriptionstring
  • home_locationstring

    Home Location (routing is optimized for that Location). Only optional if Server argument is passed.

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring
  • serverinteger (int64)

    ID of the Server to assign the Floating IP to

  • typestring required
    Possible enum values:
    ipv4ipv6

    Floating IP type

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"description":"Web Frontend","home_location":"fsn1","labels":{"labelkey":"value"},"name":"Web Frontend","server":42,"type":"ipv4"}' \
6	"https://api.hetzner.cloud/v1/floating_ips"

Request

1{
2  "description": "Web Frontend",
3  "home_location": "fsn1",
4  "labels": {
5    "labelkey": "value"
6  },
7  "name": "Web Frontend",
8  "server": 42,
9  "type": "ipv4"
10}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "create_floating_ip",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": null,
9    "id": 13,
10    "progress": 0,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      }
16    ],
17    "started": "2016-01-30T23:50:00+00:00",
18    "status": "running"
19  },
20  "floating_ip": {
21    "blocked": false,
22    "created": "2016-01-30T23:50:00+00:00",
23    "description": "Web Frontend",
24    "dns_ptr": [
25      {
26        "dns_ptr": "server.example.com",
27        "ip": "2001:db8::1"
28      }
29    ],
30    "home_location": {
31      "city": "Falkenstein",
32      "country": "DE",
33      "description": "Falkenstein DC Park 1",
34      "id": 1,
35      "latitude": 50.47612,
36      "longitude": 12.370071,
37      "name": "fsn1",
38      "network_zone": "eu-central"
39    },
40    "id": 4711,
41    "ip": "131.232.99.1",
42    "labels": {
43      "env": "dev"
44    },
45    "name": "Web Frontend",
46    "protection": {
47      "delete": false
48    },
49    "server": 42,
50    "type": "ipv4"
51  }
52}

Delete a Floating IP

Deletes a Floating IP. If it is currently assigned to a Server it will automatically get unassigned.

HTTP Request

DELETE /floating_ips/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

Example curl

1curl \
2	-X DELETE \
3	-H "Authorization: Bearer $API_TOKEN" \
4	"https://api.hetzner.cloud/v1/floating_ips/$ID"

Response headers

1Status: 204

Get a Floating IP

Returns a specific Floating IP object.

HTTP Request

GET /floating_ips/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/floating_ips/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "floating_ip": {
3    "blocked": false,
4    "created": "2016-01-30T23:55:00+00:00",
5    "description": "this describes my resource",
6    "dns_ptr": [
7      {
8        "dns_ptr": "server.example.com",
9        "ip": "2001:db8::1"
10      }
11    ],
12    "home_location": {
13      "city": "Falkenstein",
14      "country": "DE",
15      "description": "Falkenstein DC Park 1",
16      "id": 1,
17      "latitude": 50.47612,
18      "longitude": 12.370071,
19      "name": "fsn1",
20      "network_zone": "eu-central"
21    },
22    "id": 42,
23    "ip": "131.232.99.1",
24    "labels": {},
25    "name": "my-resource",
26    "protection": {
27      "delete": false
28    },
29    "server": 42,
30    "type": "ipv4"
31  }
32}

Update a Floating IP

Updates the description or labels of a Floating IP. Also note that when updating labels, the Floating IP’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

HTTP Request

PUT /floating_ips/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

Request

  • descriptionstring

    New Description to set

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New unique name to set

Response

Example curl

1curl \
2	-X PUT \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"description":"Web Frontend","labels":{"labelkey":"value"},"name":"Web Frontend"}' \
6	"https://api.hetzner.cloud/v1/floating_ips/$ID"

Request

1{
2  "description": "Web Frontend",
3  "labels": {
4    "labelkey": "value"
5  },
6  "name": "Web Frontend"
7}

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "floating_ip": {
3    "blocked": false,
4    "created": "2016-01-30T23:50:00+00:00",
5    "description": "Web Frontend",
6    "dns_ptr": [
7      {
8        "dns_ptr": "server.example.com",
9        "ip": "2001:db8::1"
10      }
11    ],
12    "home_location": {
13      "city": "Falkenstein",
14      "country": "DE",
15      "description": "Falkenstein DC Park 1",
16      "id": 1,
17      "latitude": 50.47612,
18      "longitude": 12.370071,
19      "name": "fsn1",
20      "network_zone": "eu-central"
21    },
22    "id": 4711,
23    "ip": "131.232.99.1",
24    "labels": {
25      "labelkey": "value"
26    },
27    "name": "Web Frontend",
28    "protection": {
29      "delete": false
30    },
31    "server": 42,
32    "type": "ipv4"
33  }
34}

Floating IP Actions

Get all Actions

Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.

HTTP Request

GET /floating_ips/actions

Query Parameters

  • idinteger (int64)

    Can be used multiple times, the response will contain only Actions with specified IDs.

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/floating_ips/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "start_resource",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:55:00+00:00",
10      "id": 42,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 42,
15          "type": "server"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns a specific Action object.

HTTP Request

GET /floating_ips/actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Action.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/floating_ips/actions/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "start_resource",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:55:00+00:00",
9    "id": 42,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Get all Actions for a Floating IP

Returns all Action objects for a Floating IP. You can sort the results by using the sort URI parameter, and filter them with the status parameter.

HTTP Request

GET /floating_ips/{id}/actions

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

Query Parameters

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/floating_ips/$ID/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "assign_floating_ip",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:56:00+00:00",
10      "id": 13,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 4711,
15          "type": "server"
16        },
17        {
18          "id": 4712,
19          "type": "floating_ip"
20        }
21      ],
22      "started": "2016-01-30T23:55:00+00:00",
23      "status": "success"
24    }
25  ]
26}

Assign a Floating IP to a Server

Assigns a Floating IP to a Server.

HTTP Request

POST /floating_ips/{id}/actions/assign

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

Request

  • serverinteger (int64) required

    ID of the Server the Floating IP shall be assigned to

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"server":42}' \
6	"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/assign"

Request

1{
2  "server": 42
3}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "assign_floating_ip",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      },
16      {
17        "id": 4711,
18        "type": "floating_ip"
19      }
20    ],
21    "started": "2016-01-30T23:55:00+00:00",
22    "status": "success"
23  }
24}

Change reverse DNS entry for a Floating IP

Changes the hostname that will appear when getting the hostname belonging to this Floating IP.

HTTP Request

POST /floating_ips/{id}/actions/change_dns_ptr

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

Request

Select the IP address for which to change the DNS entry by passing ip . For a Floating IP of type ipv4 this must exactly match the IP address of the Floating IP. For a Floating IP of type ipv6 this must be a single IP within the IPv6 /64 range that belongs to this Floating IP. You can add up to 100 IPv6 reverse DNS entries.

The target hostname is set by passing dns_ptr .

  • dns_ptrstring – nullablerequired

    Hostname to set as a reverse DNS PTR entry, will reset to original default value if null

  • ipstring required

    IP address for which to set the reverse DNS entry

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"dns_ptr":"server02.example.com","ip":"1.2.3.4"}' \
6	"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/change_dns_ptr"

Request

1{
2  "dns_ptr": "server02.example.com",
3  "ip": "1.2.3.4"
4}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "change_dns_ptr",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 4711,
14        "type": "floating_ip"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Change Floating IP Protection

Changes the protection configuration of the Floating IP.

HTTP Request

POST /floating_ips/{id}/actions/change_protection

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

Request

  • deleteboolean

    If true, prevents the Floating IP from being deleted

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"delete":true}' \
6	"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/change_protection"

Request

1{
2  "delete": true
3}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "change_protection",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 4711,
14        "type": "floating_ip"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Unassign a Floating IP

Unassigns a Floating IP, resulting in it being unreachable. You may assign it to a Server again at a later time.

HTTP Request

POST /floating_ips/{id}/actions/unassign

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/unassign"

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "unassign_floating_ip",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      },
16      {
17        "id": 4711,
18        "type": "floating_ip"
19      }
20    ],
21    "started": "2016-01-30T23:55:00+00:00",
22    "status": "success"
23  }
24}

Get an Action for a Floating IP

Returns a specific Action object for a Floating IP.

HTTP Request

GET /floating_ips/{id}/actions/{action_id}

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP

  • action_idinteger (int64) required

    ID of the Action

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/floating_ips/$ID/actions/$ACTION_ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "assign_floating_ip",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      },
16      {
17        "id": 4711,
18        "type": "floating_ip"
19      }
20    ],
21    "started": "2016-01-30T23:55:00+00:00",
22    "status": "success"
23  }
24}

Images

Images are blueprints for your VM disks. They can be of different types:

System Images

Distribution Images maintained by us, e.g. “Ubuntu 20.04”

Snapshot Images

Maintained by you, for example “Ubuntu 20.04 with my own settings”. These are billed per GB per month.

Backup Images

Daily Backups of your Server. Will automatically be created for Servers which have backups enabled (POST /servers/{id}/actions/enable_backup)

Bound to exactly one Server. If you delete the Server, you also delete all backups bound to it. You may convert backup Images to snapshot Images to keep them.

These are billed at 20% of your instance price for 7 backup slots.

App Images

Prebuild images with specific software configurations, e.g. “Wordpress”. All app images are created by us.

Get all Images

Returns all Image objects. You can select specific Image types only and sort the results by using URI parameters.

HTTP Request

GET /images

Query Parameters

  • sortstring
    Possible enum values:
    idid:ascid:descnamename:ascname:desccreatedcreated:asccreated:desc

    Can be used multiple times.

  • typestring
    Possible enum values:
    systemsnapshotbackupapp

    Can be used multiple times.

  • statusstring
    Possible enum values:
    availablecreating

    Can be used multiple times. The response will only contain Images matching the status.

  • bound_tostring

    Can be used multiple times. Server ID linked to the Image. Only available for Images of type backup

  • include_deprecatedboolean

    Can be used multiple times.

  • namestring

    Can be used to filter resources by their name. The response will only contain the resources matching the specified name

  • label_selectorstring

    Can be used to filter resources by labels. The response will only contain resources matching the label selector.

  • architecturestring

    Return only Images with the given architecture.

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/images"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "images": [
3    {
4      "architecture": "x86",
5      "bound_to": null,
6      "created": "2016-01-30T23:55:00+00:00",
7      "created_from": {
8        "id": 1,
9        "name": "Server"
10      },
11      "deleted": null,
12      "deprecated": "2018-02-28T00:00:00+00:00",
13      "description": "Ubuntu 20.04 Standard 64 bit",
14      "disk_size": 10,
15      "id": 42,
16      "image_size": 2.3,
17      "labels": {},
18      "name": "ubuntu-20.04",
19      "os_flavor": "ubuntu",
20      "os_version": "20.04",
21      "protection": {
22        "delete": false
23      },
24      "rapid_deploy": false,
25      "status": "available",
26      "type": "snapshot"
27    }
28  ],
29  "meta": {
30    "pagination": {
31      "last_page": 4,
32      "next_page": 4,
33      "page": 3,
34      "per_page": 25,
35      "previous_page": 2,
36      "total_entries": 100
37    }
38  }
39}

Delete an Image

Deletes an Image. Only Images of type snapshot and backup can be deleted.

HTTP Request

DELETE /images/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Image

Example curl

1curl \
2	-X DELETE \
3	-H "Authorization: Bearer $API_TOKEN" \
4	"https://api.hetzner.cloud/v1/images/$ID"

Response headers

1Status: 204

Get an Image

Returns a specific Image object.

HTTP Request

GET /images/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Image

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/images/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "image": {
3    "architecture": "x86",
4    "bound_to": null,
5    "created": "2016-01-30T23:55:00+00:00",
6    "created_from": {
7      "id": 1,
8      "name": "Server"
9    },
10    "deleted": null,
11    "deprecated": "2018-02-28T00:00:00+00:00",
12    "description": "Ubuntu 20.04 Standard 64 bit",
13    "disk_size": 10,
14    "id": 42,
15    "image_size": 2.3,
16    "labels": {},
17    "name": "ubuntu-20.04",
18    "os_flavor": "ubuntu",
19    "os_version": "20.04",
20    "protection": {
21      "delete": false
22    },
23    "rapid_deploy": false,
24    "status": "available",
25    "type": "snapshot"
26  }
27}

Update an Image

Updates the Image. You may change the description, convert a Backup Image to a Snapshot Image or change the Image labels. Only Images of type snapshot and backup can be updated.

Note that when updating labels, the current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

HTTP Request

PUT /images/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Image

Request

  • descriptionstring

    New description of Image

  • labelsobject

    User-defined labels (key-value pairs)

  • typestring
    Possible enum values:
    snapshot

    Destination Image type to convert to

Response

Example curl

1curl \
2	-X PUT \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"description":"My new Image description","labels":{"labelkey":"value"},"type":"snapshot"}' \
6	"https://api.hetzner.cloud/v1/images/$ID"

Request

1{
2  "description": "My new Image description",
3  "labels": {
4    "labelkey": "value"
5  },
6  "type": "snapshot"
7}

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "image": {
3    "architecture": "x86",
4    "bound_to": null,
5    "created": "2016-01-30T23:50:00+00:00",
6    "created_from": {
7      "id": 1,
8      "name": "Server"
9    },
10    "deleted": null,
11    "deprecated": "2018-02-28T00:00:00+00:00",
12    "description": "My new Image description",
13    "disk_size": 10,
14    "id": 4711,
15    "image_size": 2.3,
16    "labels": {
17      "labelkey": "value"
18    },
19    "name": null,
20    "os_flavor": "ubuntu",
21    "os_version": "20.04",
22    "protection": {
23      "delete": false
24    },
25    "rapid_deploy": false,
26    "status": "available",
27    "type": "snapshot"
28  }
29}

Image Actions

Get all Actions

Returns all Action objects. You can sort the results by using the sort URI parameter, and filter them with the status and id parameter.

HTTP Request

GET /images/actions

Query Parameters

  • idinteger (int64)

    Can be used multiple times, the response will contain only Actions with specified IDs.

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/images/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "start_resource",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:55:00+00:00",
10      "id": 42,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 42,
15          "type": "server"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns a specific Action object.

HTTP Request

GET /images/actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Resource

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/images/actions/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "start_resource",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:55:00+00:00",
9    "id": 42,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 42,
14        "type": "server"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Get all Actions for an Image

Returns all Action objects for an Image. You can sort the results by using the sort URI parameter, and filter them with the status parameter.

HTTP Request

GET /images/{id}/actions

Path Parameters

  • idinteger (int64) required

    ID of the Image

Query Parameters

  • sortstring
    Possible enum values:
    idid:ascid:desccommandcommand:asccommand:descstatusstatus:ascstatus:descstartedstarted:ascstarted:descfinishedfinished:ascfinished:desc

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

    Can be used multiple times, the response will contain only Actions with specified statuses

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/images/$ID/actions"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "actions": [
3    {
4      "command": "change_protection",
5      "error": {
6        "code": "action_failed",
7        "message": "Action failed"
8      },
9      "finished": "2016-01-30T23:56:00+00:00",
10      "id": 13,
11      "progress": 100,
12      "resources": [
13        {
14          "id": 4711,
15          "type": "image"
16        }
17      ],
18      "started": "2016-01-30T23:55:00+00:00",
19      "status": "success"
20    }
21  ]
22}

Change Image Protection

Changes the protection configuration of the Image. Can only be used on snapshots.

HTTP Request

POST /images/{id}/actions/change_protection

Path Parameters

  • idinteger (int64) required

    ID of the Image

Request

  • deleteboolean

    If true, prevents the snapshot from being deleted

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"delete":true}' \
6	"https://api.hetzner.cloud/v1/images/$ID/actions/change_protection"

Request

1{
2  "delete": true
3}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "change_protection",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 4711,
14        "type": "image"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

Get an Action for an Image

Returns a specific Action for an Image.

HTTP Request

GET /images/{id}/actions/{action_id}

Path Parameters

  • idinteger (int64) required

    ID of the Image

  • action_idinteger (int64) required

    ID of the Action

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/images/$ID/actions/$ACTION_ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "action": {
3    "command": "change_protection",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 4711,
14        "type": "image"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  }
20}

ISOs

ISOs are read-only Images of DVDs. While we recommend using our Image functionality to install your Servers we also provide some stock ISOs so you can install more exotic operating systems by yourself.

On request our support uploads a private ISO just for you. These are marked with type private and only visible in your Project.

To attach an ISO to your Server use POST /servers/{id}/actions/attach_iso.

Get all ISOs

Returns all available ISO objects.

HTTP Request

GET /isos

Query Parameters

  • namestring

    Can be used to filter ISOs by their name. The response will only contain the ISO matching the specified name.

  • architecturestring

    Return only ISOs with the given architecture.

  • include_architecture_wildcardboolean

    Include Images with wildcard architecture (architecture is null). Works only if architecture filter is specified.

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/isos"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "isos": [
3    {
4      "architecture": "x86",
5      "deprecated": "2018-02-28T00:00:00+00:00",
6      "deprecation": {
7        "announced": "2023-06-01T00:00:00+00:00",
8        "unavailable_after": "2023-09-01T00:00:00+00:00"
9      },
10      "description": "FreeBSD 11.0 x64",
11      "id": 42,
12      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
13      "type": "public"
14    }
15  ],
16  "meta": {
17    "pagination": {
18      "last_page": 4,
19      "next_page": 4,
20      "page": 3,
21      "per_page": 25,
22      "previous_page": 2,
23      "total_entries": 100
24    }
25  }
26}

Get an ISO

Returns a specific ISO object.

HTTP Request

GET /isos/{id}

Path Parameters

  • idinteger (int64) required

    ID of the ISO

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/isos/$ID"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "iso": {
3    "architecture": "x86",
4    "deprecated": "2018-02-28T00:00:00+00:00",
5    "deprecation": {
6      "announced": "2023-06-01T00:00:00+00:00",
7      "unavailable_after": "2023-09-01T00:00:00+00:00"
8    },
9    "description": "FreeBSD 11.0 x64",
10    "id": 42,
11    "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
12    "type": "public"
13  }
14}

Load Balancers

Get all Load Balancers

Gets all existing Load Balancers that you have available.

HTTP Request

GET /load_balancers

Query Parameters

  • sortstring
    Possible enum values:
    idid:ascid:descnamename:ascname:desccreatedcreated:asccreated:desc

    Can be used multiple times.

  • namestring

    Can be used to filter resources by their name. The response will only contain the resources matching the specified name

  • label_selectorstring

    Can be used to filter resources by labels. The response will only contain resources matching the label selector.

  • pageinteger (int64)

    Page to load.

  • per_pageinteger (int64)

    Items to load per page.

Response

Example curl

1curl \
2	-H "Authorization: Bearer $API_TOKEN" \
3	"https://api.hetzner.cloud/v1/load_balancers"

Response headers

1Content-Type: application/json
2Status: 200

Response sample

1{
2  "load_balancers": [
3    {
4      "algorithm": {
5        "type": "round_robin"
6      },
7      "created": "2016-01-30T23:55:00+00:00",
8      "id": 42,
9      "included_traffic": 10000,
10      "ingoing_traffic": null,
11      "labels": {},
12      "load_balancer_type": {
13        "deprecated": "2016-01-30T23:50:00+00:00",
14        "description": "LB11",
15        "id": 1,
16        "max_assigned_certificates": 10,
17        "max_connections": 20000,
18        "max_services": 5,
19        "max_targets": 25,
20        "name": "lb11",
21        "prices": [
22          {
23            "location": "fsn1",
24            "price_hourly": {
25              "gross": "1.1900000000000000",
26              "net": "1.0000000000"
27            },
28            "price_monthly": {
29              "gross": "1.1900000000000000",
30              "net": "1.0000000000"
31            }
32          }
33        ]
34      },
35      "location": {
36        "city": "Falkenstein",
37        "country": "DE",
38        "description": "Falkenstein DC Park 1",
39        "id": 1,
40        "latitude": 50.47612,
41        "longitude": 12.370071,
42        "name": "fsn1",
43        "network_zone": "eu-central"
44      },
45      "name": "my-resource",
46      "outgoing_traffic": null,
47      "private_net": [
48        {
49          "ip": "10.0.0.2",
50          "network": 4711
51        }
52      ],
53      "protection": {
54        "delete": false
55      },
56      "public_net": {
57        "enabled": false,
58        "ipv4": {
59          "dns_ptr": "lb1.example.com",
60          "ip": "1.2.3.4"
61        },
62        "ipv6": {
63          "dns_ptr": "lb1.example.com",
64          "ip": "2001:db8::1"
65        }
66      },
67      "services": [
68        {
69          "destination_port": 80,
70          "health_check": {
71            "http": {
72              "domain": "example.com",
73              "path": "/",
74              "response": "{\"status\": \"ok\"}",
75              "status_codes": [
76                "2??",
77                "3??"
78              ],
79              "tls": false
80            },
81            "interval": 15,
82            "port": 4711,
83            "protocol": "http",
84            "retries": 3,
85            "timeout": 10
86          },
87          "http": {
88            "certificates": [
89              897
90            ],
91            "cookie_lifetime": 300,
92            "cookie_name": "HCLBSTICKY",
93            "redirect_http": true,
94            "sticky_sessions": true
95          },
96          "listen_port": 443,
97          "protocol": "https",
98          "proxyprotocol": false
99        }
100      ],
101      "targets": [
102        {
103          "health_status": [
104            {
105              "listen_port": 443,
106              "status": "healthy"
107            }
108          ],
109          "ip": {
110            "ip": "203.0.113.1"
111          },
112          "label_selector": {
113            "selector": "env=prod"
114          },
115          "server": {
116            "id": 80
117          },
118          "targets": [
119            {
120              "health_status": [
121                {
122                  "listen_port": 443,
123                  "status": "healthy"
124                }
125              ],
126              "server": {
127                "id": 80
128              },
129              "type": "server",
130              "use_private_ip": false
131            }
132          ],
133          "type": "server",
134          "use_private_ip": false
135        }
136      ]
137    }
138  ],
139  "meta": {
140    "pagination": {
141      "last_page": 4,
142      "next_page": 4,
143      "page": 3,
144      "per_page": 25,
145      "previous_page": 2,
146      "total_entries": 100
147    }
148  }
149}

Create a Load Balancer

Creates a Load Balancer.

Call specific error codes

Code Description
cloud_resource_ip_not_allowed The IP you are trying to add as a target belongs to a Hetzner Cloud resource
ip_not_owned The IP is not owned by the owner of the project of the Load Balancer
load_balancer_not_attached_to_network The Load Balancer is not attached to a network
robot_unavailable Robot was not available. The caller may retry the operation after a short delay.
server_not_attached_to_network The server you are trying to add as a target is not attached to the same network as the Load Balancer
source_port_already_used The source port you are trying to add is already in use
target_already_defined The Load Balancer target you are trying to define is already defined

HTTP Request

POST /load_balancers

Request

  • load_balancer_typestring required

    ID or name of the Load Balancer type this Load Balancer should be created with

  • locationstring

    ID or name of Location to create Load Balancer in

  • namestring required

    Name of the Load Balancer

  • networkinteger (int64)

    ID of the network the Load Balancer should be attached to on creation

  • network_zonestring

    Name of network zone

  • public_interfaceboolean

    Enable or disable the public interface of the Load Balancer

Response

Example curl

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"algorithm":{"type":"round_robin"},"labels":{"labelkey":"value"},"load_balancer_type":"lb11","location":"string","name":"Web Frontend","network":123,"network_zone":"eu-central","public_interface":true,"services":[{"destination_port":80,"health_check":{"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false},"interval":15,"port":4711,"protocol":"http","retries":3,"timeout":10},"http":{"certificates":[897],"cookie_lifetime":300,"cookie_name":"HCLBSTICKY","redirect_http":true,"sticky_sessions":true},"listen_port":443,"protocol":"https","proxyprotocol":false}],"targets":[{"health_status":[{"listen_port":443,"status":"healthy"}],"ip":{"ip":"203.0.113.1"},"label_selector":{"selector":"env=prod"},"server":{"id":80},"targets":[{"health_status":[{"listen_port":443,"status":"healthy"}],"server":{"id":80},"type":"server","use_private_ip":false}],"type":"server","use_private_ip":false}]}' \
6	"https://api.hetzner.cloud/v1/load_balancers"

Request

1{
2  "algorithm": {
3    "type": "round_robin"
4  },
5  "labels": {
6    "labelkey": "value"
7  },
8  "load_balancer_type": "lb11",
9  "location": "string",
10  "name": "Web Frontend",
11  "network": 123,
12  "network_zone": "eu-central",
13  "public_interface": true,
14  "services": [
15    {
16      "destination_port": 80,
17      "health_check": {
18        "http": {
19          "domain": "example.com",
20          "path": "/",
21          "response": "{\"status\": \"ok\"}",
22          "status_codes": [
23            "2??",
24            "3??"
25          ],
26          "tls": false
27        },
28        "interval": 15,
29        "port": 4711,
30        "protocol": "http",
31        "retries": 3,
32        "timeout": 10
33      },
34      "http": {
35        "certificates": [
36          897
37        ],
38        "cookie_lifetime": 300,
39        "cookie_name": "HCLBSTICKY",
40        "redirect_http": true,
41        "sticky_sessions": true
42      },
43      "listen_port": 443,
44      "protocol": "https",
45      "proxyprotocol": false
46    }
47  ],
48  "targets": [
49    {
50      "health_status": [
51        {
52          "listen_port": 443,
53          "status": "healthy"
54        }
55      ],
56      "ip": {
57        "ip": "203.0.113.1"
58      },
59      "label_selector": {
60        "selector": "env=prod"
61      },
62      "server": {
63        "id": 80
64      },
65      "targets": [
66        {
67          "health_status": [
68            {
69              "listen_port": 443,
70              "status": "healthy"
71            }
72          ],
73          "server": {
74            "id": 80
75          },
76          "type": "server",
77          "use_private_ip": false
78        }
79      ],
80      "type": "server",
81      "use_private_ip": false
82    }
83  ]
84}

Response headers

1Content-Type: application/json
2Status: 201

Response sample

1{
2  "action": {
3    "command": "create_load_balancer",
4    "error": {
5      "code": "action_failed",
6      "message": "Action failed"
7    },
8    "finished": "2016-01-30T23:56:00+00:00",
9    "id": 13,
10    "progress": 100,
11    "resources": [
12      {
13        "id": 4711,
14        "type": "load_balancer"
15      }
16    ],
17    "started": "2016-01-30T23:55:00+00:00",
18    "status": "success"
19  },
20  "load_balancer": {
21    "algorithm": {
22      "type": "round_robin"
23    },
24    "created": "2016-01-30T23:50:00+00:00",
25    "id": 4711,
26    "included_traffic": 654321,
27    "ingoing_traffic": 123456,
28    "labels": {
29      "env": "dev"
30    },
31    "load_balancer_type": {
32      "deprecated": "2016-01-30T23:50:00+00:00",
33      "description": "LB11",
34      "id": 1,
35      "max_assigned_certificates": 10,
36      "max_connections": 20000,
37      "max_services": 5,
38      "max_targets": 25,
39      "name": "lb11",
40      "prices": [
41        {
42          "location": "fsn1",
43          "price_hourly": {
44            "gross": "1.1900000000000000",
45            "net": "1.0000000000"
46          },
47          "price_monthly": {
48            "gross": "1.1900000000000000",
49            "net": "1.0000000000"
50          }
51        }
52      ]
53    },
54    "location": {
55      "city": "Falkenstein",
56      "country": "DE",
57      "description": "Falkenstein DC Park 1",
58      "id": 1,
59      "latitude": 50.47612,
60      "longitude": 12.370071,
61      "name": "fsn1",
62      "network_zone": "eu-central"
63    },
64    "name": "Web Frontend",
65    "outgoing_traffic": 123456,
66    "private_net": [
67      {
68        "ip": "10.0.0.2",
69        "network": 4711
70      }
71    ],
72    "protection": {
73      "delete": false
74    },
75    "public_net": {
76      "enabled": false,
77      "ipv4": {
78        "ip": "1.2.3.4"
79      },
80      "ipv6": {
81        "ip": "2001:db8::1"
82      }
83    },
84    "services": [
85      {
86        "destination_port": 80,
87        "health_check": {
88          "http": {
89            "domain": "example.com",
90            "path": "/",
91            "response": "{\"status\": \"ok\"}",
92            "status_codes": [
93              "2??,3??"
94            ],
95            "tls": false
96          },
97          "interval": 15,
98          "port": 4711,
99          "protocol": "http",
100          "retries": 3,
101          "timeout": 10
102        },
103        "http": {
104          "certificates": [
105            897
106          ],
107          "cookie_lifetime": 300,
108          "cookie_name": "HCLBSTICKY",
109          "redirect_http": true,
110          "sticky_sessions": true
111        },
112        "listen_port": 443,
113        "protocol": "http",
114        "proxyprotocol": false
115      }
116    ],
117    "targets": [
118      {
119        "health_status": [
120          {
121            "listen_port": 443,