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

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

Example: Getting Started Request

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

Example: Getting Started Response

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

To get started using the API you first need an API token. Sign in into the Hetzner Cloud Console choose a project, go to Access → Tokens, and create a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a project, to interact with the API of another project you have to create a new token inside the project. Let’s say your new token is jEheVytlAoFl7F8MqUQ7jAo2hOXASztX.

You’re now ready to do your first request against the API. To get a list of all servers in your project, issue the example request on the right side using curl.

Make sure to replace the token in the example command with the token you have just created. Since your project probably does not contain any servers yet, the example response will look like the response on the right side. We will almost always provide a resource root like servers inside the example response. A response can also contain a meta object with information like Pagination.

Authentication

Example: Authorization header

Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj

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.

Authorization: Bearer <token>

To create a new API token for your project, switch into the Hetzner Cloud Console choose a project, go to Access → Tokens, and create a new token.

Errors

Example: Error response

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

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:

Key	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

Error Details

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

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.

Example: Pagination Link header

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

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

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:

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

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.

Sorting

Example: Sorting

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

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.

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.

Changelog

2018-04-05: Add deprecated flag to images

Property deprecated has been added to images. It’s null or an ISO8601 timestamp which when set indicates the time after which it will no longer be possible to use the image to create a new server. This applies only to system images. Images that have deprecated timestamp in the past are also not returned under Get all images endpoint, they however can still be queried individually via their ID and the Get single image endpoint.

2018-03-28: Add resource protection

Servers, snapshots and Floating IPs can now be protected from accidental deletion and rebuild via the protection configuration. Additionally, this introduced the new Image Actions resource.

2018-03-20: Filter SSH keys by fingerprint

Similar to filter by name, SSH keys can now be filtered by fingerprint.

2018-03-16: Use SSH key name in server creation

In addition to SSH key IDs, SSH key names can now be used for injecting an SSH key on server create.

2018-02-26: Add deprecated flag to ISOs

Property deprecated has been added to ISOs. It’s null or an ISO8601 timestamp which when set indicates the time after which it will no longer be possible to attach that ISO to servers. ISOs that have deprecated timestamp in the past are also not returned under get all ISOs endpoint, they however can still be queried individually via their ID and the get single ISO endpoint.

2018-02-21: Add server action to request console

Request credentials for remote access via VNC over websocket was added to the API. For more information see the documentation for the request console endpoint

Resources ¶

Actions ¶

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

List all Actions

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

HTTP Request

GET https://api.hetzner.cloud/v1/actions{?status,sort}

URI Parameters

Parameter Type Description

Parameter	Type	Description
status	string (optional)	Can be used multiple times. Response will have only actions with specified statuses. Choices: `running` `success` `error`
sort	string (optional)	Can be used multiple times. Choices: `id` `id:asc` `id:desc` `command` `command:asc` `command:desc` `status` `status:asc` `status:desc` `progress` `progress:asc` `progress:desc` `started` `started:asc` `started:desc` `finished` `finished:asc` `finished:desc`

status

string (optional)

Can be used multiple times. Response will have only actions with specified statuses.

Choices: running success error

sort

string (optional)

Can be used multiple times.

Choices: id id:asc id:desc command command:asc command:desc status status:asc status:desc progress progress:asc progress:desc started started:asc started:desc finished finished:asc finished:desc

Reply

The actions key in the reply contains an array of action objects with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get one Action

Returns a specific action object.

HTTP Request

GET https://api.hetzner.cloud/v1/actions/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the action

Reply

The action key in the reply has this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Servers ¶

Servers are virtual machines that can be provisioned.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "servers": [
    {
      "id": 42,
      "name": "my-server",
      "status": "running",
      "created": "2016-01-30T23:50+00:00",
      "public_net": {
        "ipv4": {
          "ip": "1.2.3.4",
          "blocked": false,
          "dns_ptr": "server01.example.com"
        },
        "ipv6": {
          "ip": "2001:db8::/64",
          "blocked": false,
          "dns_ptr": [
            {
              "ip": "2001:db8::1",
              "dns_ptr": "server.example.com"
            }
          ]
        },
        "floating_ips": [
          478
        ]
      },
      "server_type": {
        "id": 1,
        "name": "cx11",
        "description": "CX11",
        "cores": 1,
        "memory": 1,
        "disk": 25,
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1",
              "gross": "1.19"
            },
            "price_monthly": {
              "net": "1",
              "gross": "1.19"
            }
          }
        ],
        "storage_type": "local"
      },
      "datacenter": {
        "id": 1,
        "name": "fsn1-dc8",
        "description": "Falkenstein 1 DC 8",
        "location": {
          "id": 1,
          "name": "fsn1",
          "description": "Falkenstein DC Park 1",
          "country": "DE",
          "city": "Falkenstein",
          "latitude": 50.47612,
          "longitude": 12.370071
        },
        "server_types": {
          "supported": [
            1,
            2,
            3
          ],
          "available": [
            1,
            2,
            3
          ]
        }
      },
      "image": {
        "id": 4711,
        "type": "system",
        "status": "available",
        "name": "ubuntu-16.04",
        "description": "Ubuntu 16.04 Standard 64 bit",
        "image_size": 2.3,
        "disk_size": 10,
        "created": "2016-01-30T23:50+00:00",
        "created_from": {
          "id": 1,
          "name": "Server"
        },
        "bound_to": 1,
        "os_flavor": "ubuntu",
        "os_version": "16.04",
        "rapid_deploy": false,
        "protection": {
          "delete": false
        },
        "deprecated": "2018-02-28T00:00:00+00:00"
      },
      "iso": {
        "id": 4711,
        "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
        "description": "FreeBSD 11.0 x64",
        "type": "public",
        "deprecated": "2018-02-28T00:00:00+00:00"
      },
      "rescue_enabled": false,
      "locked": false,
      "backup_window": "22-02",
      "outgoing_traffic": 123456,
      "ingoing_traffic": 123456,
      "included_traffic": 654321,
      "protection": {
        "delete": false,
        "rebuild": false
      }
    }
  ]
}

Get all Servers

Returns all existing server objects.

HTTP Request

GET https://api.hetzner.cloud/v1/servers{?name}

URI Parameters

Parameter	Type	Description
name	string (optional)	Can be used to filter servers by their name. The response will only contain the server matching the specified name.

Reply

The servers key in the reply contains an array of server objects with this structure:

Parameter	Type	Description
id	number	ID of server
name	string	Name of the server (must be unique per project and a valid hostname as per RFC 1123)
status	string	Status of the server Choices: `running` `initializing` `starting` `stopping` `off` `deleting` `migrating` `rebuilding` `unknown`
created	string	Point in time when the server was created (in ISO-8601 format)
public_net	object	Public network information. The servers ipv4 address can be found in `public_net->ipv4->ip`
server_type	object	Type of server - determins how much ram, disk and cpu a server has
datacenter	object	Datacenter this server is located at
image	object,null	Image this server was created from.
iso	object,null	ISO image that is attached to this server. Null if no ISO is attached.
rescue_enabled	boolean	True if rescue mode is enabled: Server will then boot into rescue system on next reboot.
locked	boolean	True if server has been locked and is not available to user.
backup_window	string,null	Time window (UTC) in which the backup will run, or null if the backups are not enabled
outgoing_traffic	number,null	Outbound Traffic for the current billing period in bytes
ingoing_traffic	number,null	Inbound Traffic for the current billing period in bytes
included_traffic	number	Free Traffic for the current billing period in bytes
protection	object	Protection configuration for the server

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "server": {
    "id": 42,
    "name": "my-server",
    "status": "running",
    "created": "2016-01-30T23:50+00:00",
    "public_net": {
      "ipv4": {
        "ip": "1.2.3.4",
        "blocked": false,
        "dns_ptr": "server01.example.com"
      },
      "ipv6": {
        "ip": "2001:db8::/64",
        "blocked": false,
        "dns_ptr": [
          {
            "ip": "2001:db8::1",
            "dns_ptr": "server.example.com"
          }
        ]
      },
      "floating_ips": [
        478
      ]
    },
    "server_type": {
      "id": 1,
      "name": "cx11",
      "description": "CX11",
      "cores": 1,
      "memory": 1,
      "disk": 25,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1",
            "gross": "1.19"
          },
          "price_monthly": {
            "net": "1",
            "gross": "1.19"
          }
        }
      ],
      "storage_type": "local"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "system",
      "status": "available",
      "name": "ubuntu-16.04",
      "description": "Ubuntu 16.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": 1,
      "os_flavor": "ubuntu",
      "os_version": "16.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    }
  }
}

Get a Server

Returns a specific server object. The server must exist inside the project.

HTTP Request

GET https://api.hetzner.cloud/v1/servers/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The server key in the reply contains a server object with this structure:

Parameter	Type	Description
id	number	ID of server
name	string	Name of the server (must be unique per project and a valid hostname as per RFC 1123)
status	string	Status of the server Choices: `running` `initializing` `starting` `stopping` `off` `deleting` `migrating` `rebuilding` `unknown`
created	string	Point in time when the server was created (in ISO-8601 format)
public_net	object	Public network information. The servers ipv4 address can be found in `public_net->ipv4->ip`
server_type	object	Type of server - determins how much ram, disk and cpu a server has
datacenter	object	Datacenter this server is located at
image	object,null	Image this server was created from.
iso	object,null	ISO image that is attached to this server. Null if no ISO is attached.
rescue_enabled	boolean	True if rescue mode is enabled: Server will then boot into rescue system on next reboot.
locked	boolean	True if server has been locked and is not available to user.
backup_window	string,null	Time window (UTC) in which the backup will run, or null if the backups are not enabled
outgoing_traffic	number,null	Outbound Traffic for the current billing period in bytes
ingoing_traffic	number,null	Inbound Traffic for the current billing period in bytes
included_traffic	number	Free Traffic for the current billing period in bytes
protection	object	Protection configuration for the server

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN"  \
  -d '{"name":"my-server","server_type":"cx11","start_after_create":true,"image":"ubuntu-16.04","ssh_keys":["my-ssh-key"],"user_data":"#cloud-config\nruncmd:\n- [touch,/root/cloud-init-worked]\n"}' \
  https://api.hetzner.cloud/v1/servers

Request headers

Content-Type: application/json

Request body

{
  "name": "my-server",
  "server_type": "cx11",
  "start_after_create": true,
  "image": "ubuntu-16.04",
  "ssh_keys": [
    "my-ssh-key"
  ],
  "user_data": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n"
}

Response headers

Content-Type: application/json
Status: 201

Response body

{
  "server": {
    "id": 42,
    "name": "my-server",
    "status": "initializing",
    "created": "2016-01-30T23:50+00:00",
    "public_net": {
      "ipv4": {
        "ip": "1.2.3.4",
        "blocked": false,
        "dns_ptr": "server01.example.com"
      },
      "ipv6": {
        "ip": "2001:db8::/64",
        "blocked": false,
        "dns_ptr": [
          {
            "ip": "2001:db8::1",
            "dns_ptr": "server.example.com"
          }
        ]
      },
      "floating_ips": [
        478
      ]
    },
    "server_type": {
      "id": 1,
      "name": "cx11",
      "description": "CX11",
      "cores": 1,
      "memory": 1,
      "disk": 25,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1",
            "gross": "1.19"
          },
          "price_monthly": {
            "net": "1",
            "gross": "1.19"
          }
        }
      ],
      "storage_type": "local"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-16.04",
      "description": "Ubuntu 16.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "16.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    }
  },
  "action": {
    "id": 1337,
    "command": "create_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  },
  "root_password": "YItygq1v3GYjjMomLaKc"
}

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 https://api.hetzner.cloud/v1/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.

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.

Parameter	Type	Description
name	string (required)	Name of the server to create (must be unique per project and a valid hostname as per RFC 1123)
server_type	string (required)	ID or name of the server type this server should be created with
location	string (optional)	ID or name of location to create server in.
datacenter	string (optional)	ID or name of datacenter to create server in.
start_after_create	boolean (optional)	Start Server right after creation. Defaults to true.
image	string (required)	ID or name of the image the server is created from
ssh_keys	array (optional)	SSH key IDs or names which should be injected into the server at creation time
user_data	string (optional)	Cloud-Init user data to use during server creation. This field is limited to 32KiB.

Reply

The server key in the reply contains a server object with this structure:

Parameter	Type	Description
id	number	ID of server
name	string	Name of the server (must be unique per project and a valid hostname as per RFC 1123)
status	string	Status of the server Choices: `initializing` `starting` `running` `stopping` `off` `deleting` `migrating` `rebuilding`
created	string	Point in time when the server was created (in ISO-8601 format)
public_net	object	Public network information. The servers ipv4 address can be found in `public_net->ipv4->ip`
server_type	object	Type of server - determins how much ram, disk and cpu a server has
datacenter	object	Datacenter this server is located at
image	object,null	Image this server was created from.
iso	object,null	ISO image that is attached to this server. Null if no ISO is attached.
rescue_enabled	boolean	True if rescue mode is enabled: Server will then boot into rescue system on next reboot.
locked	boolean	True if server has been locked and is not available to user.
backup_window	string,null	Time window (UTC) in which the backup will run, or null if the backups are not enabled
outgoing_traffic	number,null	Outbound Traffic for the current billing period in bytes
ingoing_traffic	number,null	Inbound Traffic for the current billing period in bytes
included_traffic	number	Free Traffic for the current billing period in bytes
protection	object	Protection configuration for the server

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Call specific error codes

Code	Description
`placement_error`	An error during placement of the server occured

Example curl

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN"  \
  -d '{"name":"new-name"}' \
  https://api.hetzner.cloud/v1/servers/42

Request headers

Content-Type: application/json

Request body

{
  "name": "new-name"
}

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "server": {
    "id": 42,
    "name": "new-name",
    "status": "running",
    "created": "2016-01-30T23:50+00:00",
    "public_net": {
      "ipv4": {
        "ip": "1.2.3.4",
        "blocked": false,
        "dns_ptr": "server01.example.com"
      },
      "ipv6": {
        "ip": "2001:db8::/64",
        "blocked": false,
        "dns_ptr": [
          {
            "ip": "2001:db8::1",
            "dns_ptr": "server.example.com"
          }
        ]
      },
      "floating_ips": [
        478
      ]
    },
    "server_type": {
      "id": 1,
      "name": "cx11",
      "description": "CX11",
      "cores": 1,
      "memory": 1,
      "disk": 25,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1",
            "gross": "1.19"
          },
          "price_monthly": {
            "net": "1",
            "gross": "1.19"
          }
        }
      ],
      "storage_type": "local"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-16.04",
      "description": "Ubuntu 16.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "16.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    }
  }
}

Change Name of a Server

Changes the name of a server.

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

HTTP Request

PUT https://api.hetzner.cloud/v1/servers/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Request

Parameter	Type	Description
name	string (optional)	New name to set

Reply

The server key in the reply contains the modified server object with the new name.

Parameter	Type	Description
id	number	ID of server
name	string	Server name
status	string	Status of the server Choices: `running` `initializing` `starting` `stopping` `off` `deleting` `migrating` `rebuilding` `unknown`
created	string	Point in time when the server was created (in ISO-8601 format)
public_net	object	Public network information. The servers ipv4 address can be found in `public_net->ipv4->ip`
server_type	object	Type of server - determins how much ram, disk and cpu a server has
datacenter	object	Datacenter this server is located at
image	object,null	Image this server was created from.
iso	object,null	ISO image that is attached to this server. Null if no ISO is attached.
rescue_enabled	boolean	True if rescue mode is enabled: Server will then boot into rescue system on next reboot.
locked	boolean	True if server has been locked and is not available to user.
backup_window	string,null	Time window (UTC) in which the backup will run, or null if the backups are not enabled
outgoing_traffic	number,null	Outbound Traffic for the current billing period in bytes
ingoing_traffic	number,null	Inbound Traffic for the current billing period in bytes
included_traffic	number	Free Traffic for the current billing period in bytes
protection	object	Protection configuration for the server

Example curl

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42

Response headers

Content-Type: application/json
Status: 200

Response body

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

Delete a Server

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

HTTP Request

DELETE https://api.hetzner.cloud/v1/servers/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/metrics?type=cpu&start=2017-01-01T00:00:00Z&end=2017-01-01T23:00:00Z

Response headers

Content-Type: application/json
Status: 200

Response body

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

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 100 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 https://api.hetzner.cloud/v1/servers/{id}/metrics{?type,start,end,step}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server
type	string (required)	Type of metrics to get `cpu` `disk` `network`
start	string (required)	Start of period to get Metrics for (in ISO-8601 format)
end	string (required)	End of period to get Metrics for (in ISO-8601 format)
step	number (optional)	Resolution of results in seconds

Reply

The metrics key in the reply contains a metrics object with this structure:

Parameter	Type	Description
start	string	Start of period of metrics reported (in ISO-8601 format)
end	string	End of period of metrics reported (in ISO-8601 format)
step	number	Resolution of results in seconds.
time_series	string	Hash with timeseries information, containing the name of timeseries as key

The time_series key in the returned metrics object is a hash with one key per series returned with this structure:

"time_series": {
    "name_of_timeseries": {
        "values": [
          [
            1435781470.622,
            "42"
          ],
          [
            1435781471.622,
            "43"
          ]
        ]
    }
}

Contrary to the example on the right the timestamp is number and not a string.

Server Actions ¶

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get all Actions for a Server

Returns all action objects for a server.

HTTP Request

GET https://api.hetzner.cloud/v1/servers/{id}/actions{?status,sort}

URI Parameters

Parameter Type Description

string (required)

ID of the server

status

string (optional)

Can be used multiple times. Response will have only actions with specified statuses.

Choices: running success error

sort

string (optional)

Can be used multiple times.

Reply

The actions key in the reply contains an array of action objects with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get a specific Action for a Server

Returns a specific action object for a Server.

HTTP Request

GET https://api.hetzner.cloud/v1/servers/{id}/actions/{action_id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server
action_id	string (required)	ID of the action

Reply

The action key in the reply has this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/poweron

Response headers

Content-Type: application/json
Status: 201

Response body

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

Power on a Server

Starts a server by turning its power on.

HTTP Request

POST https://api.hetzner.cloud/v1/servers/{id}/actions/poweron

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/reboot

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/reboot

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/reset

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/reset

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/shutdown

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/shutdown

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/poweroff

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/poweroff

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/reset_password

Response headers

Content-Type: application/json
Status: 201

Response body

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

Reset root Password of a Server

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

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

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

HTTP Request

POST https://api.hetzner.cloud/v1/servers/{id}/actions/reset_password

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The root_password key in the reply contains the new root password that will be active if the action succeeds.

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

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

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/enable_rescue

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Request

Specify type to select the kind if rescue environment you want to boot.

To access the booted rescue system by SSH key pass the respective SSH key ids in ssh_keys.

Parameter Type Description

Parameter	Type	Description
type	string (optional)	Type of rescue system to boot (default: `linux64`) Choices: `linux64` `linux32` `freebsd64`
ssh_keys	array (optional)	Array of SSH key IDs which should be injected into the rescue system. Only available for types: `linux64` and `linux32`.

type

string (optional)

Type of rescue system to boot (default: linux64)

Choices: linux64 linux32 freebsd64

ssh_keys

array (optional)

Array of SSH key IDs which should be injected into the rescue system. Only available for types: linux64 and linux32.

Reply

The root_password key in the reply contains the root password that can be used to access the booted rescue system.

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Call specific error codes

Code	Description
`rescue_already_enabled`	Returned when the rescue system is already enabled

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/disable_rescue

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/disable_rescue

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Call specific error codes

Code	Description
`rescue_already_disabled`	Returned when the rescue system is already disabled

Example curl

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

Request headers

Content-Type: application/json

Request body

{
  "description": "my image",
  "type": "snapshot"
}

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/create_image

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Request

Parameter Type Description

Parameter	Type	Description
description	string (optional)	Description of the image. If you do not set this we auto-generate one for you.
type	string (optional)	Type of image to create (default: `snapshot`) Choices: `snapshot` `backup`

description

string (optional)

Description of the image. If you do not set this we auto-generate one for you.

type

string (optional)

Type of image to create (default: snapshot)

Choices: snapshot backup

Reply

The image key in the reply contains an the created image, which is an object with this structure:

Parameter	Type	Description
id	number	ID of the image
type	string	Type of the image Choices: `snapshot` `system` `backup`
status	string	Whether the image can be used or if it’s still being created Choices: `creating` `available`
name	string,null	Unique identifier of the image. This value is only set for system images.
description	string	Description of the image
image_size	number,null	Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image.
disk_size	number	Size of the disk contained in the image in GB.
created	string	Point in time when the image was created (in ISO-8601 format)
created_from	object,null	Information about the server the image was created from
bound_to	number,null	ID of server the image is bound to. Only set for images of type `backup`.
os_flavor	string	Flavor of operating system contained in the image Choices: `ubuntu` `centos` `debian` `fedora` `unknown`
os_version	string,null	Operating system version
rapid_deploy	boolean	Indicates that rapid deploy of the image is available
protection	object	Protection configuration for the image
deprecated	string,null	Point in time when the image is considered to be deprecated (in ISO-8601 format)

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

{
  "image": "ubuntu-16.04"
}

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/rebuild

URI Parameters

Parameter	Type	Description
id	string (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.

Parameter	Type	Description
image	string (required)	ID or name of image to rebuilt from.

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

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

Response headers

Content-Type: application/json
Status: 201

Response body

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

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.

HTTP Request

POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_type

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Request

Parameter	Type	Description
upgrade_disk	boolean (optional)	If false, do not upgrade the disk. This allows downgrading the server type later.
server_type	string (required)	ID or name of server type the server should migrate to

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Call specific error codes

Code	Description
`server_not_stopped`	Returned when the server was not powered off
`invalid_server_type`	Returned when a type change to the new server_type is not possible

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN"  \
  -d '{"backup_window":"22-02"}' \
  https://api.hetzner.cloud/v1/servers/42/actions/enable_backup

Request headers

Content-Type: application/json

Request body

{
  "backup_window": "22-02"
}

Response headers

Content-Type: application/json
Status: 201

Response body

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

Enable 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 https://api.hetzner.cloud/v1/servers/{id}/actions/enable_backup

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Request

Passing the backup_window will select the time window for the daily backup to run. All times are in UTC. 22-02 means that the backup will be started between 10 PM and 2 AM. This will be done on a best-effort base, so we cannot guarantee the backup window will be met.

If you do not provide a time window one will be randomly selected.

Parameter Type Description

backup_window

string (optional)

Time window (UTC) in which the backup will run

Choices: 22-02 02-06 06-10 10-14 14-18 18-22

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/disable_backup

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/disable_backup

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

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

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/attach_iso

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Request

Parameter	Type	Description
iso	string (required)	ID or name of ISO to attach to the server as listed in GET `/isos`

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/detach_iso

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/detach_iso

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

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

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/servers/{id}/actions/change_dns_ptr

URI Parameters

Parameter	Type	Description
id	string (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.

Parameter	Type	Description
ip	string (required)	Primary IP address for which the reverse DNS entry should be set.
dns_ptr	string,null (required)	Hostname to set as a reverse DNS PTR entry. Will reset to original value if `null`

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

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

Response headers

Content-Type: application/json
Status: 201

Response body

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

Change protection

Changes the protection configuration of the server.

HTTP Request

POST https://api.hetzner.cloud/v1/servers/{id}/actions/change_protection

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Request

Parameter	Type	Description
delete	boolean (optional)	If true, prevents the server from being deleted (currently delete and rebuild attribute needs to have the same value)
rebuild	boolean (optional)	If true, prevents the server from being rebuilt` (currently delete and rebuild attribute needs to have the same value)

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/servers/42/actions/request_console

Response headers

Content-Type: application/json
Status: 201

Response body

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

Request Console

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 https://api.hetzner.cloud/v1/servers/{id}/actions/request_console

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the server

Reply

Parameter	Type	Description
wss_url	string	URL of websocket proxy to use. This includes a token which is valid for a limited time only.
password	string	VNC password to use for this connection. This password only works in combination with a wss_url with valid token.
action	object

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.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "floating_ips": [
    {
      "id": 4711,
      "description": "Web Frontend",
      "ip": "131.232.99.1",
      "type": "ipv4",
      "server": 42,
      "dns_ptr": [
        {
          "ip": "2001:db8::1",
          "dns_ptr": "server.example.com"
        }
      ],
      "home_location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071
      },
      "blocked": false,
      "protection": {
        "delete": false
      }
    }
  ]
}

Get all Floating IPs

Returns all floating ip objects.

HTTP Request

GET https://api.hetzner.cloud/v1/floating_ips

Reply

The floating_ips key in the reply contains an array of floating ip objects with this structure:

Parameter	Type	Description
id	number	ID of the Floating IP
description	string,null	Description of the Floating IP
ip	string	IP address of the Floating IP
type	string	Type of the Floating IP Choices: `ipv4` `ipv6`
server	number,null	Id of the Server the Floating IP is assigned to, null if it is not assigned at all.
dns_ptr	array	Array of reverse DNS entries
home_location	object	Location the Floating IP was created in. Routing is optimized for this location.
blocked	boolean	Whether the IP is blocked
protection	object	Protection configuration for the Floating IP

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "floating_ip": {
    "id": 4711,
    "description": "Web Frontend",
    "ip": "131.232.99.1",
    "type": "ipv4",
    "server": 42,
    "dns_ptr": [
      {
        "ip": "2001:db8::1",
        "dns_ptr": "server.example.com"
      }
    ],
    "home_location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071
    },
    "blocked": false,
    "protection": {
      "delete": false
    }
  }
}

Get a specific Floating IP

Returns a specific floating ip object.

HTTP Request

GET https://api.hetzner.cloud/v1/floating_ips/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the Floating IP

Reply

The floating_ip key in the reply contains a floating ip object with this structure:

Parameter	Type	Description
id	number	ID of the Floating IP
description	string,null	Description of the Floating IP
ip	string	IP address of the Floating IP
type	string	Type of the Floating IP Choices: `ipv4` `ipv6`
server	number,null	Id of the Server the Floating IP is assigned to, null if it is not assigned at all.
dns_ptr	array	Array of reverse DNS entries
home_location	object	Location the Floating IP was created in. Routing is optimized for this location.
blocked	boolean	Whether the IP is blocked
protection	object	Protection configuration for the Floating IP

Example curl

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

Request headers

Content-Type: application/json

Request body

{
  "type": "ipv4",
  "server": 42,
  "description": "Web Frontend"
}

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/floating_ips

Request

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

Parameter	Type	Description
type	string (required)	Floating IP type Choices: `ipv4` `ipv6`
home_location	string (optional)	Home location (routing is optimized for that location). Only optional if server argument is passed.
server	number (optional)	Server to assign the Floating IP to
description	string (optional)

Reply

The floating_ip key in the reply contains the object that was just created:

Parameter	Type	Description
id	number	ID of the Floating IP
description	string,null	Description of the Floating IP
ip	string	IP address of the Floating IP
type	string	Type of the Floating IP Choices: `ipv4` `ipv6`
server	number,null	Id of the Server the Floating IP is assigned to, null if it is not assigned at all.
dns_ptr	array	Array of reverse DNS entries
home_location	object	Location the Floating IP was created in. Routing is optimized for this location.
blocked	boolean	Whether the IP is blocked
protection	object	Protection configuration for the Floating IP

If you chose to bind the Floating IP to a server on creation the action key in the reply contains the action that tracks assignment of the IP to the specified server:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN"  \
  -d '{"description":"New description"}' \
  https://api.hetzner.cloud/v1/floating_ips/4711

Request headers

Content-Type: application/json

Request body

{
  "description": "New description"
}

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "floating_ip": {
    "id": 4711,
    "description": "New description",
    "ip": "131.232.99.1",
    "type": "ipv4",
    "server": 42,
    "dns_ptr": [
      {
        "ip": "2001:db8::1",
        "dns_ptr": "server.example.com"
      }
    ],
    "home_location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071
    },
    "blocked": false,
    "protection": {
      "delete": false
    }
  }
}

Change description of a Floating IP

Changes the description of a Floating IP.

HTTP Request

PUT https://api.hetzner.cloud/v1/floating_ips/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the Floating IP

Request

Parameter	Type	Description
description	string (optional)	New Description to set

Reply

The floating_ip key in the reply contains the modified Floating IP object with the new description:

Parameter	Type	Description
id	number	ID of the Floating IP
description	string,null	Description of the Floating IP
ip	string	IP address of the Floating IP
type	string	Type of the Floating IP Choices: `ipv4` `ipv6`
server	number,null	Id of the Server the Floating IP is assigned to, null if it is not assigned at all.
dns_ptr	array	Array of reverse DNS entries
home_location	object	Location the Floating IP was created in. Routing is optimized for this location.
blocked	boolean	Whether the IP is blocked
protection	object	Protection configuration for the Floating IP

Example curl

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/floating_ips/4711

This response has no content.

Delete a Floating IP

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

HTTP Request

DELETE https://api.hetzner.cloud/v1/floating_ips/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the Floating IP

Floating IP Actions ¶

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

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.

HTTP Request

GET https://api.hetzner.cloud/v1/floating_ips/{id}/actions{?sort}

URI Parameters

Parameter Type Description

string (required)

ID of the Floating IP

sort

string (optional)

Can be used multiple times.

Reply

The actions key in the reply contains an array of action objects with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get an Action for a Floating IP

Returns a specific action object for a Floating IP.

HTTP Request

GET https://api.hetzner.cloud/v1/floating_ips/{id}/actions/{action_id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the Floating IP
action_id	string (required)	ID of the action

Reply

The action key in the reply has this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

{
  "server": 43
}

Response headers

Content-Type: application/json
Status: 201

Response body

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

Assign a Floating IP to a Server

Assigns a Floating IP to a server.

HTTP Request

POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/assign

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the Floating IP

Request

Parameter	Type	Description
server	number (required)	ID of the server the Floating IP shall be assigned to

Reply

The action key in the reply has this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/floating_ips/4711/actions/unassign

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/floating_ips/{id}/actions/unassign

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the Floating IP

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

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

Response headers

Content-Type: application/json
Status: 201

Response body

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

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 https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_dns_ptr

URI Parameters

Parameter	Type	Description
id	string (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.

Parameter	Type	Description
ip	string (required)	IP address for which to set the reverse DNS entry
dns_ptr	string,null (required)	Hostname to set as a reverse DNS PTR entry, will reset to original default value if `null`

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `running` `success` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response body

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

Change protection

Changes the protection configuration of the Floating IP.

HTTP Request

POST https://api.hetzner.cloud/v1/floating_ips/{id}/actions/change_protection

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the Floating IP

Request

Parameter	Type	Description
delete	boolean (optional)	If true, prevents the Floating IP from being deleted

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

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.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "ssh_keys": [
    {
      "id": 2323,
      "name": "My ssh key",
      "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
      "public_key": "ssh-rsa AAAjjk76kgf...Xt"
    }
  ]
}

Get all SSH keys

Returns all SSH key objects.

HTTP Request

GET https://api.hetzner.cloud/v1/ssh_keys{?name,fingerprint}

URI Parameters

Parameter	Type	Description
name	string (optional)	Can be used to filter SSH keys by their name. The response will only contain the SSH key matching the specified name.
fingerprint	string (optional)	Can be used to filter SSH keys by their fingerprint. The response will only contain the SSH key matching the specified fingerprint.

Reply

The ssh_keys key in the reply contains an array of SSH key objects with this structure:

Parameter	Type	Description
id	number	ID of the SSH key
name	string	Name of the SSH key (must be unique per project)
fingerprint	string	Fingerprint of public key
public_key	string	Public key

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "ssh_key": {
    "id": 2323,
    "name": "My ssh key",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt"
  }
}

Get an SSH key

Returns a specific SSH key object.

HTTP Request

GET https://api.hetzner.cloud/v1/ssh_keys/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the SSH key

Reply

The ssh_key key in the reply contains an SSH key object with this structure:

Parameter	Type	Description
id	number	ID of the SSH key
name	string	Name of the SSH key (must be unique per project)
fingerprint	string	Fingerprint of public key
public_key	string	Public key

Example curl

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

Request headers

Content-Type: application/json

Request body

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

Response headers

Content-Type: application/json
Status: 201

Response body

{
  "ssh_key": {
    "id": 2323,
    "name": "My ssh key",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt"
  }
}

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 https://api.hetzner.cloud/v1/ssh_keys

Request

Parameter	Type	Description
name	string (required)	Name of the SSH key
public_key	string (required)	Public key

Reply

The ssh_key key in the reply contains the object that was just created:

Parameter	Type	Description
id	number	ID of the SSH key
name	string	Name of the SSH key (must be unique per project)
fingerprint	string	Fingerprint of public key
public_key	string	Public key

Example curl

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN"  \
  -d '{"name":"New name"}' \
  https://api.hetzner.cloud/v1/ssh_keys/2323

Request headers

Content-Type: application/json

Request body

{
  "name": "New name"
}

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "ssh_key": {
    "id": 2323,
    "name": "New name",
    "fingerprint": "b7:2f:30:a0:2f:6c:58:6c:21:04:58:61:ba:06:3b:2f",
    "public_key": "ssh-rsa AAAjjk76kgf...Xt"
  }
}

Change the name of an SSH key

Changes the name of an SSH key.

HTTP Request

PUT https://api.hetzner.cloud/v1/ssh_keys/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the SSH key

Request

Parameter	Type	Description
name	string (optional)	New name Name to set

Reply

The ssh_key key in the reply contains the modified SSH key object with the new description:

Parameter	Type	Description
id	number	ID of the SSH key
name	string	Name of the SSH key
fingerprint	string	Fingerprint of public key
public_key	string	Public key

Example curl

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/ssh_keys/2323

This response has no content.

Delete an SSH key

Deletes an SSH key. It cannot be used anymore.

HTTP Request

DELETE https://api.hetzner.cloud/v1/ssh_keys/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the SSH key

Server Types ¶

Server types define kinds of servers offered. Each type has a 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.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "server_types": [
    {
      "id": 1,
      "name": "cx11",
      "description": "CX11",
      "cores": 1,
      "memory": 1,
      "disk": 25,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1",
            "gross": "1.19"
          },
          "price_monthly": {
            "net": "1",
            "gross": "1.19"
          }
        }
      ],
      "storage_type": "local"
    }
  ]
}

Get all Server Types

Gets all server type objects.

HTTP Request

GET https://api.hetzner.cloud/v1/server_types{?name}

URI Parameters

Parameter	Type	Description
name	string (optional)	Can be used to filter server types by their name. The response will only contain the server type matching the specified name.

Reply

The server_types key in the reply contains an array of server type objects with this structure:

Parameter	Type	Description
id	number	ID of the server type
name	string	Unique identifier of the server type
description	string	Description of the server type
cores	number	Number of cpu cores a server of this type will have
memory	number	Memory a server of this type will have in GB
disk	number	Disk size a server of this type will have in GB
prices	array	Prices in different Locations
storage_type	string	Type of server boot drive. Local has higher speed. Network has better availability. Choices: `local` `network`

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "server_type": {
    "id": 1,
    "name": "cx11",
    "description": "CX11",
    "cores": 1,
    "memory": 1,
    "disk": 25,
    "prices": [
      {
        "location": "fsn1",
        "price_hourly": {
          "net": "1",
          "gross": "1.19"
        },
        "price_monthly": {
          "net": "1",
          "gross": "1.19"
        }
      }
    ],
    "storage_type": "local"
  }
}

Get a Server Type

Gets a specific server type object.

HTTP Request

GET https://api.hetzner.cloud/v1/server_types/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of server type

Reply

The server_type key in the reply contains a server type object with this structure:

Parameter	Type	Description
id	number	ID of the server type
name	string	Unique identifier of the server type
description	string	Description of the server type
cores	number	Number of cpu cores a server of this type will have
memory	number	Memory a server of this type will have in GB
disk	number	Disk size a server of this type will have in GB
prices	array	Prices in different Locations
storage_type	string	Type of server boot drive. Local has higher speed. Network has better availability. Choices: `local` `network`

Locations ¶

Datacenters are organized by locations. Datacenters in the same location are connected with very low latency links.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get all Locations

Returns all location objects.

HTTP Request

GET https://api.hetzner.cloud/v1/locations{?name}

URI Parameters

Parameter	Type	Description
name	string (optional)	Can be used to filter locations by their name. The response will only contain the location matching the specified name.

Reply

The locations key in the reply contains an array of location objects with this structure:

Parameter	Type	Description
id	number	ID of the location
name	string	Unique identifier of the location
description	string	Description of the location
country	string	ISO 3166-1 alpha-2 code of the country the location resides in
city	string	City the location is closest to
latitude	number	Latitude of the city closest to the location
longitude	number	Longitude of the city closest to the location

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get a Location

Returns a specific location object.

HTTP Request

GET https://api.hetzner.cloud/v1/locations/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of location

Reply

The location key in the reply contains a location object with this structure:

Parameter	Type	Description
id	number	ID of the location
name	string	Unique identifier of the location
description	string	Description of the location
country	string	ISO 3166-1 alpha-2 code of the country the location resides in
city	string	City the location is closest to
latitude	number	Latitude of the city closest to the location
longitude	number	Longitude of the city closest to the location

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.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get all Datacenters

Returns all datacenter objects.

HTTP Request

GET https://api.hetzner.cloud/v1/datacenters{?name}

URI Parameters

Parameter	Type	Description
name	string (optional)	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.

Reply

The datacenters key in the reply contains an array of datacenter objects with this structure:

Parameter	Type	Description
id	number	ID of the datacenter
name	string	Unique identifier of the datacenter
description	string	Description of the datacenter
location	object	Location where the datacenter resides in
server_types	object	The server types the datacenter can handle

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get a Datacenter

Returns a specific datacenter object.

HTTP Request

GET https://api.hetzner.cloud/v1/datacenters/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of datacenter

Reply

The datacenter key in the reply contains a datacenter object with this structure:

Parameter	Type	Description
id	number	ID of the datacenter
name	string	Unique identifier of the datacenter
description	string	Description of the datacenter
location	object	Location where the datacenter resides in
server_types	object	The server types the datacenter can handle

Images ¶

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

System images

Distribution images maintained by us, e.g. “Ubuntu 16.04”

Snapshot Images

Maintained by you, for example “Ubuntu 16.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.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "images": [
    {
      "id": 4711,
      "type": "system",
      "status": "available",
      "name": "ubuntu-16.04",
      "description": "Ubuntu 16.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": 1,
      "os_flavor": "ubuntu",
      "os_version": "16.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00"
    }
  ]
}

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 https://api.hetzner.cloud/v1/images{?sort,type,bound_to,name}

URI Parameters

Parameter	Type	Description
sort	string (optional)	Can be used multiple times. Choices: `id` `id:asc` `id:desc` `name` `name:asc` `name:desc` `created` `created:asc` `created:desc`
type	string (optional)	Can be used multiple times. Choices: `system` `snapshot` `backup`
bound_to	string (optional)	Can be used multiple times. Server Id linked to the image. Only available for images of type `backup`
name	string (optional)	Can be used to filter images by their name. The response will only contain the image matching the specified name.

Reply

The images key in the reply contains an array of image objects with this structure:

Parameter	Type	Description
id	number	ID of the image
type	string	Type of the image Choices: `system` `snapshot` `backup`
status	string	Whether the image can be used or if it’s still being created Choices: `available` `creating`
name	string,null	Unique identifier of the image. This value is only set for system images.
description	string	Description of the image
image_size	number,null	Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image.
disk_size	number	Size of the disk contained in the image in GB.
created	string	Point in time when the image was created (in ISO-8601 format)
created_from	object,null	Information about the server the image was created from
bound_to	number,null	ID of server the image is bound to. Only set for images of type `backup`.
os_flavor	string	Flavor of operating system contained in the image Choices: `ubuntu` `centos` `debian` `fedora` `unknown`
os_version	string,null	Operating system version
rapid_deploy	boolean	Indicates that rapid deploy of the image is available
protection	object	Protection configuration for the image
deprecated	string,null	Point in time when the image is considered to be deprecated (in ISO-8601 format)

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "image": {
    "id": 4711,
    "type": "system",
    "status": "available",
    "name": "ubuntu-16.04",
    "description": "Ubuntu 16.04 Standard 64 bit",
    "image_size": 2.3,
    "disk_size": 10,
    "created": "2016-01-30T23:50+00:00",
    "created_from": {
      "id": 1,
      "name": "Server"
    },
    "bound_to": 1,
    "os_flavor": "ubuntu",
    "os_version": "16.04",
    "rapid_deploy": false,
    "protection": {
      "delete": false
    },
    "deprecated": "2018-02-28T00:00:00+00:00"
  }
}

Get an Image

Returns a specific image object.

HTTP Request

GET https://api.hetzner.cloud/v1/images/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the image

Reply

The image key in the reply contains an image object with this structure:

Parameter	Type	Description
id	number	ID of the image
type	string	Type of the image Choices: `system` `snapshot` `backup`
status	string	Whether the image can be used or if it’s still being created Choices: `available` `creating`
name	string,null	Unique identifier of the image. This value is only set for system images.
description	string	Description of the image
image_size	number,null	Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image.
disk_size	number	Size of the disk contained in the image in GB.
created	string	Point in time when the image was created (in ISO-8601 format)
created_from	object,null	Information about the server the image was created from
bound_to	number,null	ID of server the image is bound to. Only set for images of type `backup`.
os_flavor	string	Flavor of operating system contained in the image Choices: `ubuntu` `centos` `debian` `fedora` `unknown`
os_version	string,null	Operating system version
rapid_deploy	boolean	Indicates that rapid deploy of the image is available
protection	object	Protection configuration for the image
deprecated	string,null	Point in time when the image is considered to be deprecated (in ISO-8601 format)

Example curl

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

Request headers

Content-Type: application/json

Request body

{
  "description": "My new Image description",
  "type": "snapshot"
}

Response headers

Content-Type: application/json
Status: 200

Response body

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

Update an Image

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

HTTP Request

PUT https://api.hetzner.cloud/v1/images/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the image to be updated

Request

Parameter Type Description

description

string (optional)

New description of Image

type

string (optional)

Destination image type to convert to

Choices: snapshot

Reply

The image key in the reply contains the modified image object:

Parameter	Type	Description
id	number	ID of the image
type	string	Type of the image Choices: `snapshot` `system` `backup`
status	string	Whether the image can be used or if it’s still being created Choices: `available` `creating`
name	string,null	Unique identifier of the image. This value is only set for system images.
description	string	Description of the image
image_size	number,null	Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image.
disk_size	number	Size of the disk contained in the image in GB.
created	string	Point in time when the image was created (in ISO-8601 format)
created_from	object,null	Information about the server the image was created from
bound_to	number,null	ID of server the image is bound to. Only set for images of type `backup`.
os_flavor	string	Flavor of operating system contained in the image Choices: `ubuntu` `centos` `debian` `fedora` `unknown`
os_version	string,null	Operating system version
rapid_deploy	boolean	Indicates that rapid deploy of the image is available
protection	object	Protection configuration for the image
deprecated	string,null	Point in time when the image is considered to be deprecated (in ISO-8601 format)

Example curl

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
  https://api.hetzner.cloud/v1/images/4711

This response has no content.

Delete an Image

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

HTTP Request

DELETE https://api.hetzner.cloud/v1/images/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the Image

Image Actions ¶

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get all Actions for an Image

Returns all action objects for an image. You can sort the results by using the sort URI parameter.

HTTP Request

GET https://api.hetzner.cloud/v1/images/{id}/actions{?sort}

URI Parameters

Parameter Type Description

string (required)

ID of the Image

sort

string (optional)

Can be used multiple times.

Reply

The actions key in the reply contains an array of action objects with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get an Action for an Image

Returns a specific action object for an image.

HTTP Request

GET https://api.hetzner.cloud/v1/images/{id}/actions/{action_id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the image
action_id	string (required)	ID of the action

Reply

The action key in the reply has this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

Example curl

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

Request headers

Content-Type: application/json

Request body

{
  "delete": true
}

Response headers

Content-Type: application/json
Status: 201

Response body

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

Change protection

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

HTTP Request

POST https://api.hetzner.cloud/v1/images/{id}/actions/change_protection

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the image

Request

Parameter	Type	Description
delete	boolean (optional)	If true, prevents the snapshot from being deleted

Reply

The action key in the reply contains an action object with this structure:

Parameter	Type	Description
id	number	ID of the action
command	string	Command executed in the action
status	string	Status of the action Choices: `success` `running` `error`
progress	number	Progress of action in percent
started	string	Point in time when the action was started (in ISO-8601 format)
finished	string,null	Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.
resources	array	Resources the action relates to
error	object,null	Error message for the action if error occured, otherwise null.

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.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get all ISOs

Returns all available iso objects.

HTTP Request

GET https://api.hetzner.cloud/v1/isos{?name}

URI Parameters

Parameter	Type	Description
name	string (optional)	Can be used to filter isos by their name. The response will only contain the iso matching the specified name.

Reply

The isos key in the reply contains an array of iso objects with this structure:

Parameter	Type	Description
id	number	ID of the ISO
name	string,null	Unique identifier of the ISO. Only set for public ISOs
description	string	Description of the ISO
type	string	Type of the ISO Choices: `public` `private`
deprecated	string,null	ISO 8601 timestamp of deprecation, null if ISO is still available. After the deprecation time it will no longer be possible to attach the ISO to servers.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

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

Get an ISO

Returns a specific iso object.

HTTP Request

GET https://api.hetzner.cloud/v1/isos/{id}

URI Parameters

Parameter	Type	Description
id	string (required)	ID of the ISO

Reply

The iso key in the reply contains an iso object with this structure:

Parameter	Type	Description
id	number	ID of the ISO
name	string,null	Unique identifier of the ISO. Only set for public ISOs
description	string	Description of the ISO
type	string	Type of the ISO Choices: `public` `private`
deprecated	string,null	ISO 8601 timestamp of deprecation, null if ISO is still available. After the deprecation time it will no longer be possible to attach the ISO to servers.

Pricing ¶

Returns prices for resources.

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response body

{
  "pricing": {
    "currency": "EUR",
    "vat_rate": "19.00",
    "image": {
      "price_per_gb_month": {
        "net": "1",
        "gross": "1.19"
      }
    },
    "floating_ip": {
      "price_monthly": {
        "net": "1",
        "gross": "1.19"
      }
    },
    "traffic": {
      "price_per_tb": {
        "net": "1",
        "gross": "1.19"
      }
    },
    "server_backup": {
      "percentage": "20"
    },
    "server_types": [
      {
        "id": 4,
        "name": "CX11",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1",
              "gross": "1.19"
            },
            "price_monthly": {
              "net": "1",
              "gross": "1.19"
            }
          }
        ]
      }
    ]
  }
}

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 https://api.hetzner.cloud/v1/pricing

Reply

The pricing key in the reply contains an pricing object with this structure:

Parameter	Type	Description
currency	string	Currency the returned prices are expressed in, coded according to ISO 4217.
vat_rate	string	The VAT rate used for calculating prices with VAT
image	object	The cost of one 1GB Image for the full month.
floating_ip	object	The cost of one floating IP per month.
traffic	object	The cost of additional traffic per GB
server_backup	object	Will increase base server costs by specific percentage.
server_types	array	Costs of server types per location and type

Introduction ¶

Getting Started ¶

Authentication ¶

Errors ¶

Error Codes ¶

Error Details ¶

Pagination ¶

Sorting ¶

Rate Limiting ¶

Changelog ¶

Resources ¶

Actions ¶

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Servers ¶

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Request headers

Request body

Response headers

Response body

Call specific error codes ¶

Example curl

Request headers

Request body

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Server Actions ¶

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Response headers

Response body

Example curl

Request headers

Request body

Response headers

Response body

Call specific error codes ¶

Example curl

Response headers

Response body

Call specific error codes ¶

Example curl

Request headers

Request body

Introduction

Getting Started

Authentication

Errors

Error Codes

Error Details

Pagination

Sorting

Rate Limiting

Changelog

Call specific error codes

Call specific error codes

Call specific error codes

Call specific error codes