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 (e.g. not available for order)
server_error Error within the API backend
service_error Error within a service
uniqueness_error One or more of the objects fields must be unique
protected The Action you are trying to start is protected for this resource
maintenance Cannot perform operation due to maintenance
conflict The resource has changed during the request, please retry
unsupported_error The corresponding resource does not support the Action
token_readonly The token is only allowed to perform GET requests
unavailable A service or product is currently not available

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)

    Filter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.

  • sortstring
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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": "running"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns a specific Action object.

HTTP Request

GET /actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Action.

Response

Example request

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": "running"
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
    Allowed: id id:asc id:desc name name:asc name:desc created created:asc created:desc

    Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".

  • namestring

    Filter resources by their name. The response will only contain the resources matching the specified name.

  • label_selectorstring

    Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".

  • typestring
    Allowed: uploaded managed

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

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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  "meta": {
30    "pagination": {
31      "last_page": 1,
32      "next_page": null,
33      "page": 1,
34      "per_page": 25,
35      "previous_page": null,
36      "total_entries": 21
37    }
38  }
39}

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) for the Resource. For more information, see "Labels".

  • namestring required

    Name of the Certificate

  • private_keystring

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

  • typestring
    Allowed: uploaded managedDefault: uploaded

    Choose between uploading a Certificate in PEM format or requesting a managed Let's Encrypt Certificate.

Response

Example request

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 Certificate.

Example request

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 Certificate.

Response

Example request

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 Certificate.

Request

  • labelsobject

    User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".

  • namestring

    New Certificate name

Response

Example request

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

Request

1{
2  "labels": {
3    "environment": "prod",
4    "example.com/my": "label",
5    "just-a-key": ""
6  },
7  "name": "my website cert"
8}

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)

    Filter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.

  • sortstring
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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": "running"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

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 request

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": "running"
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 Certificate.

Query Parameters

  • sortstring
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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  "meta": {
23    "pagination": {
24      "last_page": 1,
25      "next_page": null,
26      "page": 1,
27      "per_page": 25,
28      "previous_page": null,
29      "total_entries": 21
30    }
31  }
32}

Retry 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 request

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 request

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 Datacenters.

HTTP Request

GET /datacenters

Query Parameters

  • namestring

    Filter resources by their name. The response will only contain the resources matching the specified name.

  • sortstring
    Allowed: id id:asc id:desc name name:asc name:desc

    Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

  • recommendationinteger (int64) required

    Recommended Datacenter for creating new resources.

Example request

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": 42,
11        "latitude": 50.47612,
12        "longitude": 12.370071,
13        "name": "fsn1",
14        "network_zone": "eu-central"
15      },
16      "name": "fsn1-dc8",
17      "server_types": {
18        "available": [
19          1,
20          2,
21          3
22        ],
23        "available_for_migration": [
24          1,
25          2,
26          3
27        ],
28        "supported": [
29          1,
30          2,
31          3
32        ]
33      }
34    }
35  ],
36  "meta": {
37    "pagination": {
38      "last_page": 4,
39      "next_page": 4,
40      "page": 3,
41      "per_page": 25,
42      "previous_page": 2,
43      "total_entries": 100
44    }
45  },
46  "recommendation": 1
47}

Get a Datacenter

Returns a single Datacenter.

HTTP Request

GET /datacenters/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Datacenter.

Response

Example request

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": 42,
10      "latitude": 50.47612,
11      "longitude": 12.370071,
12      "name": "fsn1",
13      "network_zone": "eu-central"
14    },
15    "name": "fsn1-dc8",
16    "server_types": {
17      "available": [
18        1,
19        2,
20        3
21      ],
22      "available_for_migration": [
23        1,
24        2,
25        3
26      ],
27      "supported": [
28        1,
29        2,
30        3
31      ]
32    }
33  }
34}

Firewalls

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 Firewalls.

Use the provided URI parameters to modify the result.

HTTP Request

GET /firewalls

Query Parameters

  • sortstring
    Allowed: id id:asc id:desc name name:asc name:desc created created:asc created:desc

    Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".

  • namestring

    Filter resources by their name. The response will only contain the resources matching the specified name.

  • label_selectorstring

    Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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        "environment": "prod",
27        "example.com/my": "label",
28        "just-a-key": ""
29      },
30      "name": "new-name",
31      "rules": [
32        {
33          "description": null,
34          "destination_ips": [],
35          "direction": "in",
36          "port": "80",
37          "protocol": "tcp",
38          "source_ips": [
39            "28.239.13.1/32",
40            "28.239.14.0/24",
41            "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
42          ]
43        }
44      ]
45    }
46  ],
47  "meta": {
48    "pagination": {
49      "last_page": 4,
50      "next_page": 4,
51      "page": 3,
52      "per_page": 25,
53      "previous_page": 2,
54      "total_entries": 100
55    }
56  }
57}

Create a Firewall

Create a Firewall.

Error Codes specific to this Call

Code Description
server_already_added Server applied more than once
incompatible_network_type The resources network type is not supported by Firewalls
firewall_resource_not_found The resource the Firewall should be attached to was not found

HTTP Request

POST /firewalls

Request

  • labelsobject

    User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".

  • namestring required

    Name of the Firewall.

    Limited to a maximum of 128 characters.

    Must be unique per Project.

Response

Example request

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      "environment": "prod",
68      "example.com/my": "label",
69      "just-a-key": ""
70    },
71    "name": "new-name",
72    "rules": [
73      {
74        "description": null,
75        "destination_ips": [],
76        "direction": "in",
77        "port": "80",
78        "protocol": "tcp",
79        "source_ips": [
80          "28.239.13.1/32",
81          "28.239.14.0/24",
82          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
83        ]
84      }
85    ]
86  }
87}

Delete a Firewall

Deletes the Firewall.

Error Codes specific to this Call

Code Description
resource_in_use Firewall still applied to a resource

HTTP Request

DELETE /firewalls/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Firewall.

Example request

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

Returns a single Firewall.

HTTP Request

GET /firewalls/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Firewall.

Response

Example request

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      "environment": "prod",
26      "example.com/my": "label",
27      "just-a-key": ""
28    },
29    "name": "new-name",
30    "rules": [
31      {
32        "description": null,
33        "destination_ips": [],
34        "direction": "in",
35        "port": "80",
36        "protocol": "tcp",
37        "source_ips": [
38          "28.239.13.1/32",
39          "28.239.14.0/24",
40          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
41        ]
42      }
43    ]
44  }
45}

Update a Firewall

Update a Firewall.

Provided Labels will overwritte the existing ones.

In case of a parallel running change on the Firewall a conflict error will be returned.

HTTP Request

PUT /firewalls/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Firewall.

Request

  • labelsobject

    User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".

  • namestring

    Name of the Firewall.

    Limited to a maximum of 128 characters.

    Must be unique per Project.

Response

Example request

1curl \
2	-X PUT \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"new-name"}' \
6	"https://api.hetzner.cloud/v1/firewalls/$ID"

Request

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

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      "environment": "prod",
26      "example.com/my": "label",
27      "just-a-key": ""
28    },
29    "name": "new-name",
30    "rules": [
31      {
32        "description": null,
33        "destination_ips": [],
34        "direction": "in",
35        "port": "80",
36        "protocol": "tcp",
37        "source_ips": [
38          "28.239.13.1/32",
39          "28.239.14.0/24",
40          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
41        ]
42      }
43    ]
44  }
45}

Firewall Actions

Get all Actions

Returns all Actions for Firewalls.

Use the provided URI parameters to modify the result.

HTTP Request

GET /firewalls/actions

Query Parameters

  • idinteger (int64)

    Filter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.

  • sortstring
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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": "running"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns the specific Action.

HTTP Request

GET /firewalls/actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Action.

Response

Example request

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": "running"
19  }
20}

Get all Actions for a Firewall

Returns all Actions for the Firewall.

Use the provided URI parameters to modify the result.

HTTP Request

GET /firewalls/{id}/actions

Path Parameters

  • idinteger (int64) required

    ID of the Firewall.

Query Parameters

  • sortstring
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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  "meta": {
23    "pagination": {
24      "last_page": 1,
25      "next_page": null,
26      "page": 1,
27      "per_page": 25,
28      "previous_page": null,
29      "total_entries": 21
30    }
31  }
32}

Apply to Resources

Applies a Firewall to multiple resources.

Supported resources:

A server can be applied to a maximum of 5 Firewalls.

Error Codes specific to this Call

Code Description
firewall_already_applied Firewall is already applied to resource
incompatible_network_type The network type of the resource is not supported by Firewalls
firewall_resource_not_found The resource the Firewall should be applied to was not found
private_net_only_server The Server the Firewall should be applied to has no public interface

HTTP Request

POST /firewalls/{id}/actions/apply_to_resources

Path Parameters

  • idinteger (int64) required

    ID of the Firewall.

Request

Response

Example request

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 a Firewall from multiple resources.

Supported resources:

  • Servers (with a public network interface)

Error Codes specific to this Call

Code Description
firewall_already_removed Firewall is already removed from the resource
firewall_resource_not_found The resource the Firewall should be removed from was not found
firewall_managed_by_label_selector Firewall is applied via a Label Selector and cannot be removed manually

HTTP Request

POST /firewalls/{id}/actions/remove_from_resources

Path Parameters

  • idinteger (int64) required

    ID of the Firewall.

Request

Response

Example request

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

Set the rules of a Firewall.

Overwrites the existing rules with the given ones. Pass an empty array to remove all rules.

Rules are limited to 50 entries per Firewall and 500 effective rules.

HTTP Request

POST /firewalls/{id}/actions/set_rules

Path Parameters

  • idinteger (int64) required

    ID of the Firewall.

Request

Response

Example request

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 request

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

List multiple Floating IPs.

Use the provided URI parameters to modify the result.

HTTP Request

GET /floating_ips

Query Parameters

  • namestring

    Filter resources by their name. The response will only contain the resources matching the specified name.

  • label_selectorstring

    Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".

  • sortstring
    Allowed: id id:asc id:desc created created:asc created:desc

    Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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": 42,
18        "latitude": 50.47612,
19        "longitude": 12.370071,
20        "name": "fsn1",
21        "network_zone": "eu-central"
22      },
23      "id": 42,
24      "ip": "131.232.99.1",
25      "labels": {
26        "environment": "prod",
27        "example.com/my": "label",
28        "just-a-key": ""
29      },
30      "name": "my-resource",
31      "protection": {
32        "delete": false
33      },
34      "server": 42,
35      "type": "ipv4"
36    }
37  ],
38  "meta": {
39    "pagination": {
40      "last_page": 4,
41      "next_page": 4,
42      "page": 3,
43      "per_page": 25,
44      "previous_page": 2,
45      "total_entries": 100
46    }
47  }
48}

Create a Floating IP

Create a Floating IP.

Provide the server attribute to assign the Floating IP to that server or provide a home_location to locate the Floating IP at. Note that the Floating IP can be assigned to a Server in any Location later on. For optimal routing it is advised to use the Floating IP in the same Location it was created in.

HTTP Request

POST /floating_ips

Request

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

  • descriptionstring – nullable

    Description of the Resource.

  • home_locationstring

    Home Location for the Floating IP.

    Either the ID or the name of the Location.

    Only optional if no Server is provided. Routing is optimized for this Locations.

  • labelsobject

    User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".

  • namestring

    Name of the Resource. Must be unique per Project.

  • serverinteger (int64) – nullable

    Server the Floating IP is assigned to.

    null if not assigned.

  • typestring required
    Allowed: ipv4 ipv6

    Floating IP type

Response

Example request

1curl \
2	-X POST \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"description":"This describes my resource","home_location":"fsn1","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"my-resource","server":42,"type":"ipv4"}' \
6	"https://api.hetzner.cloud/v1/floating_ips"

Request

1{
2  "description": "This describes my resource",
3  "home_location": "fsn1",
4  "labels": {
5    "environment": "prod",
6    "example.com/my": "label",
7    "just-a-key": ""
8  },
9  "name": "my-resource",
10  "server": 42,
11  "type": "ipv4"
12}

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 the IP is assigned to a resource it will be unassigned.

HTTP Request

DELETE /floating_ips/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP.

Example request

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 single Floating IP.

HTTP Request

GET /floating_ips/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP.

Response

Example request

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": 42,
17      "latitude": 50.47612,
18      "longitude": 12.370071,
19      "name": "fsn1",
20      "network_zone": "eu-central"
21    },
22    "id": 42,
23    "ip": "131.232.99.1",
24    "labels": {
25      "environment": "prod",
26      "example.com/my": "label",
27      "just-a-key": ""
28    },
29    "name": "my-resource",
30    "protection": {
31      "delete": false
32    },
33    "server": 42,
34    "type": "ipv4"
35  }
36}

Update a Floating IP

Update the description or Labels of a Floating IP. Note that when updating Labels, the Floating IPs current set of Labels will be replaced with the Labels provided with the request. So, for example, if you want to add a new Label, you have to provide all existing Labels plus the new Label in the request body.

HTTP Request

PUT /floating_ips/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP.

Request

  • descriptionstring – nullable

    Description of the Resource.

  • labelsobject

    User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".

  • namestring

    Name of the Resource. Must be unique per Project.

Response

Example request

1curl \
2	-X PUT \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"description":"This describes my resource","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"name":"my-resource"}' \
6	"https://api.hetzner.cloud/v1/floating_ips/$ID"

Request

1{
2  "description": "This describes my resource",
3  "labels": {
4    "environment": "prod",
5    "example.com/my": "label",
6    "just-a-key": ""
7  },
8  "name": "my-resource"
9}

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

Lists multiple Actions.

Use the provided URI parameters to modify the result.

HTTP Request

GET /floating_ips/actions

Query Parameters

  • idinteger (int64)

    Filter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.

  • sortstring
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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": "running"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns a single Action.

HTTP Request

GET /floating_ips/actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Action.

Response

Example request

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": "running"
19  }
20}

Get all Actions for a Floating IP

Lists Actions for a Floating IP.

Use the provided URI parameters to modify the result.

HTTP Request

GET /floating_ips/{id}/actions

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP.

Query Parameters

  • sortstring
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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  "meta": {
27    "pagination": {
28      "last_page": 1,
29      "next_page": null,
30      "page": 1,
31      "per_page": 25,
32      "previous_page": null,
33      "total_entries": 21
34    }
35  }
36}

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) – nullablerequired

    Server the Floating IP is assigned to.

    null if not assigned.

Response

Example request

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 records for a Floating IP

Change the reverse DNS records for this Floating IP.

Allows to modify the PTR records set for the IP address.

HTTP Request

POST /floating_ips/{id}/actions/change_dns_ptr

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP.

Request

The ip attributes specifies for which IP address the record is set. For IPv4 addresses this must be the exact address of the Floating IP. For IPv6 addresses this must be a single address within the /64 subnet of the Floating IP.

The dns_ptr attribute specifies the hostname used for the IP address.

For IPv6 Floating IPs up to 100 entries can be created.

  • dns_ptrstring required

    Domain Name to point to.

    PTR record content used for reverse DNS.

  • ipstring required

    Single IPv4 or IPv6 address to create pointer for.

Response

Example request

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

Request

1{
2  "dns_ptr": "server.example.com",
3  "ip": "2001:db8::1"
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 settings configured for the Floating IP.

HTTP Request

POST /floating_ips/{id}/actions/change_protection

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP.

Request

  • deleteboolean required

    Prevent the Resource from being deleted.

Response

Example request

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

Request

1{
2  "delete": false
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.

Results in the IP being unreachable. Can be assigned to another resource again.

HTTP Request

POST /floating_ips/{id}/actions/unassign

Path Parameters

  • idinteger (int64) required

    ID of the Floating IP.

Response

Example request

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 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 request

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
    Allowed: id id:asc id:desc name name:asc name:desc created created:asc created:desc

    Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".

  • typestring
    Allowed: system snapshot backup app

    Can be used multiple times.

  • statusstring
    Allowed: available creating

    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

    Filter resources by their name. The response will only contain the resources matching the specified name.

  • label_selectorstring

    Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".

  • architecturestring

    Return only Images with the given architecture.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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        "environment": "prod",
19        "example.com/my": "label",
20        "just-a-key": ""
21      },
22      "name": "ubuntu-20.04",
23      "os_flavor": "ubuntu",
24      "os_version": "20.04",
25      "protection": {
26        "delete": false
27      },
28      "rapid_deploy": false,
29      "status": "available",
30      "type": "snapshot"
31    }
32  ],
33  "meta": {
34    "pagination": {
35      "last_page": 4,
36      "next_page": 4,
37      "page": 3,
38      "per_page": 25,
39      "previous_page": 2,
40      "total_entries": 100
41    }
42  }
43}

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 request

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 request

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      "environment": "prod",
18      "example.com/my": "label",
19      "just-a-key": ""
20    },
21    "name": "ubuntu-20.04",
22    "os_flavor": "ubuntu",
23    "os_version": "20.04",
24    "protection": {
25      "delete": false
26    },
27    "rapid_deploy": false,
28    "status": "available",
29    "type": "snapshot"
30  }
31}

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) for the Resource. For more information, see "Labels".

  • typestring
    Allowed: snapshot

    Destination Image type to convert to

Response

Example request

1curl \
2	-X PUT \
3	-H "Authorization: Bearer $API_TOKEN" \
4	-H "Content-Type: application/json" \
5	-d '{"description":"My new Image description","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"type":"snapshot"}' \
6	"https://api.hetzner.cloud/v1/images/$ID"

Request

1{
2  "description": "My new Image description",
3  "labels": {
4    "environment": "prod",
5    "example.com/my": "label",
6    "just-a-key": ""
7  },
8  "type": "snapshot"
9}

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)

    Filter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.

  • sortstring
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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": "running"
20    }
21  ],
22  "meta": {
23    "pagination": {
24      "last_page": 4,
25      "next_page": 4,
26      "page": 3,
27      "per_page": 25,
28      "previous_page": 2,
29      "total_entries": 100
30    }
31  }
32}

Get an Action

Returns a specific Action object.

HTTP Request

GET /images/actions/{id}

Path Parameters

  • idinteger (int64) required

    ID of the Action.

Response

Example request

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": "running"
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
    Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc

    Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".

  • statusstring
    Allowed: running success error

    Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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  "meta": {
23    "pagination": {
24      "last_page": 1,
25      "next_page": null,
26      "page": 1,
27      "per_page": 25,
28      "previous_page": null,
29      "total_entries": 21
30    }
31  }
32}

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 request

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 request

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

    Filter resources by their name. The response will only contain the resources 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)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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      "deprecation": {
6        "announced": "2023-06-01T00:00:00+00:00",
7        "unavailable_after": "2023-09-01T00:00:00+00:00"
8      },
9      "description": "FreeBSD 11.0 x64",
10      "id": 42,
11      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
12      "type": "public"
13    }
14  ],
15  "meta": {
16    "pagination": {
17      "last_page": 4,
18      "next_page": 4,
19      "page": 3,
20      "per_page": 25,
21      "previous_page": 2,
22      "total_entries": 100
23    }
24  }
25}

Get an ISO

Returns a specific ISO object.

HTTP Request

GET /isos/{id}

Path Parameters

  • idinteger (int64) required

    ID of the ISO.

Response

Example request

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    "deprecation": {
5      "announced": "2023-06-01T00:00:00+00:00",
6      "unavailable_after": "2023-09-01T00:00:00+00:00"
7    },
8    "description": "FreeBSD 11.0 x64",
9    "id": 42,
10    "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
11    "type": "public"
12  }
13}

Load Balancers

Get all Load Balancers

Gets all existing Load Balancers that you have available.

HTTP Request

GET /load_balancers

Query Parameters

  • sortstring
    Allowed: id id:asc id:desc name name:asc name:desc created created:asc created:desc

    Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".

  • namestring

    Filter resources by their name. The response will only contain the resources matching the specified name.

  • label_selectorstring

    Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".

  • pageinteger (int64)
    Default: 1

    Page number to return. For more information, see "Pagination".

  • per_pageinteger (int64)
    Default: 25

    Maximum number of entries returned per page. For more information, see "Pagination".

Response

Example request

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

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
missing_ipv4 The server that you are trying to add as a public target does not have a public IPv4 address
target_already_defined The Load Balancer target you are trying to define is already defined

HTTP Request

POST /load_balancers

Request

  • labelsobject

    User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".

  • 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 request

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

Request

1{
2  "algorithm": {
3    "type": "round_robin"
4  },
5  "labels": {
6    "environment": "prod",
7    "example.com/my": "label",
8    "just-a-key": ""
9  },
10  "load_balancer_type": "lb11",
11  "location": "fsn1",
12  "name": "Web Frontend",
13  "network": 123,
14  "network_zone": "eu-central",
15  "public_interface": true,
16  "services": [
17    {
18      "destination_port": 80,
19      "health_check": {
20        "http": {
21          "domain": "example.com",
22          "path": "/",
23          "response": "{\"status\": \"ok\"}",
24          "status_codes": [
25            "2??",
26            "3??"
27          ],
28          "tls": false
29        },
30        "interval": 15,
31        "port": 4711,
32        "protocol": "http",
33        "retries": 3,
34        "timeout": 10
35      },
36      "http": {
37        "certificates": [
38          897
39        ],
40        "cookie_lifetime": 300,
41        "cookie_name": "HCLBSTICKY",
42        "redirect_http": true,
43        "sticky_sessions": true
44      },
45      "listen_port": 443,
46      "protocol": "https",
47      "proxyprotocol": false
48    }
49  ],