Hetzner API Rust SDK

current version: 1.0.0

A Rust SDK for Hetzner APIs with a domain-oriented structure and typed error handling.

Documentation

• Full docs: docs/COMPREHENSIVE_DOCUMENTATION.md
• API reference: docs/API_REFERENCE.md
• Project-owned OpenAPI: openapi.json

API Coverage

cloud (openapi-backed)

• Full Hetzner Cloud OpenAPI operation coverage via generated methods on cloud()
• Hand-written typed surfaces for:
• servers.list
• servers.get
• servers.create (typed response: server, action, next_actions, root_password)
• actions.list (ID-filtered)
• actions.get

dns (legacy)

• GetAllZones
• GetAllRecords
• CreateRecord
• GetRecord
• UpdateRecord
• DeleteRecord
• CreateZone
• GetZone
• UpdateZone
• DeleteZone

Deprecation Notice

The legacy DNS API surface is now deprecated.

• Deprecated style: direct DNS methods on HetznerClient (for example client.get_all_zones()).
• Preferred style: domain APIs (for example client.dns().list_zones()).

Compatibility wrappers remain available for now and are marked deprecated in code.

Installation

[dependencies]
hetzner = "0.3.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Quick Start

use hetzner::HetznerClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HetznerClient::new("tbzcPCFQOYdvw5udQKYpaGeeT32GvUix2Iw7T6z0ZVy22c5EnmTVCxgkYOz8b4p5");

    // Legacy DNS domain usage (preferred over deprecated direct methods):
    let zones = client.dns().list_zones().await?;
    println!("{zones:#?}");

    Ok(())
}

Cloud Servers Example

use hetzner::{HetznerClient, ListServersParams};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HetznerClient::new("tbzcPCFQOYdvw5udQKYpaGeeT32GvUix2Iw7T6z0ZVy22c5EnmTVCxgkYOz8b4p5");

    let params = ListServersParams {
        per_page: Some(25),
        page: Some(1),
        ..Default::default()
    };

    let servers = client.cloud().servers().list(Some(&params)).await?;
    println!("{servers:#?}");

    Ok(())
}

Cloud Actions Example

use hetzner::{HetznerClient, ListActionsParams};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HetznerClient::new("tbzcPCFQOYdvw5udQKYpaGeeT32GvUix2Iw7T6z0ZVy22c5EnmTVCxgkYOz8b4p5");

    let actions = client
        .cloud()
        .actions()
        .list(&ListActionsParams { ids: vec![42, 43] })
        .await?;
    println!("{actions:#?}");

    Ok(())
}

Full OpenAPI Operation Example

All operations from hetzner-cloud-openapi.json are generated as methods on CloudApi using their operationId.

use hetzner::HetznerClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HetznerClient::new("tbzcPCFQOYdvw5udQKYpaGeeT32GvUix2Iw7T6z0ZVy22c5EnmTVCxgkYOz8b4p5");

    // operationId: list_servers
    let servers = client.cloud().list_servers(None, None).await?;

    // operationId: get_server
    let server = client.cloud().get_server(42_u64, None, None).await?;

    println!("{servers:#?}");
    println!("{server:#?}");
    Ok(())
}

API Facades

The SDK now exposes direct API groups for the areas you requested:

• client.dns() legacy DNS API (records/zones)
• client.cloud().servers_api() full Servers API (CRUD/actions/metrics)
• client.cloud().domains() Domain/Zone API (zones/rrsets)
• client.cloud().private_networks() Private Network API
• client.cloud().load_balancers() Load Balancer API
• client.cloud().storage() Storage API (volumes/images/isos)
• plus complete raw OpenAPI methods via client.cloud().<operation_id>(...)

Cloud API Example Request

Since a new project commonly has no servers yet, this is the expected empty list shape.

Example Request

curl -H "Authorization: Bearer tbzcPCFQOYdvw5udQKYpaGeeT32GvUix2Iw7T6z0ZVy22c5EnmTVCxgkYOz8b4p5" \
  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 to the Hetzner Cloud API must be authenticated with an API token.

Use this header:

Authorization: Bearer tbzcPCFQOYdvw5udQKYpaGeeT32GvUix2Iw7T6z0ZVy22c5EnmTVCxgkYOz8b4p5

To create a token: Hetzner Console -> Project -> Security -> API Tokens.

Error Handling

The SDK returns typed errors (HetznerError) and preserves API error payload details.

Hetzner API error payload shape:

• code: machine-parsable error identifier
• message: human-readable description
• details: optional object with code-specific fields

Example Error Payload

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

Common Error Codes

Actions

Actions are asynchronous tasks that may be returned when mutating resources.

• Wait until action state is success or error.
• Avoid aggressive polling to reduce rate limit pressure.
• Failed actions include additional error context.

Labels

Labels are key/value pairs on resources.

• Keys: optional DNS-like prefix + required name segment (prefix/name).
• Values: up to 63 chars, empty or alphanumeric-bounded with -, _, . allowed.
• Prefix hetzner.cloud/ is reserved.

Example Labels

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

Label Selector

Supported selectors include:

• k==v or k=v
• k!=v
• k
• !k
• k in (v1,v2,v3)
• k notin (v1,v2,v3)

Examples:

env=production,type!=database
env in (testing,staging)
!type

Pagination

List endpoints can support page and per_page (default 25, usually max 50).

Responses can include:

• meta.pagination in JSON
• Link header with prev, next, last

Example Pagination Payload

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

Rate Limiting

All requests are rate limited.

Headers:

• RateLimit-Limit
• RateLimit-Remaining
• RateLimit-Reset (UNIX timestamp)

Default limit is 3600 requests/hour per project, with gradual refill.

Server Metadata

In-server metadata endpoint:

• http://169.254.169.254/hetzner/v1/metadata

Available keys include:

• hostname
• instance-id
• public-ipv4
• private-networks
• availability-zone
• region

Sorting

Some list endpoints support repeated sort query params.

Examples:

https://api.hetzner.cloud/v1/actions?sort=status
https://api.hetzner.cloud/v1/actions?sort=status:asc
https://api.hetzner.cloud/v1/actions?sort=status:desc
https://api.hetzner.cloud/v1/actions?sort=status:asc&sort=command:desc

Structure

Current crate structure:

• client: transport, auth, request lifecycle
• error: typed SDK errors and API error envelopes
• types: shared response/resource models
• api::dns: DNS domain operations
• api::cloud: Cloud domain operations (servers first)
• api::cloud::enums: OpenAPI-derived enums for server status/sort and action status
• api::cloud::generated_ops: full OpenAPI-generated operation methods

This layout is intended to support additional Hetzner domains without flattening everything into one module.