Using the API - Hetzner Docs

Get your API token ready

In order to use the API, you will need an API token. Make sure to create a separate API token for each project, as each API token is bound to the project it was created in and cannot be used for other projects.

If you haven't created an API token yet, do this now. The getting started "Generating an API token" explains step by step how this is done. Make sure to copy and save the API token after it was created, as it will not be possible to view the token again.
In all example commands, $API_TOKEN will be used as a placeholder. Remember that you will have to replace $API_TOKEN with your actual API token. Example:
```
-H "Authorization: Bearer $API_TOKEN" \
```
```
-H "Authorization: Bearer jEheVytlAoFl7F8MqUQ7jAo2hOXASztX" \
```
Example project

Project 1

$API_TOKEN_1

2x

Server

2x

Primary IP

1x

Private Network

Project 2

$API_TOKEN_2

1x

Server

1x

Primary IP

1x

Firewall

To request information about the two servers in "Project 1", you will have to add $API_TOKEN_1 to the curl command:

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

Refer to the documentation

Go to the Cloud API documentation and use the menu bar on the left to navigate to the request that you would like to perform.

Depending on the action, you will have to make one of four requests.
The four request types
GET
Read
curl \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/{api-url-ending}'
Get information about available tariffs, a resource, a location, or something else
POST
Read & Write
curl \
-X POST \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"property":value,"property":value,...}' \
'https://api.hetzner.cloud/v1/{api-url-ending}'
Create new resources and/or configure them
PUT
Read & Write
curl \
-X PUT \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"property":value,"property":value,...}' \
'https://api.hetzner.cloud/v1/{api-url-ending}/{id}'
Update the properties of an existing resource
DELETE
Read & Write
curl \
-X DELETE \
-H "Authorization: Bearer $API_TOKEN" \
'https://api.hetzner.cloud/v1/{api-url-ending}/{id}'
Delete an existing resource

Copy the curl command

After you have navigated to the action that you would like to perform, look for "HTTP Request":

The basic structure of "HTTP Request" is <request-type> <api-url-ending>.

This tells you which curl request you will have to use. There is also an example for every request on the right of the API documentation. In this example ("HTTP Request": GET /servers), the curl command would look like this:
```
curl \
    -H "Authorization: Bearer $API_TOKEN" \
    'https://api.hetzner.cloud/v1/servers'
```
Note that you have to replace $API_TOKEN with your own API token.
The curl command explained
- -X {request-type} The first line usually specifies the type of request. However, for GET requests you do not need this line.
- -H "Authorization: Bearer $API_TOKEN" This line is where you have to add the API token. The API token is bound to a specific project. Therefore, this line defines in which project the request should be performed.
- For POST and PUT requests, you will sometimes need to define certain properties that are needed to create or modify a resource. A property could be a name ("name":"unique-name"), or a type ("type":"ipv4"), for example. To add this information, two additional lines are needed:

Add properties to a POST or PUT request

When you create a new resource, or update an existing one, you will probably want to specify certain properties, such as a name or location.

To get started quickly, you can simply copy the example curl on the right. The example curl includes the most essential properties, and you can simply edit the values, or delete properties that you don't want to specify. Note, however, that some properties are mandatory and you have to specify them in the curl command. To learn more about the properties, you can look at the explanations given below the "Request" caption. Mandatory properties are marked as required.

Instead of copying the curl command, you can also use the documentation below the "Request" caption. It gives you a list of all available properties along with their value type and a short description of what the property is used for.

property value
Description of the property

To add a property to the curl command, use this format:

curl \
   -X {request-type} \
   -H "Authorization: Bearer $API_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"property":value,"property":value,...}' \
   'https://api.hetzner.cloud/v1/{api-url-ending}'

The different value types:

value format

string "any-text"

integer 12

object {"property":value}

boolean true
false

nullable null
Example request
Create Resource X
Request
name string
Name of resource
resource_y integer
ID of Resource Y which you would like to add to Resource X
labels object
User-defined labels (key-value pairs)
delete boolean
If true, prevents the resource from being deleted
description string – nullable
Description of the resource
-d '{"name":"my-resource","resource_y":18,"labels":{"labelkey":"my-label"},"delete":true,"description":null}'
When it says array of ..., you can simply use the format "property":[value]. The individual values are separated by comma:

array of ... format

strings ["any-text","any-text"]

integers [12,43]

objects [{"property":value,"property":value}]

value	format
string	`"any-text"`
integer	`12`
object	`{"property":value}`
boolean	`true` `false`
nullable	`null`

array of ...	format
strings	`["any-text","any-text"]`
integers	`[12,43]`
objects	`[{"property":value,"property":value}]`

Query Parameters

Query parameters make it possible to refine the results that are shown for a request. For example, you could specify that only resources with a certain label should be returned.

Format to refine the results:
- A simple query parameter
  
  https://api.hetzner.cloud/v1/{api-url-ending}?parameter=value
- A query parameter with an enum value
  "enum values" are predefined values that you can just copy and paste to the URL.
  
  https://api.hetzner.cloud/v1/{api-url-ending}?parameter={enum-value}
- Two or more query parameters
  The first parameter that is added to the URL begins with a question mark ?. Every other parameter that follows begins with an "and" sign &.
  
  https://api.hetzner.cloud/v1/{api-url-ending}?parameter=value&parameter=value
If you want to refine the results to a certain request, you can refer to "Query Parameters". This section gives you a list of any parameters that are available for a specific request.

parameter value
Description of the parameter
Examples
- Label selectors
  Resources can have simple labels that only consist of the key part, and they can have key value pairs ("key=value"). You can filter your resources by specifying either the "key" only, or both the "key" and the "value".
  
  https://api.hetzner.cloud/v1/floating_ips?label_selector=env
  
  In this example, the request could return resources with labels such as env production , env testing , or with a simple env label. For more information, refer to the official documentation on label selectors.
- Sort
  In the example image above, it says that you can sort your resources by ID or by their creation date. To sort the results by ID in an ascending ("asc") order, you can simply copy and paste the corresponding enum value.
  
  https://api.hetzner.cloud/v1/floating_ips?sort=id:asc
  
  For more information, refer to the official documentation on sorting.
- Two parameters in one request
  
  https://api.hetzner.cloud/v1/floating_ips?label_selector=env&sort=id:asc

Execute the curl command

After you have copied and modified the curl command, make sure you have also added the correct API token. Then, execute the command using a command-line interface (CLI).

After you executed the command, you will get a response that will let you know if the request was successful. Any changes you make via the API are also displayed in the Cloud Console.

Next: