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:

Our CLI program hcloud
Our library for Go
Our library for Python

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 Security → API Tokens, and generate a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is 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 Security → API Tokens, and generate 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 all resources.

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

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

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

Example Labels

{
  "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
availability-zone	text	Name of the availability zone that Server runs in
region	text	Network zone, e.g. eu-central

Example: Summary

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

availability-zone: hel1-dc2
hostname: my-server
instance-id: 42
public-ipv4: 1.2.3.4
region: eu-central

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

Example: Availability Zone

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

Example: Region

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

Sorting

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

Example: Sorting

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

actionsarray of objects required
metaobject

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

actionobject required

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

certificatesarray of objects required
metaobject

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.
domain_namesarray of strings
Domains and subdomains that should be contained in the Certificate issued by Let's Encrypt. Required for type managed 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

actionobject – nullable
certificateobject required

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

certificateobject required

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

certificateobject required

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

actionsarray of objects required
metaobject

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

actionobject required

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

actionobject required

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

datacentersarray of objects required
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

datacenterobject required

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

firewallsarray of objects required
metaobject

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
`firewall_resource_not_found`	The resource the Firewall should be attached to was not found

HTTP Request

POST /firewalls

Request

apply_toarray of objects
Resources the Firewall should be applied to after creation
labelsobject
User-defined labels (key-value pairs)
namestring required
Name of the Firewall
rulesarray of objects
Array of rules

Response

actionsarray of objects
firewallobject

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

firewallobject required

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

firewallobject required

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

actionsarray of objects required
metaobject

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

actionobject required

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
`firewall_resource_not_found`	The resource the Firewall should be attached to was not found

HTTP Request

POST /firewalls/{id}/actions/apply_to_resources

Path Parameters

idinteger required
ID of the Firewall

Request

apply_toarray of objects required
Resources the Firewall should be applied to

Response

actionsarray of objects required
metaobject

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
`firewall_resource_not_found`	The resource the Firewall should be attached to was not found
`firewall_managed_by_label_selector`	Firewall was applied via label selector and cannot be removed manually

HTTP Request

POST /firewalls/{id}/actions/remove_from_resources

Path Parameters

idinteger required
ID of the Firewall

Request

remove_fromarray of objects required
Resources the Firewall should be removed from

Response

actionsarray of objects required
metaobject

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. The maximum amount of rules that can be defined is 50.

Call specific error codes

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

HTTP Request

POST /firewalls/{id}/actions/set_rules

Path Parameters

idinteger required
ID of the Firewall

Request

rulesarray of objects required
Array of rules

Response

actionsarray of objects required
metaobject

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

floating_ipsarray of objects required
metaobject

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

actionobject
floating_ipobject required

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

floating_ipobject required

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

floating_ipobject required

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

actionsarray of objects required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

imagesarray of objects required
metaobject

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,
      "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

imageobject

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,
    "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

imageobject

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

actionsarray of objects required
metaobject

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

actionobject required

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

actionobject required

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

isosarray of objects required
metaobject

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

isoobject required

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

load_balancersarray of objects required
metaobject

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

algorithmobject required
Algorithm of the Load Balancer
labelsobject
User-defined labels (key-value pairs)
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
servicesarray of objects
Array of services
targetsarray of objects
Array of targets

Response

actionobject required
load_balancerobject required

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

load_balancerobject required

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

load_balancerobject required

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

metricsobject required

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

actionsarray of objects required
metaobject

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

actionobject required

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
health_checkobject required
Service health check
httpobject
Configuration option for protocols http and https
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

actionobject required

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

ipobject
IP targets where the traffic should be routed through. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well.
label_selectorobject
Configuration for label selector targets, required if type is label_selector
serverobject
Configuration for type Server, required if type is server
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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

ipobject
IP targets where the traffic should be routed through. It is only possible to use the (Public or vSwitch) IPs of Hetzner Online Root Servers belonging to the project owner. IPs belonging to other users are blocked. Additionally IPs belonging to services provided by Hetzner Cloud (Servers, Load Balancers, ...) are blocked as well.
label_selectorobject
Configuration for label selector targets, required if type is label_selector
serverobject
Configuration for type Server, required if type is server
typestring required
Possible enum values:
serverlabel_selectorip
Type of the resource

Response

actionobject required

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
health_checkobject required
Service health check
httpobject
Configuration option for protocols http and https
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

actionobject required

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

load_balancer_typesarray of objects required

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

load_balancer_typeobject

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

locationsarray of objects required

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

locationobject required

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

Primary IPs

Primary IPs help you to create more flexible networking setups. You can assign at most one Primary IP of type ipv4 and one of type ipv6 per Server. This Server then uses these IPs.

You can only unassign a Primary IP from a Server when it's powered off. This Primary IP can then be assigned to a different powered off Server, or you can keep it around for later use.

Primary IPs are bound to a specific Datacenter. You can not assign a Primary IP from one Datacenter to a Server in a different Datacenter. If you need this capability use Floating IPs instead.

If your Server's operating system supports cloud-init there is no further configuration needed to make Primary IPs work.

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

Primary IPs are billed on an hourly basis.

Get all Primary IPs

Returns all Primary IP objects.

HTTP Request

GET /primary_ips

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.
ipstring
Can be used to filter resources by their ip. The response will only contain the resources matching the specified ip.
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

metaobject
primary_ipsarray of objects required

Example curl

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

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
    }
  },
  "primary_ips": [
    {
      "assignee_id": 17,
      "assignee_type": "server",
      "auto_delete": true,
      "blocked": false,
      "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
          ]
        }
      },
      "dns_ptr": [
        {
          "dns_ptr": "server.example.com",
          "ip": "131.232.99.1"
        }
      ],
      "id": 42,
      "ip": "131.232.99.1",
      "labels": {},
      "name": "my-resource",
      "protection": {
        "delete": false
      },
      "type": "ipv4"
    }
  ]
}

Create a Primary IP

Creates a new Primary IP, optionally assigned to a Server.

If you want to create a Primary IP that is not assigned to a Server, you need to provide the datacenter key instead of assignee_id. This can be either the ID or the name of the Datacenter this Primary IP shall be created in.

Note that a Primary IP can only be assigned to a Server in the same Datacenter later on.

Call specific error codes

Code	Description
`server_not_stopped`	The specified server is running, but needs to be powered off
`server_has_ipv4`	The server already has an ipv4 address
`server_has_ipv6`	The server already has an ipv6 address

HTTP Request

POST /primary_ips

Request

The type argument is required while datacenter and assignee_id are mutually exclusive.

assignee_idinteger
ID of the resource the Primary IP should be assigned to. Omitted if it should not be assigned.
assignee_typestring required
Possible enum values:
server
Resource type the Primary IP can be assigned to
auto_deleteboolean
Delete the Primary IP when the Server it is assigned to is deleted. If omitted defaults to false.
datacenterstring
ID or name of Datacenter the Primary IP will be bound to. Needs to be omitted if assignee_id is passed.
labelsobject
User-defined labels (key-value pairs)
namestring required
typestring required
Possible enum values:
ipv4ipv6
Primary IP type

Response

actionobject
primary_ipobject required

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"assignee_id":17,"assignee_type":"server","auto_delete":false,"datacenter":"fsn1-dc8","labels":{"labelkey":"value"},"name":"my-ip","type":"ipv4"}' \
	'https://api.hetzner.cloud/v1/primary_ips'

Request

{
  "assignee_id": 17,
  "assignee_type": "server",
  "auto_delete": false,
  "datacenter": "fsn1-dc8",
  "labels": {
    "labelkey": "value"
  },
  "name": "my-ip",
  "type": "ipv4"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "command": "create_primary_ip",
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    },
    "finished": null,
    "id": 13,
    "progress": 0,
    "resources": [
      {
        "id": 17,
        "type": "server"
      }
    ],
    "started": "2016-01-30T23:50:00+00:00",
    "status": "running"
  },
  "primary_ip": {
    "assignee_id": 17,
    "assignee_type": "server",
    "auto_delete": true,
    "blocked": false,
    "created": "2016-01-30T23:50: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
        ]
      }
    },
    "dns_ptr": [
      {
        "dns_ptr": "server.example.com",
        "ip": "2001:db8::1"
      }
    ],
    "id": 42,
    "ip": "131.232.99.1",
    "labels": {
      "labelkey": "value"
    },
    "name": "my-ip",
    "protection": {
      "delete": false
    },
    "type": "ipv4"
  }
}

Delete a Primary IP

Deletes a Primary IP.

The Primary IP may be assigned to a Server. In this case it is unassigned automatically. The Server must be powered off (status off) in order for this operation to succeed.

HTTP Request

DELETE /primary_ips/{id}

Path Parameters

idinteger required
ID of the resource

Example curl

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

Response headers

Status: 204

Get a Primary IP

Returns a specific Primary IP object.

HTTP Request

GET /primary_ips/{id}

Path Parameters

idinteger required
ID of the resource

Response

primary_ipobject required

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "primary_ip": {
    "assignee_id": 17,
    "assignee_type": "server",
    "auto_delete": true,
    "blocked": false,
    "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
        ]
      }
    },
    "dns_ptr": [
      {
        "dns_ptr": "server.example.com",
        "ip": "131.232.99.1"
      }
    ],
    "id": 42,
    "ip": "131.232.99.1",
    "labels": {},
    "name": "my-resource",
    "protection": {
      "delete": false
    },
    "type": "ipv4"
  }
}

Update a Primary IP

Updates the Primary IP.

Note that when updating labels, the Primary 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.

If the Primary IP object changes during the request, the response will be a “conflict” error.

HTTP Request

PUT /primary_ips/{id}

Path Parameters

idinteger required
ID of the resource

Request

auto_deleteboolean
Delete this Primary IP when the resource it is assigned to is deleted
labelsobject
User-defined labels (key-value pairs)
namestring
New unique name to set

Response

primary_ipobject required

Example curl

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

Request

{
  "auto_delete": true,
  "labels": {
    "labelkey": "value"
  },
  "name": "my-ip"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "primary_ip": {
    "assignee_id": 17,
    "assignee_type": "server",
    "auto_delete": true,
    "blocked": false,
    "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
        ]
      }
    },
    "dns_ptr": [
      {
        "dns_ptr": "server.example.com",
        "ip": "131.232.99.1"
      }
    ],
    "id": 42,
    "ip": "131.232.99.1",
    "labels": {},
    "name": "my-resource",
    "protection": {
      "delete": false
    },
    "type": "ipv4"
  }
}

Primary IP Actions

Assign a Primary IP to a resource

Assigns a Primary IP to a Server.

A Server can only have one Primary IP of type ipv4 and one of type ipv6 assigned. If you need more IPs use Floating IPs.

The Server must be powered off (status off) in order for this operation to succeed.

Call specific error codes

Code	Description
`server_not_stopped`	The server is running, but needs to be powered off
`primary_ip_already_assigned`	Primary ip is already assigned to a different server
`server_has_ipv4`	The server already has an ipv4 address
`server_has_ipv6`	The server already has an ipv6 address

HTTP Request

POST /primary_ips/{id}/actions/assign

Path Parameters

idinteger required
ID of the Primary IP

Request

assignee_idinteger required
ID of a resource of type assignee_type
assignee_typestring required
Possible enum values:
server
Type of resource assigning the Primary IP to

Response

actionobject required

Example curl

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

Request

{
  "assignee_id": 4711,
  "assignee_type": "server"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

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

Change reverse DNS entry for a Primary IP

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

HTTP Request

POST /primary_ips/{id}/actions/change_dns_ptr

Path Parameters

idinteger required
ID of the Primary IP

Request

Select the IP address for which to change the DNS entry by passing ip. For a Primary IP of type ipv4 this must exactly match the IP address of the Primary IP. For a Primary IP of type ipv6 this must be a single IP within the IPv6 /64 range that belongs to this Primary 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

actionobject required

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/primary_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": "primary_ip"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Change Primary IP Protection

Changes the protection configuration of a Primary IP.

A Primary IP can only be delete protected if its auto_delete property is set to false.

HTTP Request

POST /primary_ips/{id}/actions/change_protection

Path Parameters

idinteger required
ID of the Primary IP

Request

deleteboolean
If true, prevents the Primary IP from being deleted

Response

actionobject required

Example curl

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":true}' \
	'https://api.hetzner.cloud/v1/primary_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": "primary_ip"
      }
    ],
    "started": "2016-01-30T23:55:00+00:00",
    "status": "success"
  }
}

Unassign a Primary IP from a resource

Unassigns a Primary IP from a Server.

The Server must be powered off (status off) in order for this operation to succeed.

Note that only Servers that have at least one network interface (public or private) attached can be powered on.

Call specific error codes

Code	Description
`server_not_stopped`	The server is running, but needs to be powered off
`server_is_load_balancer_target`	The server ipv4 address is a loadbalancer target

HTTP Request

POST /primary_ips/{id}/actions/unassign

Path Parameters

idinteger required
ID of the Primary IP

Response

actionobject required

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response sample

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

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 these network zones exist:

Network Zone	Contains Locations
eu-central	nbg1, fsn1, hel1
us-east	ash

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

metaobject
networksarray of objects required

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.
labelsobject
User-defined labels (key-value pairs)
namestring required
Name of the network
routesarray of objects
Array of routes set in this network. The destination of the route must be one of the private IPv4 ranges of RFC1918. The gateway must be a subnet/IP of the ip_range of the network object. The destination 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. The gateway cannot be the first IP of the networks ip_range and also cannot be 172.31.1.1.
subnetsarray of objects
Array of subnets allocated.

Response

networkobject

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

networkobject

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

labelsobject
User-defined labels (key-value pairs)
namestring
New network name

Response

networkobject

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

actionsarray of objects required
metaobject

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

actionobject required

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

actionobject required

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. The Location object contains the network_zone property each Location belongs to.
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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

metaobject
placement_groupsarray of objects required

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

actionobject – nullable
placement_groupobject required

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

placement_groupobject required

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

placement_groupobject required

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

pricingobject required

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"
            }
          }
        ]
      }
    ],
    "primary_ips": [
      {
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            },
            "price_monthly": {
              "gross": "1.1900000000000000",
              "net": "1.0000000000"
            }
          }
        ],
        "type": "ipv4"
      }
    ],
    "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

metaobject
serversarray of objects required

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,
        "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",
          "id": 42,
          "ip": "1.2.3.4"
        },
        "ipv6": {
          "blocked": false,
          "dns_ptr": [
            {
              "dns_ptr": "server.example.com",
              "ip": "2001:db8::1"
            }
          ],
          "id": 42,
          "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
`primary_ip_assigned`	The specified Primary IP is already assigned to a server
`primary_ip_datacenter_mismatch`	The specified Primary IP is in a different datacenter
`primary_ip_version_mismatch`	The specified Primary IP has the wrong IP Version

automountboolean
Auto-mount Volumes after attach
datacenterstring
ID or name of Datacenter to create Server in (must not be used together with location)
firewallsarray of objects
Firewalls which should be applied on the Server's public network interface at creation time
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)
networksarray of integers
Network IDs which should be attached to the Server private network interface at the creation time
placement_groupinteger
ID of the Placement Group the server should be in
public_netobject
Public Network options
server_typestring required
ID or name of the Server type this Server should be created with
ssh_keysarray of strings
SSH key IDs (integer) or names (string) which should be injected into the Server at creation time
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.
volumesarray of integers
Volume IDs which should be attached to the Server at the creation time. Volumes must be in the same Location.

Response

actionobject required
next_actionsarray of objects required
root_passwordstring – nullablerequired
Root password when no SSH keys have been specified
serverobject required

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],"placement_group":1,"public_net":{"enable_ipv4":false,"enable_ipv6":false,"ipv4":null,"ipv6":null},"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
  ],
  "placement_group": 1,
  "public_net": {
    "enable_ipv4": false,
    "enable_ipv6": false,
    "ipv4": null,
    "ipv6": null
  },
  "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

actionobject

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

serverobject

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,
      "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",
        "id": 42,
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "blocked": false,
        "dns_ptr": [
          {
            "dns_ptr": "server.example.com",
            "ip": "2001:db8::1"
          }
        ],
        "id": 42,
        "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

serverobject

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,
      "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",
        "id": 42,
        "ip": "1.2.3.4"
      },
      "ipv6": {
        "blocked": false,
        "dns_ptr": [
          {
            "dns_ptr": "server.example.com",
            "ip": "2001:db8::1"
          }
        ],
        "id": 42,
        "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

metricsobject required

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

actionsarray of objects required
metaobject

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

actionobject required

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

actionobject required

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

actionobject required

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

alias_ipsarray of strings
Additional IPs to be assigned to this Server
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

actionobject required

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

alias_ipsarray of strings required
New alias IPs to set for this Server
networkinteger required
ID of an existing Network already attached to the Server

Response

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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
labelsobject
User-defined labels (key-value pairs)
typestring
Possible enum values:
snapshotbackup
Type of Image to create (default: snapshot)

Response

actionobject
imageobject

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

ssh_keysarray of integers
Array of SSH key IDs which should be injected into the rescue system.
typestring
Possible enum values:
linux64linux32
Type of rescue system to boot (default: linux64)

Response

actionobject
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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject
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

actionobject required

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

actionobject required
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

actionobject required

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 (status running) in order for this operation to succeed.

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

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

HTTP Request

POST /servers/{id}/actions/reset_password

Path Parameters

idinteger required
ID of the Server

Response

actionobject
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

actionobject required

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

server_typesarray of objects required

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

server_typeobject required

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

metaobject
ssh_keysarray of objects required

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

ssh_keyobject required

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

ssh_keyobject required

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

ssh_keyobject required

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

metaobject
volumesarray of objects required

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

actionobject required
next_actionsarray of objects required
volumeobject required

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

volumeobject required

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

labelsobject
User-defined labels (key-value pairs)
namestring required
New Volume name

Response

volumeobject required

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

actionsarray of objects required
metaobject

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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

actionobject required

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