Hetzner Cloud API

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

Introduction

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

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

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

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

  • The type of integration you would like to develop

  • Link to the GitHub repo you will use for the project

  • Link to some other Open Source work you have already done (if you have done so)

Getting Started

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

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.

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
ParameterTypeDescription
statusstring (optional) 

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

Choices: running success error

sortstring (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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the action

Reply

The action key in the reply has this structure:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
      },
      "iso": {
        "id": 4711,
        "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
        "description": "FreeBSD 11.0 x64",
        "type": "public"
      },
      "rescue_enabled": false,
      "locked": false,
      "backup_window": "22-02",
      "outgoing_traffic": 123456,
      "ingoing_traffic": 123456,
      "included_traffic": 654321
    }
  ]
}

Get all Servers

Returns all existing server objects.

HTTP Request
GET https://api.hetzner.cloud/v1/servers{?name}
URI Parameters
ParameterTypeDescription
namestring (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:

ParameterTypeDescription
idnumber 

ID of server

namestring 

Name of the server (must be unique per project and a valid hostname as per RFC 1123)

statusstring 

Status of the server

Choices: running initializing starting stopping off deleting migrating rebuilding unknown

createdstring 

Point in time when the server was created (in ISO-8601 format)

public_netobject 

Public network information. The servers ipv4 address can be found in public_net->ipv4->ip

server_typeobject 

Type of server - determins how much ram, disk and cpu a server has

datacenterobject 

Datacenter this server is located at

imageobject,null 

Image this server was created from.

isoobject,null 

ISO image that is attached to this server. Null if no ISO is attached.

rescue_enabledboolean 

True if rescue mode is enabled: Server will then boot into rescue system on next reboot.

lockedboolean 

True if server has been locked and is not available to user.

backup_windowstring,null 

Time window (UTC) in which the backup will run, or null if the backups are not enabled

outgoing_trafficnumber,null 

Outbound Traffic for the current billing period in bytes

ingoing_trafficnumber,null 

Inbound Traffic for the current billing period in bytes

included_trafficnumber 

Free Traffic for the current billing period in bytes


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
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321
  }
}

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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of server

namestring 

Name of the server (must be unique per project and a valid hostname as per RFC 1123)

statusstring 

Status of the server

Choices: running initializing starting stopping off deleting migrating rebuilding unknown

createdstring 

Point in time when the server was created (in ISO-8601 format)

public_netobject 

Public network information. The servers ipv4 address can be found in public_net->ipv4->ip

server_typeobject 

Type of server - determins how much ram, disk and cpu a server has

datacenterobject 

Datacenter this server is located at

imageobject,null 

Image this server was created from.

isoobject,null 

ISO image that is attached to this server. Null if no ISO is attached.

rescue_enabledboolean 

True if rescue mode is enabled: Server will then boot into rescue system on next reboot.

lockedboolean 

True if server has been locked and is not available to user.

backup_windowstring,null 

Time window (UTC) in which the backup will run, or null if the backups are not enabled

outgoing_trafficnumber,null 

Outbound Traffic for the current billing period in bytes

ingoing_trafficnumber,null 

Inbound Traffic for the current billing period in bytes

included_trafficnumber 

Free Traffic for the current billing period in bytes


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":[2323],"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": [
    2323
  ],
  "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
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321
  },
  "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 specific datacenter, you must set datacenter to the ID or name as listed in /datacenters. If you want to be less specific you can instead set location to the ID or name as listed in /locations.

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.

ParameterTypeDescription
namestring (required) 

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

server_typestring (required) 

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

datacenterstring (optional) 

ID or name of datacenter to create server in.

locationstring (optional) 

ID or name of location to create server in.

start_after_createboolean (optional) 

Start Server right after creation. Defaults to true.

imagestring (required) 

ID or name of the image the server is created from

ssh_keysarray (optional) 

SSH key IDs which should be injected into the server at creation time

user_datastring (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:

ParameterTypeDescription
idnumber 

ID of server

namestring 

Name of the server (must be unique per project and a valid hostname as per RFC 1123)

statusstring 

Status of the server

Choices: initializing starting running stopping off deleting migrating rebuilding

createdstring 

Point in time when the server was created (in ISO-8601 format)

public_netobject 

Public network information. The servers ipv4 address can be found in public_net->ipv4->ip

server_typeobject 

Type of server - determins how much ram, disk and cpu a server has

datacenterobject 

Datacenter this server is located at

imageobject,null 

Image this server was created from.

isoobject,null 

ISO image that is attached to this server. Null if no ISO is attached.

rescue_enabledboolean 

True if rescue mode is enabled: Server will then boot into rescue system on next reboot.

lockedboolean 

True if server has been locked and is not available to user.

backup_windowstring,null 

Time window (UTC) in which the backup will run, or null if the backups are not enabled

outgoing_trafficnumber,null 

Outbound Traffic for the current billing period in bytes

ingoing_trafficnumber,null 

Inbound Traffic for the current billing period in bytes

included_trafficnumber 

Free Traffic for the current billing period in bytes

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321
  }
}

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
ParameterTypeDescription
idstring (required) 

ID of the server

Request
ParameterTypeDescription
namestring (optional) 

New name to set

Reply

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

ParameterTypeDescription
idnumber 

ID of server

namestring 

Server name

statusstring 

Status of the server

Choices: running initializing starting stopping off deleting migrating rebuilding unknown

createdstring 

Point in time when the server was created (in ISO-8601 format)

public_netobject 

Public network information. The servers ipv4 address can be found in public_net->ipv4->ip

server_typeobject 

Type of server - determins how much ram, disk and cpu a server has

datacenterobject 

Datacenter this server is located at

imageobject,null 

Image this server was created from.

isoobject,null 

ISO image that is attached to this server. Null if no ISO is attached.

rescue_enabledboolean 

True if rescue mode is enabled: Server will then boot into rescue system on next reboot.

lockedboolean 

True if server has been locked and is not available to user.

backup_windowstring,null 

Time window (UTC) in which the backup will run, or null if the backups are not enabled

outgoing_trafficnumber,null 

Outbound Traffic for the current billing period in bytes

ingoing_trafficnumber,null 

Inbound Traffic for the current billing period in bytes

included_trafficnumber 

Free Traffic for the current billing period in bytes


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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

typestring (required) 

Type of metrics to get

  • cpu

  • disk

  • network

startstring (required) 

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

endstring (required) 

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

stepnumber (optional) 

Resolution of results in seconds

Reply

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

ParameterTypeDescription
startstring 

Start of period of metrics reported (in ISO-8601 format)

endstring 

End of period of metrics reported (in ISO-8601 format)

stepnumber 

Resolution of results in seconds.

time_seriesstring 

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
ParameterTypeDescription
idstring (required) 

ID of the server

statusstring (optional) 

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

Choices: running success error

sortstring (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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

action_idstring (required) 

ID of the action

Reply

The action key in the reply has this structure:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (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.

ParameterTypeDescription
typestring (optional) 

Type of rescue system to boot (default: linux64)

Choices: linux64 linux32 freebsd64

ssh_keysarray (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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
  },
  "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
ParameterTypeDescription
idstring (required) 

ID of the server

Request
ParameterTypeDescription
descriptionstring (optional) 

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

typestring (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:

ParameterTypeDescription
idnumber 

ID of the image

typestring 

Type of the image

Choices: snapshot system backup

statusstring 

Whether the image can be used or if it’s still being created

Choices: creating available

namestring,null 

Unique identifier of the image. This value is only set for system images.

descriptionstring 

Description of the image

image_sizenumber,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_sizenumber 

Size of the disk contained in the image in GB.

createdstring 

Point in time when the image was created (in ISO-8601 format)

created_fromobject,null 

Information about the server the image was created from

bound_tonumber,null 

ID of server the image is bound to. Only set for images of type backup.

os_flavorstring 

Flavor of operating system contained in the image

Choices: ubuntu centos debian fedora unknown

os_versionstring,null 

Operating system version

rapid_deployboolean 

Indicates that rapid deploy of the image is available

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (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.

ParameterTypeDescription
imagestring (required) 

ID or name of image to rebuilt from.

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Request
ParameterTypeDescription
upgrade_diskboolean (optional) 

If false, do not upgrade the disk. This allows downgrading the server type later.

server_typestring (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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (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.

ParameterTypeDescription
backup_windowstring (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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Request
ParameterTypeDescription
isostring (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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (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.

ParameterTypeDescription
ipstring (required) 

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

dns_ptrstring,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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the server

Reply
ParameterTypeDescription
wss_urlstring 

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

passwordstring 

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

actionobject 

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

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:

ParameterTypeDescription
idnumber 

ID of the Floating IP

descriptionstring,null 

Description of the Floating IP

ipstring 

IP address of the Floating IP

typestring 

Type of the Floating IP

Choices: ipv4 ipv6

servernumber,null 

Id of the Server the Floating IP is assigned to, null if it is not assigned at all.

dns_ptrarray 

Array of reverse DNS entries

home_locationobject 

Location the Floating IP was created in. Routing is optimized for this location.

blockedboolean 

Whether the IP is blocked


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

Get a specific Floating IP

Returns a specific floating ip object.

HTTP Request
GET https://api.hetzner.cloud/v1/floating_ips/{id}
URI Parameters
ParameterTypeDescription
idstring (required) 

ID of the Floating IP

Reply

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

ParameterTypeDescription
idnumber 

ID of the Floating IP

descriptionstring,null 

Description of the Floating IP

ipstring 

IP address of the Floating IP

typestring 

Type of the Floating IP

Choices: ipv4 ipv6

servernumber,null 

Id of the Server the Floating IP is assigned to, null if it is not assigned at all.

dns_ptrarray 

Array of reverse DNS entries

home_locationobject 

Location the Floating IP was created in. Routing is optimized for this location.

blockedboolean 

Whether the IP is blocked


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

ParameterTypeDescription
typestring (required) 

Floating IP type

Choices: ipv4 ipv6

home_locationstring (optional) 

Home location (routing is optimized for that location). Only optional if server argument is passed.

servernumber (optional) 

Server to assign the Floating IP to

descriptionstring (optional) 
Reply

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

ParameterTypeDescription
idnumber 

ID of the Floating IP

descriptionstring,null 

Description of the Floating IP

ipstring 

IP address of the Floating IP

typestring 

Type of the Floating IP

Choices: ipv4 ipv6

servernumber,null 

Id of the Server the Floating IP is assigned to, null if it is not assigned at all.

dns_ptrarray 

Array of reverse DNS entries

home_locationobject 

Location the Floating IP was created in. Routing is optimized for this location.

blockedboolean 

Whether the IP is blocked

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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
  }
}

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
ParameterTypeDescription
idstring (required) 

ID of the Floating IP

Request
ParameterTypeDescription
descriptionstring (optional) 

New Description to set

Reply

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

ParameterTypeDescription
idnumber 

ID of the Floating IP

descriptionstring,null 

Description of the Floating IP

ipstring 

IP address of the Floating IP

typestring 

Type of the Floating IP

Choices: ipv4 ipv6

servernumber,null 

Id of the Server the Floating IP is assigned to, null if it is not assigned at all.

dns_ptrarray 

Array of reverse DNS entries

home_locationobject 

Location the Floating IP was created in. Routing is optimized for this location.

blockedboolean 

Whether the IP is blocked


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
ParameterTypeDescription
idstring (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
ParameterTypeDescription
idstring (required) 

ID of the Floating IP

sortstring (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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the Floating IP

action_idstring (required) 

ID of the action

Reply

The action key in the reply has this structure:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: success running error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the Floating IP

Request
ParameterTypeDescription
servernumber (required) 

ID of the server the Floating IP shall be assigned to

Reply

The action key in the reply has this structure:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (required) 

ID of the Floating IP

Reply

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

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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
ParameterTypeDescription
idstring (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.

ParameterTypeDescription
ipstring (required) 

IP address for which to set the reverse DNS entry

dns_ptrstring,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:

ParameterTypeDescription
idnumber 

ID of the action

commandstring 

Command executed in the action

statusstring 

Status of the action

Choices: running success error

progressnumber 

Progress of action in percent

startedstring 

Point in time when the action was started (in ISO-8601 format)

finishedstring,null 

Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null.

resourcesarray 

Resources the action relates to

errorobject,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}
URI Parameters
ParameterTypeDescription
namestring (optional) 

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

Reply

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

ParameterTypeDescription
idnumber 

ID of the SSH key

namestring 

Name of the SSH key (must be unique per project)

fingerprintstring 

Fingerprint of public key

public_keystring 

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 a SSH Key

Returns a specific ssh key object.

HTTP Request
GET https://api.hetzner.cloud/v1/ssh_keys/{id}
URI Parameters
ParameterTypeDescription
idstring (required) 

ID of the SSH key

Reply

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

ParameterTypeDescription
idnumber 

ID of the SSH key

namestring 

Name of the SSH key (must be unique per project)

fingerprintstring 

Fingerprint of public key

public_keystring 

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 a SSH Key

Creates a new SSH Key with the given name and public_key. Once a 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
ParameterTypeDescription
namestring (required) 

Name of the SSH key

public_keystring (required) 

Public key

Reply

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

ParameterTypeDescription
idnumber 

ID of the SSH key

namestring 

Name of the SSH key (must be unique per project)

fingerprintstring 

Fingerprint of public key

public_keystring 

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 a SSH Key

Changes the name of a ssh key.

HTTP Request
PUT https://api.hetzner.cloud/v1/ssh_keys/{id}
URI Parameters
ParameterTypeDescription
idstring (required) 

ID of the SSH key

Request
ParameterTypeDescription
namestring (optional) 

New name Name to set

Reply

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

ParameterTypeDescription
idnumber 

ID of the SSH key

namestring 

Name of the SSH key

fingerprintstring 

Fingerprint of public key

public_keystring 

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 a SSH Key

Deletes a SSH key. It cannot be used anymore.

HTTP Request
DELETE https://api.hetzner.cloud/v1/ssh_keys/{id}
URI Parameters
ParameterTypeDescription
idstring (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
ParameterTypeDescription
namestring (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:

ParameterTypeDescription
idnumber 

ID of the server type

namestring 

Unique identifier of the server type

descriptionstring 

Description of the server type

coresnumber 

Number of cpu cores a server of this type will have

memorynumber 

Memory a server of this type will have in GB

disknumber 

Disk size a server of this type will have in GB

pricesarray 

Prices in different Locations

storage_typestring 

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
ParameterTypeDescription
idstring (required) 

ID of server type

Reply

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

ParameterTypeDescription
idnumber 

ID of the server type

namestring 

Unique identifier of the server type

descriptionstring 

Description of the server type

coresnumber 

Number of cpu cores a server of this type will have

memorynumber 

Memory a server of this type will have in GB

disknumber 

Disk size a server of this type will have in GB

pricesarray 

Prices in different Locations

storage_typestring 

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
ParameterTypeDescription
namestring (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:

ParameterTypeDescription
idnumber 

ID of the location

namestring 

Unique identifier of the location

descriptionstring 

Description of the location

countrystring 

ISO 3166-1 alpha-2 code of the country the location resides in

citystring 

City the location is closest to

latitudenumber 

Latitude of the city closest to the location

longitudenumber 

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
ParameterTypeDescription
idstring (required) 

ID of location

Reply

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

ParameterTypeDescription
idnumber 

ID of the location

namestring 

Unique identifier of the location

descriptionstring 

Description of the location

countrystring 

ISO 3166-1 alpha-2 code of the country the location resides in

citystring 

City the location is closest to

latitudenumber 

Latitude of the city closest to the location

longitudenumber 

Longitude of the city closest to the location

Datacenters

Each datacenter in the same location represents its own availability zone. 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
ParameterTypeDescription
namestring (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:

ParameterTypeDescription
idnumber 

ID of the datacenter

namestring 

Unique identifier of the datacenter

descriptionstring 

Description of the datacenter

locationobject 

Location where the datacenter resides in

server_typesobject 

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
ParameterTypeDescription
idstring (required) 

ID of datacenter

Reply

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

ParameterTypeDescription
idnumber 

ID of the datacenter

namestring 

Unique identifier of the datacenter

descriptionstring 

Description of the datacenter

locationobject 

Location where the datacenter resides in

server_typesobject 

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

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
ParameterTypeDescription
sortstring (optional) 

Can be used multiple times.

Choices: id id:asc id:desc name name:asc name:desc created created:asc created:desc

typestring (optional) 

Can be used multiple times.

Choices: system snapshot backup

bound_tostring (optional) 

Can be used multiple times. Server Id linked to the image. Only available for images of type backup

namestring (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:

ParameterTypeDescription
idnumber 

ID of the image

typestring 

Type of the image

Choices: system snapshot backup

statusstring 

Whether the image can be used or if it’s still being created

Choices: available creating

namestring,null 

Unique identifier of the image. This value is only set for system images.

descriptionstring 

Description of the image

image_sizenumber,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_sizenumber 

Size of the disk contained in the image in GB.

createdstring 

Point in time when the image was created (in ISO-8601 format)

created_fromobject,null 

Information about the server the image was created from

bound_tonumber,null 

ID of server the image is bound to. Only set for images of type backup.

os_flavorstring 

Flavor of operating system contained in the image

Choices: ubuntu centos debian fedora unknown

os_versionstring,null 

Operating system version

rapid_deployboolean 

Indicates that rapid deploy of the image is available


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

Get an Image

Returns a specific image object.

HTTP Request
GET https://api.hetzner.cloud/v1/images/{id}
URI Parameters
ParameterTypeDescription
idstring (required) 

ID of the image

Reply

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

ParameterTypeDescription
idnumber 

ID of the image

typestring 

Type of the image

Choices: system snapshot backup

statusstring 

Whether the image can be used or if it’s still being created

Choices: available creating

namestring,null 

Unique identifier of the image. This value is only set for system images.

descriptionstring 

Description of the image

image_sizenumber,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_sizenumber 

Size of the disk contained in the image in GB.

createdstring 

Point in time when the image was created (in ISO-8601 format)

created_fromobject,null 

Information about the server the image was created from

bound_tonumber,null 

ID of server the image is bound to. Only set for images of type backup.

os_flavorstring 

Flavor of operating system contained in the image

Choices: ubuntu centos debian fedora unknown

os_versionstring,null 

Operating system version

rapid_deployboolean 

Indicates that rapid deploy of the image is available


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

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
ParameterTypeDescription
idstring (required) 

ID of the image to be updated

Request
ParameterTypeDescription
descriptionstring (optional) 

New description of Image

typestring (optional) 

Destination image type to convert to

Choices: snapshot

Reply

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

ParameterTypeDescription
idnumber 

ID of the image

typestring 

Type of the image

Choices: snapshot system backup

statusstring 

Whether the image can be used or if it’s still being created

Choices: available creating

namestring,null 

Unique identifier of the image. This value is only set for system images.

descriptionstring 

Description of the image

image_sizenumber,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_sizenumber 

Size of the disk contained in the image in GB.

createdstring 

Point in time when the image was created (in ISO-8601 format)

created_fromobject,null 

Information about the server the image was created from

bound_tonumber,null 

ID of server the image is bound to. Only set for images of type backup.

os_flavorstring 

Flavor of operating system contained in the image

Choices: ubuntu centos debian fedora unknown

os_versionstring,null 

Operating system version

rapid_deployboolean 

Indicates that rapid deploy of the image is available


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
ParameterTypeDescription
idstring (required) 

ID of the Image

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

Get all ISOs

Returns all available iso objects.

HTTP Request
GET https://api.hetzner.cloud/v1/isos{?name}
URI Parameters
ParameterTypeDescription
namestring (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:

ParameterTypeDescription
idnumber 

ID of the ISO

namestring,null 

Unique identifier of the ISO. Only set for public ISOs

descriptionstring 

Description of the ISO

typestring 

Type of the ISO

Choices: public private


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

Get an ISO

Returns a specific iso object.

HTTP Request
GET https://api.hetzner.cloud/v1/isos/{id}
URI Parameters
ParameterTypeDescription
idstring (required) 

ID of the ISO

Reply

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

ParameterTypeDescription
idnumber 

ID of the ISO

namestring,null 

Unique identifier of the ISO. Only set for public ISOs

descriptionstring 

Description of the ISO

typestring 

Type of the ISO

Choices: public private

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:

ParameterTypeDescription
currencystring 

Currency the returned prices are expressed in, coded according to ISO 4217.

vat_ratestring 

The VAT rate used for calculating prices with VAT

imageobject 

The cost of one 1GB Image for the full month.

floating_ipobject 

The cost of one floating IP per month.

trafficobject 

The cost of additional traffic per GB

server_backupobject 

Will increase base server costs by specific percentage.

server_typesarray 

Costs of server types per location and type