Hetzner Cloud

Hetzner Cloud API

Quick Reference

Base URL: https://api.hetzner.cloud

Getting Started

Alternative Tools

• CLI: hcloud - Official command-line tool
• Go Library: Official Hetzner Go SDK
• Python Library: Official Hetzner Python SDK
• See Awesome Hetzner for more integrations

Open Source Credits

If you're developing an open-source project that supports Hetzner APIs, you may be eligible for a free one-time credit of up to €50/$50. Contact support via Hetzner Console with:

• Project name and description
• Link to project website/repo
• Your role in the project
• Links to other open-source work

Note: Only Hetzner-specific projects are eligible. Generic S3 clients/SDKs (since Object Storage uses standard S3 API) are not eligible.

Creating an API Token

1. Sign into Hetzner Console
2. Select a Project
3. Go to Security → API Tokens
4. Generate a new token (copy immediately - won't be shown again)

Tokens are bound to a Project. Create separate tokens for different Projects.

First Request

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

Example Response:

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

Authentication

All requests require an API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Error Handling

Errors return an error object with code, message, and optional details. The schema of details depends on the error code:

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

deprecated_api_endpoint:

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

Error Codes

Labels

Key/value pairs attached to resources for organization and filtering.

Label Format

Keys: [prefix/]name

• prefix (optional): DNS subdomain, max 253 chars, ends with /
• name (required): 1-63 chars, alphanumeric with -, _, .

Values: 0-63 chars, alphanumeric with -, _, .

The hetzner.cloud/ prefix is reserved.

{
  "labels": {
    "environment": "development",
    "service": "backend",
    "example.com/my": "label",
    "just-a-key": ""
  }
}

Label Selectors

Filter resources using label selector query language:

Examples:

env=production,type!=database    # production, not database
env in (testing,staging)         # testing or staging
!type                            # no type label

Pagination

Paginated endpoints support:

Response includes:

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

Link Header:

Responses also include a Link header with pagination URLs:

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"

Line breaks above are for display only. Responses may only contain some rel values.

The keys previous_page, next_page, last_page, and total_entries may be null when on the first page, last page, or when total entries are unknown.

Rate Limiting

• Default limit: 3600 requests/hour per Project
• Burst requests are allowed
• Remaining requests increase gradually (1 per second)

Response Headers:

• RateLimit-Limit - Total requests allowed per hour
• RateLimit-Remaining - Requests remaining
• RateLimit-Reset - UNIX timestamp when limit resets

Sorting

Sort with sort query parameter. Append :asc or :desc for direction (default: ascending).

?sort=status
?sort=status:asc
?sort=status:desc
?sort=status:asc&sort=command:desc

Deprecation Notices

You can find all announced deprecations in the Hetzner Changelog.

Server Metadata

Servers can discover their own metadata via HTTP:

Base URL: http://169.254.169.254/hetzner/v1/metadata

# Get all metadata
curl http://169.254.169.254/hetzner/v1/metadata

# Get hostname only
curl http://169.254.169.254/hetzner/v1/metadata/hostname

Private Networks Example Response:

- ip: 10.0.0.2
  alias_ips: [10.0.0.3, 10.0.0.4]
  interface_num: 1
  mac_address: 86:00:00:2a:7d:e0
  network_id: 1234
  network_name: nw-test1
  network: 10.0.0.0/8
  subnet: 10.0.0.0/24
  gateway: 10.0.0.1
- ip: 192.168.0.2
  alias_ips: []
  interface_num: 2
  mac_address: 86:00:00:2a:7d:e1
  network_id: 4321
  network_name: nw-test2
  network: 192.168.0.0/16
  subnet: 192.168.0.0/24
  gateway: 192.168.0.1

Servers

Virtual machines that can be provisioned.

List Servers

curl 'https://api.hetzner.cloud/v1/servers' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Query Parameters:

• name - Filter by exact name
• label_selector - Filter by labels
• status - Filter by status: running, initializing, starting, stopping, off, deleting, migrating, rebuilding, unknown
• sort - Sort by: id, name, created (with :asc/:desc)
• page, per_page - Pagination

Create a Server

curl https://api.hetzner.cloud/v1/servers \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "name": "my-server",
    "location": "nbg1",
    "server_type": "cpx22",
    "image": "ubuntu-24.04",
    "start_after_create": true,
    "ssh_keys": ["my-ssh-key"],
    "labels": {
      "environment": "prod"
    }
  }'

Operation-Specific Errors:

Required Fields:

• name - Unique per Project, valid hostname (RFC 1123)
• server_type - ID or name (e.g., cpx22)
• image - ID or name (e.g., ubuntu-24.04)

Optional Fields:

• location - ID or name (e.g., nbg1, fsn1, hel1)
• datacenter - DEPRECATED (will be removed after July 1, 2026). Use location instead.
• ssh_keys - Array of SSH key IDs or names
• networks - Network IDs for private networking
• firewalls - Firewall configurations applied to public network interface at creation
• volumes - Volume IDs to attach
• placement_group - Placement group ID
• user_data - Cloud-init user data (⚠️ stored in Hetzner systems - don't use for passwords/sensitive info)

  # Example user_data (cloud-init):
  #cloud-config
  runcmd:
    - [touch, /root/cloud-init-worked]
  

• labels - Key/value labels
• automount - Auto-mount volumes after attach (default: false)
• start_after_create - Start server after creation (default: true, set to false to create powered-off)
• public_net - Public network configuration:
  • enable_ipv4 - Enable public IPv4
  • enable_ipv6 - Enable public IPv6
  • ipv4 - Specific Primary IP ID
  • ipv6 - Specific Primary IP ID

If no ssh_keys provided, a root password is generated and returned in the response.

Properties like start_after_create or automount trigger follow-up Actions. These are listed in the next_actions field of the response.

Get a Server

curl https://api.hetzner.cloud/v1/servers/42 \
  -H 'Authorization: Bearer YOUR_TOKEN'

Update a Server

curl https://api.hetzner.cloud/v1/servers/42 \
  -X PUT \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "name": "new-server-name",
    "labels": { "environment": "staging" }
  }'

Delete a Server

curl https://api.hetzner.cloud/v1/servers/42 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_TOKEN'

Attached resources (Volumes, Primary IPs, Floating IPs, Firewalls, Placement Groups) are detached automatically.

Server Response Fields

The server object in responses includes:

Get Server Metrics

curl 'https://api.hetzner.cloud/v1/servers/42/metrics?type=cpu&start=2024-01-01T00:00:00Z&end=2024-01-02T00:00:00Z' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Metric Types and Timeseries:

You can specify multiple types with comma separation, e.g. ?type=cpu,disk.

Metrics available for last 30 days. Max 500 samples returned. If no step parameter provided, it auto-adjusts for max 200 samples.

Server Actions

Server Types

Define kinds of servers with different specs and pricing.

List Server Types

curl https://api.hetzner.cloud/v1/server_types \
  -H 'Authorization: Bearer YOUR_TOKEN'

Get Server Type

curl https://api.hetzner.cloud/v1/server_types/42 \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response includes:

• cores - Number of CPU cores
• memory - RAM in GB
• disk - Disk size in GB
• storage_type - local or network
• cpu_type - shared or dedicated
• architecture - x86 or arm
• category - Human-readable category (e.g., "Shared vCPU")
• deprecated - Whether this type is deprecated
• prices - Pricing per location, each containing:
  • price_hourly - Hourly cost (net/gross)
  • price_monthly - Monthly cost (net/gross)
  • included_traffic - Traffic included in price (bytes)
  • price_per_tb_traffic - Cost for additional traffic
• locations - Available locations with optional deprecation info:
  • announced - When deprecation was announced
  • unavailable_after - When location becomes unavailable

Billing: You pay whichever is lower: hourly or monthly cost based on your usage.

Images

Blueprints for VM disks.

Image Types:

• System Images - Distribution images maintained by Hetzner (e.g., "Ubuntu 24.04")
• Snapshot Images - Custom snapshots maintained by you (billed per GB/month)
• Backup Images - Daily backups of your Server (20% of server price for 7 backup slots)
  • Bound to exactly one Server - if you delete the Server, all backups bound to it are also deleted
  • You can convert backup Images to snapshot Images to keep them after Server deletion
• App Images - Prebuilt images with specific software configurations (e.g., "Wordpress"), created by Hetzner

Image Response Fields:

• os_flavor - OS flavor (e.g., ubuntu, debian, centos)
• os_version - OS version (e.g., 24.04)
• image_size - Actual size of the image in GB
• disk_size - Size of disk the image creates in GB
• rapid_deploy - Whether the image supports rapid deploy (faster provisioning)
• created_from - For snapshots: source server info (id, name)
• bound_to - For backups: ID of the server this backup is bound to
• deprecated - Deprecation timestamp if the image is deprecated
• deleted - Deletion timestamp if the image was deleted

Endpoints

Image Actions

Volumes

Highly-available, scalable SSD block storage for Servers.

Pricing depends on Volume size and Location, not actual used storage. See Hetzner Docs for more details.

Endpoints

Volume Actions

Networks

Private networking for servers. Networks are optional and coexist with the public network every Server has by default. They allow Servers to communicate over a dedicated interface using private IPs (RFC1918).

Note: Private networks do not provide public internet connectivity. Use the server's public network interface for internet access.

Concepts

• Networks - Define IP range (RFC1918). Currently IPv4 only.
• Subnets - Divide network into smaller ranges within the parent Network's ip_range
  • cloud - Connect cloud resources (recommended)
  • server - DEPRECATED (replaced by cloud)
  • vswitch - Connect dedicated server vSwitch (requires vswitch_id)
  • Important: Subnets cannot have overlapping IP ranges within the same network
• Routes - Custom routing rules automatically applied to private traffic. A route ensures all packets for a given destination IP prefix are sent to the address specified in its gateway.

IP Address Management

When a Server attaches to a network without specifying an IP, it automatically gets an IP from a subnet of type server in the same network zone (note: server type is deprecated and replaced by cloud). Servers can have multiple IPs in a Network using alias IPs.

IP Specification: If you specify an IP when attaching to a network, the Server's location must be covered by the Subnet's Network Zone. At minimum, one Subnet with a zone covering the Server's location must exist.

Reserved IPs (cannot be used):

• First IP of the network ip_range (default gateway for private interface)
• 172.31.1.1 (default gateway for public interface)

Coupling Dedicated Servers

Using vswitch subnets, you can couple Cloud Networks with existing Dedicated Server vSwitches. Dedicated servers must only use IPs from the subnet and require special network configuration. See Hetzner FAQ for details. vSwitch Layer 2 features are not supported.

Network Zones

Endpoints

Network Actions

Reserved IPs

• First IP of network range (default gateway)
• 172.31.1.1 (public network gateway)

Firewalls

Control network access to resources.

• No in rules = DROP all inbound (default for in: DROP)
• No out rules = ACCEPT all outbound (default for out: ACCEPT)

Endpoints

Firewall Actions

Load Balancers

Load Balancer types define kinds of Load Balancers offered. Each type has an hourly and monthly cost - you pay whichever is lower for your usage. Costs may differ between Locations.

All prices are displayed in the currency of the project owner's account.

Pricing includes:

• included_traffic - Traffic included in the price
• price_per_tb_traffic - Cost for additional traffic beyond included amount

Load Balancer Types

Endpoints

Load Balancer Actions

Floating IPs

IPs that can be reassigned between servers globally for high availability setups.

• Can reassign to servers in any location (globally routable)
• For optimal routing and latency, use Floating IPs in the location where they were created
• Must configure within your operating system - Floating IPs require manual OS network configuration to work
• IPv4: single address
• IPv6: /64 network (any IP within the network can be used)
• Billed monthly (regardless of assignment status)

Endpoints

Floating IP Actions

Primary IPs

IPs bound to a datacenter for flexible networking setups.

• One IPv4 and one IPv6 per server max
• Can only assign/unassign when server is powered off
• Bound to specific datacenter (cannot assign across datacenters - use Floating IPs for that)
• Works automatically with cloud-init
• IPv4: single address; IPv6: /64 network (any IP within can be used)
• Billed hourly

Endpoints

Primary IP Actions

DNS Zones

Manage DNS zones and records. Supports all zone names with well-known public suffixes (e.g., .de, .com, .co.uk). Subdomains are not supported.

Zone Modes

• Primary - Manage RRSets via API/Console. Hetzner automatically increases SOA record serial (YYYYMMDDnn format).
• Secondary - Hetzner nameservers query RRSets from given primary nameservers via AXFR.

Note: Zone mode cannot be changed after creation. Delete and recreate the zone to change modes.

Endpoints

Zone Actions

RRSets (Resource Record Sets)

The API operates on resource record sets (RRSets) instead of individual resource records (RRs). An RRSet is identified by a name and type. For example, these two RRs:

• (name: @, type: MX, value: 10 smtp.example.com.)
• (name: @, type: MX, value: 20 smtp-backup.example.com.)

...are part of the RRSet identified by (name: @, type: MX).

See Hetzner Docs for more information on record types.

RRSet Actions

Zone File Import

Zone file import (BIND RFC 1034/1035 format) is only for zones in primary mode.

Import Rules:

• $ORIGIN directive is optional but must match Zone name with ending dot
• $TTL directive is optional and sets default Zone TTL
• Only IN (internet) class records allowed
• Assigned Hetzner nameservers must be present as NS records
• SOA record must be present
• Comments for individual records are imported; standalone comments are discarded

Example Zone File:

$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. ; Comment preserved
@   IN  10800  NS    oxygen.ns.hetzner.com.
@   IN  10800  NS    helium.ns.hetzner.de.

SSH Keys

Public keys for server authentication. SSH keys are injected into Servers at creation time.

Strongly recommended: Use SSH keys instead of passwords to manage your Servers.

Endpoints

Certificates

TLS/SSL Certificates prove the identity of a Server and are used to encrypt client traffic.

Endpoints

Certificate Actions

Locations & Datacenters

Locations

Physical locations where servers are hosted.

Datacenters

Virtual datacenters within locations. Each Datacenter represents a virtual Datacenter which is made up of possibly many physical Datacenters where Servers are hosted.

See Hetzner Locations Docs for more details.

Placement Groups

Influence server placement for availability. By enforcing rules on where servers are placed, you can improve availability to fit your needs.

• Spread - All servers run on different physical hosts, decreasing the probability that multiple servers fail together

Endpoints

ISOs

Read-only DVD images for custom OS installation. While Hetzner recommends using their Image functionality, stock ISOs are provided for exotic OS installations.

On request, Hetzner support can upload a private ISO just for you. These are marked with type: private and only visible in your Project.

To attach an ISO to your Server, use POST /servers/{id}/actions/attach_iso.

ISO Types: public (standard) or private (uploaded by support for you)

ISO Response includes:

• architecture - x86 or arm
• deprecation - Optional object with announced and unavailable_after timestamps

Pricing

Get resource prices. VAT and currency are based on the Project owner's account.

curl https://api.hetzner.cloud/v1/pricing \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response includes:

• currency - Currency code (e.g., "EUR")
• vat_rate - VAT rate percentage (e.g., "19.00")

Price categories:

• Server types (hourly/monthly per location, plus traffic pricing)
• Load balancer types (hourly/monthly per location, plus traffic pricing)
• Primary IPs (hourly/monthly per location)
• Floating IPs (monthly per location)
• Images (per GB/month for snapshots)
• Volumes (per GB/month)
• Server backups (percentage of server cost, e.g., "20.00")

Both net and gross prices are included in all pricing responses.

Actions

All asynchronous operations return an Action object showing results and progress.

Note: The /actions list endpoint was deprecated in July 2023 and removed in January 2025. Use resource-specific action endpoints (e.g., /servers/{id}/actions) instead.

{
  "action": {
    "id": 42,
    "command": "start_resource",
    "status": "running",
    "started": "2024-01-30T23:55:00Z",
    "finished": null,
    "progress": 50,
    "resources": [{ "id": 42, "type": "server" }],
    "error": null
  }
}

Action Fields:

• id - Unique Action ID
• command - Command name (e.g., start_resource, create_server)
• status - Current status (e.g., running)
• progress - Progress percentage (0-100)
• started - Start timestamp
• finished - Completion timestamp (null while running)
• resources - Array of affected resources (id + type)
• error - Error object on failure with code and message

Get Actions by ID

# Get multiple actions by ID (the only remaining way to query /actions)
curl 'https://api.hetzner.cloud/v1/actions?id=42&id=43' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Get Action Status

curl https://api.hetzner.cloud/v1/actions/42 \
  -H 'Authorization: Bearer YOUR_TOKEN'