canonical: https://jentic.com/apis/hetzner.cloud/hetzner-cloud

# Hetzner Cloud API

The Hetzner Cloud API is a RESTful interface for provisioning and managing servers, volumes, networks, load balancers, firewalls, floating IPs, and SSH keys in Hetzner's European cloud regions. It exposes 162 endpoints covering server lifecycle actions, image management, ISO mounting, placement groups, and metric collection, with project-scoped Bearer token authentication. Resources support label-based selection so agents can filter and act on fleets without tracking IDs manually.

## For AI agents

Provision Hetzner Cloud servers, attach volumes, configure networks and firewalls, and run lifecycle actions like reboot, resize, and snapshot via Bearer-token REST calls.

## Scope

Does not handle dedicated bare-metal servers, Hetzner Storage Box, DNS hosting, or domain registration - use for Hetzner Cloud project resources only.

## Capabilities

- Provision and resize Cloud Servers across Hetzner's Falkenstein, Nuremberg, Helsinki, Hillsboro, Ashburn, and Singapore locations
- Attach and detach block volumes, mount ISOs, and create on-demand snapshots and backups for running servers
- Configure private networks, subnets, routes, and floating IPs to isolate workloads at the project level
- Define stateful firewalls with inbound and outbound rules and apply them to servers via label selectors
- Provision and configure load balancers with targets, services, and health checks for HTTP and TCP traffic
- Trigger server actions such as power on, power off, reboot, rebuild from image, change protection, and rescue mode
- Query datacenters, server types, locations, pricing, and ISOs to plan deployments before committing resources

## Use cases

### Automated Server Provisioning

Provision Hetzner Cloud Servers on demand from CI pipelines or agent workflows by calling POST /servers with image, server_type, datacenter, and ssh_keys, then poll the returned action until status becomes success. Supports cloud-init user_data for first-boot configuration, automatic backups, and placement groups for spread or affinity. End-to-end provisioning typically completes in under 60 seconds.

Example prompt: Create a CPX21 server with image ubuntu-22.04 in datacenter fsn1-dc14, attach SSH key id 12345, then verify the create_server action completes with status success.

### Disaster Recovery and Backup

Use POST `/servers/{id}/actions/create_image` to capture snapshots before risky operations and POST `/servers/{id}/actions/enable_backup` to schedule daily backups retained for seven days. Snapshots and backups are stored as images that can be used to rebuild a server via the rebuild action, keeping recovery time to a few minutes.

Example prompt: Trigger create_image on server 98765 with type=snapshot and description=pre-deploy-snapshot, then confirm the resulting image is available via GET `/images/{id}.`

### Network Isolation and Security

Build private networks with POST /networks, attach servers via POST `/servers/{id}/actions/attach_to_network`, and apply firewalls created with POST /firewalls to control ingress and egress at the cloud edge. Label selectors let firewalls auto-apply to any server matching a tag, so newly provisioned servers inherit the right rules without extra calls.

Example prompt: Create a firewall named web-tier allowing TCP 80 and 443 inbound from 0.0.0.0/0, then apply it to all servers with label role=web using the apply_to_resources action.

### AI Agent Infrastructure Operations

Through Jentic, an AI agent can search for Hetzner operations by natural-language intent (e.g., 'create a server') and receive the input schema for POST /servers along with the required Bearer token reference. Jentic's vault holds the project-scoped API token, so the agent never sees the raw secret. Agents can chain actions - provision, attach volume, run rebuild - without bespoke SDK code.

Example prompt: Search Jentic for 'provision a cloud server', load the create_server schema, and execute it with image=debian-12, server_type=cx22, location=nbg1.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/servers` | Create a Cloud Server |
| GET | `/servers` | List servers, optionally filtered by label_selector |
| POST | `/servers/{id}/actions/create_image` | Create a snapshot or backup image of a server |
| POST | `/volumes` | Create a block storage volume |
| POST | `/firewalls` | Create a firewall with inbound and outbound rules |
| POST | `/load_balancers` | Create a load balancer with targets and services |
| GET | `/actions/{id}` | Get the status of a long-running action |

## Key resources

- **Servers** — Create, list, update, delete, and run lifecycle actions on Cloud Servers including reboot, resize, rebuild, and rescue
- **Volumes** — Provision block storage volumes and attach or detach them from servers
- **Networks** — Manage private networks, subnets, and routes for project-level isolation
- **Firewalls** — Define inbound and outbound rules and apply them to resources via label selectors
- **Load Balancers** — Provision load balancers with targets, services, and health checks for HTTP and TCP
- **Images** — List system images, snapshots, and backups, and rebuild servers from them
- **Actions** — Track the status of long-running operations such as create_server, create_image, and reboot

## Why Jentic

- **Setup:** Wiring the Hetzner Cloud API by hand means learning its bearer token auth, scoping tokens per project, and polling the /actions endpoints yourself to track long-running provisioning. Through Jentic you install once, import the Hetzner Cloud API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Hetzner puts the server and action id in the URL path (`/servers/{id}`, `/actions/{id}`), so a rule can pin your agent to acting on specific resources. You choose the operations it may call, so creating servers, volumes, firewalls, or load balancers is only included if you add it, while listing and reading actions stays separate.
- **Credential handling:** Your Hetzner bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time, scoped to its project. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'provision a cloud server' or 'attach a volume', and Jentic returns the matching Hetzner operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **DigitalOcean API** — DigitalOcean offers a similar developer-friendly cloud with Droplets, Spaces, and Kubernetes, primarily in US and Asia regions
- **Linode API** — Akamai Linode provides comparable VPS hosting with a global region footprint and managed Kubernetes
- **AWS API** — AWS covers managed databases, queues, and AI services that Hetzner does not provide natively

## FAQ

### What authentication does the Hetzner Cloud API use?

The Hetzner Cloud API uses Bearer token authentication. Tokens are project-scoped and generated in the Hetzner Cloud Console under Security > API Tokens, then sent as Authorization: Bearer <token>. Through Jentic, the token is held in the encrypted vault and never exposed to the agent's context - agents call operations via Jentic and receive only scoped results.

### Can I provision and configure a full server stack with the Hetzner Cloud API?

Yes. POST /servers creates a server with a chosen image, server_type, location, ssh_keys, networks, and user_data for cloud-init. You can chain calls to attach volumes (POST `/volumes/{id}/actions/attach`), join networks (POST `/servers/{id}/actions/attach_to_network`), and apply firewalls (POST `/firewalls/{id}/actions/apply_to_resources`) to bring up a complete stack.

### What are the rate limits for the Hetzner Cloud API?

The default limit is 3600 requests per hour per project, refilling at one request per second. Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers; exceeding the limit returns HTTP 429. Read-only tokens further restrict the endpoints that can be called.

### How do I use the Hetzner Cloud API for AI agent server provisioning through Jentic?

Install the SDK with pip install jentic, then search for 'provision a cloud server', load the schema for POST /servers, and execute with the required fields. Jentic resolves the Bearer token from the vault and returns the action object so the agent can poll until status becomes success.

### How does Hetzner handle long-running operations like creating snapshots?

Most write operations return an action object with a status field of 'running' or 'success'. Agents poll GET `/actions/{id}` until status is 'success' (or 'error'). Actions also have progress (0-100) so you can surface progress updates in a UI without re-issuing the original write request.

### Can I filter resources by label without managing IDs?

Yes. Resources accept key=value labels and most list endpoints support a label_selector query parameter using a small expression language (env=production, role in (web,api), !legacy). Firewalls can be applied to label-selected resources so newly created servers automatically inherit firewall rules.

### Can I limit what my agent is allowed to do with the Hetzner Cloud API?

Yes. Because you run Jentic One yourself, your own rules decide which Hetzner Cloud operations and which project-scoped token the agent may use. You can allow it to only list and read servers and actions while withholding writes such as POST /servers, POST /volumes, POST /firewalls, and POST /load_balancers, so provisioning is included only if you add it. Since Hetzner puts the resource id in the URL path (`/servers/{id}`, `/actions/{id}`), you can also pin the agent to acting on specific servers rather than the whole project.