Hetzner Cloud API

https://docs.hetzner.cloud/
Admin
This API documentation provides a comprehensive overview of the available endpoints for managing...
Tokens:64,882
Snippets:427
Trust Score:9.5
Update:1 day ago
Show doc for...
Tokens:
Raw
### Get multiple Actions with Go client (client.Action.AllWithOpts)

Source: https://docs.hetzner.cloud/reference/cloud

Go example for the `get/actions` endpoint. Uses the hcloud-go v2 client to fetch actions by IDs. Requires the `HCLOUD_TOKEN` environment variable. The `ActionListOpts.ID` field filters actions by ID.

```Go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	actions, err := client.Action.AllWithOpts(ctx, hcloud.ActionListOpts{ID: []int64{123, 456}})
}
```

--------------------------------

### Get a single Action with Go client (client.Action.GetByID)

Source: https://docs.hetzner.cloud/reference/cloud

Go example for the `get/actions/{id}` endpoint. Uses the hcloud-go v2 client to fetch a single action by its ID. Requires the `HCLOUD_TOKEN` environment variable.

```Go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	action, _, err := client.Action.GetByID(ctx, 123)
}
```

--------------------------------

### Example Pagination Link header

Source: https://docs.hetzner.cloud/reference/cloud

Example Link header with pagination information. Line breaks have been added for display purposes only and responses may only contain some of the rel values shown.

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

--------------------------------

### GET /firewalls/actions

Source: https://docs.hetzner.cloud/reference/cloud

Lists all firewall actions.

```APIDOC
## GET /firewalls/actions

### Description
Lists all firewall actions.

### Method
GET

### Endpoint
/firewalls/actions

### Response
#### Success Response (200)
- **actions** (array) - List of action objects.

#### Response Example
{
  "actions": []
}
```

--------------------------------

### GET /zones/actions

Source: https://docs.hetzner.cloud/reference/cloud

Lists all actions for all zones.

```APIDOC
## GET /zones/actions

### Description
Lists all actions for all zones.

### Method
GET

### Endpoint
/zones/actions

```

--------------------------------

### GET /firewalls

Source: https://docs.hetzner.cloud/reference/cloud

Lists all firewalls in the Hetzner Cloud project.

```APIDOC
## GET /firewalls

### Description
Lists all firewalls in the Hetzner Cloud project.

### Method
GET

### Endpoint
/firewalls

### Response
#### Success Response (200)
- **firewalls** (array) - List of firewall objects.

#### Response Example
{
  "firewalls": []
}
```

--------------------------------

### GET /certificates

Source: https://docs.hetzner.cloud/reference/cloud

Lists all certificates.

```APIDOC
## GET /certificates

### Description
Lists all certificates.

### Method
GET

### Endpoint
/certificates

```

--------------------------------

### Example Pagination JSON response

Source: https://docs.hetzner.cloud/reference/cloud

Example JSON response body showing the pagination object inside the meta object. 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.

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

--------------------------------

### BIND Zone File Example for Hetzner DNS Import

Source: https://docs.hetzner.cloud/reference/cloud

Example zone file in BIND format for importing into a Hetzner DNS zone in primary mode. It includes an $ORIGIN directive matching the zone name with a trailing dot, a $TTL directive, SOA and NS records, and comments that are discarded during import.

```dns
$ORIGIN	example.com.
$TTL	3600

@	IN	SOA	hydrogen.ns.hetzner.com. dns.hetzner.com. 2024010100 86400 10800 3600000 3600

@	IN	10800	NS	hydrogen.ns.hetzner.com. ; Some comment.
@	IN	10800	NS	oxygen.ns.hetzner.com.
@	IN	10800	NS	helium.ns.hetzner.de.
```

--------------------------------

### resource_limit_exceeded error example

Source: https://docs.hetzner.cloud/reference/cloud

Example error response for the resource_limit_exceeded error code, indicating that a resource limit has been exceeded.

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

--------------------------------

### Example response for list servers

Source: https://docs.hetzner.cloud/reference/cloud

Shows the JSON response structure when listing servers. The servers array is empty and pagination metadata is included.

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

--------------------------------

### POST /servers/{id}/actions/enable_backup

Source: https://docs.hetzner.cloud/reference/cloud

Enables backups for a server.

```APIDOC
## POST /servers/{id}/actions/enable_backup

### Description
Enables backups for a server.

### Method
POST

### Endpoint
/servers/{id}/actions/enable_backup

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the server.

#### Request Body
- **backup_window** (string) - Optional - Backup window (e.g., 22-02).

### Request Example
{
  "backup_window": "22-02"
}

### Response
#### Success Response (201)
- **action** (object) - The action that was executed.

#### Response Example
{
  "action": {
    "id": 123,
    "status": "running"
  }
}
```

--------------------------------

### uniqueness_error error example

Source: https://docs.hetzner.cloud/reference/cloud

Example error response for the uniqueness_error error code, indicating a uniqueness constraint violation.

```json
{
  "error": {
    "code": "uniqueness_error",
    "message": "SSH key with the same fingerprint already exists",
    "details": {
      "fields": [
        {
          "name": "public_key"
        }
      ]
    }
  }
}
```

--------------------------------

### deprecated_api_endpoint error example

Source: https://docs.hetzner.cloud/reference/cloud

Example error response for the deprecated_api_endpoint error code, indicating that the API endpoint functionality has been removed.

```json
{
  "error": {
    "code": "deprecated_api_endpoint",
    "message": "API functionality was removed",
    "details": {
      "announcement": "https://docs.hetzner.cloud/changelog#2023-07-20-foo-endpoint-is-deprecated"
    }
  }
}
```

--------------------------------

### POST /servers/{id}/actions/rebuild

Source: https://docs.hetzner.cloud/reference/cloud

Rebuilds a server from an image.

```APIDOC
## POST /servers/{id}/actions/rebuild

### Description
Rebuilds a server from an image.

### Method
POST

### Endpoint
/servers/{id}/actions/rebuild

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the server.

#### Request Body
- **image** (string) - Required - Image to rebuild from.

### Request Example
{
  "image": "ubuntu-22.04"
}

### Response
#### Success Response (201)
- **action** (object) - The action that was executed.
- **root_password** (string) - Temporary root password.

#### Response Example
{
  "action": {
    "id": 123,
    "status": "running"
  },
  "root_password": "temporary-password"
}
```

--------------------------------

### POST /firewalls

Source: https://docs.hetzner.cloud/reference/cloud

Creates a new firewall in the Hetzner Cloud project.

```APIDOC
## POST /firewalls

### Description
Creates a new firewall in the Hetzner Cloud project.

### Method
POST

### Endpoint
/firewalls

### Request Body
- **name** (string) - Required - Name of the firewall.
- **rules** (array) - Optional - List of firewall rules.
- **apply_to** (array) - Optional - Resources to apply the firewall to.

### Request Example
{
  "name": "my-firewall",
  "rules": [],
  "apply_to": []
}

### Response
#### Success Response (201)
- **firewall** (object) - The created firewall object.

#### Response Example
{
  "firewall": {}
}
```

--------------------------------

### Error response example

Source: https://docs.hetzner.cloud/reference/cloud

Example JSON error response containing code, message, and details fields. The details schema depends on the error code.

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

--------------------------------

### Go: Get pricing with hcloud-go client

Source: https://docs.hetzner.cloud/reference/cloud

Uses the hcloud-go v2 client to fetch pricing. Requires the HCLOUD_TOKEN environment variable. The response includes pricing data with net and gross prices.

```Go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	pricing, _, err := client.Pricing.Get(ctx)
}
```

--------------------------------

### JSON: Pricing response schema

Source: https://docs.hetzner.cloud/reference/cloud

Example response schema for the get/pricing endpoint. Shows the structure with currency, VAT rate, and pricing details for primary IPs, floating IPs, images, volumes, server backups, server types, and load balancer types.

```JSON
{
  "pricing": {
    "currency": "EUR",
    "vat_rate": "19.00",
    "primary_ips": [
      {
        "type": "ipv4",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1.0000",
              "gross": "1.1900"
            },
            "price_monthly": {
              "net": "1.0000",
              "gross": "1.1900"
            }
          }
        ]
      }
    ],
    "floating_ips": [
      {
        "type": "ipv4",
        "prices": [
          {
            "location": "fsn1",
            "price_monthly": {
              "net": "1.0000",
              "gross": "1.1900"
            }
          }
        ]
      }
    ],
    "image": {
      "price_per_gb_month": {
        "net": "1.0000",
        "gross": "1.1900"
      }
    },
    "volume": {
      "price_per_gb_month": {
        "net": "1.0000",
        "gross": "1.1900"
      }
    },
    "server_backup": {
      "percentage": "20.00"
    },
    "server_types": [
      {
        "id": 104,
        "name": "cpx22",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1.0000",
              "gross": "1.1900"
            },
            "price_monthly": {
              "net": "1.0000",
              "gross": "1.1900"
            },
            "included_traffic": 654321,
            "price_per_tb_traffic": {
              "net": "1.0000",
              "gross": "1.1900"
            }
          }
        ]
      }
    ],
    "load_balancer_types": [
      {
        "id": 1,
        "name": "lb11",
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1.0000",
              "gross": "1.1900"
            },
            "price_monthly": {
              "net": "1.0000",
              "gross": "1.1900"
            },
            "included_traffic": 654321,
            "price_per_tb_traffic": {
              "net": "1.0000",
              "gross": "1.1900"
            }
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### POST /servers/{id}/actions/create_image

Source: https://docs.hetzner.cloud/reference/cloud

Creates an image from a server.

```APIDOC
## POST /servers/{id}/actions/create_image

### Description
Creates an image from a server.

### Method
POST

### Endpoint
/servers/{id}/actions/create_image

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the server.

#### Request Body
- **type** (string) - Optional - Type of image (e.g., snapshot).
- **description** (string) - Optional - Description of the image.

### Request Example
{
  "type": "snapshot",
  "description": "My snapshot"
}

### Response
#### Success Response (201)
- **action** (object) - The action that was executed.
- **image** (object) - The created image.

#### Response Example
{
  "action": {
    "id": 123,
    "status": "running"
  },
  "image": {
    "id": 456,
    "type": "snapshot"
  }
}
```

--------------------------------

### POST /servers/{id}/actions/request_console

Source: https://docs.hetzner.cloud/reference/cloud

Requests a VNC console for a server.

```APIDOC
## POST /servers/{id}/actions/request_console

### Description
Requests a VNC console for a server.

### Method
POST

### Endpoint
/servers/{id}/actions/request_console

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the server.

### Response
#### Success Response (201)
- **action** (object) - The action that was executed.
- **wss_url** (string) - WebSocket URL for the console.
- **password** (string) - Console password.

#### Response Example
{
  "action": {
    "id": 123,
    "status": "running"
  },
  "wss_url": "wss://console.hetzner.cloud",
  "password": "console-password"
}
```

--------------------------------

### GET /hetzner/v1/metadata/hostname

Source: https://docs.hetzner.cloud/reference/cloud

Retrieves the hostname of the server.

```APIDOC
## GET /hetzner/v1/metadata/hostname

### Description
Retrieves the hostname of the server.

### Method
GET

### Endpoint
http://169.254.169.254/hetzner/v1/metadata/hostname

### Response
#### Success Response (200)
- **hostname** (text) - Name of the Server as set in the api

#### Response Example
```
my-server
```
```

--------------------------------

### POST /servers/{id}/actions/attach_iso

Source: https://docs.hetzner.cloud/reference/cloud

Attaches an ISO image to a server.

```APIDOC
## POST /servers/{id}/actions/attach_iso

### Description
Attaches an ISO image to a server.

### Method
POST

### Endpoint
/servers/{id}/actions/attach_iso

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the server.

#### Request Body
- **iso** (string) - Required - ISO image identifier.

### Request Example
{
  "iso": "ubuntu-22.04"
}

### Response
#### Success Response (201)
- **action** (object) - The action that was executed.

#### Response Example
{
  "action": {
    "id": 123,
    "status": "running"
  }
}
```

--------------------------------

### GET /hetzner/v1/metadata/availability-zone

Source: https://docs.hetzner.cloud/reference/cloud

Retrieves the availability zone of the server.

```APIDOC
## GET /hetzner/v1/metadata/availability-zone

### Description
Retrieves the availability zone of the server.

### Method
GET

### Endpoint
http://169.254.169.254/hetzner/v1/metadata/availability-zone

### Response
#### Success Response (200)
- **availability-zone** (text) - Name of the availability zone that Server runs in

#### Response Example
```
hel1-dc2
```
```

--------------------------------

### GET /hetzner/v1/metadata/instance-id

Source: https://docs.hetzner.cloud/reference/cloud

Retrieves the instance ID of the server.

```APIDOC
## GET /hetzner/v1/metadata/instance-id

### Description
Retrieves the instance ID of the server.

### Method
GET

### Endpoint
http://169.254.169.254/hetzner/v1/metadata/instance-id

### Response
#### Success Response (200)
- **instance-id** (number) - ID of the server

#### Response Example
```
42
```
```

--------------------------------

### GET /locations/{id}

Source: https://docs.hetzner.cloud/reference/cloud

Retrieves a specific location by its ID.

```APIDOC
## GET /locations/{id}

### Description
Retrieves a specific location by its ID.

### Method
GET

### Endpoint
/locations/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the location.

```

--------------------------------

### POST /servers

Source: https://docs.hetzner.cloud/reference/cloud

Creates a new server in the Hetzner Cloud project. The request body must include the server name and type, and optionally an image, location, or datacenter.

```APIDOC
## POST /servers

### Description
Creates a new server in the Hetzner Cloud project.

### Method
POST

### Endpoint
/servers

### Parameters
#### Request Body
- **name** (string) - Required - Name of the server.
- **server_type** (string) - Required - Type of the server (e.g., cx11).
- **image** (string) - Optional - Image to use for the server.
- **location** (string) - Optional - Location of the server.
- **datacenter** (string) - Optional - Datacenter of the server.

### Request Example
{
  "name": "my-server",
  "server_type": "cx11",
  "image": "ubuntu-22.04"
}

### Response
#### Success Response (201)
- **server** (object) - The created server object.
- **action** (object) - The action that was executed.

#### Response Example
{
  "server": {
    "id": 42,
    "name": "my-server"
  },
  "action": {
    "id": 123,
    "status": "running"
  }
}
```

--------------------------------

### Label selector examples

Source: https://docs.hetzner.cloud/reference/cloud

Examples of label selector expressions for filtering resources. Use 'env=production,type!=database' to match resources with an env=production label and without a type=database label; 'env in (testing,staging)' to match resources with an env=testing or env=staging label; and '!type' to match resources without a type label.

```plaintext
env=production,type!=database
```

```plaintext
env in (testing,staging)
```

```plaintext
!type
```

--------------------------------

### GET /locations

Source: https://docs.hetzner.cloud/reference/cloud

Lists all locations. Datacenters are organized by locations.

```APIDOC
## GET /locations

### Description
Lists all locations.

### Method
GET

### Endpoint
/locations

```

--------------------------------

### POST /servers/{id}/actions/add_to_placement_group

Source: https://docs.hetzner.cloud/reference/cloud

Adds a server to a placement group.

```APIDOC
## POST /servers/{id}/actions/add_to_placement_group

### Description
Adds a server to a placement group.

### Method
POST

### Endpoint
/servers/{id}/actions/add_to_placement_group

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the server.

#### Request Body
- **placement_group** (integer) - Required - ID of the placement group.

### Request Example
{
  "placement_group": 1
}

### Response
#### Success Response (201)
- **action** (object) - The action that was executed.

#### Response Example
{
  "action": {
    "id": 123,
    "status": "running"
  }
}
```

--------------------------------

### GET /certificates/{id}

Source: https://docs.hetzner.cloud/reference/cloud

Retrieves a specific certificate by its ID.

```APIDOC
## GET /certificates/{id}

### Description
Retrieves a specific certificate by its ID.

### Method
GET

### Endpoint
/certificates/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the certificate.

```
Tokens:
Raw