Hetzner Cloud API
This is the official API documentation for the Public Hetzner Cloud.
Introduction
The Hetzner Cloud API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.
As an alternative to working directly with our API you may also consider to use:
Our CLI program hcloud
Our library for Go
Also you can find a list of libraries, tools, and integrations on GitHub.
If you are developing integrations based on our API and your product is Open Source you may be eligible for a free one time €50 (excl. VAT) credit on your account. Please contact us via the the support page on your Cloud Console and let us know the following:
The type of integration you would like to develop
Link to the GitHub repo you will use for the project
Link to some other Open Source work you have already done (if you have done so)
Getting Started
To get started using the API you first need an API token. Sign in into the
Hetzner Cloud Console choose a project, go to Access → Tokens, and create a new token. Make
sure to copy the token because it won’t be shown to you again.
A token is bound to a project, to interact with the API of another project you have to create a new token inside the project.
Let’s say your new token is jEheVytlAoFl7F8MqUQ7jAo2hOXASztX.
You’re now ready to do your first request against the API. To get a list of all servers in your project, issue the example request on the right side using curl.
Make sure to replace the token in the example command with the token you have
just created. Since your project probably does not contain any servers yet,
the example response will look like the response on the right side.
We will almost always provide a resource root like servers inside the example response.
A response can also contain a meta object with information like Pagination.
Example: 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 Access → Tokens, 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
pageparameter specifies the page to fetch. The number of the first page is 1.A
per_pageparameter 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.
Example: Pagination Link header
Link: <https://api.hetzner.cloud/actions?page=2&per_page=5>; rel="prev",
<https://api.hetzner.cloud/actions?page=4&per_page=5>; rel="next",
<https://api.hetzner.cloud/actions?page=6&per_page=5>; rel="last"
Line breaks have been added for display purposes only and responses may only contain
some of the above rel values.
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-Limitheader contains the total number of requests you can perform per hour.The
RateLimit-Remainingheader contains the number of requests remaining in the current rate limit time frame.The
RateLimit-Resetheader 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.
Labels
Labels are key/value pairs that can be attached to servers, Floating IPs, SSH keys, and images.
Valid label keys have two segments: an optional prefix and name, separated by a slash (/).
The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional.
If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).
Valid label values must be 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.
The hetzner.cloud/ prefix is reserved and cannot be used.
Examples
environment=developmentservice=backendexample.com/my=labeljust-a-key=
Label Selector
For resources with labels, you can filter resources by their labels using the label selector query language.
| Expression | Meaning |
|---|---|
k==v / k=v |
Value of key k does equal value v |
k!=v |
Value of key k does not equal value v |
k |
Key k is present |
!k |
Key k is not present |
k in (v1,v2,v3) |
Value of key k is v1, v2, or v3 |
k notin (v1,v2,v3) |
Value of key k is neither v1, nor v2, nor v3 |
k1==v,!k2 |
Value of key k1 is v and key k2 is not present |
Examples
Returns all resources that have a
env=productionlabel and that don’t have atype=databaselabel:env=production,type=!databaseReturns all resources that have a
env=testingorenv=staginglabel:env in (testing,staging)Returns all resources that don’t have a
typelabel:!type
Changelog
2018-09-05: Add labels
Property labels has been added to servers, Floating IPs, SSH keys, and images. You can filter resources by labels using the label selector query language.
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
| Parameter | Type | Description |
|---|---|---|
| status | enum[string] (optional) | Can be used multiple times. Response will have only actions with specified statuses. Choices: running success error |
| sort | enum[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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the action |
Reply
The action key in the reply has this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: success, running, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/actions/1337
Response headers
Content-Type: application/jsonStatus: 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,label_selector} URI Parameters
| Parameter | Type | Description |
|---|---|---|
| name | string (optional) | Can be used to filter servers by their name. The response will only contain the server matching the specified name. |
| label_selector | string (optional) | Can be used to filter servers by labels. The response will only contain servers matching the label selector. |
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 |
| labels | object | User-defined labels (key-value pairs) |
Example curl
curl -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers
Response headers
Content-Type: application/jsonStatus: 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",
"labels": {}
},
"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
},
"labels": {}
}
]
}{
"$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)"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"type",
"status",
"name",
"description",
"image_size",
"disk_size",
"created",
"created_from",
"bound_to",
"os_flavor",
"os_version",
"protection",
"deprecated",
"labels"
],
"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"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"name",
"status",
"created",
"public_net",
"server_type",
"datacenter",
"image",
"iso",
"rescue_enabled",
"locked",
"backup_window",
"outgoing_traffic",
"ingoing_traffic",
"included_traffic",
"protection",
"labels"
]
}
}
},
"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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The server key in the reply contains a server object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of server |
| name | string | Name of the server (must be unique per project and a valid hostname as per RFC 1123) |
| status | string | Status of the server Choices: running, initializing, starting, stopping, off, deleting, migrating, rebuilding, unknown |
| created | string | Point in time when the server was created (in ISO-8601 format) |
| public_net | object | Public network information. The servers ipv4 address can be found in public_net->ipv4->ip |
| server_type | object | Type of server - 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 |
| labels | object | User-defined labels (key-value pairs) |
Example curl
curl -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42
Response headers
Content-Type: application/jsonStatus: 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",
"labels": {}
},
"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
},
"labels": {}
}
}{
"$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)"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"type",
"status",
"name",
"description",
"image_size",
"disk_size",
"created",
"created_from",
"bound_to",
"os_flavor",
"os_version",
"protection",
"deprecated",
"labels"
],
"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"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"name",
"status",
"created",
"public_net",
"server_type",
"datacenter",
"image",
"iso",
"rescue_enabled",
"locked",
"backup_window",
"outgoing_traffic",
"ingoing_traffic",
"included_traffic",
"protection",
"labels"
]
}
},
"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. |
| labels | object (optional) | User-defined labels (key-value pairs) |
| 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 |
| labels | object | User-defined labels (key-value pairs) |
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/jsonRequest
{
"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."
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"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/jsonStatus: 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",
"labels": {}
},
"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
},
"labels": {}
},
"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)"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"type",
"status",
"name",
"description",
"image_size",
"disk_size",
"created",
"created_from",
"bound_to",
"os_flavor",
"os_version",
"protection",
"deprecated",
"labels"
],
"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"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"name",
"status",
"created",
"public_net",
"server_type",
"datacenter",
"image",
"iso",
"rescue_enabled",
"locked",
"backup_window",
"outgoing_traffic",
"ingoing_traffic",
"included_traffic",
"protection",
"labels"
]
},
"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"
]
}Update a Server
Updates a server. You can update a server’s name and a server’s labels.
Please note that server names must be unique per project and valid hostnames as per RFC 1123 (i.e. may only contain letters, digits, periods, and dashes).
Also note that when updating labels, the server’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.
HTTP Request
PUT https://api.hetzner.cloud/v1/servers/{id} URI Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Request
| Parameter | Type | Description |
|---|---|---|
| name | string (optional) | New name to set |
| labels | object (optional) | New labels |
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 |
| labels | object | User-defined labels (key-value pairs) |
Example curl
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-d '{"name": "new-name", "labels": {}}' \
https://api.hetzner.cloud/v1/servers/42
Request headers
Content-Type: application/jsonRequest
{
"name": "new-name",
"labels": {}
}{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "New name to set"
},
"labels": {
"type": "object",
"properties": {},
"description": "New labels"
}
}
}Response headers
Content-Type: application/jsonStatus: 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",
"labels": {}
},
"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
},
"labels": {}
}
}{
"$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)"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"type",
"status",
"name",
"description",
"image_size",
"disk_size",
"created",
"created_from",
"bound_to",
"os_flavor",
"os_version",
"protection",
"deprecated",
"labels"
],
"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"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"name",
"status",
"created",
"public_net",
"server_type",
"datacenter",
"image",
"iso",
"rescue_enabled",
"locked",
"backup_window",
"outgoing_traffic",
"ingoing_traffic",
"included_traffic",
"protection",
"labels"
]
}
},
"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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
| type | string (required) | Type of metrics to get
|
| start | string (required) | Start of period to get Metrics for (in ISO-8601 format) |
| end | string (required) | End of period to get Metrics for (in ISO-8601 format) |
| step | number (optional) | Resolution of results in seconds |
Reply
The metrics key in the reply contains a metrics object with this structure:
| Parameter | Type | Description |
|---|---|---|
| start | string | Start of period of metrics reported (in ISO-8601 format) |
| end | string | End of period of metrics reported (in ISO-8601 format) |
| step | number | Resolution of results in seconds. |
| time_series | 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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
| status | enum[string] (optional) | Can be used multiple times. Response will have only actions with specified statuses. Choices: running success error |
| sort | enum[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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
| action_id | string (required) | ID of the action |
Reply
The action key in the reply has this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: success, running, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/1337
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/poweron
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/reboot
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/reset
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/shutdown
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/poweroff
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The root_password key in the reply contains the new root password that will be active if the action succeeds.
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/reset_password
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Request
Specify type to select the kind if rescue environment you want to boot.
To access the booted rescue system by SSH key pass the respective SSH key ids in ssh_keys.
| Parameter | Type | Description |
|---|---|---|
| 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/jsonRequest
{
"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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Call specific error codes
| Code | Description |
|---|---|
rescue_already_disabled |
Returned when the rescue system is already disabled |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/disable_rescue
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (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 |
| labels | object (optional) | User-defined labels (key-value pairs) |
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) |
| labels | object | User-defined labels (key-value pairs) |
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/jsonRequest
{
"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`)"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
}
}Response headers
Content-Type: application/jsonStatus: 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",
"labels": {}
},
"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)"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"type",
"status",
"name",
"description",
"image_size",
"disk_size",
"created",
"created_from",
"bound_to",
"os_flavor",
"os_version",
"protection",
"deprecated",
"labels"
],
"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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Request
To select which image to rebuild from you can either pass an id or a name as the image argument.
Passing a name only works for system images since the other image types do not have a name set.
| Parameter | Type | Description |
|---|---|---|
| image | string (required) | ID or name of image to rebuilt from. |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-d '{"image": "ubuntu-16.04"}' \
https://api.hetzner.cloud/v1/servers/42/actions/rebuild
Request headers
Content-Type: application/jsonRequest
{
"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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Request
| Parameter | Type | Description |
|---|---|---|
| upgrade_disk | boolean (optional) | If false, do not upgrade the disk. This allows downgrading the server type later. |
| server_type | string (required) | ID or name of server type the server should migrate to |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Call specific error codes
| Code | Description |
|---|---|
server_not_stopped |
Returned when the server was not powered off |
invalid_server_type |
Returned when a type change to the new server_type is not possible |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-d '{"upgrade_disk": true, "server_type": "cx11"}' \
https://api.hetzner.cloud/v1/servers/42/actions/change_type
Request headers
Content-Type: application/jsonRequest
{
"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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Request
Passing the backup_window will select the time window for the daily backup to run. All times are in UTC. 22-02 means
that the backup will be started between 10 PM and 2 AM. This will be done on a best-effort base, so we cannot
guarantee the backup window will be met.
If you do not provide a time window one will be randomly selected.
| Parameter | Type | Description |
|---|---|---|
| backup_window | string (optional) | Time window (UTC) in which the backup will run Choices: 22-02, 02-06, 06-10, 10-14, 14-18, 18-22 |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: success, running, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-d '{"backup_window": "22-02"}' \
https://api.hetzner.cloud/v1/servers/42/actions/enable_backup
Request headers
Content-Type: application/jsonRequest
{
"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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: success, running, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/disable_backup
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Request
| Parameter | Type | Description |
|---|---|---|
| iso | string (required) | ID or name of ISO to attach to the server as listed in GET /isos |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-d '{"iso": "FreeBSD-11.0-RELEASE-amd64-dvd1"}' \
https://api.hetzner.cloud/v1/servers/42/actions/attach_iso
Request headers
Content-Type: application/jsonRequest
{
"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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/servers/42/actions/detach_iso
Response headers
Content-Type: application/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Request
Select the IP address for which to change the dns entry by passing ip. It can be either ipv4 or ipv6.
The target hostname is set by passing dns_ptr.
| Parameter | Type | Description |
|---|---|---|
| ip | string (required) | Primary IP address for which the reverse DNS entry should be set. |
| dns_ptr | string, null (required) | Hostname to set as a reverse DNS PTR entry. Will reset to original value if null |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: running, success, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-d '{"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/jsonRequest
{
"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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Request
| Parameter | Type | Description |
|---|---|---|
| delete | boolean (optional) | If true, prevents the server from being deleted (currently delete and rebuild attribute needs to have the same value) |
| rebuild | boolean (optional) | If true, prevents the server from being rebuilt` (currently delete and rebuild attribute needs to have the same value) |
Reply
The action key in the reply contains an action object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the action |
| command | string | Command executed in the action |
| status | string | Status of the action Choices: success, running, error |
| progress | number | Progress of action in percent |
| started | string | Point in time when the action was started (in ISO-8601 format) |
| finished | string, null | Point in time when the action was finished (in ISO-8601 format). Only set if the action is finished otherwise null. |
| resources | array | Resources the action relates to |
| error | object, null | Error message for the action if error occured, otherwise null. |
Example curl
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $API_TOKEN" \
-d '{"delete": true, "rebuild": true}' \
https://api.hetzner.cloud/v1/servers/42/actions/change_protection
Request headers
Content-Type: application/jsonRequest
{
"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/jsonStatus: 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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the server |
Reply
| Parameter | Type | Description |
|---|---|---|
| wss_url | string | URL of websocket proxy to use. This includes a token which is valid for a limited time only. |
| password | string | VNC password to use for this connection. This password only works in combination with a wss_url with valid token. |
| action | object | 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/jsonStatus: 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{?label_selector} URI Parameters
| Parameter | Type | Description |
|---|---|---|
| label_selector | string (optional) | Can be used to filter Floating IPs by labels. The response will only contain Floating IPs matching the label selector. |
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 |
| labels | object | User-defined labels (key-value pairs) |
Example curl
curl -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/floating_ips
Response headers
Content-Type: application/jsonStatus: 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
},
"labels": {}
}
]
}{
"$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"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"description",
"ip",
"type",
"server",
"dns_ptr",
"home_location",
"blocked",
"protection",
"labels"
]
}
}
},
"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
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the Floating IP |
Reply
The floating_ip key in the reply contains a floating ip object with this structure:
| Parameter | Type | Description |
|---|---|---|
| id | number | ID of the Floating IP |
| description | string, null | Description of the Floating IP |
| ip | string | IP address of the Floating IP |
| type | string | Type of the Floating IP Choices: ipv4, ipv6 |
| server | number, null | Id of the Server the Floating IP is assigned to, null if it is not assigned at all. |
| dns_ptr | array | Array of reverse DNS entries |
| home_location | object | Location the Floating IP was created in. Routing is optimized for this location. |
| blocked | boolean | Whether the IP is blocked |
| protection | object | Protection configuration for the Floating IP |
| labels | object | User-defined labels (key-value pairs) |
Example curl
curl -H "Authorization: Bearer $API_TOKEN" \
https://api.hetzner.cloud/v1/floating_ips/4711
Response headers
Content-Type: application/jsonStatus: 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
},
"labels": {}
}
}{
"$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"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"description",
"ip",
"type",
"server",
"dns_ptr",
"home_location",
"blocked",
"protection",
"labels"
]
}
},
"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) | |
| labels | object (optional) | User-defined labels (key-value pairs) |
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 |
| labels | object | User-defined labels (key-value pairs) |
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/jsonRequest
{
"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"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"type"
]
}Response headers
Content-Type: application/jsonStatus: 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
},
"labels": {}
},
"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"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
},
"required": [
"id",
"description",
"ip",
"type",
"server",
"dns_ptr",
"home_location",
"blocked",
"protection",
"labels"
]
},
"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 Floating IP
Changes the description or labels of a Floating IP.
Also note that when updating labels, the floating_ip’s current set of labels will be replaced with the labels provided in the request body. So, for example, if you want to add a new label, you have to provide all existing labels plus the new label in the request body.
HTTP Request
PUT https://api.hetzner.cloud/v1/floating_ips/{id} URI Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string (required) | ID of the Floating IP |
Request
| Parameter | Type | Description |
|---|---|---|
| description | string (optional) | New Description to set |
| labels | object (optional) | User-defined labels (key-value pairs) |
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 |
| labels | object | User-defined labels (key-value pairs) |
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/jsonRequest
{
"description": "New description"
}{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "New Description to set"
},
"labels": {
"type": "object",
"properties": {},
"description": "User-defined labels (key-value pairs)"
}
}
}Response headers
Content-Type: application/jsonStatus: 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
},
"labels": {}
}
}{
"$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",