API Docs

Hetzner Cloud API

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

Introduction

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

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

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

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

  • The type of integration you would like to develop

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

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

Getting Started

To get started using the API you first need an API token. Sign in into the Hetzner Cloud Console choose a project, go to 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.

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

Authentication

All requests to the Hetzner Cloud API must be authenticated via a API token. Include your secret API token in every request you send to the API with the Authorization HTTP header.

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.

Example: Authorization header

Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj

Errors

Errors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code.

The error response contains the following keys:

Key Meaning
code Short string indicating the type of error (machine-parsable)
message Textual description on what has gone wrong
details An object providing for details on the error (schema depends on code)

Error Codes

Code Description
forbidden Insufficient permissions for this request
invalid_input Error while parsing or processing the input
json_error Invalid JSON input in your request
locked The item you are trying to access is locked (there is already an action running)
not_found Entity not found
rate_limit_exceeded Error when sending too many requests
resource_limit_exceeded Error when exceeding the maximum quantity of a resource for an account
resource_unavailable The requested resource is currently unavailable
service_error Error within a service
uniqueness_error One or more of the objects fields must be unique
protected The action you are trying to start is protected for this resource
maintenance Cannot perform operation due to maintenance

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

resource_limit_exceeded

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

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

Pagination

Responses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:

  • A page parameter specifies the page to fetch. The number of the first page is 1.

  • A per_page parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation.

Responses contain a Link header with pagination information.

Additionally, if the response body is JSON and the root object is an object, that object has a pagination object inside the meta object with pagination information:

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

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.

Sorting

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

Example: Sorting

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

Rate Limiting

All requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a 429 Too Many Requests error. Burst requests are allowed. Responses contain serveral headers which provide information about your current rate limit status.

  • The RateLimit-Limit header contains the total number of requests you can perform per hour.

  • The RateLimit-Remaining header contains the number of requests remaining in the current rate limit time frame.

  • The RateLimit-Reset header contains a UNIX timestamp of the point in time when your rate limit will have recovered and you will have the full number of requests available again.

The default limit is 3600 requests per hour and per project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second.

Changelog

2018-04-05: Add deprecated flag to images

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


2018-03-28: Add resource protection

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


2018-03-20: Filter SSH keys by fingerprint

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


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

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


2018-02-26: Add deprecated flag to ISOs

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


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

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

Actions

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

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
statusenum[string] (optional)

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

Choices: running success error
sortenum[string] (optional)

Can be used multiple times.

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

Reply

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

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "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"
      }
    }
  ]
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "ID of the action"
          },
          "command": {
            "type": "string",
            "description": "Command executed in the action"
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "running",
              "error"
            ],
            "description": "Status of the action"
          },
          "progress": {
            "type": "number",
            "description": "Progress of action in percent"
          },
          "started": {
            "type": "string",
            "description": "Point in time when the action was started (in ISO-8601 format)"
          },
          "finished": {
            "type": [
              "string",
              "null"
            ],
            "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "number",
                  "description": "ID of resource referenced"
                },
                "type": {
                  "type": "string",
                  "description": "Type of resource referenced"
                }
              },
              "required": [
                "id",
                "type"
              ]
            },
            "description": "Resources the action relates to"
          },
          "error": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Fixed machine readable code"
              },
              "message": {
                "type": "string",
                "description": "Humanized error message."
              }
            },
            "required": [
              "code",
              "message"
            ],
            "description": "Error message for the action if error occured, otherwise null."
          }
        },
        "required": [
          "id",
          "command",
          "status",
          "progress",
          "started",
          "finished",
          "resources",
          "error"
        ]
      }
    }
  },
  "required": [
    "actions"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "running",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

Servers

Servers are virtual machines that can be provisioned.

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "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.0000000000",
              "gross": "1.1900000000000000"
            },
            "price_monthly": {
              "net": "1.0000000000",
              "gross": "1.1900000000000000"
            }
          }
        ],
        "storage_type": "local",
        "cpu_type": "shared"
      },
      "datacenter": {
        "id": 1,
        "name": "fsn1-dc8",
        "description": "Falkenstein 1 DC 8",
        "location": {
          "id": 1,
          "name": "fsn1",
          "description": "Falkenstein DC Park 1",
          "country": "DE",
          "city": "Falkenstein",
          "latitude": 50.47612,
          "longitude": 12.370071
        },
        "server_types": {
          "supported": [
            1,
            2,
            3
          ],
          "available": [
            1,
            2,
            3
          ]
        }
      },
      "image": {
        "id": 4711,
        "type": "snapshot",
        "status": "available",
        "name": "ubuntu-16.04",
        "description": "Ubuntu 16.04 Standard 64 bit",
        "image_size": 2.3,
        "disk_size": 10,
        "created": "2016-01-30T23:50+00:00",
        "created_from": {
          "id": 1,
          "name": "Server"
        },
        "bound_to": null,
        "os_flavor": "ubuntu",
        "os_version": "16.04",
        "rapid_deploy": false,
        "protection": {
          "delete": false
        },
        "deprecated": "2018-02-28T00:00:00+00:00"
      },
      "iso": {
        "id": 4711,
        "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
        "description": "FreeBSD 11.0 x64",
        "type": "public",
        "deprecated": "2018-02-28T00:00:00+00:00"
      },
      "rescue_enabled": false,
      "locked": false,
      "backup_window": "22-02",
      "outgoing_traffic": 123456,
      "ingoing_traffic": 123456,
      "included_traffic": 654321,
      "protection": {
        "delete": false,
        "rebuild": false
      }
    }
  ]
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "servers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "ID of server"
          },
          "name": {
            "type": "string",
            "description": "Name of the server (must be unique per project and a valid hostname as per RFC 1123)"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "initializing",
              "starting",
              "stopping",
              "off",
              "deleting",
              "migrating",
              "rebuilding",
              "unknown"
            ],
            "description": "Status of the server"
          },
          "created": {
            "type": "string",
            "description": "Point in time when the server was created (in ISO-8601 format)"
          },
          "public_net": {
            "type": "object",
            "properties": {
              "ipv4": {
                "type": "object",
                "properties": {
                  "ip": {
                    "type": "string",
                    "description": "IP address (v4) of this server."
                  },
                  "blocked": {
                    "type": "boolean",
                    "description": "If the IP is blocked by our anti abuse dept"
                  },
                  "dns_ptr": {
                    "type": "string",
                    "description": "Reverse DNS PTR entry for the IPv4 addresses of this server."
                  }
                },
                "required": [
                  "ip",
                  "blocked",
                  "dns_ptr"
                ],
                "description": "IP address (v4) and its reverse dns entry of this server."
              },
              "ipv6": {
                "type": "object",
                "properties": {
                  "ip": {
                    "type": "string",
                    "description": "IP address (v4) of this server."
                  },
                  "blocked": {
                    "type": "boolean",
                    "description": "If the IP is blocked by our anti abuse dept"
                  },
                  "dns_ptr": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "properties": {
                        "ip": {
                          "type": "string",
                          "description": "Single IPv6 address of this server for which the reverse DNS entry has been set up."
                        },
                        "dns_ptr": {
                          "type": "string",
                          "description": "DNS pointer for the specific IP address."
                        }
                      },
                      "required": [
                        "ip",
                        "dns_ptr"
                      ]
                    },
                    "description": "Reverse DNS PTR entries for the IPv6 addresses of this server, `null` by default."
                  }
                },
                "required": [
                  "ip",
                  "blocked",
                  "dns_ptr"
                ],
                "description": "IPv6 network assigned to this server and its reverse dns entry."
              },
              "floating_ips": {
                "type": "array",
                "items": {
                  "type": "number"
                },
                "description": "IDs of floating IPs assigned to this server."
              }
            },
            "required": [
              "ipv4",
              "ipv6",
              "floating_ips"
            ],
            "description": "Public network information. The servers ipv4 address can be found in `public_net->ipv4->ip`"
          },
          "server_type": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of the server type"
              },
              "name": {
                "type": "string",
                "description": "Unique identifier of the server type"
              },
              "description": {
                "type": "string",
                "description": "Description of the server type"
              },
              "cores": {
                "type": "number",
                "description": "Number of cpu cores a server of this type will have"
              },
              "memory": {
                "type": "number",
                "description": "Memory a server of this type will have in GB"
              },
              "disk": {
                "type": "number",
                "description": "Disk size a server of this type will have in GB"
              },
              "prices": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string",
                      "description": "Name of the location the price is for"
                    },
                    "price_hourly": {
                      "type": "object",
                      "properties": {
                        "net": {
                          "type": "string",
                          "description": "Price without VAT"
                        },
                        "gross": {
                          "type": "string",
                          "description": "Price with VAT added"
                        }
                      },
                      "required": [
                        "net",
                        "gross"
                      ],
                      "description": "Hourly costs for a server type in this location"
                    },
                    "price_monthly": {
                      "type": "object",
                      "properties": {
                        "net": {
                          "type": "string",
                          "description": "Price without VAT"
                        },
                        "gross": {
                          "type": "string",
                          "description": "Price with VAT added"
                        }
                      },
                      "required": [
                        "net",
                        "gross"
                      ],
                      "description": "Monthly costs for a server type in this location"
                    }
                  },
                  "required": [
                    "location",
                    "price_hourly",
                    "price_monthly"
                  ]
                },
                "description": "Prices in different Locations"
              },
              "storage_type": {
                "type": "string",
                "enum": [
                  "local",
                  "network"
                ],
                "description": "Type of server boot drive. Local has higher speed. Network has better availability."
              },
              "cpu_type": {
                "type": "string",
                "enum": [
                  "shared",
                  "dedicated"
                ],
                "description": "Type of cpu."
              }
            },
            "required": [
              "id",
              "name",
              "description",
              "cores",
              "memory",
              "disk",
              "prices",
              "storage_type",
              "cpu_type"
            ],
            "description": "Type of server - determines how much ram, disk and cpu a server has"
          },
          "datacenter": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of the datacenter"
              },
              "name": {
                "type": "string",
                "description": "Unique identifier of the datacenter"
              },
              "description": {
                "type": "string",
                "description": "Description of the datacenter"
              },
              "location": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number",
                    "description": "ID of the location"
                  },
                  "name": {
                    "type": "string",
                    "description": "Unique identifier of the location"
                  },
                  "description": {
                    "type": "string",
                    "description": "Description of the location"
                  },
                  "country": {
                    "type": "string",
                    "description": "ISO 3166-1 alpha-2 code of the country the location resides in"
                  },
                  "city": {
                    "type": "string",
                    "description": "City the location is closest to"
                  },
                  "latitude": {
                    "type": "number",
                    "description": "Latitude of the city closest to the location"
                  },
                  "longitude": {
                    "type": "number",
                    "description": "Longitude of the city closest to the location"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "description",
                  "country",
                  "city",
                  "latitude",
                  "longitude"
                ],
                "description": "Location where the datacenter resides in"
              },
              "server_types": {
                "type": "object",
                "properties": {
                  "supported": {
                    "type": "array",
                    "items": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "IDs of server types that are supported in the datacenter"
                  },
                  "available": {
                    "type": "array",
                    "items": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "number"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "IDs of server types that are supported and for which the datacenter has enough resources left"
                  }
                },
                "required": [
                  "supported",
                  "available"
                ],
                "description": "The server types the datacenter can handle"
              }
            },
            "required": [
              "id",
              "name",
              "description",
              "location",
              "server_types"
            ],
            "description": "Datacenter this server is located at"
          },
          "image": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of the image"
              },
              "type": {
                "type": "string",
                "enum": [
                  "system",
                  "snapshot",
                  "backup"
                ],
                "description": "Type of the image"
              },
              "status": {
                "type": "string",
                "enum": [
                  "available",
                  "creating"
                ],
                "description": "Whether the image can be used or if it's still being created"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Unique identifier of the image. This value is only set for system images."
              },
              "description": {
                "type": "string",
                "description": "Description of the image"
              },
              "image_size": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image."
              },
              "disk_size": {
                "type": "number",
                "description": "Size of the disk contained in the image in GB."
              },
              "created": {
                "type": "string",
                "description": "Point in time when the image was created (in ISO-8601 format)"
              },
              "created_from": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "id": {
                    "type": "number",
                    "description": "ID of the server the image was created from"
                  },
                  "name": {
                    "type": "string",
                    "description": "Server name at the time the image was created"
                  }
                },
                "required": [
                  "id",
                  "name"
                ],
                "description": "Information about the server the image was created from"
              },
              "bound_to": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "ID of server the image is bound to. Only set for images of type `backup`."
              },
              "os_flavor": {
                "type": "string",
                "enum": [
                  "ubuntu",
                  "centos",
                  "debian",
                  "fedora",
                  "unknown"
                ],
                "description": "Flavor of operating system contained in the image"
              },
              "os_version": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Operating system version"
              },
              "rapid_deploy": {
                "type": "boolean",
                "description": "Indicates that rapid deploy of the image is available"
              },
              "protection": {
                "type": "object",
                "properties": {
                  "delete": {
                    "type": "boolean",
                    "description": "If true, prevents the snapshot from being deleted"
                  }
                },
                "required": [
                  "delete"
                ],
                "description": "Protection configuration for the image"
              },
              "deprecated": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Point in time when the image is considered to be deprecated (in ISO-8601 format)"
              }
            },
            "required": [
              "id",
              "type",
              "status",
              "name",
              "description",
              "image_size",
              "disk_size",
              "created",
              "created_from",
              "bound_to",
              "os_flavor",
              "os_version",
              "protection",
              "deprecated"
            ],
            "description": "Image this server was created from."
          },
          "iso": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of the ISO"
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Unique identifier of the ISO. Only set for public ISOs"
              },
              "description": {
                "type": "string",
                "description": "Description of the ISO"
              },
              "type": {
                "type": "string",
                "enum": [
                  "public",
                  "private"
                ],
                "description": "Type of the ISO"
              },
              "deprecated": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 8601 timestamp of deprecation, null if ISO is still available. After the deprecation time it will no longer be possible to attach the ISO to servers."
              }
            },
            "required": [
              "id",
              "name",
              "description",
              "type",
              "deprecated"
            ],
            "description": "ISO image that is attached to this server. Null if no ISO is attached."
          },
          "rescue_enabled": {
            "type": "boolean",
            "description": "True if rescue mode is enabled: Server will then boot into rescue system on next reboot."
          },
          "locked": {
            "type": "boolean",
            "description": "True if server has been locked and is not available to user."
          },
          "backup_window": {
            "type": [
              "string",
              "null"
            ],
            "description": "Time window (UTC) in which the backup will run, or null if the backups are not enabled"
          },
          "outgoing_traffic": {
            "type": [
              "number",
              "null"
            ],
            "description": "Outbound Traffic for the current billing period in bytes"
          },
          "ingoing_traffic": {
            "type": [
              "number",
              "null"
            ],
            "description": "Inbound Traffic for the current billing period in bytes"
          },
          "included_traffic": {
            "type": "number",
            "description": "Free Traffic for the current billing period in bytes"
          },
          "protection": {
            "type": "object",
            "properties": {
              "delete": {
                "type": "boolean",
                "description": "If true, prevents the server from being deleted"
              },
              "rebuild": {
                "type": "boolean",
                "description": "If true, prevents the server from being rebuilt"
              }
            },
            "required": [
              "delete",
              "rebuild"
            ],
            "description": "Protection configuration for the server"
          }
        },
        "required": [
          "id",
          "name",
          "status",
          "created",
          "public_net",
          "server_type",
          "datacenter",
          "image",
          "iso",
          "rescue_enabled",
          "locked",
          "backup_window",
          "outgoing_traffic",
          "ingoing_traffic",
          "included_traffic",
          "protection"
        ]
      }
    }
  },
  "required": [
    "servers"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "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.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ],
      "storage_type": "local",
      "cpu_type": "shared"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-16.04",
      "description": "Ubuntu 16.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "16.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "server": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of server"
        },
        "name": {
          "type": "string",
          "description": "Name of the server (must be unique per project and a valid hostname as per RFC 1123)"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "initializing",
            "starting",
            "stopping",
            "off",
            "deleting",
            "migrating",
            "rebuilding",
            "unknown"
          ],
          "description": "Status of the server"
        },
        "created": {
          "type": "string",
          "description": "Point in time when the server was created (in ISO-8601 format)"
        },
        "public_net": {
          "type": "object",
          "properties": {
            "ipv4": {
              "type": "object",
              "properties": {
                "ip": {
                  "type": "string",
                  "description": "IP address (v4) of this server."
                },
                "blocked": {
                  "type": "boolean",
                  "description": "If the IP is blocked by our anti abuse dept"
                },
                "dns_ptr": {
                  "type": "string",
                  "description": "Reverse DNS PTR entry for the IPv4 addresses of this server."
                }
              },
              "required": [
                "ip",
                "blocked",
                "dns_ptr"
              ],
              "description": "IP address (v4) and its reverse dns entry of this server."
            },
            "ipv6": {
              "type": "object",
              "properties": {
                "ip": {
                  "type": "string",
                  "description": "IP address (v4) of this server."
                },
                "blocked": {
                  "type": "boolean",
                  "description": "If the IP is blocked by our anti abuse dept"
                },
                "dns_ptr": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "properties": {
                      "ip": {
                        "type": "string",
                        "description": "Single IPv6 address of this server for which the reverse DNS entry has been set up."
                      },
                      "dns_ptr": {
                        "type": "string",
                        "description": "DNS pointer for the specific IP address."
                      }
                    },
                    "required": [
                      "ip",
                      "dns_ptr"
                    ]
                  },
                  "description": "Reverse DNS PTR entries for the IPv6 addresses of this server, `null` by default."
                }
              },
              "required": [
                "ip",
                "blocked",
                "dns_ptr"
              ],
              "description": "IPv6 network assigned to this server and its reverse dns entry."
            },
            "floating_ips": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "IDs of floating IPs assigned to this server."
            }
          },
          "required": [
            "ipv4",
            "ipv6",
            "floating_ips"
          ],
          "description": "Public network information. The servers ipv4 address can be found in `public_net->ipv4->ip`"
        },
        "server_type": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the server type"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the server type"
            },
            "description": {
              "type": "string",
              "description": "Description of the server type"
            },
            "cores": {
              "type": "number",
              "description": "Number of cpu cores a server of this type will have"
            },
            "memory": {
              "type": "number",
              "description": "Memory a server of this type will have in GB"
            },
            "disk": {
              "type": "number",
              "description": "Disk size a server of this type will have in GB"
            },
            "prices": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "Name of the location the price is for"
                  },
                  "price_hourly": {
                    "type": "object",
                    "properties": {
                      "net": {
                        "type": "string",
                        "description": "Price without VAT"
                      },
                      "gross": {
                        "type": "string",
                        "description": "Price with VAT added"
                      }
                    },
                    "required": [
                      "net",
                      "gross"
                    ],
                    "description": "Hourly costs for a server type in this location"
                  },
                  "price_monthly": {
                    "type": "object",
                    "properties": {
                      "net": {
                        "type": "string",
                        "description": "Price without VAT"
                      },
                      "gross": {
                        "type": "string",
                        "description": "Price with VAT added"
                      }
                    },
                    "required": [
                      "net",
                      "gross"
                    ],
                    "description": "Monthly costs for a server type in this location"
                  }
                },
                "required": [
                  "location",
                  "price_hourly",
                  "price_monthly"
                ]
              },
              "description": "Prices in different Locations"
            },
            "storage_type": {
              "type": "string",
              "enum": [
                "local",
                "network"
              ],
              "description": "Type of server boot drive. Local has higher speed. Network has better availability."
            },
            "cpu_type": {
              "type": "string",
              "enum": [
                "shared",
                "dedicated"
              ],
              "description": "Type of cpu."
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "cores",
            "memory",
            "disk",
            "prices",
            "storage_type",
            "cpu_type"
          ],
          "description": "Type of server - determines how much ram, disk and cpu a server has"
        },
        "datacenter": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the datacenter"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the datacenter"
            },
            "description": {
              "type": "string",
              "description": "Description of the datacenter"
            },
            "location": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "number",
                  "description": "ID of the location"
                },
                "name": {
                  "type": "string",
                  "description": "Unique identifier of the location"
                },
                "description": {
                  "type": "string",
                  "description": "Description of the location"
                },
                "country": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 code of the country the location resides in"
                },
                "city": {
                  "type": "string",
                  "description": "City the location is closest to"
                },
                "latitude": {
                  "type": "number",
                  "description": "Latitude of the city closest to the location"
                },
                "longitude": {
                  "type": "number",
                  "description": "Longitude of the city closest to the location"
                }
              },
              "required": [
                "id",
                "name",
                "description",
                "country",
                "city",
                "latitude",
                "longitude"
              ],
              "description": "Location where the datacenter resides in"
            },
            "server_types": {
              "type": "object",
              "properties": {
                "supported": {
                  "type": "array",
                  "items": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ],
                  "description": "IDs of server types that are supported in the datacenter"
                },
                "available": {
                  "type": "array",
                  "items": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ],
                  "description": "IDs of server types that are supported and for which the datacenter has enough resources left"
                }
              },
              "required": [
                "supported",
                "available"
              ],
              "description": "The server types the datacenter can handle"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "location",
            "server_types"
          ],
          "description": "Datacenter this server is located at"
        },
        "image": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the image"
            },
            "type": {
              "type": "string",
              "enum": [
                "system",
                "snapshot",
                "backup"
              ],
              "description": "Type of the image"
            },
            "status": {
              "type": "string",
              "enum": [
                "available",
                "creating"
              ],
              "description": "Whether the image can be used or if it's still being created"
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Unique identifier of the image. This value is only set for system images."
            },
            "description": {
              "type": "string",
              "description": "Description of the image"
            },
            "image_size": {
              "type": [
                "number",
                "null"
              ],
              "description": "Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image."
            },
            "disk_size": {
              "type": "number",
              "description": "Size of the disk contained in the image in GB."
            },
            "created": {
              "type": "string",
              "description": "Point in time when the image was created (in ISO-8601 format)"
            },
            "created_from": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "id": {
                  "type": "number",
                  "description": "ID of the server the image was created from"
                },
                "name": {
                  "type": "string",
                  "description": "Server name at the time the image was created"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "description": "Information about the server the image was created from"
            },
            "bound_to": {
              "type": [
                "number",
                "null"
              ],
              "description": "ID of server the image is bound to. Only set for images of type `backup`."
            },
            "os_flavor": {
              "type": "string",
              "enum": [
                "ubuntu",
                "centos",
                "debian",
                "fedora",
                "unknown"
              ],
              "description": "Flavor of operating system contained in the image"
            },
            "os_version": {
              "type": [
                "string",
                "null"
              ],
              "description": "Operating system version"
            },
            "rapid_deploy": {
              "type": "boolean",
              "description": "Indicates that rapid deploy of the image is available"
            },
            "protection": {
              "type": "object",
              "properties": {
                "delete": {
                  "type": "boolean",
                  "description": "If true, prevents the snapshot from being deleted"
                }
              },
              "required": [
                "delete"
              ],
              "description": "Protection configuration for the image"
            },
            "deprecated": {
              "type": [
                "string",
                "null"
              ],
              "description": "Point in time when the image is considered to be deprecated (in ISO-8601 format)"
            }
          },
          "required": [
            "id",
            "type",
            "status",
            "name",
            "description",
            "image_size",
            "disk_size",
            "created",
            "created_from",
            "bound_to",
            "os_flavor",
            "os_version",
            "protection",
            "deprecated"
          ],
          "description": "Image this server was created from."
        },
        "iso": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the ISO"
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Unique identifier of the ISO. Only set for public ISOs"
            },
            "description": {
              "type": "string",
              "description": "Description of the ISO"
            },
            "type": {
              "type": "string",
              "enum": [
                "public",
                "private"
              ],
              "description": "Type of the ISO"
            },
            "deprecated": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 8601 timestamp of deprecation, null if ISO is still available. After the deprecation time it will no longer be possible to attach the ISO to servers."
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "type",
            "deprecated"
          ],
          "description": "ISO image that is attached to this server. Null if no ISO is attached."
        },
        "rescue_enabled": {
          "type": "boolean",
          "description": "True if rescue mode is enabled: Server will then boot into rescue system on next reboot."
        },
        "locked": {
          "type": "boolean",
          "description": "True if server has been locked and is not available to user."
        },
        "backup_window": {
          "type": [
            "string",
            "null"
          ],
          "description": "Time window (UTC) in which the backup will run, or null if the backups are not enabled"
        },
        "outgoing_traffic": {
          "type": [
            "number",
            "null"
          ],
          "description": "Outbound Traffic for the current billing period in bytes"
        },
        "ingoing_traffic": {
          "type": [
            "number",
            "null"
          ],
          "description": "Inbound Traffic for the current billing period in bytes"
        },
        "included_traffic": {
          "type": "number",
          "description": "Free Traffic for the current billing period in bytes"
        },
        "protection": {
          "type": "object",
          "properties": {
            "delete": {
              "type": "boolean",
              "description": "If true, prevents the server from being deleted"
            },
            "rebuild": {
              "type": "boolean",
              "description": "If true, prevents the server from being rebuilt"
            }
          },
          "required": [
            "delete",
            "rebuild"
          ],
          "description": "Protection configuration for the server"
        }
      },
      "required": [
        "id",
        "name",
        "status",
        "created",
        "public_net",
        "server_type",
        "datacenter",
        "image",
        "iso",
        "rescue_enabled",
        "locked",
        "backup_window",
        "outgoing_traffic",
        "ingoing_traffic",
        "included_traffic",
        "protection"
      ]
    }
  },
  "required": [
    "server"
  ]
}

Create a Server

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

HTTP Request

POST https://api.hetzner.cloud/v1/servers

Request

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

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

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

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

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

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

Reply

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

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

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

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

Call specific error codes

Code Description
placement_error An error during placement of the server occured

Example curl

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

Request headers

Content-Type: application/json

Request

{
  "name": "my-server",
  "server_type": "cx11",
  "location": "nbg1",
  "start_after_create": true,
  "image": "ubuntu-16.04",
  "ssh_keys": [
    "my-ssh-key"
  ],
  "user_data": "#cloud-config\nruncmd:\n- [touch, /root/cloud-init-worked]\n"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the server to create (must be unique per project and a valid hostname as per RFC 1123)"
    },
    "server_type": {
      "type": "string",
      "description": "ID or name of the server type this server should be created with"
    },
    "start_after_create": {
      "type": "boolean",
      "description": "Start Server right after creation. Defaults to true."
    },
    "image": {
      "type": "string",
      "description": "ID or name of the image the server is created from"
    },
    "ssh_keys": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "SSH key IDs or names which should be injected into the server at creation time"
    },
    "user_data": {
      "type": "string",
      "description": "Cloud-Init user data to use during server creation. This field is limited to 32KiB."
    }
  },
  "required": [
    "name",
    "server_type",
    "image"
  ],
  "oneOf": [
    {
      "properties": {
        "location": {
          "type": "string",
          "description": "ID or name of location to create server in."
        }
      }
    },
    {
      "properties": {
        "datacenter": {
          "type": "string",
          "description": "ID or name of datacenter to create server in."
        }
      }
    }
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ],
      "storage_type": "local",
      "cpu_type": "shared"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-16.04",
      "description": "Ubuntu 16.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "16.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    }
  },
  "action": {
    "id": 1337,
    "command": "create_server",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  },
  "root_password": "YItygq1v3GYjjMomLaKc"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "server": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of server"
        },
        "name": {
          "type": "string",
          "description": "Name of the server (must be unique per project and a valid hostname as per RFC 1123)"
        },
        "status": {
          "type": "string",
          "enum": [
            "initializing",
            "starting",
            "running",
            "stopping",
            "off",
            "deleting",
            "migrating",
            "rebuilding"
          ],
          "description": "Status of the server"
        },
        "created": {
          "type": "string",
          "description": "Point in time when the server was created (in ISO-8601 format)"
        },
        "public_net": {
          "type": "object",
          "properties": {
            "ipv4": {
              "type": "object",
              "properties": {
                "ip": {
                  "type": "string",
                  "description": "IP address (v4) of this server."
                },
                "blocked": {
                  "type": "boolean",
                  "description": "If the IP is blocked by our anti abuse dept"
                },
                "dns_ptr": {
                  "type": "string",
                  "description": "Reverse DNS PTR entry for the IPv4 addresses of this server."
                }
              },
              "required": [
                "ip",
                "blocked",
                "dns_ptr"
              ],
              "description": "IP address (v4) and its reverse dns entry of this server."
            },
            "ipv6": {
              "type": "object",
              "properties": {
                "ip": {
                  "type": "string",
                  "description": "IP address (v4) of this server."
                },
                "blocked": {
                  "type": "boolean",
                  "description": "If the IP is blocked by our anti abuse dept"
                },
                "dns_ptr": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "properties": {
                      "ip": {
                        "type": "string",
                        "description": "Single IPv6 address of this server for which the reverse DNS entry has been set up."
                      },
                      "dns_ptr": {
                        "type": "string",
                        "description": "DNS pointer for the specific IP address."
                      }
                    },
                    "required": [
                      "ip",
                      "dns_ptr"
                    ]
                  },
                  "description": "Reverse DNS PTR entries for the IPv6 addresses of this server, `null` by default."
                }
              },
              "required": [
                "ip",
                "blocked",
                "dns_ptr"
              ],
              "description": "IPv6 network assigned to this server and its reverse dns entry."
            },
            "floating_ips": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "IDs of floating IPs assigned to this server."
            }
          },
          "required": [
            "ipv4",
            "ipv6",
            "floating_ips"
          ],
          "description": "Public network information. The servers ipv4 address can be found in `public_net->ipv4->ip`"
        },
        "server_type": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the server type"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the server type"
            },
            "description": {
              "type": "string",
              "description": "Description of the server type"
            },
            "cores": {
              "type": "number",
              "description": "Number of cpu cores a server of this type will have"
            },
            "memory": {
              "type": "number",
              "description": "Memory a server of this type will have in GB"
            },
            "disk": {
              "type": "number",
              "description": "Disk size a server of this type will have in GB"
            },
            "prices": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "Name of the location the price is for"
                  },
                  "price_hourly": {
                    "type": "object",
                    "properties": {
                      "net": {
                        "type": "string",
                        "description": "Price without VAT"
                      },
                      "gross": {
                        "type": "string",
                        "description": "Price with VAT added"
                      }
                    },
                    "required": [
                      "net",
                      "gross"
                    ],
                    "description": "Hourly costs for a server type in this location"
                  },
                  "price_monthly": {
                    "type": "object",
                    "properties": {
                      "net": {
                        "type": "string",
                        "description": "Price without VAT"
                      },
                      "gross": {
                        "type": "string",
                        "description": "Price with VAT added"
                      }
                    },
                    "required": [
                      "net",
                      "gross"
                    ],
                    "description": "Monthly costs for a server type in this location"
                  }
                },
                "required": [
                  "location",
                  "price_hourly",
                  "price_monthly"
                ]
              },
              "description": "Prices in different Locations"
            },
            "storage_type": {
              "type": "string",
              "enum": [
                "local",
                "network"
              ],
              "description": "Type of server boot drive. Local has higher speed. Network has better availability."
            },
            "cpu_type": {
              "type": "string",
              "enum": [
                "shared",
                "dedicated"
              ],
              "description": "Type of cpu."
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "cores",
            "memory",
            "disk",
            "prices",
            "storage_type",
            "cpu_type"
          ],
          "description": "Type of server - determines how much ram, disk and cpu a server has"
        },
        "datacenter": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the datacenter"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the datacenter"
            },
            "description": {
              "type": "string",
              "description": "Description of the datacenter"
            },
            "location": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "number",
                  "description": "ID of the location"
                },
                "name": {
                  "type": "string",
                  "description": "Unique identifier of the location"
                },
                "description": {
                  "type": "string",
                  "description": "Description of the location"
                },
                "country": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 code of the country the location resides in"
                },
                "city": {
                  "type": "string",
                  "description": "City the location is closest to"
                },
                "latitude": {
                  "type": "number",
                  "description": "Latitude of the city closest to the location"
                },
                "longitude": {
                  "type": "number",
                  "description": "Longitude of the city closest to the location"
                }
              },
              "required": [
                "id",
                "name",
                "description",
                "country",
                "city",
                "latitude",
                "longitude"
              ],
              "description": "Location where the datacenter resides in"
            },
            "server_types": {
              "type": "object",
              "properties": {
                "supported": {
                  "type": "array",
                  "items": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ],
                  "description": "IDs of server types that are supported in the datacenter"
                },
                "available": {
                  "type": "array",
                  "items": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ],
                  "description": "IDs of server types that are supported and for which the datacenter has enough resources left"
                }
              },
              "required": [
                "supported",
                "available"
              ],
              "description": "The server types the datacenter can handle"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "location",
            "server_types"
          ],
          "description": "Datacenter this server is located at"
        },
        "image": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the image"
            },
            "type": {
              "type": "string",
              "enum": [
                "system",
                "snapshot",
                "backup"
              ],
              "description": "Type of the image"
            },
            "status": {
              "type": "string",
              "enum": [
                "available",
                "creating"
              ],
              "description": "Whether the image can be used or if it's still being created"
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Unique identifier of the image. This value is only set for system images."
            },
            "description": {
              "type": "string",
              "description": "Description of the image"
            },
            "image_size": {
              "type": [
                "number",
                "null"
              ],
              "description": "Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image."
            },
            "disk_size": {
              "type": "number",
              "description": "Size of the disk contained in the image in GB."
            },
            "created": {
              "type": "string",
              "description": "Point in time when the image was created (in ISO-8601 format)"
            },
            "created_from": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "id": {
                  "type": "number",
                  "description": "ID of the server the image was created from"
                },
                "name": {
                  "type": "string",
                  "description": "Server name at the time the image was created"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "description": "Information about the server the image was created from"
            },
            "bound_to": {
              "type": [
                "number",
                "null"
              ],
              "description": "ID of server the image is bound to. Only set for images of type `backup`."
            },
            "os_flavor": {
              "type": "string",
              "enum": [
                "ubuntu",
                "centos",
                "debian",
                "fedora",
                "unknown"
              ],
              "description": "Flavor of operating system contained in the image"
            },
            "os_version": {
              "type": [
                "string",
                "null"
              ],
              "description": "Operating system version"
            },
            "rapid_deploy": {
              "type": "boolean",
              "description": "Indicates that rapid deploy of the image is available"
            },
            "protection": {
              "type": "object",
              "properties": {
                "delete": {
                  "type": "boolean",
                  "description": "If true, prevents the snapshot from being deleted"
                }
              },
              "required": [
                "delete"
              ],
              "description": "Protection configuration for the image"
            },
            "deprecated": {
              "type": [
                "string",
                "null"
              ],
              "description": "Point in time when the image is considered to be deprecated (in ISO-8601 format)"
            }
          },
          "required": [
            "id",
            "type",
            "status",
            "name",
            "description",
            "image_size",
            "disk_size",
            "created",
            "created_from",
            "bound_to",
            "os_flavor",
            "os_version",
            "protection",
            "deprecated"
          ],
          "description": "Image this server was created from."
        },
        "iso": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the ISO"
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Unique identifier of the ISO. Only set for public ISOs"
            },
            "description": {
              "type": "string",
              "description": "Description of the ISO"
            },
            "type": {
              "type": "string",
              "enum": [
                "public",
                "private"
              ],
              "description": "Type of the ISO"
            },
            "deprecated": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 8601 timestamp of deprecation, null if ISO is still available. After the deprecation time it will no longer be possible to attach the ISO to servers."
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "type",
            "deprecated"
          ],
          "description": "ISO image that is attached to this server. Null if no ISO is attached."
        },
        "rescue_enabled": {
          "type": "boolean",
          "description": "True if rescue mode is enabled: Server will then boot into rescue system on next reboot."
        },
        "locked": {
          "type": "boolean",
          "description": "True if server has been locked and is not available to user."
        },
        "backup_window": {
          "type": [
            "string",
            "null"
          ],
          "description": "Time window (UTC) in which the backup will run, or null if the backups are not enabled"
        },
        "outgoing_traffic": {
          "type": [
            "number",
            "null"
          ],
          "description": "Outbound Traffic for the current billing period in bytes"
        },
        "ingoing_traffic": {
          "type": [
            "number",
            "null"
          ],
          "description": "Inbound Traffic for the current billing period in bytes"
        },
        "included_traffic": {
          "type": "number",
          "description": "Free Traffic for the current billing period in bytes"
        },
        "protection": {
          "type": "object",
          "properties": {
            "delete": {
              "type": "boolean",
              "description": "If true, prevents the server from being deleted"
            },
            "rebuild": {
              "type": "boolean",
              "description": "If true, prevents the server from being rebuilt"
            }
          },
          "required": [
            "delete",
            "rebuild"
          ],
          "description": "Protection configuration for the server"
        }
      },
      "required": [
        "id",
        "name",
        "status",
        "created",
        "public_net",
        "server_type",
        "datacenter",
        "image",
        "iso",
        "rescue_enabled",
        "locked",
        "backup_window",
        "outgoing_traffic",
        "ingoing_traffic",
        "included_traffic",
        "protection"
      ]
    },
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    },
    "root_password": {
      "type": [
        "string",
        "null"
      ],
      "description": "Root password when no SSH keys have been specified"
    }
  },
  "required": [
    "server",
    "action",
    "root_password"
  ]
}

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

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

Reply

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

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

Example curl

curl -X 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

{
  "name": "new-name"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "New name to set"
    }
  }
}

Response headers

Content-Type: application/json
Status: 200

Response

{
  "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.0000000000",
            "gross": "1.1900000000000000"
          },
          "price_monthly": {
            "net": "1.0000000000",
            "gross": "1.1900000000000000"
          }
        }
      ],
      "storage_type": "local",
      "cpu_type": "shared"
    },
    "datacenter": {
      "id": 1,
      "name": "fsn1-dc8",
      "description": "Falkenstein 1 DC 8",
      "location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071
      },
      "server_types": {
        "supported": [
          1,
          2,
          3
        ],
        "available": [
          1,
          2,
          3
        ]
      }
    },
    "image": {
      "id": 4711,
      "type": "snapshot",
      "status": "available",
      "name": "ubuntu-16.04",
      "description": "Ubuntu 16.04 Standard 64 bit",
      "image_size": 2.3,
      "disk_size": 10,
      "created": "2016-01-30T23:50+00:00",
      "created_from": {
        "id": 1,
        "name": "Server"
      },
      "bound_to": null,
      "os_flavor": "ubuntu",
      "os_version": "16.04",
      "rapid_deploy": false,
      "protection": {
        "delete": false
      },
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "iso": {
      "id": 4711,
      "name": "FreeBSD-11.0-RELEASE-amd64-dvd1",
      "description": "FreeBSD 11.0 x64",
      "type": "public",
      "deprecated": "2018-02-28T00:00:00+00:00"
    },
    "rescue_enabled": false,
    "locked": false,
    "backup_window": "22-02",
    "outgoing_traffic": 123456,
    "ingoing_traffic": 123456,
    "included_traffic": 654321,
    "protection": {
      "delete": false,
      "rebuild": false
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "server": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of server"
        },
        "name": {
          "type": "string",
          "description": "Server name"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "initializing",
            "starting",
            "stopping",
            "off",
            "deleting",
            "migrating",
            "rebuilding",
            "unknown"
          ],
          "description": "Status of the server"
        },
        "created": {
          "type": "string",
          "description": "Point in time when the server was created (in ISO-8601 format)"
        },
        "public_net": {
          "type": "object",
          "properties": {
            "ipv4": {
              "type": "object",
              "properties": {
                "ip": {
                  "type": "string",
                  "description": "IP address (v4) of this server."
                },
                "blocked": {
                  "type": "boolean",
                  "description": "If the IP is blocked by our anti abuse dept"
                },
                "dns_ptr": {
                  "type": "string",
                  "description": "Reverse DNS PTR entry for the IPv4 addresses of this server."
                }
              },
              "required": [
                "ip",
                "blocked",
                "dns_ptr"
              ],
              "description": "IP address (v4) and its reverse dns entry of this server."
            },
            "ipv6": {
              "type": "object",
              "properties": {
                "ip": {
                  "type": "string",
                  "description": "IP address (v4) of this server."
                },
                "blocked": {
                  "type": "boolean",
                  "description": "If the IP is blocked by our anti abuse dept"
                },
                "dns_ptr": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "properties": {
                      "ip": {
                        "type": "string",
                        "description": "Single IPv6 address of this server for which the reverse DNS entry has been set up."
                      },
                      "dns_ptr": {
                        "type": "string",
                        "description": "DNS pointer for the specific IP address."
                      }
                    },
                    "required": [
                      "ip",
                      "dns_ptr"
                    ]
                  },
                  "description": "Reverse DNS PTR entries for the IPv6 addresses of this server, `null` by default."
                }
              },
              "required": [
                "ip",
                "blocked",
                "dns_ptr"
              ],
              "description": "IPv6 network assigned to this server and its reverse dns entry."
            },
            "floating_ips": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "description": "IDs of floating IPs assigned to this server."
            }
          },
          "required": [
            "ipv4",
            "ipv6",
            "floating_ips"
          ],
          "description": "Public network information. The servers ipv4 address can be found in `public_net->ipv4->ip`"
        },
        "server_type": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the server type"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the server type"
            },
            "description": {
              "type": "string",
              "description": "Description of the server type"
            },
            "cores": {
              "type": "number",
              "description": "Number of cpu cores a server of this type will have"
            },
            "memory": {
              "type": "number",
              "description": "Memory a server of this type will have in GB"
            },
            "disk": {
              "type": "number",
              "description": "Disk size a server of this type will have in GB"
            },
            "prices": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "Name of the location the price is for"
                  },
                  "price_hourly": {
                    "type": "object",
                    "properties": {
                      "net": {
                        "type": "string",
                        "description": "Price without VAT"
                      },
                      "gross": {
                        "type": "string",
                        "description": "Price with VAT added"
                      }
                    },
                    "required": [
                      "net",
                      "gross"
                    ],
                    "description": "Hourly costs for a server type in this location"
                  },
                  "price_monthly": {
                    "type": "object",
                    "properties": {
                      "net": {
                        "type": "string",
                        "description": "Price without VAT"
                      },
                      "gross": {
                        "type": "string",
                        "description": "Price with VAT added"
                      }
                    },
                    "required": [
                      "net",
                      "gross"
                    ],
                    "description": "Monthly costs for a server type in this location"
                  }
                },
                "required": [
                  "location",
                  "price_hourly",
                  "price_monthly"
                ]
              },
              "description": "Prices in different Locations"
            },
            "storage_type": {
              "type": "string",
              "enum": [
                "local",
                "network"
              ],
              "description": "Type of server boot drive. Local has higher speed. Network has better availability."
            },
            "cpu_type": {
              "type": "string",
              "enum": [
                "shared",
                "dedicated"
              ],
              "description": "Type of cpu."
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "cores",
            "memory",
            "disk",
            "prices",
            "storage_type",
            "cpu_type"
          ],
          "description": "Type of server - determines how much ram, disk and cpu a server has"
        },
        "datacenter": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the datacenter"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the datacenter"
            },
            "description": {
              "type": "string",
              "description": "Description of the datacenter"
            },
            "location": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "number",
                  "description": "ID of the location"
                },
                "name": {
                  "type": "string",
                  "description": "Unique identifier of the location"
                },
                "description": {
                  "type": "string",
                  "description": "Description of the location"
                },
                "country": {
                  "type": "string",
                  "description": "ISO 3166-1 alpha-2 code of the country the location resides in"
                },
                "city": {
                  "type": "string",
                  "description": "City the location is closest to"
                },
                "latitude": {
                  "type": "number",
                  "description": "Latitude of the city closest to the location"
                },
                "longitude": {
                  "type": "number",
                  "description": "Longitude of the city closest to the location"
                }
              },
              "required": [
                "id",
                "name",
                "description",
                "country",
                "city",
                "latitude",
                "longitude"
              ],
              "description": "Location where the datacenter resides in"
            },
            "server_types": {
              "type": "object",
              "properties": {
                "supported": {
                  "type": "array",
                  "items": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ],
                  "description": "IDs of server types that are supported in the datacenter"
                },
                "available": {
                  "type": "array",
                  "items": [
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "number"
                    }
                  ],
                  "description": "IDs of server types that are supported and for which the datacenter has enough resources left"
                }
              },
              "required": [
                "supported",
                "available"
              ],
              "description": "The server types the datacenter can handle"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "location",
            "server_types"
          ],
          "description": "Datacenter this server is located at"
        },
        "image": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the image"
            },
            "type": {
              "type": "string",
              "enum": [
                "system",
                "snapshot",
                "backup"
              ],
              "description": "Type of the image"
            },
            "status": {
              "type": "string",
              "enum": [
                "available",
                "creating"
              ],
              "description": "Whether the image can be used or if it's still being created"
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Unique identifier of the image. This value is only set for system images."
            },
            "description": {
              "type": "string",
              "description": "Description of the image"
            },
            "image_size": {
              "type": [
                "number",
                "null"
              ],
              "description": "Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image."
            },
            "disk_size": {
              "type": "number",
              "description": "Size of the disk contained in the image in GB."
            },
            "created": {
              "type": "string",
              "description": "Point in time when the image was created (in ISO-8601 format)"
            },
            "created_from": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "id": {
                  "type": "number",
                  "description": "ID of the server the image was created from"
                },
                "name": {
                  "type": "string",
                  "description": "Server name at the time the image was created"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "description": "Information about the server the image was created from"
            },
            "bound_to": {
              "type": [
                "number",
                "null"
              ],
              "description": "ID of server the image is bound to. Only set for images of type `backup`."
            },
            "os_flavor": {
              "type": "string",
              "enum": [
                "ubuntu",
                "centos",
                "debian",
                "fedora",
                "unknown"
              ],
              "description": "Flavor of operating system contained in the image"
            },
            "os_version": {
              "type": [
                "string",
                "null"
              ],
              "description": "Operating system version"
            },
            "rapid_deploy": {
              "type": "boolean",
              "description": "Indicates that rapid deploy of the image is available"
            },
            "protection": {
              "type": "object",
              "properties": {
                "delete": {
                  "type": "boolean",
                  "description": "If true, prevents the snapshot from being deleted"
                }
              },
              "required": [
                "delete"
              ],
              "description": "Protection configuration for the image"
            },
            "deprecated": {
              "type": [
                "string",
                "null"
              ],
              "description": "Point in time when the image is considered to be deprecated (in ISO-8601 format)"
            }
          },
          "required": [
            "id",
            "type",
            "status",
            "name",
            "description",
            "image_size",
            "disk_size",
            "created",
            "created_from",
            "bound_to",
            "os_flavor",
            "os_version",
            "protection",
            "deprecated"
          ],
          "description": "Image this server was created from."
        },
        "iso": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the ISO"
            },
            "name": {
              "type": [
                "string",
                "null"
              ],
              "description": "Unique identifier of the ISO. Only set for public ISOs"
            },
            "description": {
              "type": "string",
              "description": "Description of the ISO"
            },
            "type": {
              "type": "string",
              "enum": [
                "public",
                "private"
              ],
              "description": "Type of the ISO"
            },
            "deprecated": {
              "type": [
                "string",
                "null"
              ],
              "description": "ISO 8601 timestamp of deprecation, null if ISO is still available. After the deprecation time it will no longer be possible to attach the ISO to servers."
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "type",
            "deprecated"
          ],
          "description": "ISO image that is attached to this server. Null if no ISO is attached."
        },
        "rescue_enabled": {
          "type": "boolean",
          "description": "True if rescue mode is enabled: Server will then boot into rescue system on next reboot."
        },
        "locked": {
          "type": "boolean",
          "description": "True if server has been locked and is not available to user."
        },
        "backup_window": {
          "type": [
            "string",
            "null"
          ],
          "description": "Time window (UTC) in which the backup will run, or null if the backups are not enabled"
        },
        "outgoing_traffic": {
          "type": [
            "number",
            "null"
          ],
          "description": "Outbound Traffic for the current billing period in bytes"
        },
        "ingoing_traffic": {
          "type": [
            "number",
            "null"
          ],
          "description": "Inbound Traffic for the current billing period in bytes"
        },
        "included_traffic": {
          "type": "number",
          "description": "Free Traffic for the current billing period in bytes"
        },
        "protection": {
          "type": "object",
          "properties": {
            "delete": {
              "type": "boolean",
              "description": "If true, prevents the server from being deleted"
            },
            "rebuild": {
              "type": "boolean",
              "description": "If true, prevents the server from being rebuilt"
            }
          },
          "required": [
            "delete",
            "rebuild"
          ],
          "description": "Protection configuration for the server"
        }
      },
      "required": [
        "id",
        "name",
        "status",
        "created",
        "public_net",
        "server_type",
        "datacenter",
        "image",
        "iso",
        "rescue_enabled",
        "locked",
        "backup_window",
        "outgoing_traffic",
        "ingoing_traffic",
        "included_traffic",
        "protection"
      ]
    }
  },
  "required": [
    "server"
  ]
}

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:

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

Example curl

curl -X 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

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

Parameter Type Description
start string Start of period of metrics reported (in ISO-8601 format)
end string End of period of metrics reported (in ISO-8601 format)
step number Resolution of results in seconds.
time_series object 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 a number and not a string.

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

{
  "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"
          ]
        ]
      }
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "metrics": {
      "type": "object",
      "properties": {
        "start": {
          "type": "string",
          "description": "Start of period of metrics reported (in ISO-8601 format)"
        },
        "end": {
          "type": "string",
          "description": "End of period of metrics reported (in ISO-8601 format)"
        },
        "step": {
          "type": "number",
          "description": "Resolution of results in seconds."
        },
        "time_series": {
          "$ref": "#/definitions/name_of_timeseries",
          "required": [
            "name_of_timeseries"
          ],
          "description": "Hash with timeseries information, containing the name of timeseries as key"
        }
      },
      "required": [
        "start",
        "end",
        "step",
        "time_series"
      ]
    }
  },
  "required": [
    "metrics"
  ],
  "definitions": {
    "name_of_timeseries": {
      "type": "object",
      "patternProperties": {
        "": {
          "type": "object",
          "properties": {
            "values": {
              "type": "array",
              "items": {
                "type": "array"
              },
              "description": "Metrics Timestamps with values"
            }
          },
          "required": [
            "values"
          ]
        }
      }
    }
  }
}

Server Actions

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

statusenum[string] (optional)

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

Choices: running success error
sortenum[string] (optional)

Can be used multiple times.

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

Reply

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

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "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"
      }
    }
  ]
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "ID of the action"
          },
          "command": {
            "type": "string",
            "description": "Command executed in the action"
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "running",
              "error"
            ],
            "description": "Status of the action"
          },
          "progress": {
            "type": "number",
            "description": "Progress of action in percent"
          },
          "started": {
            "type": "string",
            "description": "Point in time when the action was started (in ISO-8601 format)"
          },
          "finished": {
            "type": [
              "string",
              "null"
            ],
            "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
          },
          "resources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "number",
                  "description": "ID of resource referenced"
                },
                "type": {
                  "type": "string",
                  "description": "Type of resource referenced"
                }
              },
              "required": [
                "id",
                "type"
              ]
            },
            "description": "Resources the action relates to"
          },
          "error": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Fixed machine readable code"
              },
              "message": {
                "type": "string",
                "description": "Humanized error message."
              }
            },
            "required": [
              "code",
              "message"
            ],
            "description": "Error message for the action if error occured, otherwise null."
          }
        },
        "required": [
          "id",
          "command",
          "status",
          "progress",
          "started",
          "finished",
          "resources",
          "error"
        ]
      }
    }
  },
  "required": [
    "actions"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "running",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "root_password": {
      "type": "string",
      "description": "Password that will be set for this server once the action succeeds."
    },
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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.

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

Reply

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

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

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

Call specific error codes

Code Description
rescue_already_enabled Returned when the rescue system is already enabled

Example curl

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

Request headers

Content-Type: application/json

Request

{
  "type": "linux64",
  "ssh_keys": [
    2323
  ]
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "linux64",
        "linux32",
        "freebsd64"
      ],
      "description": "Type of rescue system to boot (default: `linux64`)"
    },
    "ssh_keys": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Array of SSH key IDs which should be injected into the rescue system. Only available for types: `linux64` and `linux32`."
    }
  }
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "root_password": {
      "type": "string",
      "description": "Root Password for Server once it gets booted in rescue mode"
    },
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "running",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Call specific error codes

Code Description
rescue_already_disabled Returned when the rescue system is already disabled

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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

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

Reply

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

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

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

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

Example curl

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

Request headers

Content-Type: application/json

Request

{
  "description": "my image",
  "type": "snapshot"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "description": "Description of the image. If you do not set this we auto-generate one for you."
    },
    "type": {
      "type": "string",
      "enum": [
        "snapshot",
        "backup"
      ],
      "description": "Type of image to create (default: `snapshot`)"
    }
  }
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "image": {
    "id": 4711,
    "type": "snapshot",
    "status": "creating",
    "name": null,
    "description": "my image",
    "image_size": 2.3,
    "disk_size": 10,
    "created": "2016-01-30T23:50+00:00",
    "created_from": {
      "id": 1,
      "name": "Server"
    },
    "bound_to": null,
    "os_flavor": "ubuntu",
    "os_version": "16.04",
    "rapid_deploy": false,
    "protection": {
      "delete": false
    },
    "deprecated": "2018-02-28T00:00:00+00:00"
  },
  "action": {
    "id": 1337,
    "command": "create_image",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "image": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the image"
        },
        "type": {
          "type": "string",
          "enum": [
            "snapshot",
            "system",
            "backup"
          ],
          "description": "Type of the image"
        },
        "status": {
          "type": "string",
          "enum": [
            "creating",
            "available"
          ],
          "description": "Whether the image can be used or if it's still being created"
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Unique identifier of the image. This value is only set for system images."
        },
        "description": {
          "type": "string",
          "description": "Description of the image"
        },
        "image_size": {
          "type": [
            "number",
            "null"
          ],
          "description": "Size of the image file in our storage in GB. For snapshot images this is the value relevant for calculating costs for the image."
        },
        "disk_size": {
          "type": "number",
          "description": "Size of the disk contained in the image in GB."
        },
        "created": {
          "type": "string",
          "description": "Point in time when the image was created (in ISO-8601 format)"
        },
        "created_from": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the server the image was created from"
            },
            "name": {
              "type": "string",
              "description": "Server name at the time the image was created"
            }
          },
          "required": [
            "id",
            "name"
          ],
          "description": "Information about the server the image was created from"
        },
        "bound_to": {
          "type": [
            "number",
            "null"
          ],
          "description": "ID of server the image is bound to. Only set for images of type `backup`."
        },
        "os_flavor": {
          "type": "string",
          "enum": [
            "ubuntu",
            "centos",
            "debian",
            "fedora",
            "unknown"
          ],
          "description": "Flavor of operating system contained in the image"
        },
        "os_version": {
          "type": [
            "string",
            "null"
          ],
          "description": "Operating system version"
        },
        "rapid_deploy": {
          "type": "boolean",
          "description": "Indicates that rapid deploy of the image is available"
        },
        "protection": {
          "type": "object",
          "properties": {
            "delete": {
              "type": "boolean",
              "description": "If true, prevents the snapshot from being deleted"
            }
          },
          "required": [
            "delete"
          ],
          "description": "Protection configuration for the image"
        },
        "deprecated": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the image is considered to be deprecated (in ISO-8601 format)"
        }
      },
      "required": [
        "id",
        "type",
        "status",
        "name",
        "description",
        "image_size",
        "disk_size",
        "created",
        "created_from",
        "bound_to",
        "os_flavor",
        "os_version",
        "protection",
        "deprecated"
      ],
      "description": "The newly created image"
    },
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "running",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "image",
    "action"
  ]
}

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.

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

Reply

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

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

Example curl

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

Request headers

Content-Type: application/json

Request

{
  "image": "ubuntu-16.04"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "ID or name of image to rebuilt from."
    }
  },
  "required": [
    "image"
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    },
    "root_password": {
      "type": [
        "string",
        "null"
      ],
      "description": "New root password when not using SSH keys"
    }
  },
  "required": [
    "action",
    "root_password"
  ]
}

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

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

Reply

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

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

Call specific error codes

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

Example curl

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

Request headers

Content-Type: application/json

Request

{
  "upgrade_disk": true,
  "server_type": "cx11"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "upgrade_disk": {
      "type": "boolean",
      "description": "If false, do not upgrade the disk. This allows downgrading the server type later."
    },
    "server_type": {
      "type": "string",
      "description": "ID or name of server type the server should migrate to"
    }
  },
  "required": [
    "server_type"
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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.

Parameter Type Description
backup_window string (optional) Time window (UTC) in which the backup will run
Choices: 22-02, 02-06, 06-10, 10-14, 14-18, 18-22

Reply

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

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

Example curl

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

Request headers

Content-Type: application/json

Request

{
  "backup_window": "22-02"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "backup_window": {
      "type": "string",
      "enum": [
        "22-02",
        "02-06",
        "06-10",
        "10-14",
        "14-18",
        "18-22"
      ],
      "description": "Time window (UTC) in which the backup will run"
    }
  }
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "running",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "running",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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

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

Reply

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

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

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-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

{
  "iso": "FreeBSD-11.0-RELEASE-amd64-dvd1"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "iso": {
      "type": "string",
      "description": "ID or name of ISO to attach to the server as listed in GET `/isos`"
    }
  },
  "required": [
    "iso"
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

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.

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

Reply

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

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

Example curl

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-d '{"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

{
  "ip": "1.2.3.4",
  "dns_ptr": "server01.example.com"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ip": {
      "type": "string",
      "description": "Primary IP address for which the reverse DNS entry should be set."
    },
    "dns_ptr": {
      "type": [
        "string",
        "null"
      ],
      "description": "Hostname to set as a reverse DNS PTR entry. Will reset to original value if `null`"
    }
  },
  "required": [
    "ip",
    "dns_ptr"
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

Change protection for a Server

Changes the protection configuration of the server.

HTTP Request

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

URI Parameters

ParameterTypeDescription
idstring (required)

ID of the server

Request

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

Reply

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

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

Example curl

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

Request headers

Content-Type: application/json

Request

{
  "delete": true,
  "rebuild": true
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delete": {
      "type": "boolean",
      "description": "If true, prevents the server from being deleted (currently delete and rebuild attribute needs to have the same value)"
    },
    "rebuild": {
      "type": "boolean",
      "description": "If true, prevents the server from being rebuilt` (currently delete and rebuild attribute needs to have the same value)"
    }
  }
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "action": {
    "id": 1337,
    "command": "change_protection",
    "status": "success",
    "progress": 100,
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:56:00+00:00",
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "running",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ]
    }
  },
  "required": [
    "action"
  ]
}

Request Console for a Server

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

HTTP Request

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

URI Parameters

ParameterTypeDescription
idstring (required)

ID of the server

Reply

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

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

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

Example curl

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

Response headers

Content-Type: application/json
Status: 201

Response

{
  "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"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "wss_url": {
      "type": "string",
      "description": "URL of websocket proxy to use. This includes a token which is valid for a limited time only."
    },
    "password": {
      "type": "string",
      "description": "VNC password to use for this connection. This password only works in combination with a wss_url with valid token."
    },
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "success",
            "running",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ],
      "description": "Action created by this call"
    }
  },
  "required": [
    "wss_url",
    "password",
    "action"
  ]
}

Floating IPs

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

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

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

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

Floating IPs are billed on a monthly basis.

Get all Floating IPs

Returns all floating ip objects.

HTTP Request

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

Reply

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

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "floating_ips": [
    {
      "id": 4711,
      "description": "Web Frontend",
      "ip": "131.232.99.1",
      "type": "ipv4",
      "server": 42,
      "dns_ptr": [
        {
          "ip": "2001:db8::1",
          "dns_ptr": "server.example.com"
        }
      ],
      "home_location": {
        "id": 1,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071
      },
      "blocked": false,
      "protection": {
        "delete": false
      }
    }
  ]
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "floating_ips": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "ID of the Floating IP"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Description of the Floating IP"
          },
          "ip": {
            "type": "string",
            "description": "IP address of the Floating IP"
          },
          "type": {
            "type": "string",
            "enum": [
              "ipv4",
              "ipv6"
            ],
            "description": "Type of the Floating IP"
          },
          "server": {
            "type": [
              "number",
              "null"
            ],
            "description": "Id of the Server the Floating IP is assigned to, null if it is not assigned at all."
          },
          "dns_ptr": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "ip": {
                  "type": "string",
                  "description": "Single IPv4 or IPv6 address"
                },
                "dns_ptr": {
                  "type": "string",
                  "description": "DNS pointer for the specific IP address"
                }
              },
              "required": [
                "ip",
                "dns_ptr"
              ]
            },
            "description": "Array of reverse DNS entries"
          },
          "home_location": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of the location"
              },
              "name": {
                "type": "string",
                "description": "Unique identifier of the location"
              },
              "description": {
                "type": "string",
                "description": "Description of the location"
              },
              "country": {
                "type": "string",
                "description": "ISO 3166-1 alpha-2 code of the country the location resides in"
              },
              "city": {
                "type": "string",
                "description": "City the location is closest to"
              },
              "latitude": {
                "type": "number",
                "description": "Latitude of the city closest to the location"
              },
              "longitude": {
                "type": "number",
                "description": "Longitude of the city closest to the location"
              }
            },
            "required": [
              "id",
              "name",
              "description",
              "country",
              "city",
              "latitude",
              "longitude"
            ],
            "description": "Location the Floating IP was created in. Routing is optimized for this location."
          },
          "blocked": {
            "type": "boolean",
            "description": "Whether the IP is blocked"
          },
          "protection": {
            "type": "object",
            "properties": {
              "delete": {
                "type": "boolean",
                "description": "If true, prevents the Floating IP from being deleted"
              }
            },
            "required": [
              "delete"
            ],
            "description": "Protection configuration for the Floating IP"
          }
        },
        "required": [
          "id",
          "description",
          "ip",
          "type",
          "server",
          "dns_ptr",
          "home_location",
          "blocked",
          "protection"
        ]
      }
    }
  },
  "required": [
    "floating_ips"
  ]
}

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:

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "floating_ip": {
    "id": 4711,
    "description": "Web Frontend",
    "ip": "131.232.99.1",
    "type": "ipv4",
    "server": 42,
    "dns_ptr": [
      {
        "ip": "2001:db8::1",
        "dns_ptr": "server.example.com"
      }
    ],
    "home_location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071
    },
    "blocked": false,
    "protection": {
      "delete": false
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "floating_ip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the Floating IP"
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Description of the Floating IP"
        },
        "ip": {
          "type": "string",
          "description": "IP address of the Floating IP"
        },
        "type": {
          "type": "string",
          "enum": [
            "ipv4",
            "ipv6"
          ],
          "description": "Type of the Floating IP"
        },
        "server": {
          "type": [
            "number",
            "null"
          ],
          "description": "Id of the Server the Floating IP is assigned to, null if it is not assigned at all."
        },
        "dns_ptr": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "ip": {
                "type": "string",
                "description": "Single IPv4 or IPv6 address"
              },
              "dns_ptr": {
                "type": "string",
                "description": "DNS pointer for the specific IP address"
              }
            },
            "required": [
              "ip",
              "dns_ptr"
            ]
          },
          "description": "Array of reverse DNS entries"
        },
        "home_location": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the location"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the location"
            },
            "description": {
              "type": "string",
              "description": "Description of the location"
            },
            "country": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 code of the country the location resides in"
            },
            "city": {
              "type": "string",
              "description": "City the location is closest to"
            },
            "latitude": {
              "type": "number",
              "description": "Latitude of the city closest to the location"
            },
            "longitude": {
              "type": "number",
              "description": "Longitude of the city closest to the location"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "country",
            "city",
            "latitude",
            "longitude"
          ],
          "description": "Location the Floating IP was created in. Routing is optimized for this location."
        },
        "blocked": {
          "type": "boolean",
          "description": "Whether the IP is blocked"
        },
        "protection": {
          "type": "object",
          "properties": {
            "delete": {
              "type": "boolean",
              "description": "If true, prevents the Floating IP from being deleted"
            }
          },
          "required": [
            "delete"
          ],
          "description": "Protection configuration for the Floating IP"
        }
      },
      "required": [
        "id",
        "description",
        "ip",
        "type",
        "server",
        "dns_ptr",
        "home_location",
        "blocked",
        "protection"
      ]
    }
  },
  "required": [
    "floating_ip"
  ]
}

Create a Floating IP

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

HTTP Request

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

Request

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

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

Reply

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

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

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

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

Example curl

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

Request headers

Content-Type: application/json

Request

{
  "type": "ipv4",
  "server": 42,
  "home_location": "fsn1",
  "description": "Web Frontend"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "ipv4",
        "ipv6"
      ],
      "description": "Floating IP type"
    },
    "server": {
      "type": "number",
      "description": "Server to assign the Floating IP to"
    },
    "home_location": {
      "type": "string",
      "description": "Home location (routing is optimized for that location). Only optional if server argument is passed."
    },
    "description": {
      "type": "string"
    }
  },
  "required": [
    "type"
  ]
}

Response headers

Content-Type: application/json
Status: 201

Response

{
  "floating_ip": {
    "id": 4711,
    "description": "Web Frontend",
    "ip": "131.232.99.1",
    "type": "ipv4",
    "server": 42,
    "dns_ptr": [
      {
        "ip": "2001:db8::1",
        "dns_ptr": "server.example.com"
      }
    ],
    "home_location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071
    },
    "blocked": false,
    "protection": {
      "delete": false
    }
  },
  "action": {
    "id": 1337,
    "command": "assign_floating_ip",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "floating_ip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the Floating IP"
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Description of the Floating IP"
        },
        "ip": {
          "type": "string",
          "description": "IP address of the Floating IP"
        },
        "type": {
          "type": "string",
          "enum": [
            "ipv4",
            "ipv6"
          ],
          "description": "Type of the Floating IP"
        },
        "server": {
          "type": [
            "number",
            "null"
          ],
          "description": "Id of the Server the Floating IP is assigned to, null if it is not assigned at all."
        },
        "dns_ptr": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "ip": {
                "type": "string",
                "description": "Single IPv4 or IPv6 address"
              },
              "dns_ptr": {
                "type": "string",
                "description": "DNS pointer for the specific IP address"
              }
            },
            "required": [
              "ip",
              "dns_ptr"
            ]
          },
          "description": "Array of reverse DNS entries"
        },
        "home_location": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the location"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the location"
            },
            "description": {
              "type": "string",
              "description": "Description of the location"
            },
            "country": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 code of the country the location resides in"
            },
            "city": {
              "type": "string",
              "description": "City the location is closest to"
            },
            "latitude": {
              "type": "number",
              "description": "Latitude of the city closest to the location"
            },
            "longitude": {
              "type": "number",
              "description": "Longitude of the city closest to the location"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "country",
            "city",
            "latitude",
            "longitude"
          ],
          "description": "Location the Floating IP was created in. Routing is optimized for this location."
        },
        "blocked": {
          "type": "boolean",
          "description": "Whether the IP is blocked"
        },
        "protection": {
          "type": "object",
          "properties": {
            "delete": {
              "type": "boolean",
              "description": "If true, prevents the Floating IP from being deleted"
            }
          },
          "required": [
            "delete"
          ],
          "description": "Protection configuration for the Floating IP"
        }
      },
      "required": [
        "id",
        "description",
        "ip",
        "type",
        "server",
        "dns_ptr",
        "home_location",
        "blocked",
        "protection"
      ]
    },
    "action": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the action"
        },
        "command": {
          "type": "string",
          "description": "Command executed in the action"
        },
        "status": {
          "type": "string",
          "enum": [
            "running",
            "success",
            "error"
          ],
          "description": "Status of the action"
        },
        "progress": {
          "type": "number",
          "description": "Progress of action in percent"
        },
        "started": {
          "type": "string",
          "description": "Point in time when the action was started (in ISO-8601 format)"
        },
        "finished": {
          "type": [
            "string",
            "null"
          ],
          "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number",
                "description": "ID of resource referenced"
              },
              "type": {
                "type": "string",
                "description": "Type of resource referenced"
              }
            },
            "required": [
              "id",
              "type"
            ]
          },
          "description": "Resources the action relates to"
        },
        "error": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "code": {
              "type": "string",
              "description": "Fixed machine readable code"
            },
            "message": {
              "type": "string",
              "description": "Humanized error message."
            }
          },
          "required": [
            "code",
            "message"
          ],
          "description": "Error message for the action if error occured, otherwise null."
        }
      },
      "required": [
        "id",
        "command",
        "status",
        "progress",
        "started",
        "finished",
        "resources",
        "error"
      ],
      "description": "Assign action (only present if a server was provided)"
    }
  },
  "required": [
    "floating_ip"
  ]
}

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

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

Reply

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

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

Example curl

curl -X 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

{
  "description": "New description"
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "description": "New Description to set"
    }
  }
}

Response headers

Content-Type: application/json
Status: 200

Response

{
  "floating_ip": {
    "id": 4711,
    "description": "New description",
    "ip": "131.232.99.1",
    "type": "ipv4",
    "server": 42,
    "dns_ptr": [
      {
        "ip": "2001:db8::1",
        "dns_ptr": "server.example.com"
      }
    ],
    "home_location": {
      "id": 1,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071
    },
    "blocked": false,
    "protection": {
      "delete": false
    }
  }
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "floating_ip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "ID of the Floating IP"
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Description of the Floating IP"
        },
        "ip": {
          "type": "string",
          "description": "IP address of the Floating IP"
        },
        "type": {
          "type": "string",
          "enum": [
            "ipv4",
            "ipv6"
          ],
          "description": "Type of the Floating IP"
        },
        "server": {
          "type": [
            "number",
            "null"
          ],
          "description": "Id of the Server the Floating IP is assigned to, null if it is not assigned at all."
        },
        "dns_ptr": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "ip": {
                "type": "string",
                "description": "Single IPv4 or IPv6 address"
              },
              "dns_ptr": {
                "type": "string",
                "description": "DNS pointer for the specific IP address"
              }
            },
            "required": [
              "ip",
              "dns_ptr"
            ]
          },
          "description": "Array of reverse DNS entries"
        },
        "home_location": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "ID of the location"
            },
            "name": {
              "type": "string",
              "description": "Unique identifier of the location"
            },
            "description": {
              "type": "string",
              "description": "Description of the location"
            },
            "country": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 code of the country the location resides in"
            },
            "city": {
              "type": "string",
              "description": "City the location is closest to"
            },
            "latitude": {
              "type": "number",
              "description": "Latitude of the city closest to the location"
            },
            "longitude": {
              "type": "number",
              "description": "Longitude of the city closest to the location"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "country",
            "city",
            "latitude",
            "longitude"
          ],
          "description": "Location the Floating IP was created in. Routing is optimized for this location."
        },
        "blocked": {
          "type": "boolean",
          "description": "Whether the IP is blocked"
        },
        "protection": {
          "type": "object",
          "properties": {
            "delete": {
              "type": "boolean",
              "description": "If true, prevents the Floating IP from being deleted"
            }
          },
          "required": [
            "delete"
          ],
          "description": "Protection configuration for the Floating IP"
        }
      },
      "required": [
        "id",
        "description",
        "ip",
        "type",
        "server",
        "dns_ptr",
        "home_location",
        "blocked",
        "protection"
      ]
    }
  },
  "required": [
    "floating_ip"
  ]
}

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

Example curl

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

Response headers

Status: 204

Floating IP Actions

Get all Actions for a Floating IP

Returns all action objects for a Floating IP. You can sort the results by using the sort URI parameter.

HTTP Request

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

URI Parameters

ParameterTypeDescription
idstring (required)

ID of the Floating IP

sortenum[string] (optional)

Can be used multiple times.

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

Reply

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

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

Example curl

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

Response headers

Content-Type: application/json
Status: 200

Response

{
  "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"
        },
        {
          "id": 4711,
          "type": "floating_ip"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ]
}
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "ID of the action"
          },
          "command": {
            "type": "string",
            "description": "Command executed in the action"
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "running",
              "error"
            ],
            "description": "Status of the action"
          },
          "progress": {
            "type": "number",
            "description": "Progress of action in percent"
          },
          "started": {
            "type": "string",
            "description": "Point in time when the action was started (in ISO-8601 format)"
          },
          "finished": {
            "type": [
              "string",
              "null"
            ],
            "description": "Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null."
          },
          "resources": {
            "type": "array",
            "items": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number",
                    "description": "ID of resource referenced"
                  },
                  "type": {
                    "type": "string",
                    "description": "Type of resource referenced"
                  }
                },
                "required": [
                  "id",
                  "type"
                ]
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number",
                    "description": "ID of resource referenced"
                  },
                  "type": {
                    "type": "string",
                    "description": "Type of resource referenced"
                  }
                },
                "required": [
                  "id",
                  "type"
                ]
              }
            ],
            "description": "Resources the action relates to"
          },
          "error": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description":