Cloud API

Hetzner Cloud API

This is the official API documentation for the Public Hetzner Cloud.

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 Access → Tokens, and create 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 jEheVytlAoFl7F8MqUQ7jAo2hOXASztX.

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

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

Example Response

{
    "servers": [],
    "meta": {
        "pagination": {
            "page": 1,
            "per_page": 25,
            "previous_page": null,
            "next_page": null,
            "last_page": 1,
            "total_entries": 0
        }
    }
}

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 Access → Security, and create a new token.

Example Authorization header

Authorization: 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
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
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

Example response

{
  "error": {
    "code": "invalid_input",
    "message": "invalid input in field 'broken_field': is too long",
    "details": {
      "fields": [
        {
          "name": "broken_field",
          "messages": ["is too long"]
        }
      ]
    }
  }
}

invalid_input

{
  "error": {
    "code": "invalid_input",
    "message": "invalid input in field 'broken_field': is too long",
    "details": {
      "fields": [
        {
          "name": "broken_field",
          "messages": ["is too long"]
        }
      ]
    }
  }
}

uniqueness_error

{
  "error": {
    "code": "uniqueness_error",
    "message": "SSH key with the same fingerprint already exists",
    "details": {
      "fields": [
        {
          "name": "public_key"
        }
      ]
    }
  }
}

resource_limit_exceeded

{
  "error": {
    "code": "resource_limit_exceeded",
    "message": "project limit exceeded",
    "details": {
      "limits": [
        {
          "name": "project_limit"
        }
      ]
    }
  }
}

Labels

Labels are key/value pairs that can be attached to Servers, Floating IPs, Volumes, SSH keys and Images.

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

{
  "labels": {
    "environment":"development",
    "service":"backend",
    "example.com/my":"label",
    "just-a-key":""
  }
}

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

{
    "servers": [...],
    "meta": {
        "pagination": {
            "page": 2,
            "per_page": 25,
            "previous_page": 1,
            "next_page": 3,
            "last_page": 4,
            "total_entries": 100
        }
    }
}

Example Pagination Link header

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

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

Example: Hostname

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

Example: Instance ID

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

Example: Public IPv4

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

Example: Private Networks

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

- ip: 10.0.0.2
  alias_ips: [10.0.0.3, 10.0.0.4]
  interface_num: 1
  mac_address: 86:00:00:2a:7d:e0
  network_id: 1234
  network_name: nw-test1
  network: 10.0.0.0/8
  subnet: 10.0.0.0/24
  gateway: 10.0.0.1
- ip: 192.168.0.2
  alias_ips: []
  interface_num: 2
  mac_address: 86:00:00:2a:7d:e1
  network_id: 4321
  network_name: nw-test2
  network: 192.168.0.0/16
  subnet: 192.168.0.0/24
  gateway: 192.168.0.1

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

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

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

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

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "start_server",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:55:00+00:00",
      "id": 42,
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ],
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  }
}

Get an Action

Returns a specific Action object.

HTTP Request

GET /actions/{id}

Path Parameters

  • idinteger required

    ID of the Resource

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/actions/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "start_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:55:00+00:00",
    "id": 42,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Certificates

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

Get all Certificates

Returns all Certificate objects.

HTTP Request

GET /certificates

Query Parameters

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

    Can be used multiple times.

  • namestring

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

  • label_selectorstring

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

  • typestring
    Possible enum values:
    uploadedmanaged

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

Response

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "certificates": [
    {
      "certificate": "-----BEGIN CERTIFICATE-----\n...",
      "created": "2019-01-08T12:10:00+00:00",
      "domain_names": [
        "example.com",
        "webmail.example.com",
        "www.example.com"
      ],
      "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
      "id": 897,
      "labels": {
        "env": "dev"
      },
      "name": "my website cert",
      "not_valid_after": "2019-07-08T09:59:59+00:00",
      "not_valid_before": "2019-01-08T10:00:00+00:00",
      "status": null,
      "type": "uploaded",
      "used_by": [
        {
          "id": 4711,
          "type": "load_balancer"
        }
      ]
    }
  ]
}

Create a Certificate

Creates a new Certificate.

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

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

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

HTTP Request

POST /certificates

Request

  • certificatestring

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

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring required

    Name of the Certificate

  • private_keystring

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

  • typestring
    Possible enum values:
    uploadedmanaged

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

Response

Example curl

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

Request

{
  "domain_names": [
    "example.com",
    "webmail.example.com",
    "www.example.com"
  ],
  "name": "my website cert",
  "type": "managed"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "create_certificate",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 879,
        "type": "certificate"
      }
    ],
    "started": "2019-01-08T12:10:00+00:00",
    "status": "running"
  },
  "certificate": {
    "certificate": null,
    "created": "2019-01-08T12:10:00+00:00",
    "domain_names": [
      "example.com",
      "webmail.example.com",
      "www.example.com"
    ],
    "fingerprint": null,
    "id": 897,
    "labels": {
      "env": "dev"
    },
    "name": "my website cert",
    "not_valid_after": null,
    "not_valid_before": null,
    "status": {
      "error": null,
      "issuance": "pending",
      "renewal": "unavailable"
    },
    "type": "managed",
    "used_by": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ]
  }
}

Delete a Certificate

Deletes a Certificate.

HTTP Request

DELETE /certificates/{id}

Path Parameters

  • idinteger required

    ID of the resource

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/certificates/{id}'

Response headers

Status: 204

Get a Certificate

Gets a specific Certificate object.

HTTP Request

GET /certificates/{id}

Path Parameters

  • idinteger required

    ID of the resource

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/certificates/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "certificate": {
    "certificate": "-----BEGIN CERTIFICATE-----\n...",
    "created": "2019-01-08T12:10:00+00:00",
    "domain_names": [
      "example.com",
      "webmail.example.com",
      "www.example.com"
    ],
    "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
    "id": 897,
    "labels": {
      "env": "dev"
    },
    "name": "my website cert",
    "not_valid_after": "2019-07-08T09:59:59+00:00",
    "not_valid_before": "2019-01-08T10:00:00+00:00",
    "status": null,
    "type": "uploaded",
    "used_by": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ]
  }
}

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 required

    ID of the resource

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New Certificate name

Response

Example curl

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

Request

{
  "labels": {
    "labelkey": "value"
  },
  "name": "my website cert"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "certificate": {
    "certificate": "-----BEGIN CERTIFICATE-----\n...",
    "created": "2019-01-08T12:10:00+00:00",
    "domain_names": [
      "example.com",
      "webmail.example.com",
      "www.example.com"
    ],
    "fingerprint": "03:c7:55:9b:2a:d1:04:17:09:f6:d0:7f:18:34:63:d4:3e:5f",
    "id": 897,
    "labels": {
      "labelkey": "value"
    },
    "name": "my website cert",
    "not_valid_after": "2019-07-08T09:59:59+00:00",
    "not_valid_before": "2019-01-08T10:00:00+00:00",
    "status": null,
    "type": "uploaded",
    "used_by": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ]
  }
}

Certificate Actions

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 required

    ID of the Resource

Query Parameters

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/certificates/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "issue_certificate",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2021-01-30T23:57:00+00:00",
      "id": 14,
      "progress": 100,
      "resources": [
        {
          "id": 896,
          "type": "certificate"
        }
      ],
      "started": "2021-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

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 required

    ID of the Certificate

  • action_idinteger required

    ID of the Action

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/certificates/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "issue_certificate",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2021-01-30T23:57:00+00:00",
    "id": 14,
    "progress": 100,
    "resources": [
      {
        "id": 896,
        "type": "certificate"
      }
    ],
    "started": "2021-01-30T23:55:00+00:00",
    "status": "success"
  }
}

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 required

    ID of the Certificate

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/certificates/{id}/actions/retry'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "issue_certificate",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2021-01-30T23:57:00+00:00",
    "id": 14,
    "progress": 100,
    "resources": [
      {
        "id": 896,
        "type": "certificate"
      }
    ],
    "started": "2021-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Datacenters

Each Datacenter represents a physical entity where virtual machines are hosted. Note that Datacenters are not guaranteed to be entirely independent failure domains.

Datacenters in the same Location are connected by very low latency links.

Datacenter names are made up of their Location and Datacenter number, for example fsn1-dc8 means Datacenter 8 in Location fsn1.

Get all Datacenters

Returns all Datacenter objects.

HTTP Request

GET /datacenters

Query Parameters

  • namestring

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

Response

  • recommendationnumber required

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "datacenters": [
    {
      "description": "Falkenstein DC Park 8",
      "id": 42,
      "location": {
        "city": "Falkenstein",
        "country": "DE",
        "description": "Falkenstein DC Park 1",
        "id": 1,
        "latitude": 50.47612,
        "longitude": 12.370071,
        "name": "fsn1",
        "network_zone": "eu-central"
      },
      "name": "fsn1-dc8",
      "server_types": {
        "available": [
          1,
          2,
          3
        ],
        "available_for_migration": [
          1,
          2,
          3
        ],
        "supported": [
          1,
          2,
          3
        ]
      }
    }
  ],
  "recommendation": 1
}

Get a Datacenter

Returns a specific Datacenter object.

HTTP Request

GET /datacenters/{id}

Path Parameters

  • idinteger required

    ID of Datacenter

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/datacenters/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "datacenter": {
    "description": "Falkenstein DC Park 8",
    "id": 42,
    "location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "name": "fsn1-dc8",
    "server_types": {
      "available": [
        1,
        2,
        3
      ],
      "available_for_migration": [
        1,
        2,
        3
      ],
      "supported": [
        1,
        2,
        3
      ]
    }
  }
}

Firewalls

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

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

Get all Firewalls

Returns all Firewall objects.

HTTP Request

GET /firewalls

Query Parameters

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

    Can be used multiple times.

  • namestring

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

  • label_selectorstring

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

Response

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "firewalls": [
    {
      "applied_to": [
        {
          "applied_to_resources": [
            {
              "server": {
                "id": 42
              },
              "type": "server"
            }
          ],
          "label_selector": {
            "selector": "env=prod"
          },
          "server": {
            "id": 42
          },
          "type": "server"
        }
      ],
      "created": "2016-01-30T23:55:00+00:00",
      "id": 42,
      "labels": {},
      "name": "my-resource",
      "rules": [
        {
          "description": null,
          "destination_ips": [
            "28.239.13.1/32",
            "28.239.14.0/24",
            "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
          ],
          "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"
          ]
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  }
}

Create a Firewall

Creates a new Firewall.

Call specific error codes

Code Description
server_already_added Server added more than one time to resource
incompatible_network_type The Network type is incompatible for the given resource

HTTP Request

POST /firewalls

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring required

    Name of the Firewall

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-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"]}]}' \
	'https://api.hetzner.cloud/v1/firewalls'

Request

{
  "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"
      ]
    }
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "actions": [
    {
      "command": "set_firewall_rules",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 38,
          "type": "firewall"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    },
    {
      "command": "apply_firewall",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 14,
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        },
        {
          "id": 38,
          "type": "firewall"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ],
  "firewall": {
    "applied_to": [
      {
        "applied_to_resources": [
          {
            "server": {
              "id": 42
            },
            "type": "server"
          }
        ],
        "label_selector": {
          "selector": "env=prod"
        },
        "server": {
          "id": 42
        },
        "type": "server"
      }
    ],
    "created": "2016-01-30T23:55:00+00:00",
    "id": 42,
    "labels": {},
    "name": "my-resource",
    "rules": [
      {
        "description": null,
        "destination_ips": [
          "28.239.13.1/32",
          "28.239.14.0/24",
          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
        ],
        "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"
        ]
      }
    ]
  }
}

Delete a Firewall

Deletes a Firewall.

Call specific error codes

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

HTTP Request

DELETE /firewalls/{id}

Path Parameters

  • idinteger required

    ID of the resource

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/firewalls/{id}'

Response headers

Status: 204

Get a Firewall

Gets a specific Firewall object.

HTTP Request

GET /firewalls/{id}

Path Parameters

  • idinteger required

    ID of the resource

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/firewalls/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "firewall": {
    "applied_to": [
      {
        "applied_to_resources": [
          {
            "server": {
              "id": 42
            },
            "type": "server"
          }
        ],
        "label_selector": {
          "selector": "env=prod"
        },
        "server": {
          "id": 42
        },
        "type": "server"
      }
    ],
    "created": "2016-01-30T23:55:00+00:00",
    "id": 42,
    "labels": {},
    "name": "my-resource",
    "rules": [
      {
        "description": null,
        "destination_ips": [
          "28.239.13.1/32",
          "28.239.14.0/24",
          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
        ],
        "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"
        ]
      }
    ]
  }
}

Update a Firewall

Updates the Firewall.

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

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

HTTP Request

PUT /firewalls/{id}

Path Parameters

  • idinteger required

    ID of the resource

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New Firewall name

Response

Example curl

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

Request

{
  "labels": {
    "labelkey": "value"
  },
  "name": "new-name"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "firewall": {
    "applied_to": [
      {
        "applied_to_resources": [
          {
            "server": {
              "id": 42
            },
            "type": "server"
          }
        ],
        "label_selector": {
          "selector": "env=prod"
        },
        "server": {
          "id": 42
        },
        "type": "server"
      }
    ],
    "created": "2016-01-30T23:55:00+00:00",
    "id": 42,
    "labels": {},
    "name": "my-resource",
    "rules": [
      {
        "description": null,
        "destination_ips": [
          "28.239.13.1/32",
          "28.239.14.0/24",
          "ff21:1eac:9a3b:ee58:5ca:990c:8bc9:c03b/128"
        ],
        "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"
        ]
      }
    ]
  }
}

Firewall Actions

Get all Actions for a Firewall

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

HTTP Request

GET /firewalls/{id}/actions

Path Parameters

  • idinteger required

    ID of the Resource

Query Parameters

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/firewalls/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "set_firewall_rules",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 38,
          "type": "firewall"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Get an Action for a Firewall

Returns a specific Action for a Firewall.

HTTP Request

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

Path Parameters

  • idinteger required

    ID of the Firewall

  • action_idinteger required

    ID of the Action

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/firewalls/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "set_firewall_rules",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 38,
        "type": "firewall"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Apply to Resources

Applies one Firewall to multiple resources.

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

Call specific error codes

Code Description
firewall_already_applied Firewall was already applied on resource
incompatible_network_type The Network type is incompatible for the given resource

HTTP Request

POST /firewalls/{id}/actions/apply_to_resources

Path Parameters

  • idinteger required

    ID of the Firewall

Request

Response

Example curl

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

Request

{
  "apply_to": [
    {
      "server": {
        "id": 42
      },
      "type": "server"
    }
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "actions": [
    {
      "command": "apply_firewall",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 14,
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        },
        {
          "id": 38,
          "type": "firewall"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Remove from Resources

Removes one Firewall from multiple resources.

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

Call specific error codes

Code Description
firewall_already_removed Firewall was already removed from the resource

HTTP Request

POST /firewalls/{id}/actions/remove_from_resources

Path Parameters

  • idinteger required

    ID of the Firewall

Request

Response

Example curl

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

Request

{
  "remove_from": [
    {
      "server": {
        "id": 42
      },
      "type": "server"
    }
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "actions": [
    {
      "command": "remove_firewall",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 14,
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        },
        {
          "id": 38,
          "type": "firewall"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Set Rules

Sets the rules of a Firewall.

All existing rules will be overwritten. Pass an empty rules array to remove all rules.

HTTP Request

POST /firewalls/{id}/actions/set_rules

Path Parameters

  • idinteger required

    ID of the Firewall

Request

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-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"]}]}' \
	'https://api.hetzner.cloud/v1/firewalls/{id}/actions/set_rules'

Request

{
  "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"
      ]
    }
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "actions": [
    {
      "command": "set_firewall_rules",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 38,
          "type": "firewall"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    },
    {
      "command": "apply_firewall",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 14,
      "progress": 100,
      "resources": [
        {
          "id": 38,
          "type": "firewall"
        },
        {
          "id": 42,
          "type": "server"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Floating IPs

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

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

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

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

Floating IPs are billed on a monthly basis.

Get all Floating IPs

Returns all Floating IP objects.

HTTP Request

GET /floating_ips

Query Parameters

  • namestring

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

  • label_selectorstring

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

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

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

Response

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "floating_ips": [
    {
      "blocked": false,
      "created": "2016-01-30T23:55:00+00:00",
      "description": "this describes my resource",
      "dns_ptr": [
        {
          "dns_ptr": "server.example.com",
          "ip": "2001:db8::1"
        }
      ],
      "home_location": {
        "city": "Falkenstein",
        "country": "DE",
        "description": "Falkenstein DC Park 1",
        "id": 1,
        "latitude": 50.47612,
        "longitude": 12.370071,
        "name": "fsn1",
        "network_zone": "eu-central"
      },
      "id": 42,
      "ip": "131.232.99.1",
      "labels": {},
      "name": "my-resource",
      "protection": {
        "delete": false
      },
      "server": 42,
      "type": "ipv4"
    }
  ],
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  }
}

Create a Floating IP

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

HTTP Request

POST /floating_ips

Request

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

  • descriptionstring
  • home_locationstring

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

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring
  • serverinteger

    Server to assign the Floating IP to

  • typestring required
    Possible enum values:
    ipv4ipv6

    Floating IP type

Response

Example curl

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

Request

{
  "description": "Web Frontend",
  "home_location": "fsn1",
  "labels": {
    "labelkey": "value"
  },
  "name": "Web Frontend",
  "server": 42,
  "type": "ipv4"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "create_floating_ip",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  },
  "floating_ip": {
    "blocked": false,
    "created": "2016-01-30T23:50:00+00:00",
    "description": "Web Frontend",
    "dns_ptr": [
      {
        "dns_ptr": "server.example.com",
        "ip": "2001:db8::1"
      }
    ],
    "home_location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "id": 4711,
    "ip": "131.232.99.1",
    "labels": {
      "env": "dev"
    },
    "name": "Web Frontend",
    "protection": {
      "delete": false
    },
    "server": 42,
    "type": "ipv4"
  }
}

Delete a Floating IP

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

HTTP Request

DELETE /floating_ips/{id}

Path Parameters

  • idinteger required

    ID of the Floating IP

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}'

Response headers

Status: 204

Get a Floating IP

Returns a specific Floating IP object.

HTTP Request

GET /floating_ips/{id}

Path Parameters

  • idinteger required

    ID of the Floating IP

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "floating_ip": {
    "blocked": false,
    "created": "2016-01-30T23:55:00+00:00",
    "description": "this describes my resource",
    "dns_ptr": [
      {
        "dns_ptr": "server.example.com",
        "ip": "2001:db8::1"
      }
    ],
    "home_location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "id": 42,
    "ip": "131.232.99.1",
    "labels": {},
    "name": "my-resource",
    "protection": {
      "delete": false
    },
    "server": 42,
    "type": "ipv4"
  }
}

Update a Floating IP

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

HTTP Request

PUT /floating_ips/{id}

Path Parameters

  • idinteger required

    ID of the Floating IP

Request

  • descriptionstring

    New Description to set

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New unique name to set

Response

Example curl

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

Request

{
  "description": "Web Frontend",
  "labels": {
    "labelkey": "value"
  },
  "name": "Web Frontend"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "floating_ip": {
    "blocked": false,
    "created": "2016-01-30T23:50:00+00:00",
    "description": "Web Frontend",
    "dns_ptr": [
      {
        "dns_ptr": "server.example.com",
        "ip": "2001:db8::1"
      }
    ],
    "home_location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "id": 4711,
    "ip": "131.232.99.1",
    "labels": {
      "labelkey": "value"
    },
    "name": "Web Frontend",
    "protection": {
      "delete": false
    },
    "server": 42,
    "type": "ipv4"
  }
}

Floating IP Actions

Get all Actions for a Floating IP

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

HTTP Request

GET /floating_ips/{id}/actions

Path Parameters

  • idinteger required

    ID of the Floating IP

Query Parameters

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "assign_floating_ip",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 4711,
          "type": "server"
        },
        {
          "id": 4712,
          "type": "floating_ip"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Get an Action for a Floating IP

Returns a specific Action object for a Floating IP.

HTTP Request

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

Path Parameters

  • idinteger required

    ID of the Floating IP

  • action_idinteger required

    ID of the Action

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "assign_floating_ip",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

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 required

    ID of the Floating IP

Request

  • serverinteger required

    ID of the Server the Floating IP shall be assigned to

Response

Example curl

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

Request

{
  "server": 42
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "assign_floating_ip",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Change reverse DNS entry for a Floating IP

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

HTTP Request

POST /floating_ips/{id}/actions/change_dns_ptr

Path Parameters

  • idinteger required

    ID of the Floating IP

Request

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

The target hostname is set by passing dns_ptr.

  • dns_ptrstring – nullablerequired

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

  • ipstring required

    IP address for which to set the reverse DNS entry

Response

Example curl

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

Request

{
  "dns_ptr": "server02.example.com",
  "ip": "1.2.3.4"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_dns_ptr",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Change Floating IP Protection

Changes the protection configuration of the Floating IP.

HTTP Request

POST /floating_ips/{id}/actions/change_protection

Path Parameters

  • idinteger required

    ID of the Floating IP

Request

  • deleteboolean

    If true, prevents the Floating IP from being deleted

Response

Example curl

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

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_protection",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Unassign a Floating IP

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

HTTP Request

POST /floating_ips/{id}/actions/unassign

Path Parameters

  • idinteger required

    ID of the Floating IP

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/floating_ips/{id}/actions/unassign'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "unassign_floating_ip",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "floating_ip"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Images

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

System Images

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

Snapshot Images

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

Backup Images

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

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

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

App Images

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

Get all Images

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

HTTP Request

GET /images

Query Parameters

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

    Can be used multiple times.

  • typestring
    Possible enum values:
    systemsnapshotbackupapp

    Can be used multiple times.

  • statusstring
    Possible enum values:
    availablecreating

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

  • bound_tostring

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

  • include_deprecatedboolean

    Can be used multiple times.

  • namestring

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

  • label_selectorstring

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

Response

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "images": [
    {
      "bound_to": null,
      "build_id": "c313fe40383af26094a5a92026054320ab55abc7",
      "created": "2016-01-30T23:55:00+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "deleted": null,
      "deprecated": "2018-02-28T00:00:00+00:00",
      "description": "Ubuntu 20.04 Standard 64 bit",
      "disk_size": 10,
      "id": 42,
      "image_size": 2.3,
      "labels": {},
      "name": "ubuntu-20.04",
      "os_flavor": "ubuntu",
      "os_version": "20.04",
      "protection": {
        "delete": false
      },
      "rapid_deploy": false,
      "status": "available",
      "type": "snapshot"
    }
  ],
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  }
}

Delete an Image

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

HTTP Request

DELETE /images/{id}

Path Parameters

  • idinteger required

    ID of the Image

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images/{id}'

Response headers

Status: 204

Get an Image

Returns a specific Image object.

HTTP Request

GET /images/{id}

Path Parameters

  • idinteger required

    ID of the Image

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "image": {
    "bound_to": null,
    "build_id": "c313fe40383af26094a5a92026054320ab55abc7",
    "created": "2016-01-30T23:55:00+00:00",
    "created_from": {
      "id": 1,
      "name": "Server"
    },
    "deleted": null,
    "deprecated": "2018-02-28T00:00:00+00:00",
    "description": "Ubuntu 20.04 Standard 64 bit",
    "disk_size": 10,
    "id": 42,
    "image_size": 2.3,
    "labels": {},
    "name": "ubuntu-20.04",
    "os_flavor": "ubuntu",
    "os_version": "20.04",
    "protection": {
      "delete": false
    },
    "rapid_deploy": false,
    "status": "available",
    "type": "snapshot"
  }
}

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 required

    ID of the Image

Request

  • descriptionstring

    New description of Image

  • labelsobject

    User-defined labels (key-value pairs)

  • typestring
    Possible enum values:
    snapshot

    Destination Image type to convert to

Response

Example curl

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

Request

{
  "description": "My new Image description",
  "labels": {
    "labelkey": "value"
  },
  "type": "snapshot"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "image": {
    "bound_to": null,
    "build_id": "c313fe40383af26094a5a92026054320ab55abc7",
    "created": "2016-01-30T23:50:00+00:00",
    "created_from": {
      "id": 1,
      "name": "Server"
    },
    "deleted": null,
    "deprecated": "2018-02-28T00:00:00+00:00",
    "description": "My new Image description",
    "disk_size": 10,
    "id": 4711,
    "image_size": 2.3,
    "labels": {
      "labelkey": "value"
    },
    "name": null,
    "os_flavor": "ubuntu",
    "os_version": "20.04",
    "protection": {
      "delete": false
    },
    "rapid_deploy": false,
    "status": "available",
    "type": "snapshot"
  }
}

Image Actions

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 required

    ID of the Image

Query Parameters

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "change_protection",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 4711,
          "type": "image"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Get an Action for an Image

Returns a specific Action for an Image.

HTTP Request

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

Path Parameters

  • idinteger required

    ID of the Image

  • action_idinteger required

    ID of the Action

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/images/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "change_protection",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "image"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

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 required

    ID of the Image

Request

  • deleteboolean

    If true, prevents the snapshot from being deleted

Response

Example curl

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

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_protection",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "image"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

ISOs

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

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

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

Get all ISOs

Returns all available ISO objects.

HTTP Request

GET /isos

Query Parameters

  • namestring

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

Response

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "isos": [
    {
      "deprecated": "2018-02-28T00:00:00+00:00",
      "description": "FreeBSD 11.0 x64",
      "id": 42,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "type": "public"
    }
  ],
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  }
}

Get an ISO

Returns a specific ISO object.

HTTP Request

GET /isos/{id}

Path Parameters

  • idinteger required

    ID of the ISO

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/isos/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "iso": {
    "deprecated": "2018-02-28T00:00:00+00:00",
    "description": "FreeBSD 11.0 x64",
    "id": 42,
    "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
    "type": "public"
  }
}

Load Balancers

Get all Load Balancers

Gets all existing Load Balancers that you have available.

HTTP Request

GET /load_balancers

Query Parameters

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

    Can be used multiple times.

  • namestring

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

  • label_selectorstring

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

Response

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancers": [
    {
      "algorithm": {
        "type": "round_robin"
      },
      "created": "2016-01-30T23:55:00+00:00",
      "id": 42,
      "included_traffic": 10000,
      "ingoing_traffic": null,
      "labels": {},
      "load_balancer_type": {
        "deprecated": "2016-01-30T23:50:00+00:00",
        "description": "LB11",
        "id": 1,
        "max_assigned_certificates": 10,
        "max_connections": 20000,
        "max_services": 5,
        "max_targets": 25,
        "name": "lb11",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            },
            "price_monthly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            }
          }
        ]
      },
      "location": {
        "city": "Falkenstein",
        "country": "DE",
        "description": "Falkenstein DC Park 1",
        "id": 1,
        "latitude": 50.47612,
        "longitude": 12.370071,
        "name": "fsn1",
        "network_zone": "eu-central"
      },
      "name": "my-resource",
      "outgoing_traffic": null,
      "private_net": [
        {
          "ip": "10.0.0.2",
          "network": 4711
        }
      ],
      "protection": {
        "delete": false
      },
      "public_net": {
        "enabled": false,
        "ipv4": {
          "dns_ptr": "lb1.example.com",
          "ip": "1.2.3.4"
        },
        "ipv6": {
          "dns_ptr": "lb1.example.com",
          "ip": "2001:db8::1"
        }
      },
      "services": [
        {
          "destination_port": 80,
          "health_check": {
            "http": {
              "domain": "example.com",
              "path": "/",
              "response": "{\"status\": \"ok\"}",
              "status_codes": [
                "2??",
                "3??"
              ],
              "tls": false
            },
            "interval": 15,
            "port": 4711,
            "protocol": "http",
            "retries": 3,
            "timeout": 10
          },
          "http": {
            "certificates": [
              897
            ],
            "cookie_lifetime": 300,
            "cookie_name": "HCLBSTICKY",
            "redirect_http": true,
            "sticky_sessions": true
          },
          "listen_port": 443,
          "protocol": "https",
          "proxyprotocol": false
        }
      ],
      "targets": [
        {
          "health_status": [
            {
              "listen_port": 443,
              "status": "healthy"
            }
          ],
          "ip": {
            "ip": "203.0.113.1"
          },
          "label_selector": {
            "selector": "env=prod"
          },
          "server": {
            "id": 80
          },
          "targets": [
            {
              "health_status": [
                {
                  "listen_port": 443,
                  "status": "healthy"
                }
              ],
              "server": {
                "id": 85
              },
              "type": "server",
              "use_private_ip": false
            }
          ],
          "type": "server",
          "use_private_ip": false
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  }
}

Create a Load Balancer

Creates a Load Balancer.

Call specific error codes

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

HTTP Request

POST /load_balancers

Request

  • load_balancer_typestring required

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

  • locationstring

    ID or name of Location to create Load Balancer in

  • namestring required

    Name of the Load Balancer

  • networkinteger

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

  • network_zonestring

    Name of network zone

  • public_interfaceboolean

    Enable or disable the public interface of the Load Balancer

Response

Example curl

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

Request

{
  "algorithm": {
    "type": "round_robin"
  },
  "labels": {
    "labelkey": "value"
  },
  "load_balancer_type": "lb11",
  "location": "string",
  "name": "Web Frontend",
  "network": 123,
  "network_zone": "eu-central",
  "public_interface": true,
  "services": [
    {
      "destination_port": 80,
      "health_check": {
        "http": {
          "domain": "example.com",
          "path": "/",
          "response": "{\"status\": \"ok\"}",
          "status_codes": [
            "2??",
            "3??"
          ],
          "tls": false
        },
        "interval": 15,
        "port": 4711,
        "protocol": "http",
        "retries": 3,
        "timeout": 10
      },
      "http": {
        "certificates": [
          897
        ],
        "cookie_lifetime": 300,
        "cookie_name": "HCLBSTICKY",
        "redirect_http": true,
        "sticky_sessions": true
      },
      "listen_port": 443,
      "protocol": "https",
      "proxyprotocol": false
    }
  ],
  "targets": [
    {
      "health_status": [
        {
          "listen_port": 443,
          "status": "healthy"
        }
      ],
      "ip": {
        "ip": "203.0.113.1"
      },
      "label_selector": {
        "selector": "env=prod"
      },
      "server": {
        "id": 80
      },
      "targets": [
        {
          "health_status": [
            {
              "listen_port": 443,
              "status": "healthy"
            }
          ],
          "server": {
            "id": 85
          },
          "type": "server",
          "use_private_ip": false
        }
      ],
      "type": "server",
      "use_private_ip": false
    }
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "create_load_balancer",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  },
  "load_balancer": {
    "algorithm": {
      "type": "round_robin"
    },
    "created": "2016-01-30T23:50:00+00:00",
    "id": 4711,
    "included_traffic": 654321,
    "ingoing_traffic": 123456,
    "labels": {
      "env": "dev"
    },
    "load_balancer_type": {
      "deprecated": "2016-01-30T23:50:00+00:00",
      "description": "LB11",
      "id": 1,
      "max_assigned_certificates": 10,
      "max_connections": 20000,
      "max_services": 5,
      "max_targets": 25,
      "name": "lb11",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          },
          "price_monthly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          }
        }
      ]
    },
    "location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "name": "Web Frontend",
    "outgoing_traffic": 123456,
    "private_net": [
      {
        "ip": "10.0.0.2",
        "network": 4711
      }
    ],
    "protection": {
      "delete": false
    },
    "public_net": {
      "enabled": false,
      "ipv4": {
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "ip": "2001:db8::1"
      }
    },
    "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": "http",
        "proxyprotocol": false
      }
    ],
    "targets": [
      {
        "health_status": [
          {
            "listen_port": 443,
            "status": "healthy"
          }
        ],
        "server": {
          "id": 80
        },
        "targets": [
          {
            "health_status": [
              {
                "listen_port": 443,
                "status": "healthy"
              }
            ],
            "label_selector": null,
            "server": {
              "id": 80
            },
            "type": "server",
            "use_private_ip": true
          }
        ],
        "type": "server",
        "use_private_ip": true
      }
    ]
  }
}

Delete a Load Balancer

Deletes a Load Balancer.

HTTP Request

DELETE /load_balancers/{id}

Path Parameters

  • idinteger required

    ID of the Load Balancer

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}'

Response headers

Status: 204

Get a Load Balancer

Gets a specific Load Balancer object.

HTTP Request

GET /load_balancers/{id}

Path Parameters

  • idinteger required

    ID of the Load Balancer

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancer": {
    "algorithm": {
      "type": "round_robin"
    },
    "created": "2016-01-30T23:55:00+00:00",
    "id": 42,
    "included_traffic": 10000,
    "ingoing_traffic": null,
    "labels": {},
    "load_balancer_type": {
      "deprecated": "2016-01-30T23:50:00+00:00",
      "description": "LB11",
      "id": 1,
      "max_assigned_certificates": 10,
      "max_connections": 20000,
      "max_services": 5,
      "max_targets": 25,
      "name": "lb11",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          },
          "price_monthly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          }
        }
      ]
    },
    "location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "name": "my-resource",
    "outgoing_traffic": null,
    "private_net": [
      {
        "ip": "10.0.0.2",
        "network": 4711
      }
    ],
    "protection": {
      "delete": false
    },
    "public_net": {
      "enabled": false,
      "ipv4": {
        "dns_ptr": "lb1.example.com",
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "dns_ptr": "lb1.example.com",
        "ip": "2001:db8::1"
      }
    },
    "services": [
      {
        "destination_port": 80,
        "health_check": {
          "http": {
            "domain": "example.com",
            "path": "/",
            "response": "{\"status\": \"ok\"}",
            "status_codes": [
              "2??",
              "3??"
            ],
            "tls": false
          },
          "interval": 15,
          "port": 4711,
          "protocol": "http",
          "retries": 3,
          "timeout": 10
        },
        "http": {
          "certificates": [
            897
          ],
          "cookie_lifetime": 300,
          "cookie_name": "HCLBSTICKY",
          "redirect_http": true,
          "sticky_sessions": true
        },
        "listen_port": 443,
        "protocol": "https",
        "proxyprotocol": false
      }
    ],
    "targets": [
      {
        "health_status": [
          {
            "listen_port": 443,
            "status": "healthy"
          }
        ],
        "ip": {
          "ip": "203.0.113.1"
        },
        "label_selector": {
          "selector": "env=prod"
        },
        "server": {
          "id": 80
        },
        "targets": [
          {
            "health_status": [
              {
                "listen_port": 443,
                "status": "healthy"
              }
            ],
            "server": {
              "id": 85
            },
            "type": "server",
            "use_private_ip": false
          }
        ],
        "type": "server",
        "use_private_ip": false
      }
    ]
  }
}

Update a Load Balancer

Updates a Load Balancer. You can update a Load Balancer’s name and a Load Balancer’s labels.

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

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

HTTP Request

PUT /load_balancers/{id}

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New Load Balancer name

Response

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"labels":{"labelkey":"value"},"name":"new-name"}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}'

Request

{
  "labels": {
    "labelkey": "value"
  },
  "name": "new-name"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancer": {
    "algorithm": {
      "type": "round_robin"
    },
    "created": "2016-01-30T23:50:00+00:00",
    "id": 4711,
    "included_traffic": 654321,
    "ingoing_traffic": 123456,
    "labels": {
      "labelkey": "value"
    },
    "load_balancer_type": {
      "deprecated": "2016-01-30T23:50:00+00:00",
      "description": "LB11",
      "id": 1,
      "max_assigned_certificates": 10,
      "max_connections": 20000,
      "max_services": 5,
      "max_targets": 25,
      "name": "lb11",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          },
          "price_monthly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          }
        }
      ]
    },
    "location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "name": "new-name",
    "outgoing_traffic": 123456,
    "private_net": [
      {
        "ip": "10.0.0.2",
        "network": 4711
      }
    ],
    "protection": {
      "delete": false
    },
    "public_net": {
      "enabled": false,
      "ipv4": {
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "ip": "2001:db8::1"
      }
    },
    "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": "http",
        "proxyprotocol": false
      }
    ],
    "targets": [
      {
        "health_status": [
          {
            "listen_port": 443,
            "status": "healthy"
          }
        ],
        "ip": {
          "ip": "203.0.113.1"
        },
        "label_selector": {
          "selector": "env=prod"
        },
        "server": {
          "id": 80
        },
        "targets": [
          {
            "health_status": [
              {
                "listen_port": 443,
                "status": "healthy"
              }
            ],
            "label_selector": null,
            "server": {
              "id": 80
            },
            "type": "server",
            "use_private_ip": true
          }
        ],
        "type": "server",
        "use_private_ip": true
      }
    ]
  }
}

Get Metrics for a LoadBalancer

You must specify the type of metric to get: open_connections, connections_per_second, requests_per_second or bandwidth. You can also specify more than one type by comma separation, e.g. requests_per_second,bandwidth.

Depending on the type you will get different time series data:

Type Timeseries Unit Description
open_connections open_connections number Open connections
connections_per_second connections_per_second connections/s Connections per second
requests_per_second requests_per_second requests/s Requests per second
bandwidth bandwidth.in bytes/s Ingress bandwidth
bandwidth.out bytes/s Egress bandwidth

Metrics are available for the last 30 days only.

If you do not provide the step argument we will automatically adjust it so that 200 samples are returned.

We limit the number of samples to a maximum of 500 and will adjust the step parameter accordingly.

HTTP Request

GET /load_balancers/{id}/metrics

Path Parameters

  • idinteger required

    ID of the Load Balancer

Query Parameters

  • typestring required
    Possible enum values:
    open_connectionsconnections_per_secondrequests_per_secondbandwidth

    Type of metrics to get

  • startstring required

    Start of period to get Metrics for (in ISO-8601 format)

  • endstring required

    End of period to get Metrics for (in ISO-8601 format)

  • stepstring

    Resolution of results in seconds

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/metrics'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "metrics": {
    "end": "2017-01-01T23:00:00+00:00",
    "start": "2017-01-01T00:00:00+00:00",
    "step": 60,
    "time_series": {
      "name_of_timeseries": {
        "values": [
          [
            1435781470.622,
            "42"
          ],
          [
            1435781471.622,
            "43"
          ]
        ]
      }
    }
  }
}

Load Balancer Actions

Get all Actions for a Load Balancer

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

HTTP Request

GET /load_balancers/{id}/actions

Path Parameters

  • idinteger required

    ID of the Load Balancer

Query Parameters

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "add_service",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 4711,
          "type": "load_balancer"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Get an Action for a Load Balancer

Returns a specific Action for a Load Balancer.

HTTP Request

GET /load_balancers/{id}/actions/{action_id}

Path Parameters

  • idinteger required

    ID of the Load Balancer

  • action_idinteger required

    ID of the Action

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "change_protection",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Add Service

Adds a service to a Load Balancer.

Call specific error codes

Code Description
source_port_already_used The source port you are trying to add is already in use

HTTP Request

POST /load_balancers/{id}/actions/add_service

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • destination_portinteger required

    Port the Load Balancer will balance to

  • listen_portinteger required

    Port the Load Balancer listens on

  • protocolstring required
    Possible enum values:
    tcphttphttps

    Protocol of the Load Balancer

  • proxyprotocolboolean required

    Is Proxyprotocol enabled or not

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"destination_port":80,"health_check":{"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false},"interval":15,"port":4711,"protocol":"http","retries":3,"timeout":10},"http":{"certificates":[897],"cookie_lifetime":300,"cookie_name":"HCLBSTICKY","redirect_http":true,"sticky_sessions":true},"listen_port":443,"protocol":"https","proxyprotocol":false}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_service'

Request

{
  "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
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "add_service",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Add Target

Adds a target to 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 you are trying to add as a target is not owned by the Project owner
load_balancer_not_attached_to_network The Load Balancer is not attached to a network
robot_unavailable Robot was not available. The caller may retry the operation after a short delay.
server_not_attached_to_network The server you are trying to add as a target is not attached to the same network as the Load Balancer
target_already_defined The Load Balancer target you are trying to define is already defined

HTTP Request

POST /load_balancers/{id}/actions/add_target

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • typestring required
    Possible enum values:
    serverlabel_selectorip

    Type of the resource

  • use_private_ipboolean

    Use the private network IP instead of the public IP of the Server, requires the Server and Load Balancer to be in the same network. Default value is false.

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip":{"ip":"203.0.113.1"},"label_selector":{"selector":"env=prod"},"server":{"id":80},"type":"server","use_private_ip":true}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/add_target'

Request

{
  "ip": {
    "ip": "203.0.113.1"
  },
  "label_selector": {
    "selector": "env=prod"
  },
  "server": {
    "id": 80
  },
  "type": "server",
  "use_private_ip": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "add_target",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Attach a Load Balancer to a Network

Attach a Load Balancer to a Network.

Call specific error codes

Code Description
load_balancer_already_attached The Load Balancer is already attached to a network
ip_not_available The provided Network IP is not available
no_subnet_available No Subnet or IP is available for the Load Balancer within the network

HTTP Request

POST /load_balancers/{id}/actions/attach_to_network

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • ipstring

    IP to request to be assigned to this Load Balancer; if you do not provide this then you will be auto assigned an IP address

  • networknumber required

    ID of an existing network to attach the Load Balancer to

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip":"10.0.1.1","network":4711}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/attach_to_network'

Request

{
  "ip": "10.0.1.1",
  "network": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "attach_to_network",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Change Algorithm

Change the algorithm that determines to which target new requests are sent.

HTTP Request

POST /load_balancers/{id}/actions/change_algorithm

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • typestring required
    Possible enum values:
    round_robinleast_connections

    Algorithm of the Load Balancer

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"type":"round_robin"}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_algorithm'

Request

{
  "type": "round_robin"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_algorithm",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Change reverse DNS entry for this Load Balancer

Changes the hostname that will appear when getting the hostname belonging to the public IPs (IPv4 and IPv6) of this Load Balancer.

Floating IPs assigned to the Server are not affected by this.

HTTP Request

POST /load_balancers/{id}/actions/change_dns_ptr

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

Select the IP address for which to change the DNS entry by passing ip. It can be either IPv4 or IPv6. The target hostname is set by passing dns_ptr.

  • dns_ptrstring – nullablerequired

    Hostname to set as a reverse DNS PTR entry

  • ipstring required

    Public IP address for which the reverse DNS entry should be set

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"dns_ptr":"lb1.example.com","ip":"1.2.3.4"}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_dns_ptr'

Request

{
  "dns_ptr": "lb1.example.com",
  "ip": "1.2.3.4"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_dns_ptr",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Change Load Balancer Protection

Changes the protection configuration of a Load Balancer.

HTTP Request

POST /load_balancers/{id}/actions/change_protection

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • deleteboolean

    If true, prevents the Load Balancer from being deleted

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_protection'

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_protection",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Change the Type of a Load Balancer

Changes the type (Max Services, Max Targets and Max Connections) of a Load Balancer.

Call specific error codes

Code Description
invalid_load_balancer_type The Load Balancer type does not fit for the given Load Balancer

HTTP Request

POST /load_balancers/{id}/actions/change_type

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • load_balancer_typestring required

    ID or name of Load Balancer type the Load Balancer should migrate to

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"load_balancer_type":"lb21"}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/change_type'

Request

{
  "load_balancer_type": "lb21"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_load_balancer_type",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Delete Service

Delete a service of a Load Balancer.

HTTP Request

POST /load_balancers/{id}/actions/delete_service

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • listen_portnumber required

    The listen port of the service you want to delete

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"listen_port":4711}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/delete_service'

Request

{
  "listen_port": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "delete_service",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Detach a Load Balancer from a Network

Detaches a Load Balancer from a network.

HTTP Request

POST /load_balancers/{id}/actions/detach_from_network

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • networknumber required

    ID of an existing network to detach the Load Balancer from

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"network":4711}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/detach_from_network'

Request

{
  "network": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "detach_from_network",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Disable the public interface of a Load Balancer

Disable the public interface of a Load Balancer. The Load Balancer will be not accessible from the internet via its public IPs.

Call specific error codes

Code Description
load_balancer_not_attached_to_network The Load Balancer is not attached to a network
targets_without_use_private_ip The Load Balancer has targets that use the public IP instead of the private IP

HTTP Request

POST /load_balancers/{id}/actions/disable_public_interface

Path Parameters

  • idinteger required

    ID of the Load Balancer

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/disable_public_interface'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "disable_public_interface",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Enable the public interface of a Load Balancer

Enable the public interface of a Load Balancer. The Load Balancer will be accessible from the internet via its public IPs.

HTTP Request

POST /load_balancers/{id}/actions/enable_public_interface

Path Parameters

  • idinteger required

    ID of the Load Balancer

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/enable_public_interface'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "enable_public_interface",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Remove Target

Removes a target from a Load Balancer.

HTTP Request

POST /load_balancers/{id}/actions/remove_target

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • typestring required
    Possible enum values:
    serverlabel_selectorip

    Type of the resource

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip":{"ip":"203.0.113.1"},"label_selector":{"selector":"env=prod"},"server":{"id":80},"type":"server"}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/remove_target'

Request

{
  "ip": {
    "ip": "203.0.113.1"
  },
  "label_selector": {
    "selector": "env=prod"
  },
  "server": {
    "id": 80
  },
  "type": "server"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "remove_target",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Update Service

Updates a Load Balancer Service.

Call specific error codes

Code Description
source_port_already_used The source port you are trying to add is already in use

HTTP Request

POST /load_balancers/{id}/actions/update_service

Path Parameters

  • idinteger required

    ID of the Load Balancer

Request

  • destination_portinteger required

    Port the Load Balancer will balance to

  • listen_portinteger required

    Port the Load Balancer listens on

  • protocolstring required
    Possible enum values:
    tcphttphttps

    Protocol of the Load Balancer

  • proxyprotocolboolean required

    Is Proxyprotocol enabled or not

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"destination_port":80,"health_check":{"http":{"domain":"example.com","path":"/","response":"{\"status\": \"ok\"}","status_codes":["2??","3??"],"tls":false},"interval":15,"port":4711,"protocol":"http","retries":3,"timeout":10},"http":{"certificates":[897],"cookie_lifetime":300,"cookie_name":"HCLBSTICKY","redirect_http":true,"sticky_sessions":true},"listen_port":443,"protocol":"https","proxyprotocol":false}' \
	'https://api.hetzner.cloud/v1/load_balancers/{id}/actions/update_service'

Request

{
  "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
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "update_service",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "load_balancer"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Load Balancer Types

Load Balancer types define kinds of Load Balancers offered. Each type has an hourly and a monthly cost. You will pay whichever amount is lower for your usage of this specific Load Balancer. Costs may differ between Locations.

Currency for all amounts is €. All prices exclude VAT.

Get all Load Balancer Types

Gets all Load Balancer type objects.

HTTP Request

GET /load_balancer_types

Query Parameters

  • namestring

    Can be used to filter Load Balancer types by their name. The response will only contain the Load Balancer type matching the specified name.

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancer_types'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancer_types": [
    {
      "deprecated": "2016-01-30T23:50:00+00:00",
      "description": "LB11",
      "id": 1,
      "max_assigned_certificates": 10,
      "max_connections": 20000,
      "max_services": 5,
      "max_targets": 25,
      "name": "lb11",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          },
          "price_monthly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          }
        }
      ]
    }
  ]
}

Get a Load Balancer Type

Gets a specific Load Balancer type object.

HTTP Request

GET /load_balancer_types/{id}

Path Parameters

  • idinteger required

    ID of Load Balancer type

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/load_balancer_types/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "load_balancer_type": {
    "deprecated": "2016-01-30T23:50:00+00:00",
    "description": "LB11",
    "id": 1,
    "max_assigned_certificates": 10,
    "max_connections": 20000,
    "max_services": 5,
    "max_targets": 25,
    "name": "lb11",
    "prices": [
      {
        "location": "fsn1",
        "price_hourly": {
          "gross": "1.1900000000000000",
          "net": "1.0000000000"
        },
        "price_monthly": {
          "gross": "1.1900000000000000",
          "net": "1.0000000000"
        }
      }
    ]
  }
}

Locations

Datacenters are organized by Locations. Datacenters in the same Location are connected with very low latency links.

Get all Locations

Returns all Location objects.

HTTP Request

GET /locations

Query Parameters

  • namestring

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/locations'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "locations": [
    {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    }
  ]
}

Get a Location

Returns a specific Location object.

HTTP Request

GET /locations/{id}

Path Parameters

  • idinteger required

    ID of Location

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/locations/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "location": {
    "city": "Falkenstein",
    "country": "DE",
    "description": "Falkenstein DC Park 1",
    "id": 1,
    "latitude": 50.47612,
    "longitude": 12.370071,
    "name": "fsn1",
    "network_zone": "eu-central"
  }
}

Networks

Networks is a private networks feature. These Networks are optional and they coexist with the public network that every Server has by default.

They allow Servers to talk to each other over a dedicated network interface using private IP addresses not available publicly.

The IP addresses are allocated and managed via the API, they must conform to RFC1918 standard. IPs and network interfaces defined under Networks do not provide public internet connectivity, you will need to use the already existing public network interface for that.

Each network has a user selected ip_range which defines all available IP addresses which can be used for Subnets within the Network.

To assign individual IPs to Servers you will need to create Network Subnets, described below.

Currently Networks support IPv4 only.

Subnets

Subnets divide the ip_range from the parent Network object into multiple Subnetworks that you can use for different specific purposes.

For each subnet you need to specify its own ip_range which must be contained within the parent Network’s ip_range. Additionally each subnet must belong to one of the available Network Zones described below. Subnets can not have overlapping IP ranges.

Currently there are three types of subnet:

  • type cloud is used to connect cloud Resources into your Network.
  • type server was used to connect only cloud Servers into your Network. This type is deprecated and is replaced by type cloud.
  • type vswitch allows you to connect Dedicated Server vSwitch - and all Dedicated Servers attached to it - into your Network

Subnets of type vswitch must set a vswitch_id which is the ID of the existing vSwitch in Hetzner Robot that should be coupled.

Network Zones

Network Zones are groups of Locations which have special high-speed network connections between them. The Location object contains the network_zone property each Location belongs to. Currently only one Network zone exists and is called eu-central. It spans the nbg1, fsn1 and hel1 Locations.

IP address management

When a cloud Server is attached to a network without the user specifying an IP it automatically gets an IP address assigned from a subnet of type server in the same network zone. If you specify the optional ip parameter when attaching then we will try to assign that IP. Keep in mind that the Server’s location must be covered by the Subnet’s Network Zone if you specify an IP, or that at least one Subnet with the zone covering Server’s location must exist.

A cloud Server can also have more than one IP address in a Network by specifying aliases. For details see the attach to network action.

The following IP addresses are reserved in networks and can not be used:

  • the first IP of the network ip_range as it will be used as a default gateway for the private Network interface.
  • 172.31.1.1 as it is being used as default gateway for our public Network interfaces.

Coupling Dedicated Servers

By using subnets of type vswitch you can couple the Cloud Networks with an existing Dedicated Server vSwitch and enable dedicated and cloud servers to talk to each other over the Network. In order for this to work the dedicated servers may only use IPs from the subnet and must have a special network configuration. Please refer to FAQ. vSwitch Layer 2 features are not supported.

Routes

Networks also support the notion of routes which are automatically applied to private traffic. A route makes sure that all packets for a given destination IP prefix will be sent to the address specified in its gateway.

Get all Networks

Gets all existing networks that you have available.

HTTP Request

GET /networks

Query Parameters

  • namestring

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

  • label_selectorstring

    Can be used to filter networks by labels. The response will only contain networks with a matching label selector pattern.

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  },
  "networks": [
    {
      "created": "2016-01-30T23:50:00+00:00",
      "id": 4711,
      "ip_range": "10.0.0.0/16",
      "labels": {},
      "load_balancers": [
        42
      ],
      "name": "mynet",
      "protection": {
        "delete": false
      },
      "routes": [
        {
          "destination": "10.100.1.0/24",
          "gateway": "10.0.1.1"
        }
      ],
      "servers": [
        42
      ],
      "subnets": [
        {
          "gateway": "10.0.0.1",
          "ip_range": "10.0.1.0/24",
          "network_zone": "eu-central",
          "type": "cloud"
        }
      ]
    }
  ]
}

Create a Network

Creates a network with the specified ip_range.

You may specify one or more subnets. You can also add more Subnets later by using the add subnet action. If you do not specify an ip_range in the subnet we will automatically pick the first available /24 range for you.

You may specify one or more routes in routes. You can also add more routes later by using the add route action.

HTTP Request

POST /networks

Request

  • ip_rangestring required

    IP range of the whole network which must span all included subnets. Must be one of the private IPv4 ranges of RFC1918. Minimum network size is /24. We highly recommend that you pick a larger network with a /16 netmask.

  • namestring required

    Name of the network

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip_range":"10.0.0.0/16","labels":{"labelkey":"value"},"name":"mynet","routes":[{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}],"subnets":[{"ip_range":"10.0.1.0/24","network_zone":"eu-central","type":"cloud"}]}' \
	'https://api.hetzner.cloud/v1/networks'

Request

{
  "ip_range": "10.0.0.0/16",
  "labels": {
    "labelkey": "value"
  },
  "name": "mynet",
  "routes": [
    {
      "destination": "10.100.1.0/24",
      "gateway": "10.0.1.1"
    }
  ],
  "subnets": [
    {
      "ip_range": "10.0.1.0/24",
      "network_zone": "eu-central",
      "type": "cloud"
    }
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "network": {
    "created": "2016-01-30T23:50:00+00:00",
    "id": 4711,
    "ip_range": "10.0.0.0/16",
    "labels": {},
    "load_balancers": [
      42
    ],
    "name": "mynet",
    "protection": {
      "delete": false
    },
    "routes": [
      {
        "destination": "10.100.1.0/24",
        "gateway": "10.0.1.1"
      }
    ],
    "servers": [
      42
    ],
    "subnets": [
      {
        "gateway": "10.0.0.1",
        "ip_range": "10.0.1.0/24",
        "network_zone": "eu-central",
        "type": "cloud"
      }
    ]
  }
}

Delete a Network

Deletes a network. If there are Servers attached they will be detached in the background.

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

HTTP Request

DELETE /networks/{id}

Path Parameters

  • idinteger required

    ID of the network

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks/{id}'

Response headers

Status: 204

Get a Network

Gets a specific network object.

HTTP Request

GET /networks/{id}

Path Parameters

  • idinteger required

    ID of the network

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "network": {
    "created": "2016-01-30T23:50:00+00:00",
    "id": 4711,
    "ip_range": "10.0.0.0/16",
    "labels": {},
    "load_balancers": [
      42
    ],
    "name": "mynet",
    "protection": {
      "delete": false
    },
    "routes": [
      {
        "destination": "10.100.1.0/24",
        "gateway": "10.0.1.1"
      }
    ],
    "servers": [
      42
    ],
    "subnets": [
      {
        "gateway": "10.0.0.1",
        "ip_range": "10.0.1.0/24",
        "network_zone": "eu-central",
        "type": "cloud"
      }
    ]
  }
}

Update a Network

Updates the network properties.

Note that when updating labels, the network’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 network object changes during the request, the response will be a “conflict” error.

HTTP Request

PUT /networks/{id}

Path Parameters

  • idinteger required

    ID of the network

Request

  • namestring

    New network name

Response

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"labels":{"labelkey":"value"},"name":"new-name"}' \
	'https://api.hetzner.cloud/v1/networks/{id}'

Request

{
  "labels": {
    "labelkey": "value"
  },
  "name": "new-name"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "network": {
    "created": "2016-01-30T23:50:00+00:00",
    "id": 4711,
    "ip_range": "10.0.0.0/16",
    "labels": {
      "labelkey": "value"
    },
    "load_balancers": [
      42
    ],
    "name": "new-name",
    "protection": {
      "delete": false
    },
    "routes": [
      {
        "destination": "10.100.1.0/24",
        "gateway": "10.0.1.1"
      }
    ],
    "servers": [
      42
    ],
    "subnets": [
      {
        "gateway": "10.0.0.1",
        "ip_range": "10.0.1.0/24",
        "network_zone": "eu-central",
        "type": "cloud"
      }
    ]
  }
}

Network Actions

Get all Actions for a Network

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

HTTP Request

GET /networks/{id}/actions

Path Parameters

  • idinteger required

    ID of the Network

Query Parameters

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "add_subnet",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Get an Action for a Network

Returns a specific Action for a Network.

HTTP Request

GET /networks/{id}/actions/{action_id}

Path Parameters

  • idinteger required

    ID of the Network

  • action_idinteger required

    ID of the Action

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "add_subnet",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Add a route to a Network

Adds a route entry to a Network.

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

HTTP Request

POST /networks/{id}/actions/add_route

Path Parameters

  • idinteger required

    ID of the Network

Request

  • destinationstring required

    Destination network or host of this route. Must not overlap with an existing ip_range in any subnets or with any destinations in other routes or with the first IP of the networks ip_range or with 172.31.1.1. Must be one of the private IPv4 ranges of RFC1918.

  • gatewaystring required

    Gateway for the route. Cannot be the first IP of the networks ip_range, an IP behind a vSwitch or 172.31.1.1, as this IP is being used as a gateway for the public network interface of Servers.

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/add_route'

Request

{
  "destination": "10.100.1.0/24",
  "gateway": "10.0.1.1"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "add_route",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Add a subnet to a Network

Adds a new subnet object to the Network. If you do not specify an ip_range for the subnet we will automatically pick the first available /24 range for you if possible.

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

HTTP Request

POST /networks/{id}/actions/add_subnet

Path Parameters

  • idinteger required

    ID of the Network

Request

  • ip_rangestring

    Range to allocate IPs from. Must be a Subnet of the ip_range of the parent network object and must not overlap with any other subnets or with any destinations in routes. If the Subnet is of type vSwitch, it also can not overlap with any gateway in routes. Minimum Network size is /30. We suggest that you pick a bigger Network with a /24 netmask.

  • network_zonestring required

    Name of Network zone. Currently eu-central is the only available zone.

  • typestring required
    Possible enum values:
    cloudservervswitch

    Type of Subnetwork

  • vswitch_idinteger

    ID of the robot vSwitch. Must be supplied if the subnet is of type vswitch.

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip_range":"10.0.1.0/24","network_zone":"eu-central","type":"cloud","vswitch_id":1000}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/add_subnet'

Request

{
  "ip_range": "10.0.1.0/24",
  "network_zone": "eu-central",
  "type": "cloud",
  "vswitch_id": 1000
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "add_subnet",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Change IP range of a Network

Changes the IP range of a Network. IP ranges can only be extended and never shrunk. You can only add IPs at the end of an existing IP range. This means that the IP part of your existing range must stay the same and you can only change its netmask.

For example if you have a range 10.0.0.0/16 you want to extend then your new range must also start with the IP 10.0.0.0. Your CIDR netmask /16 may change to a number that is smaller than 16 thereby increasing the IP range. So valid entries would be 10.0.0.0/15, 10.0.0.0/14, 10.0.0.0/13 and so on.

After changing the IP range you will have to adjust the routes on your connected Servers by either rebooting them or manually changing the routes to your private Network interface.

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

HTTP Request

POST /networks/{id}/actions/change_ip_range

Path Parameters

  • idinteger required

    ID of the Network

Request

  • ip_rangestring required

    The new prefix for the whole Network

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip_range":"10.0.0.0/12"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/change_ip_range'

Request

{
  "ip_range": "10.0.0.0/12"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_ip_range",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Change Network Protection

Changes the protection configuration of a Network.

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

HTTP Request

POST /networks/{id}/actions/change_protection

Path Parameters

  • idinteger required

    ID of the Network

Request

  • deleteboolean

    If true, prevents the Network from being deleted

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/change_protection'

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_protection",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Delete a route from a Network

Delete a route entry from a Network.

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

HTTP Request

POST /networks/{id}/actions/delete_route

Path Parameters

  • idinteger required

    ID of the Network

Request

  • destinationstring required

    Destination network or host of this route. Must not overlap with an existing ip_range in any subnets or with any destinations in other routes or with the first IP of the networks ip_range or with 172.31.1.1. Must be one of the private IPv4 ranges of RFC1918.

  • gatewaystring required

    Gateway for the route. Cannot be the first IP of the networks ip_range, an IP behind a vSwitch or 172.31.1.1, as this IP is being used as a gateway for the public network interface of Servers.

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"destination":"10.100.1.0/24","gateway":"10.0.1.1"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/delete_route'

Request

{
  "destination": "10.100.1.0/24",
  "gateway": "10.0.1.1"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "delete_route",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Delete a subnet from a Network

Deletes a single subnet entry from a Network. You cannot delete subnets which still have Servers attached. If you have Servers attached you first need to detach all Servers that use IPs from this subnet before you can delete the subnet.

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

HTTP Request

POST /networks/{id}/actions/delete_subnet

Path Parameters

  • idinteger required

    ID of the Network

Request

  • ip_rangestring required

    IP range of subnet to delete

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ip_range":"10.0.1.0/24"}' \
	'https://api.hetzner.cloud/v1/networks/{id}/actions/delete_subnet'

Request

{
  "ip_range": "10.0.1.0/24"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "delete_subnet",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Placement Groups

Placement groups are used to influence the location of interdependent virtual servers in our data centers. The distribution of the different instances within a group is based on a pattern specified in the type. By enforcing certain rules on the placement of instances within our infrastructure, availability can be influenced in a way that fits your needs best.

In spread placement groups, all virtual servers will run on different physical servers. This decreases the probability that some instances might fail together.

Get all PlacementGroups

Returns all PlacementGroup objects.

HTTP Request

GET /placement_groups

Query Parameters

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

    Can be used multiple times.

  • namestring

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

  • label_selectorstring

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

  • typestring
    Possible enum values:
    spread

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/placement_groups'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "placement_groups": [
    {
      "created": "2019-01-08T12:10:00+00:00",
      "id": 897,
      "labels": {
        "key": "value"
      },
      "name": "my Placement Group",
      "servers": [
        4711,
        4712
      ],
      "type": "spread"
    }
  ]
}

Create a PlacementGroup

Creates a new PlacementGroup.

HTTP Request

POST /placement_groups

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring required

    Name of the PlacementGroup

  • typestring required
    Possible enum values:
    spread

    Define the Placement Group Type.

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"my Placement Group","type":"spread"}' \
	'https://api.hetzner.cloud/v1/placement_groups'

Request

{
  "name": "my Placement Group",
  "type": "spread"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "placement_group": {
    "created": "2019-01-08T12:10:00+00:00",
    "id": 897,
    "labels": {
      "key": "value"
    },
    "name": "my Placement Group",
    "servers": [],
    "type": "spread"
  }
}

Delete a PlacementGroup

Deletes a PlacementGroup.

HTTP Request

DELETE /placement_groups/{id}

Path Parameters

  • idinteger required

    ID of the resource

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/placement_groups/{id}'

Response headers

Status: 204

Get a PlacementGroup

Gets a specific PlacementGroup object.

HTTP Request

GET /placement_groups/{id}

Path Parameters

  • idinteger required

    ID of the resource

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/placement_groups/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "placement_group": {
    "created": "2019-01-08T12:10:00+00:00",
    "id": 897,
    "labels": {
      "key": "value"
    },
    "name": "my Placement Group",
    "servers": [
      4711,
      4712
    ],
    "type": "spread"
  }
}

Update a PlacementGroup

Updates the PlacementGroup properties.

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

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

HTTP Request

PUT /placement_groups/{id}

Path Parameters

  • idinteger required

    ID of the resource

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New PlacementGroup name

Response

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"labels":{"labelkey":"value"},"name":"my Placement Group"}' \
	'https://api.hetzner.cloud/v1/placement_groups/{id}'

Request

{
  "labels": {
    "labelkey": "value"
  },
  "name": "my Placement Group"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "placement_group": {
    "created": "2019-01-08T12:10:00+00:00",
    "id": 897,
    "labels": {
      "key": "value"
    },
    "name": "my Placement Group",
    "servers": [
      4711,
      4712
    ],
    "type": "spread"
  }
}

Pricing

Returns prices for resources.

Get all prices

Returns prices for all resources available on the platform. VAT and currency of the Project owner are used for calculations.

Both net and gross prices are included in the response.

HTTP Request

GET /pricing

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/pricing'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "pricing": {
    "currency": "EUR",
    "floating_ip": {
      "price_monthly": {
        "gross": "1.1900000000000000",
        "net": "1.0000000000"
      }
    },
    "floating_ips": [
      {
        "prices": [
          {
            "location": "fsn1",
            "price_monthly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            }
          }
        ],
        "type": "ipv4"
      }
    ],
    "image": {
      "price_per_gb_month": {
        "gross": "1.1900000000000000",
        "net": "1.0000000000"
      }
    },
    "load_balancer_types": [
      {
        "id": 1,
        "name": "lb11",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            },
            "price_monthly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            }
          }
        ]
      }
    ],
    "server_backup": {
      "percentage": "20.0000000000"
    },
    "server_types": [
      {
        "id": 4,
        "name": "cx11",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            },
            "price_monthly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            }
          }
        ]
      }
    ],
    "traffic": {
      "price_per_tb": {
        "gross": "1.1900000000000000",
        "net": "1.0000000000"
      }
    },
    "vat_rate": "19.000000",
    "volume": {
      "price_per_gb_month": {
        "gross": "1.1900000000000000",
        "net": "1.0000000000"
      }
    }
  }
}

Servers

Servers are virtual machines that can be provisioned.

Get all Servers

Returns all existing Server objects

HTTP Request

GET /servers

Query Parameters

  • namestring

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

  • label_selectorstring

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

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    initializingstartingrunningstoppingoffdeletingrebuildingmigratingunknown

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  },
  "servers": [
    {
      "backup_window": "22-02",
      "created": "2016-01-30T23:55:00+00:00",
      "datacenter": {
        "description": "Falkenstein DC Park 8",
        "id": 42,
        "location": {
          "city": "Falkenstein",
          "country": "DE",
          "description": "Falkenstein DC Park 1",
          "id": 1,
          "latitude": 50.47612,
          "longitude": 12.370071,
          "name": "fsn1",
          "network_zone": "eu-central"
        },
        "name": "fsn1-dc8",
        "server_types": {
          "available": [
            1,
            2,
            3
          ],
          "available_for_migration": [
            1,
            2,
            3
          ],
          "supported": [
            1,
            2,
            3
          ]
        }
      },
      "id": 42,
      "image": {
        "bound_to": null,
        "build_id": "c313fe40383af26094a5a92026054320ab55abc7",
        "created": "2016-01-30T23:55:00+00:00",
        "created_from": {
          "id": 1,
          "name": "Server"
        },
        "deleted": null,
        "deprecated": "2018-02-28T00:00:00+00:00",
        "description": "Ubuntu 20.04 Standard 64 bit",
        "disk_size": 10,
        "id": 42,
        "image_size": 2.3,
        "labels": {},
        "name": "ubuntu-20.04",
        "os_flavor": "ubuntu",
        "os_version": "20.04",
        "protection": {
          "delete": false
        },
        "rapid_deploy": false,
        "status": "available",
        "type": "snapshot"
      },
      "included_traffic": 654321,
      "ingoing_traffic": 123456,
      "iso": {
        "deprecated": "2018-02-28T00:00:00+00:00",
        "description": "FreeBSD 11.0 x64",
        "id": 42,
        "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
        "type": "public"
      },
      "labels": {},
      "load_balancers": [],
      "locked": false,
      "name": "my-resource",
      "outgoing_traffic": 123456,
      "placement_group": {
        "created": "2016-01-30T23:55:00+00:00",
        "id": 42,
        "labels": {},
        "name": "my-resource",
        "servers": [
          42
        ],
        "type": "spread"
      },
      "primary_disk_size": 50,
      "private_net": [
        {
          "alias_ips": [],
          "ip": "10.0.0.2",
          "mac_address": "86:00:ff:2a:7d:e1",
          "network": 4711
        }
      ],
      "protection": {
        "delete": false,
        "rebuild": false
      },
      "public_net": {
        "firewalls": [
          {
            "id": 42,
            "status": "applied"
          }
        ],
        "floating_ips": [
          478
        ],
        "ipv4": {
          "blocked": false,
          "dns_ptr": "server01.example.com",
          "ip": "1.2.3.4"
        },
        "ipv6": {
          "blocked": false,
          "dns_ptr": [
            {
              "dns_ptr": "server.example.com",
              "ip": "2001:db8::1"
            }
          ],
          "ip": "2001:db8::/64"
        }
      },
      "rescue_enabled": false,
      "server_type": {
        "cores": 1,
        "cpu_type": "shared",
        "deprecated": false,
        "description": "CX11",
        "disk": 25,
        "id": 1,
        "memory": 1,
        "name": "cx11",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            },
            "price_monthly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            }
          }
        ],
        "storage_type": "local"
      },
      "status": "running",
      "volumes": []
    }
  ]
}

Create a Server

Creates a new Server. Returns preliminary information about the Server as well as an Action that covers progress of creation.

HTTP Request

POST /servers

Request

Please note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes).

For server_type you can either use the ID as listed in /server_types or its name.

For image you can either use the ID as listed in /images or its name.

If you want to create the Server in a Location, you must set location to the ID or name as listed in /locations. This is the recommended way. You can be even more specific by setting datacenter to the ID or name as listed in /datacenters. However directly specifying the Datacenter is discouraged since supply availability in Datacenters varies greatly and Datacenters may be out of stock for extended periods of time or not serve certain Server types at all.

Some properties like start_after_create or automount will trigger Actions after the Server is created. Those Actions are listed in the next_actions field in the response.

For accessing your Server we strongly recommend to use SSH keys by passing the respective key IDs in ssh_keys. If you do not specify any ssh_keys we will generate a root password for you and return it in the response.

Please note that provided user-data is stored in our systems. While we take measures to protect it we highly recommend that you don’t use it to store passwords or other sensitive information.

Call specific error codes

Code Description
placement_error An error during the placement occurred
  • automountboolean

    Auto-mount Volumes after attach

  • datacenterstring

    ID or name of Datacenter to create Server in (must not be used together with location)

  • imagestring required

    ID or name of the Image the Server is created from

  • labelsobject

    User-defined labels (key-value pairs)

  • locationstring

    ID or name of Location to create Server in (must not be used together with datacenter)

  • namestring required

    Name of the Server to create (must be unique per Project and a valid hostname as per RFC 1123)

  • server_typestring required

    ID or name of the Server type this Server should be created with

  • start_after_createboolean

    Start Server right after creation. Defaults to true.

  • user_datastring

    Cloud-Init user data to use during Server creation. This field is limited to 32KiB.

Response

  • root_passwordstring – nullablerequired

    Root password when no SSH keys have been specified

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"automount":false,"datacenter":"nbg1-dc3","firewalls":[{"firewall":38}],"image":"ubuntu-20.04","labels":{},"location":"nbg1","name":"my-server","networks":[456],"server_type":"cx11","ssh_keys":["my-ssh-key"],"start_after_create":true,"user_data":"#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n","volumes":[123]}' \
	'https://api.hetzner.cloud/v1/servers'

Request

{
  "automount": false,
  "datacenter": "nbg1-dc3",
  "firewalls": [
    {
      "firewall": 38
    }
  ],
  "image": "ubuntu-20.04",
  "labels": {},
  "location": "nbg1",
  "name": "my-server",
  "networks": [
    456
  ],
  "server_type": "cx11",
  "ssh_keys": [
    "my-ssh-key"
  ],
  "start_after_create": true,
  "user_data": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n",
  "volumes": [
    123
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "create_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 1,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  },
  "next_actions": [
    {
      "command": "start_server",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": null,
      "id": 13,
      "progress": 0,
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "started": "2016-01-30T23:50:00+00:00",
      "status": "running"
    }
  ],
  "root_password": "YItygq1v3GYjjMomLaKc",
  "server": {
    "backup_window": "22-02",
    "created": "2016-01-30T23:50:00+00:00",
    "datacenter": {
      "description": "Falkenstein 1 DC 8",
      "id": 1,
      "location": {
        "city": "Falkenstein",
        "country": "DE",
        "description": "Falkenstein DC Park 1",
        "id": 1,
        "latitude": 50.47612,
        "longitude": 12.370071,
        "name": "fsn1",
        "network_zone": "eu-central"
      },
      "name": "fsn1-dc8",
      "server_types": {
        "available": [
          1,
          2,
          3
        ],
        "available_for_migration": [
          1,
          2,
          3
        ],
        "supported": [
          1,
          2,
          3
        ]
      }
    },
    "id": 42,
    "image": {
      "bound_to": null,
      "created": "2016-01-30T23:50:00+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "deleted": null,
      "deprecated": "2018-02-28T00:00:00+00:00",
      "description": "Ubuntu 20.04 Standard 64 bit",
      "disk_size": 10,
      "id": 4711,
      "image_size": 2.3,
      "labels": {
        "env": "dev"
      },
      "name": "ubuntu-20.04",
      "os_flavor": "ubuntu",
      "os_version": "20.04",
      "protection": {
        "delete": false
      },
      "rapid_deploy": false,
      "status": "available",
      "type": "snapshot"
    },
    "included_traffic": 654321,
    "ingoing_traffic": 123456,
    "iso": {
      "deprecated": "2018-02-28T00:00:00+00:00",
      "description": "FreeBSD 11.0 x64",
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "type": "public"
    },
    "labels": {
      "env": "dev"
    },
    "load_balancers": [],
    "locked": false,
    "name": "my-server",
    "outgoing_traffic": 123456,
    "primary_disk_size": 50,
    "private_net": [
      {
        "alias_ips": [],
        "ip": "10.0.0.2",
        "mac_address": "86:00:ff:2a:7d:e1",
        "network": 4711
      }
    ],
    "protection": {
      "delete": false,
      "rebuild": false
    },
    "public_net": {
      "firewalls": [
        {
          "id": 38,
          "status": "applied"
        }
      ],
      "floating_ips": [
        478
      ],
      "ipv4": {
        "blocked": false,
        "dns_ptr": "server01.example.com",
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "blocked": false,
        "dns_ptr": [
          {
            "dns_ptr": "server.example.com",
            "ip": "2001:db8::1"
          }
        ],
        "ip": "2001:db8::/64"
      }
    },
    "rescue_enabled": false,
    "server_type": {
      "cores": 1,
      "cpu_type": "shared",
      "deprecated": true,
      "description": "CX11",
      "disk": 25,
      "id": 1,
      "memory": 1,
      "name": "cx11",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          },
          "price_monthly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          }
        }
      ],
      "storage_type": "local"
    },
    "status": "initializing",
    "volumes": []
  }
}

Delete a Server

Deletes a Server. This immediately removes the Server from your account, and it is no longer accessible.

HTTP Request

DELETE /servers/{id}

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "start_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:55:00+00:00",
    "id": 42,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Get a Server

Returns a specific Server object. The Server must exist inside the Project

HTTP Request

GET /servers/{id}

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "server": {
    "backup_window": "22-02",
    "created": "2016-01-30T23:55:00+00:00",
    "datacenter": {
      "description": "Falkenstein DC Park 8",
      "id": 42,
      "location": {
        "city": "Falkenstein",
        "country": "DE",
        "description": "Falkenstein DC Park 1",
        "id": 1,
        "latitude": 50.47612,
        "longitude": 12.370071,
        "name": "fsn1",
        "network_zone": "eu-central"
      },
      "name": "fsn1-dc8",
      "server_types": {
        "available": [
          1,
          2,
          3
        ],
        "available_for_migration": [
          1,
          2,
          3
        ],
        "supported": [
          1,
          2,
          3
        ]
      }
    },
    "id": 42,
    "image": {
      "bound_to": null,
      "build_id": "c313fe40383af26094a5a92026054320ab55abc7",
      "created": "2016-01-30T23:55:00+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "deleted": null,
      "deprecated": "2018-02-28T00:00:00+00:00",
      "description": "Ubuntu 20.04 Standard 64 bit",
      "disk_size": 10,
      "id": 42,
      "image_size": 2.3,
      "labels": {},
      "name": "ubuntu-20.04",
      "os_flavor": "ubuntu",
      "os_version": "20.04",
      "protection": {
        "delete": false
      },
      "rapid_deploy": false,
      "status": "available",
      "type": "snapshot"
    },
    "included_traffic": 654321,
    "ingoing_traffic": 123456,
    "iso": {
      "deprecated": "2018-02-28T00:00:00+00:00",
      "description": "FreeBSD 11.0 x64",
      "id": 42,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "type": "public"
    },
    "labels": {},
    "load_balancers": [],
    "locked": false,
    "name": "my-resource",
    "outgoing_traffic": 123456,
    "placement_group": {
      "created": "2016-01-30T23:55:00+00:00",
      "id": 42,
      "labels": {},
      "name": "my-resource",
      "servers": [
        42
      ],
      "type": "spread"
    },
    "primary_disk_size": 50,
    "private_net": [
      {
        "alias_ips": [],
        "ip": "10.0.0.2",
        "mac_address": "86:00:ff:2a:7d:e1",
        "network": 4711
      }
    ],
    "protection": {
      "delete": false,
      "rebuild": false
    },
    "public_net": {
      "firewalls": [
        {
          "id": 42,
          "status": "applied"
        }
      ],
      "floating_ips": [
        478
      ],
      "ipv4": {
        "blocked": false,
        "dns_ptr": "server01.example.com",
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "blocked": false,
        "dns_ptr": [
          {
            "dns_ptr": "server.example.com",
            "ip": "2001:db8::1"
          }
        ],
        "ip": "2001:db8::/64"
      }
    },
    "rescue_enabled": false,
    "server_type": {
      "cores": 1,
      "cpu_type": "shared",
      "deprecated": false,
      "description": "CX11",
      "disk": 25,
      "id": 1,
      "memory": 1,
      "name": "cx11",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          },
          "price_monthly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          }
        }
      ],
      "storage_type": "local"
    },
    "status": "running",
    "volumes": []
  }
}

Update a Server

Updates a Server. You can update a Server’s name and a Server’s labels. Please note that Server names must be unique per Project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes). Also note that when updating labels, the Server’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.

HTTP Request

PUT /servers/{id}

Path Parameters

  • idinteger required

    ID of the Server

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New name to set

Response

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"labels":{"labelkey":"value"},"name":"my-server"}' \
	'https://api.hetzner.cloud/v1/servers/{id}'

Request

{
  "labels": {
    "labelkey": "value"
  },
  "name": "my-server"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "server": {
    "backup_window": "22-02",
    "created": "2016-01-30T23:55:00+00:00",
    "datacenter": {
      "description": "Falkenstein DC Park 8",
      "id": 42,
      "location": {
        "city": "Falkenstein",
        "country": "DE",
        "description": "Falkenstein DC Park 1",
        "id": 1,
        "latitude": 50.47612,
        "longitude": 12.370071,
        "name": "fsn1",
        "network_zone": "eu-central"
      },
      "name": "fsn1-dc8",
      "server_types": {
        "available": [
          1,
          2,
          3
        ],
        "available_for_migration": [
          1,
          2,
          3
        ],
        "supported": [
          1,
          2,
          3
        ]
      }
    },
    "id": 42,
    "image": {
      "bound_to": null,
      "build_id": "c313fe40383af26094a5a92026054320ab55abc7",
      "created": "2016-01-30T23:55:00+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "deleted": null,
      "deprecated": "2018-02-28T00:00:00+00:00",
      "description": "Ubuntu 20.04 Standard 64 bit",
      "disk_size": 10,
      "id": 42,
      "image_size": 2.3,
      "labels": {},
      "name": "ubuntu-20.04",
      "os_flavor": "ubuntu",
      "os_version": "20.04",
      "protection": {
        "delete": false
      },
      "rapid_deploy": false,
      "status": "available",
      "type": "snapshot"
    },
    "included_traffic": 654321,
    "ingoing_traffic": 123456,
    "iso": {
      "deprecated": "2018-02-28T00:00:00+00:00",
      "description": "FreeBSD 11.0 x64",
      "id": 42,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "type": "public"
    },
    "labels": {},
    "load_balancers": [],
    "locked": false,
    "name": "my-resource",
    "outgoing_traffic": 123456,
    "placement_group": {
      "created": "2016-01-30T23:55:00+00:00",
      "id": 42,
      "labels": {},
      "name": "my-resource",
      "servers": [
        42
      ],
      "type": "spread"
    },
    "primary_disk_size": 50,
    "private_net": [
      {
        "alias_ips": [],
        "ip": "10.0.0.2",
        "mac_address": "86:00:ff:2a:7d:e1",
        "network": 4711
      }
    ],
    "protection": {
      "delete": false,
      "rebuild": false
    },
    "public_net": {
      "firewalls": [
        {
          "id": 42,
          "status": "applied"
        }
      ],
      "floating_ips": [
        478
      ],
      "ipv4": {
        "blocked": false,
        "dns_ptr": "server01.example.com",
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "blocked": false,
        "dns_ptr": [
          {
            "dns_ptr": "server.example.com",
            "ip": "2001:db8::1"
          }
        ],
        "ip": "2001:db8::/64"
      }
    },
    "rescue_enabled": false,
    "server_type": {
      "cores": 1,
      "cpu_type": "shared",
      "deprecated": false,
      "description": "CX11",
      "disk": 25,
      "id": 1,
      "memory": 1,
      "name": "cx11",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          },
          "price_monthly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          }
        }
      ],
      "storage_type": "local"
    },
    "status": "running",
    "volumes": []
  }
}

Get Metrics for a Server

Get Metrics for specified Server.

You must specify the type of metric to get: cpu, disk or network. You can also specify more than one type by comma separation, e.g. cpu,disk.

Depending on the type you will get different time series data

Type Timeseries Unit Description
cpu cpu percent Percent CPU usage
disk disk.0.iops.read iop/s Number of read IO operations per second
disk.0.iops.write iop/s Number of write IO operations per second
disk.0.bandwidth.read bytes/s Bytes read per second
disk.0.bandwidth.write bytes/s Bytes written per second
network network.0.pps.in packets/s Public Network interface packets per second received
network.0.pps.out packets/s Public Network interface packets per second sent
network.0.bandwidth.in bytes/s Public Network interface bytes/s received
network.0.bandwidth.out bytes/s Public Network interface bytes/s sent

Metrics are available for the last 30 days only.

If you do not provide the step argument we will automatically adjust it so that a maximum of 200 samples are returned.

We limit the number of samples returned to a maximum of 500 and will adjust the step parameter accordingly.

HTTP Request

GET /servers/{id}/metrics

Path Parameters

  • idinteger required

    ID of the Server

Query Parameters

  • typestring required
    Possible enum values:
    cpudisknetwork

    Type of metrics to get

  • startstring required

    Start of period to get Metrics for (in ISO-8601 format)

  • endstring required

    End of period to get Metrics for (in ISO-8601 format)

  • stepstring

    Resolution of results in seconds

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/metrics'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "metrics": {
    "end": "2017-01-01T23:00:00+00:00",
    "start": "2017-01-01T00:00:00+00:00",
    "step": 60,
    "time_series": {
      "name_of_timeseries": {
        "values": [
          [
            1435781470.622,
            "42"
          ],
          [
            1435781471.622,
            "43"
          ]
        ]
      }
    }
  }
}

Server Actions

Get all Actions for a Server

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

HTTP Request

GET /servers/{id}/actions

Path Parameters

  • idinteger required

    ID of the Resource

Query Parameters

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "start_server",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Get an Action for a Server

Returns a specific Action object for a Server.

HTTP Request

GET /servers/{id}/actions/{action_id}

Path Parameters

  • idinteger required

    ID of the Server

  • action_idinteger required

    ID of the Action

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "start_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Add a Server to a Placement Group

Adds a Server to a Placement Group.

Server must be powered off for this command to succeed.

Call specific error codes

Code Description
server_not_stopped The action requires a stopped server

HTTP Request

POST /servers/{id}/actions/add_to_placement_group

Path Parameters

  • idinteger required

    ID of the Server

Request

  • placement_groupinteger required

    ID of Placement Group the Server should be added to

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"placement_group":1}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/add_to_placement_group'

Request

{
  "placement_group": 1
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "add_to_placement_group",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Attach an ISO to a Server

Attaches an ISO to a Server. The Server will immediately see it as a new disk. An already attached ISO will automatically be detached before the new ISO is attached.

Servers with attached ISOs have a modified boot order: They will try to boot from the ISO first before falling back to hard disk.

HTTP Request

POST /servers/{id}/actions/attach_iso

Path Parameters

  • idinteger required

    ID of the Server

Request

  • isostring required

    ID or name of ISO to attach to the Server as listed in GET /isos

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"iso":"FreeBSD-11.0-RELEASE-amd64-dvd1"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/attach_iso'

Request

{
  "iso": "FreeBSD-11.0-RELEASE-amd64-dvd1"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "attach_iso",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Attach a Server to a Network

Attaches a Server to a network. This will complement the fixed public Server interface by adding an additional ethernet interface to the Server which is connected to the specified network.

The Server will get an IP auto assigned from a subnet of type server in the same network_zone.

Using the alias_ips attribute you can also define one or more additional IPs to the Servers. Please note that you will have to configure these IPs by hand on your Server since only the primary IP will be given out by DHCP.

Call specific error codes

Code Description
server_already_attached The server is already attached to the network
ip_not_available The provided Network IP is not available
no_subnet_available No Subnet or IP is available for the Server within the network
networks_overlap The network IP range overlaps with one of the server networks

HTTP Request

POST /servers/{id}/actions/attach_to_network

Path Parameters

  • idinteger required

    ID of the Server

Request

  • ipstring

    IP to request to be assigned to this Server; if you do not provide this then you will be auto assigned an IP address

  • networkinteger required

    ID of an existing network to attach the Server to

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"alias_ips":["10.0.1.2"],"ip":"10.0.1.1","network":4711}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/attach_to_network'

Request

{
  "alias_ips": [
    "10.0.1.2"
  ],
  "ip": "10.0.1.1",
  "network": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "attach_to_network",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Change alias IPs of a Network

Changes the alias IPs of an already attached Network. Note that the existing aliases for the specified Network will be replaced with these provided in the request body. So if you want to add an alias IP, you have to provide the existing ones from the Network plus the new alias IP in the request body.

HTTP Request

POST /servers/{id}/actions/change_alias_ips

Path Parameters

  • idinteger required

    ID of the Server

Request

  • networkinteger required

    ID of an existing Network already attached to the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"alias_ips":["10.0.1.2"],"network":4711}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/change_alias_ips'

Request

{
  "alias_ips": [
    "10.0.1.2"
  ],
  "network": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_alias_ips",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Change reverse DNS entry for this Server

Changes the hostname that will appear when getting the hostname belonging to the primary IPs (IPv4 and IPv6) of this Server.

Floating IPs assigned to the Server are not affected by this.

HTTP Request

POST /servers/{id}/actions/change_dns_ptr

Path Parameters

  • idinteger required

    ID of the Server

Request

Select the IP address for which to change the DNS entry by passing ip. It can be either IPv4 or IPv6. The target hostname is set by passing dns_ptr.

  • dns_ptrstring – nullablerequired

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

  • ipstring required

    Primary IP address for which the reverse DNS entry should be set

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"dns_ptr":"server01.example.com","ip":"1.2.3.4"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/change_dns_ptr'

Request

{
  "dns_ptr": "server01.example.com",
  "ip": "1.2.3.4"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_dns_ptr",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Change Server Protection

Changes the protection configuration of the Server.

HTTP Request

POST /servers/{id}/actions/change_protection

Path Parameters

  • idinteger required

    ID of the Server

Request

  • deleteboolean

    If true, prevents the Server from being deleted (currently delete and rebuild attribute needs to have the same value)

  • rebuildboolean

    If true, prevents the Server from being rebuilt (currently delete and rebuild attribute needs to have the same value)

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true,"rebuild":true}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/change_protection'

Request

{
  "delete": true,
  "rebuild": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_protection",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Change the Type of a Server

Changes the type (Cores, RAM and disk sizes) of a Server.

Server must be powered off for this command to succeed.

This copies the content of its disk, and starts it again.

You can only migrate to Server types with the same storage_type and equal or bigger disks. Shrinking disks is not possible as it might destroy data.

If the disk gets upgraded, the Server type can not be downgraded any more. If you plan to downgrade the Server type, set upgrade_disk to false.

Call specific error codes

Code Description
invalid_server_type The server type does not fit for the given server or is deprecated
server_not_stopped The action requires a stopped server

HTTP Request

POST /servers/{id}/actions/change_type

Path Parameters

  • idinteger required

    ID of the Server

Request

  • server_typestring required

    ID or name of Server type the Server should migrate to

  • upgrade_diskboolean required

    If false, do not upgrade the disk (this allows downgrading the Server type later)

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"server_type":"cx11","upgrade_disk":true}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/change_type'

Request

{
  "server_type": "cx11",
  "upgrade_disk": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_server_type",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Create Image from a Server

Creates an Image (snapshot) from a Server by copying the contents of its disks. This creates a snapshot of the current state of the disk and copies it into an Image. If the Server is currently running you must make sure that its disk content is consistent. Otherwise, the created Image may not be readable.

To make sure disk content is consistent, we recommend to shut down the Server prior to creating an Image.

You can either create a backup Image that is bound to the Server and therefore will be deleted when the Server is deleted, or you can create an snapshot Image which is completely independent of the Server it was created from and will survive Server deletion. Backup Images are only available when the backup option is enabled for the Server. Snapshot Images are billed on a per GB basis.

HTTP Request

POST /servers/{id}/actions/create_image

Path Parameters

  • idinteger required

    ID of the Server

Request

  • descriptionstring

    Description of the Image, will be auto-generated if not set

  • typestring
    Possible enum values:
    snapshotbackup

    Type of Image to create (default: snapshot)

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"description":"my image","labels":{"labelkey":"value"},"type":"snapshot"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/create_image'

Request

{
  "description": "my image",
  "labels": {
    "labelkey": "value"
  },
  "type": "snapshot"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "create_image",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  },
  "image": {
    "bound_to": null,
    "created": "2016-01-30T23:50:00+00:00",
    "created_from": {
      "id": 1,
      "name": "Server"
    },
    "deleted": null,
    "deprecated": "2018-02-28T00:00:00+00:00",
    "description": "my image",
    "disk_size": 10,
    "id": 4711,
    "image_size": 2.3,
    "labels": {
      "env": "dev"
    },
    "name": null,
    "os_flavor": "ubuntu",
    "os_version": "20.04",
    "protection": {
      "delete": false
    },
    "rapid_deploy": false,
    "status": "creating",
    "type": "snapshot"
  }
}

Detach a Server from a Network

Detaches a Server from a network. The interface for this network will vanish.

HTTP Request

POST /servers/{id}/actions/detach_from_network

Path Parameters

  • idinteger required

    ID of the Server

Request

  • networkinteger required

    ID of an existing network to detach the Server from

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"network":4711}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/detach_from_network'

Request

{
  "network": 4711
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "detach_from_network",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 4711,
        "type": "network"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Detach an ISO from a Server

Detaches an ISO from a Server. In case no ISO Image is attached to the Server, the status of the returned Action is immediately set to success

HTTP Request

POST /servers/{id}/actions/detach_iso

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/detach_iso'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "detach_iso",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Disable Backups for a Server

Disables the automatic backup option and deletes all existing Backups for a Server. No more additional charges for backups will be made.

Caution: This immediately removes all existing backups for the Server!

HTTP Request

POST /servers/{id}/actions/disable_backup

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/disable_backup'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "disable_backup",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Disable Rescue Mode for a Server

Disables the Hetzner Rescue System for a Server. This makes a Server start from its disks on next reboot.

Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.

Disabling rescue mode will not reboot your Server — you will have to do this yourself.

HTTP Request

POST /servers/{id}/actions/disable_rescue

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/disable_rescue'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "disable_rescue",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Enable and Configure Backups for a Server

Enables and configures the automatic daily backup option for the Server. Enabling automatic backups will increase the price of the Server by 20%. In return, you will get seven slots where Images of type backup can be stored.

Backups are automatically created daily.

HTTP Request

POST /servers/{id}/actions/enable_backup

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/enable_backup'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "enable_backup",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Enable Rescue Mode for a Server

Enable the Hetzner Rescue System for this Server. The next time a Server with enabled rescue mode boots it will start a special minimal Linux distribution designed for repair and reinstall.

In case a Server cannot boot on its own you can use this to access a Server’s disks.

Rescue Mode is automatically disabled when you first boot into it or if you do not use it for 60 minutes.

Enabling rescue mode will not reboot your Server — you will have to do this yourself.

HTTP Request

POST /servers/{id}/actions/enable_rescue

Path Parameters

  • idinteger required

    ID of the Server

Request

  • typestring
    Possible enum values:
    linux64linux32freebsd64

    Type of rescue system to boot (default: linux64)

Response

  • root_passwordstring

    Password that will be set for this Server once the Action succeeds

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"ssh_keys":[2323],"type":"linux64"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/enable_rescue'

Request

{
  "ssh_keys": [
    2323
  ],
  "type": "linux64"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "enable_rescue",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  },
  "root_password": "zCWbFhnu950dUTko5f40"
}

Power off a Server

Cuts power to the Server. This forcefully stops it without giving the Server operating system time to gracefully stop. May lead to data loss, equivalent to pulling the power cord. Power off should only be used when shutdown does not work.

HTTP Request

POST /servers/{id}/actions/poweroff

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/poweroff'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "stop_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Power on a Server

Starts a Server by turning its power on.

HTTP Request

POST /servers/{id}/actions/poweron

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/poweron'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "start_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Soft-reboot a Server

Reboots a Server gracefully by sending an ACPI request. The Server operating system must support ACPI and react to the request, otherwise the Server will not reboot.

HTTP Request

POST /servers/{id}/actions/reboot

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/reboot'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "reboot_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Rebuild a Server from an Image

Rebuilds a Server overwriting its disk with the content of an Image, thereby destroying all data on the target Server

The Image can either be one you have created earlier (backup or snapshot Image) or it can be a completely fresh system Image provided by us. You can get a list of all available Images with GET /images.

Your Server will automatically be powered off before the rebuild command executes.

HTTP Request

POST /servers/{id}/actions/rebuild

Path Parameters

  • idinteger required

    ID of the Server

Request

To select which Image to rebuild from you can either pass an ID or a name as the image argument. Passing a name only works for system Images since the other Image types do not have a name set.

  • imagestring required

    ID or name of Image to rebuilt from.

Response

  • root_passwordstring – nullable

    New root password when not using SSH keys

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"image":"ubuntu-20.04"}' \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/rebuild'

Request

{
  "image": "ubuntu-20.04"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "rebuild_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  },
  "root_password": null
}

Remove from Placement Group

Removes a Server from a Placement Group.

HTTP Request

POST /servers/{id}/actions/remove_from_placement_group

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/remove_from_placement_group'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "remove_from_placement_group",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Request Console for a Server

Requests credentials for remote access via VNC over websocket to keyboard, monitor, and mouse for a Server. The provided URL is valid for 1 minute, after this period a new url needs to be created to connect to the Server. How long the connection is open after the initial connect is not subject to this timeout.

HTTP Request

POST /servers/{id}/actions/request_console

Path Parameters

  • idinteger required

    ID of the Server

Response

  • passwordstring required

    VNC password to use for this connection (this password only works in combination with a wss_url with valid token)

  • wss_urlstring required

    URL of websocket proxy to use; this includes a token which is valid for a limited time only

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/request_console'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "request_console",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  },
  "password": "9MQaTg2VAGI0FIpc10k3UpRXcHj2wQ6x",
  "wss_url": "wss://console.hetzner.cloud/?server_id=1&token=3db32d15-af2f-459c-8bf8-dee1fd05f49c"
}

Reset a Server

Cuts power to a Server and starts it again. This forcefully stops it without giving the Server operating system time to gracefully stop. This may lead to data loss, it’s equivalent to pulling the power cord and plugging it in again. Reset should only be used when reboot does not work.

HTTP Request

POST /servers/{id}/actions/reset

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/reset'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "reset_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Reset root Password of a Server

Resets the root password. Only works for Linux systems that are running the qemu guest agent. Server must be powered on (state on) in order for this operation to succeed.

This will generate a new password for this Server and return it.

If this does not succeed you can use the rescue system to netboot the Server and manually change your Server password by hand.

HTTP Request

POST /servers/{id}/actions/reset_password

Path Parameters

  • idinteger required

    ID of the Server

Response

  • root_passwordstring

    Password that will be set for this Server once the Action succeeds

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/reset_password'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "reset_password",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  },
  "root_password": "zCWbFhnu950dUTko5f40"
}

Shutdown a Server

Shuts down a Server gracefully by sending an ACPI shutdown request. The Server operating system must support ACPI and react to the request, otherwise the Server will not shut down.

HTTP Request

POST /servers/{id}/actions/shutdown

Path Parameters

  • idinteger required

    ID of the Server

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/servers/{id}/actions/shutdown'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "shutdown_server",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Server Types

Server types define kinds of Servers offered. Each type has an hourly and a monthly cost. You will pay whichever cost is lower for your usage of this specific Server. Costs may differ between Locations.

Currency for all amounts is €. All prices exclude VAT.

Get all Server Types

Gets all Server type objects.

HTTP Request

GET /server_types

Query Parameters

  • namestring

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/server_types'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "server_types": [
    {
      "cores": 1,
      "cpu_type": "shared",
      "deprecated": false,
      "description": "CX11",
      "disk": 24,
      "id": 1,
      "memory": 1,
      "name": "cx11",
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          },
          "price_monthly": {
            "gross": "1.1900000000000000",
            "net": "1.0000000000"
          }
        }
      ],
      "storage_type": "local"
    }
  ]
}

Get a Server Type

Gets a specific Server type object.

HTTP Request

GET /server_types/{id}

Path Parameters

  • idinteger required

    ID of Server Type

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/server_types/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "server_type": {
    "cores": 1,
    "cpu_type": "shared",
    "deprecated": false,
    "description": "CX11",
    "disk": 24,
    "id": 1,
    "memory": 1,
    "name": "cx11",
    "prices": [
      {
        "location": "fsn1",
        "price_hourly": {
          "gross": "1.1900000000000000",
          "net": "1.0000000000"
        },
        "price_monthly": {
          "gross": "1.1900000000000000",
          "net": "1.0000000000"
        }
      }
    ],
    "storage_type": "local"
  }
}

SSH Keys

SSH keys are public keys you provide to the cloud system. They can be injected into Servers at creation time. We highly recommend that you use keys instead of passwords to manage your Servers.

Get all SSH keys

Returns all SSH key objects.

HTTP Request

GET /ssh_keys

Query Parameters

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

    Can be used multiple times.

  • namestring

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

  • fingerprintstring

    Can be used to filter SSH keys by their fingerprint. The response will only contain the SSH key matching the specified fingerprint.

  • label_selectorstring

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/ssh_keys'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  },
  "ssh_keys": [
    {
      "created": "2016-01-30T23:55:00+00:00",
      "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
      "id": 42,
      "labels": {},
      "name": "my-resource",
      "public_key": "ssh-rsa AAAjjk76kgf...Xt"
    }
  ]
}

Create an SSH key

Creates a new SSH key with the given name and public_key. Once an SSH key is created, it can be used in other calls such as creating Servers.

HTTP Request

POST /ssh_keys

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring required

    Name of the SSH key

  • public_keystring required

    Public key

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"labels":{},"name":"My ssh key","public_key":"ssh-rsa AAAjjk76kgf...Xt"}' \
	'https://api.hetzner.cloud/v1/ssh_keys'

Request

{
  "labels": {},
  "name": "My ssh key",
  "public_key": "ssh-rsa AAAjjk76kgf...Xt"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "ssh_key": {
    "created": "2016-01-30T23:55:00+00:00",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "id": 42,
    "labels": {},
    "name": "my-resource",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt"
  }
}

Delete an SSH key

Deletes an SSH key. It cannot be used anymore.

HTTP Request

DELETE /ssh_keys/{id}

Path Parameters

  • idstring required

    ID of the SSH key

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/ssh_keys/{id}'

Response headers

Status: 204

Get a SSH key

Returns a specific SSH key object.

HTTP Request

GET /ssh_keys/{id}

Path Parameters

  • idinteger required

    ID of the SSH key

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/ssh_keys/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "ssh_key": {
    "created": "2016-01-30T23:55:00+00:00",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "id": 42,
    "labels": {},
    "name": "my-resource",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt"
  }
}

Update an SSH key

Updates an SSH key. You can update an SSH key name and an SSH key labels.

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

HTTP Request

PUT /ssh_keys/{id}

Path Parameters

  • idstring required

    ID of the SSH key

Request

  • labelsobject

    User-defined labels (key-value pairs)

  • namestring

    New name Name to set

Response

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"labels":{"labelkey":"value"},"name":"My ssh key"}' \
	'https://api.hetzner.cloud/v1/ssh_keys/{id}'

Request

{
  "labels": {
    "labelkey": "value"
  },
  "name": "My ssh key"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "ssh_key": {
    "created": "2016-01-30T23:50:00+00:00",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "id": 2323,
    "labels": {
      "labelkey": "value"
    },
    "name": "My ssh key",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt"
  }
}

Volumes

A Volume is a highly-available, scalable, and SSD-based block storage for Servers.

Pricing for Volumes depends on the Volume size and Location, not the actual used storage.

Please see Hetzner Docs for more details about Volumes.

Get all Volumes

Gets all existing Volumes that you have available.

HTTP Request

GET /volumes

Query Parameters

  • statusstring
    Possible enum values:
    availablecreating

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

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

    Can be used multiple times.

  • namestring

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

  • label_selectorstring

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "meta": {
    "pagination": {
      "last_page": 4,
      "next_page": 4,
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "total_entries": 100
    }
  },
  "volumes": [
    {
      "created": "2016-01-30T23:55:00+00:00",
      "format": "xfs",
      "id": 42,
      "labels": {},
      "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
      "location": {
        "city": "Falkenstein",
        "country": "DE",
        "description": "Falkenstein DC Park 1",
        "id": 1,
        "latitude": 50.47612,
        "longitude": 12.370071,
        "name": "fsn1",
        "network_zone": "eu-central"
      },
      "name": "my-resource",
      "protection": {
        "delete": false
      },
      "server": 12,
      "size": 42,
      "status": "available"
    }
  ]
}

Create a Volume

Creates a new Volume attached to a Server. If you want to create a Volume that is not attached to a Server, you need to provide the location key instead of server. This can be either the ID or the name of the Location this Volume will be created in. Note that a Volume can be attached to a Server only in the same Location as the Volume itself.

Specifying the Server during Volume creation will automatically attach the Volume to that Server after it has been initialized. In that case, the next_actions key in the response is an array which contains a single attach_volume action.

The minimum Volume size is 10GB and the maximum size is 10TB (10240GB).

A volume’s name can consist of alphanumeric characters, dashes, underscores, and dots, but has to start and end with an alphanumeric character. The total length is limited to 64 characters. Volume names must be unique per Project.

Call specific error codes

Code Description
no_space_left_in_location There is no volume space left in the given location

HTTP Request

POST /volumes

Request

  • automountboolean

    Auto-mount Volume after attach. server must be provided.

  • formatstring

    Format Volume after creation. One of: xfs, ext4

  • labelsobject

    User-defined labels (key-value pairs)

  • locationstring

    Location to create the Volume in (can be omitted if Server is specified)

  • namestring required

    Name of the volume

  • serverinteger

    Server to which to attach the Volume once it's created (Volume will be created in the same Location as the server)

  • sizeinteger required

    Size of the Volume in GB

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"automount":false,"format":"xfs","labels":{"labelkey":"value"},"location":"nbg1","name":"test-database","size":42}' \
	'https://api.hetzner.cloud/v1/volumes'

Request

{
  "automount": false,
  "format": "xfs",
  "labels": {
    "labelkey": "value"
  },
  "location": "nbg1",
  "name": "test-database",
  "size": 42
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "create_volume",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 554,
        "type": "volume"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  },
  "next_actions": [
    {
      "command": "attach_volume",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": null,
      "id": 13,
      "progress": 0,
      "resources": [
        {
          "id": 42,
          "type": "server"
        },
        {
          "id": 554,
          "type": "volume"
        }
      ],
      "started": "2016-01-30T23:50:00+00:00",
      "status": "running"
    }
  ],
  "volume": {
    "created": "2016-01-30T23:50:11+00:00",
    "format": "xfs",
    "id": 4711,
    "labels": {
      "env": "dev"
    },
    "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
    "location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "name": "database-storage",
    "protection": {
      "delete": false
    },
    "server": 12,
    "size": 42,
    "status": "available"
  }
}

Delete a Volume

Deletes a volume. All Volume data is irreversibly destroyed. The Volume must not be attached to a Server and it must not have delete protection enabled.

HTTP Request

DELETE /volumes/{id}

Path Parameters

  • idstring required

    ID of the Volume

Example curl

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}'

Response headers

Status: 204

Get a Volume

Gets a specific Volume object.

HTTP Request

GET /volumes/{id}

Path Parameters

  • idinteger required

    ID of the Volume

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "volume": {
    "created": "2016-01-30T23:55:00+00:00",
    "format": "xfs",
    "id": 42,
    "labels": {},
    "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
    "location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "name": "my-resource",
    "protection": {
      "delete": false
    },
    "server": 12,
    "size": 42,
    "status": "available"
  }
}

Update a Volume

Updates the Volume properties.

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

HTTP Request

PUT /volumes/{id}

Path Parameters

  • idstring required

    ID of the Volume to update

Request

  • namestring required

    New Volume name

Response

Example curl

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"labels":{"labelkey":"value"},"name":"database-storage"}' \
	'https://api.hetzner.cloud/v1/volumes/{id}'

Request

{
  "labels": {
    "labelkey": "value"
  },
  "name": "database-storage"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "volume": {
    "created": "2016-01-30T23:50:11+00:00",
    "format": "xfs",
    "id": 4711,
    "labels": {
      "labelkey": "value"
    },
    "linux_device": "/dev/disk/by-id/scsi-0HC_Volume_4711",
    "location": {
      "city": "Falkenstein",
      "country": "DE",
      "description": "Falkenstein DC Park 1",
      "id": 1,
      "latitude": 50.47612,
      "longitude": 12.370071,
      "name": "fsn1",
      "network_zone": "eu-central"
    },
    "name": "database-storage",
    "protection": {
      "delete": false
    },
    "server": 12,
    "size": 42,
    "status": "available"
  }
}

Volume Actions

Get all Actions for a Volume

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

HTTP Request

GET /volumes/{id}/actions

Path Parameters

  • idinteger required

    ID of the Volume

Query Parameters

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

    Can be used multiple times.

  • statusstring
    Possible enum values:
    runningsuccesserror

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

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "command": "attach_volume",
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      },
      "finished": "2016-01-30T23:56:00+00:00",
      "id": 13,
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        },
        {
          "id": 13,
          "type": "volume"
        }
      ],
      "started": "2016-01-30T23:55:00+00:00",
      "status": "success"
    }
  ]
}

Get an Action for a Volume

Returns a specific Action for a Volume.

HTTP Request

GET /volumes/{id}/actions/{action_id}

Path Parameters

  • idinteger required

    ID of the Volume

  • action_idinteger required

    ID of the Action

Response

Example curl

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/{action_id}'

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "command": "attach_volume",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Attach Volume to a Server

Attaches a Volume to a Server. Works only if the Server is in the same Location as the Volume.

HTTP Request

POST /volumes/{id}/actions/attach

Path Parameters

  • idinteger required

    ID of the Volume

Request

  • automountboolean

    Auto-mount the Volume after attaching it

  • serverinteger required

    ID of the Server the Volume will be attached to

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"automount":false,"server":43}' \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/attach'

Request

{
  "automount": false,
  "server": 43
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "attach_volume",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 43,
        "type": "server"
      },
      {
        "id": 554,
        "type": "volume"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Change Volume Protection

Changes the protection configuration of a Volume.

HTTP Request

POST /volumes/{id}/actions/change_protection

Path Parameters

  • idinteger required

    ID of the Volume

Request

  • deleteboolean

    If true, prevents the Volume from being deleted

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/change_protection'

Request

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "change_protection",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": "2016-01-30T23:56:00+00:00",
    "id": 13,
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      },
      {
        "id": 554,
        "type": "volume"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Detach Volume

Detaches a Volume from the Server it’s attached to. You may attach it to a Server again at a later time.

HTTP Request

POST /volumes/{id}/actions/detach

Path Parameters

  • idinteger required

    ID of the Volume

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/detach'

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "detach_volume",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}

Resize Volume

Changes the size of a Volume. Note that downsizing a Volume is not possible.

HTTP Request

POST /volumes/{id}/actions/resize

Path Parameters

  • idinteger required

    ID of the Volume

Request

  • sizenumber required

    New Volume size in GB (must be greater than current size)

Response

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"size":50}' \
	'https://api.hetzner.cloud/v1/volumes/{id}/actions/resize'

Request

{
  "size": 50
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "resize_volume",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 554,
        "type": "volume"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  }
}