Hetzner API

This is the official documentation for the Hetzner API.

Introduction

The Hetzner API operates over HTTPS and uses JSON as its data format. The API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.

Open source credits

If you are developing an open-source project that supports or intends to add support for Hetzner APIs, you may be eligible for a free one-time credit of up to € 50 / $ 50 on your account. Please contact us via the support page on your Console and let us know the following:

The name of the project you are working on
A short description of the project
Link to the project website or repo where the project is hosted
Affiliation with / role in the project (e.g. project maintainer)
Link to some other open-source work you have already done (if you have done so)

Note: We only consider rewards for projects that provide Hetzner-specific functionality or integrations. For example, our Object Storage exposes a standard S3 API without any Hetzner-specific extensions. Projects that focus solely on generic S3 capabilities (e.g., general S3 clients or SDKs) are not Hetzner-specific and are therefore not eligible for Hetzner Rewards.

Getting Started

To get started using the API you first need an API token. Sign in into the Hetzner Console choose a Project, go to Security → API Tokens, and generate a new token. Make sure to copy the token because it won’t be shown to you again. A token is bound to a Project, to interact with the API of another Project you have to create a new token inside the Project. Let’s say your new token is LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj.

You’re now ready to do your first request against the API. To get a list of all Storage Boxes in your Project, issue the example request on the right side using curl.

Make sure to replace the token in the example command with the token you have just created. Since your Project probably does not contain any Storage Boxes yet, the example response will look like the response on the right side. We will almost always provide a resource root like storage_boxes inside the example response. A response can also contain a meta object with information like Pagination.

Example Request

curl -H "Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj" \
  https://api.hetzner.com/v1/storage_boxes

Example Response

{
  "storage_boxes": [],
  "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 API must be authenticated via a API token. Include your secret API token in every request you send to the API with the Authorization HTTP header.

To create a new API token for your Project, switch into the Hetzner Console choose a Project, go to Security → API Tokens, and generate a new token.

Example Authorization header

Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj

Errors

Errors are indicated by HTTP status codes. Further, the response of the request which generated the error contains an error code, an error message, and, optionally, error details. The schema of the error details object depends on the error code.

The error response contains the following keys:

Keys	Meaning
`code`	Short string indicating the type of error (machine-parsable)
`message`	Textual description on what has gone wrong
`details`	An object providing for details on the error (schema depends on code)

Error Codes

Code	Description
`forbidden`	Insufficient permissions for this request
`unauthorized`	Request was made with an invalid or unknown token
`invalid_input`	Error while parsing or processing the input
`json_error`	Invalid JSON input in your request
`locked`	The item you are trying to access is locked (there is already an Action running)
`not_found`	Entity not found
`rate_limit_exceeded`	Error when sending too many requests
`resource_limit_exceeded`	Error when exceeding the maximum quantity of a resource for an account
`resource_unavailable`	The requested resource is currently unavailable (e.g. not available for order)
`server_error`	Error within the API backend
`service_error`	Error within a service
`uniqueness_error`	One or more of the objects fields must be unique
`protected`	The Action you are trying to start is protected for this resource
`maintenance`	Cannot perform operation due to maintenance
`conflict`	The resource has changed during the request, please retry
`unsupported_error`	The corresponding resource does not support the Action
`token_readonly`	The token is only allowed to perform GET requests
`unavailable`	A service or product is currently not available
`deprecated_api_endpoint`	The request can not be answered because the API functionality was removed
`timeout`	The request could not be answered in time, please retry
`method_not_allowed`	The request method is not allowed

Example response

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

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

Labels

Labels are key/value pairs that can be attached to all resources.

Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be a string of 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

Valid label values must be a string of 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.

The hetzner.cloud/ prefix is reserved and cannot be used.

Example Labels

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

Label Selector

For resources with labels, you can filter resources by their labels using the label selector query language.

Expression	Meaning
`k==v` / `k=v`	Value of key `k` does equal value `v`
`k!=v`	Value of key `k` does not equal value `v`
`k`	Key `k` is present
`!k`	Key `k` is not present
`k in (v1,v2,v3)`	Value of key `k` is `v1`, `v2`, or `v3`
`k notin (v1,v2,v3)`	Value of key `k` is neither `v1`, nor `v2`, nor `v3`
`k1==v,!k2`	Value of key `k1` is `v` and key `k2` is not present

Examples

Returns all resources that have a env=production label and that don't have a type=database label:

env=production,type!=database
Returns all resources that have a env=testing or env=staging label:

env in (testing,staging)
Returns all resources that don't have a type label:

!type

Pagination

Responses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:

A page parameter specifies the page to fetch. The number of the first page is 1.
A per_page parameter specifies the number of items returned per page. The default value is 25, the maximum value is 50 except otherwise specified in the documentation.

Responses contain a Link header with pagination information.

Additionally, if the response body is JSON and the root object is an object, that object has a pagination object inside the meta object with pagination information:

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.

Line breaks have been added for display purposes only and responses may only contain some of the above rel values.

Example Pagination

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

Example Pagination Link header

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

Rate Limiting

All requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a 429 Too Many Requests error. Burst requests are allowed. Responses contain several headers which provide information about your current rate limit status.

The RateLimit-Limit header contains the total number of requests you can perform per hour.
The RateLimit-Remaining header contains the number of requests remaining in the current rate limit time frame.
The RateLimit-Reset header contains a UNIX timestamp of the point in time when your rate limit will have recovered, and you will have the full number of requests available again.

The default limit is 3600 requests per hour and per Project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second.

Sorting

Some responses which return multiple items support sorting. If they do support sorting the documentation states which fields can be used for sorting. You specify sorting with the sort query string parameter. You can sort by multiple fields. You can set the sort direction by appending :asc or :desc to the field name. By default, ascending sorting is used.

Example: Sorting

https://api.hetzner.com/v1/storage_boxes?sort=status:asc
https://api.hetzner.com/v1/storage_boxes?sort=status:desc
https://api.hetzner.com/v1/storage_boxes?sort=status:asc&sort=command:desc

Deprecation Notices

You can find all announced deprecations in our Changelog.

Storage Boxes

Storage Boxes offer storage capacity for both small and large amounts of data. Any data you save in your Storage Box is saved on several disks configured in a RAID array, increasing redundancy and fault tolerance.

Please see Hetzner Docs for more details about Storage Boxes.

Password policy

This policy applies to both Storage Boxes and Storage Box Subaccounts.

The password must be between 12 and 128 characters long
The password can only contain these characters: a-z A-Z Ä Ö Ü ä ö ü ß 0-9 ^ ° ! § $ % / ( ) = ? + # - . , ; : ~ * @ { } _ &
The password must contain at least one upper case letter, one lower case letter, one number, and a special character
The password must not have appeared in any known data breach

List Storage Boxes

Returns a paginated list of Storage Boxes.

HTTP Request

GET /storage_boxes

Query Parameters

namestring
Filter resources by their name. The response will only contain the resources matching exactly the specified name.
label_selectorstring
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
sortarray of strings
Allowed: id id:asc id:desc name name:asc name:desc created created:asc created:desc stats.size stats.size:asc stats.size:desc stats.size_filesystem stats.size_filesystem:asc stats.size_filesystem:desc
Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
pageinteger (int64)
Default: 1
Page number to return. For more information, see "Pagination".
per_pageinteger (int64)
Default: 25
Maximum number of entries returned per page. For more information, see "Pagination".

Response

storage_boxesarray of objects required
metaobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "storage_boxes": [
    {
      "id": 42,
      "name": "string",
      "username": "u12345",
      "status": "active",
      "storage_box_type": {
        "id": 42,
        "name": "bx11",
        "description": "BX11",
        "snapshot_limit": 10,
        "automatic_snapshot_limit": 10,
        "subaccounts_limit": 200,
        "size": 1073741824,
        "prices": [
          {
            "location": "fsn1",
            "price_hourly": {
              "net": "1.0000",
              "gross": "1.1900"
            },
            "price_monthly": {
              "net": "1.0000",
              "gross": "1.1900"
            },
            "setup_fee": {
              "net": "1.0000",
              "gross": "1.1900"
            }
          }
        ],
        "deprecation": {
          "unavailable_after": "2023-09-01T00:00:00+00:00",
          "announced": "2023-06-01T00:00:00+00:00"
        }
      },
      "location": {
        "id": 42,
        "name": "fsn1",
        "description": "Falkenstein DC Park 1",
        "country": "DE",
        "city": "Falkenstein",
        "latitude": 50.47612,
        "longitude": 12.370071,
        "network_zone": "eu-central"
      },
      "access_settings": {
        "reachable_externally": false,
        "samba_enabled": false,
        "ssh_enabled": false,
        "webdav_enabled": false,
        "zfs_enabled": false
      },
      "server": "u1337.your-storagebox.de",
      "system": "FSN1-BX355",
      "stats": {
        "size": 0,
        "size_data": 0,
        "size_snapshots": 0
      },
      "labels": {
        "environment": "prod",
        "example.com/my": "label",
        "just-a-key": ""
      },
      "protection": {
        "delete": false
      },
      "snapshot_plan": {
        "max_snapshots": 10,
        "minute": 30,
        "hour": 3,
        "day_of_week": 7,
        "day_of_month": null
      },
      "created": "2016-01-30T23:55:00+00:00"
    }
  ],
  "meta": {
    "pagination": {
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "next_page": 4,
      "last_page": 4,
      "total_entries": 100
    }
  }
}

Create a Storage Box

Creates a Storage Box.

HTTP Request

POST /storage_boxes

Request

namestring required
Name of the Storage Box.
locationstring required
ID or Name of Location.
storage_box_typestring required
ID or Name of the Storage Box Type.
passwordstring required
Password of the Storage Box.

For more details, see the Storage Boxes password policy.
labelsobject
User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".
ssh_keysarray of strings
SSH public keys in OpenSSH format to inject into the Storage Box.
access_settingsobject
Access settings of the Storage Box.

Response

storage_boxobject required
actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"string","location":"fsn1","storage_box_type":"bx20","password":"string","labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"ssh_keys":["ssh-rsa AAAjjk76kgf...Xt"],"access_settings":{"reachable_externally":false,"samba_enabled":false,"ssh_enabled":false,"webdav_enabled":false,"zfs_enabled":false}}' \
	"https://api.hetzner.com/v1/storage_boxes"

Request

{
  "name": "string",
  "location": "fsn1",
  "storage_box_type": "bx20",
  "password": "string",
  "labels": {
    "environment": "prod",
    "example.com/my": "label",
    "just-a-key": ""
  },
  "ssh_keys": [
    "ssh-rsa AAAjjk76kgf...Xt"
  ],
  "access_settings": {
    "reachable_externally": false,
    "samba_enabled": false,
    "ssh_enabled": false,
    "webdav_enabled": false,
    "zfs_enabled": false
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "storage_box": {
    "id": 42,
    "status": "initializing",
    "name": "my-resource",
    "storage_box_type": {
      "id": 1,
      "name": "bx20",
      "description": "BX20",
      "snapshot_limit": 10,
      "automatic_snapshot_limit": 10,
      "subaccounts_limit": 100,
      "size": 1073741824,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "gross": "0.0061",
            "net": "0.0051"
          },
          "price_monthly": {
            "gross": "3.8080",
            "net": "3.2000"
          },
          "setup_fee": {
            "gross": "0.0000",
            "net": "0.0000"
          }
        }
      ]
    },
    "location": {
      "id": 1,
      "country": "DE",
      "city": "Falkenstein",
      "name": "fsn1",
      "network_zone": "eu-central",
      "latitude": 50.476119,
      "longitude": 12.370071,
      "description": "Falkenstein DC Park 1"
    },
    "access_settings": {
      "reachable_externally": false,
      "samba_enabled": false,
      "ssh_enabled": false,
      "webdav_enabled": false,
      "zfs_enabled": false
    },
    "server": null,
    "system": null,
    "stats": null,
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "protection": {
      "delete": false
    },
    "snapshot_plan": null,
    "created": "2016-01-30T23:50:00Z"
  },
  "action": {
    "id": 13,
    "command": "create",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00Z",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      }
    ]
  }
}

Get a Storage Box

Returns a specific Storage Box.

HTTP Request

GET /storage_boxes/{id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Response

storage_boxobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "storage_box": {
    "id": 42,
    "name": "string",
    "username": "u12345",
    "status": "active",
    "storage_box_type": {
      "id": 42,
      "name": "bx11",
      "description": "BX11",
      "snapshot_limit": 10,
      "automatic_snapshot_limit": 10,
      "subaccounts_limit": 200,
      "size": 1073741824,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000",
            "gross": "1.1900"
          },
          "price_monthly": {
            "net": "1.0000",
            "gross": "1.1900"
          },
          "setup_fee": {
            "net": "1.0000",
            "gross": "1.1900"
          }
        }
      ],
      "deprecation": {
        "unavailable_after": "2023-09-01T00:00:00+00:00",
        "announced": "2023-06-01T00:00:00+00:00"
      }
    },
    "location": {
      "id": 42,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "access_settings": {
      "reachable_externally": false,
      "samba_enabled": false,
      "ssh_enabled": false,
      "webdav_enabled": false,
      "zfs_enabled": false
    },
    "server": "u1337.your-storagebox.de",
    "system": "FSN1-BX355",
    "stats": {
      "size": 0,
      "size_data": 0,
      "size_snapshots": 0
    },
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "protection": {
      "delete": false
    },
    "snapshot_plan": {
      "max_snapshots": 10,
      "minute": 30,
      "hour": 3,
      "day_of_week": 7,
      "day_of_month": null
    },
    "created": "2016-01-30T23:55:00+00:00"
  }
}

Update a Storage Box

Updates a Storage Box.

HTTP Request

PUT /storage_boxes/{id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

namestring
Name of the Storage Box.
labelsobject
User-defined labels (key/value pairs) for the Resource.

Note that the set of Labels provided in the request will overwrite the existing one.

For more information, see "Labels".

Response

storage_boxobject required

Example request

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"name":"string","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID"

Request

{
  "name": "string",
  "labels": {
    "environment": "prod",
    "example.com/my": "label",
    "just-a-key": ""
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "storage_box": {
    "id": 42,
    "name": "string",
    "username": "u12345",
    "status": "active",
    "storage_box_type": {
      "id": 42,
      "name": "bx11",
      "description": "BX11",
      "snapshot_limit": 10,
      "automatic_snapshot_limit": 10,
      "subaccounts_limit": 200,
      "size": 1073741824,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000",
            "gross": "1.1900"
          },
          "price_monthly": {
            "net": "1.0000",
            "gross": "1.1900"
          },
          "setup_fee": {
            "net": "1.0000",
            "gross": "1.1900"
          }
        }
      ],
      "deprecation": {
        "unavailable_after": "2023-09-01T00:00:00+00:00",
        "announced": "2023-06-01T00:00:00+00:00"
      }
    },
    "location": {
      "id": 42,
      "name": "fsn1",
      "description": "Falkenstein DC Park 1",
      "country": "DE",
      "city": "Falkenstein",
      "latitude": 50.47612,
      "longitude": 12.370071,
      "network_zone": "eu-central"
    },
    "access_settings": {
      "reachable_externally": false,
      "samba_enabled": false,
      "ssh_enabled": false,
      "webdav_enabled": false,
      "zfs_enabled": false
    },
    "server": "u1337.your-storagebox.de",
    "system": "FSN1-BX355",
    "stats": {
      "size": 0,
      "size_data": 0,
      "size_snapshots": 0
    },
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "protection": {
      "delete": false
    },
    "snapshot_plan": {
      "max_snapshots": 10,
      "minute": 30,
      "hour": 3,
      "day_of_week": 7,
      "day_of_month": null
    },
    "created": "2016-01-30T23:55:00+00:00"
  }
}

Delete a Storage Box

Deletes a Storage Box.

HTTP Request

DELETE /storage_boxes/{id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Response

actionobject required

Example request

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID"

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "delete",
    "status": "success",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      }
    ],
    "error": null
  }
}

List folders of a Storage Box

Returns a list of (sub)folders in a Storage Box.

The folder location is specified by the path query parameter.

HTTP Request

GET /storage_boxes/{id}/folders

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Query Parameters

pathstring
Default: .
Relative path for which the listing is to be made.

Response

foldersarray of strings required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/folders"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "folders": [
    "offsite-backup",
    "photos"
  ]
}

Storage Box Actions

List Actions

Returns all Action objects.

HTTP Request

GET /storage_boxes/actions

Query Parameters

idarray of integers (int64)
Filter the actions by ID. Can be used multiple times. The response will only contain actions matching the specified IDs.
sortarray of strings
Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc
Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
statusarray of strings
Allowed: running success error
Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
pageinteger (int64)
Default: 1
Page number to return. For more information, see "Pagination".
per_pageinteger (int64)
Default: 25
Maximum number of entries returned per page. For more information, see "Pagination".

Response

actionsarray of objects required
metaobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/actions"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 42,
      "command": "start_resource",
      "status": "running",
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:55:00+00:00",
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "next_page": 4,
      "last_page": 4,
      "total_entries": 100
    }
  }
}

Get an Action

Returns a specific Action object.

HTTP Request

GET /storage_boxes/actions/{id}

Path Parameters

idinteger (int64) required
ID of the Action.

Response

actionobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/actions/$ID"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 42,
    "command": "start_resource",
    "status": "running",
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:55:00+00:00",
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

List Actions for a Storage Box

List all Actions related to a specific Storage Box.

HTTP Request

GET /storage_boxes/{id}/actions

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Query Parameters

sortarray of strings
Allowed: id id:asc id:desc command command:asc command:desc status status:asc status:desc started started:asc started:desc finished finished:asc finished:desc
Sort actions by field and direction. Can be used multiple times. For more information, see "Sorting".
statusarray of strings
Allowed: running success error
Filter the actions by status. Can be used multiple times. The response will only contain actions matching the specified statuses.
pageinteger (int64)
Default: 1
Page number to return. For more information, see "Pagination".
per_pageinteger (int64)
Default: 25
Maximum number of entries returned per page. For more information, see "Pagination".

Response

actionsarray of objects required
metaobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "actions": [
    {
      "id": 42,
      "command": "start_resource",
      "status": "running",
      "started": "2016-01-30T23:55:00+00:00",
      "finished": "2016-01-30T23:55:00+00:00",
      "progress": 100,
      "resources": [
        {
          "id": 42,
          "type": "server"
        }
      ],
      "error": {
        "code": "action_failed",
        "message": "Action failed"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "next_page": 4,
      "last_page": 4,
      "total_entries": 100
    }
  }
}

Get an Action for a Storage Box

Returns a specific Action object for a Storage Box.

HTTP Request

GET /storage_boxes/{id}/actions/{action_id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.
action_idinteger (int64) required
ID of the Action.

Response

actionobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions/$ACTION_ID"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "action": {
    "id": 42,
    "command": "start_resource",
    "status": "running",
    "started": "2016-01-30T23:55:00+00:00",
    "finished": "2016-01-30T23:55:00+00:00",
    "progress": 100,
    "resources": [
      {
        "id": 42,
        "type": "server"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Change Protection

Changes the protection configuration of a Storage Box.

HTTP Request

POST /storage_boxes/{id}/actions/change_protection

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

deleteboolean
Prevent the Resource from being deleted.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"delete":false}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions/change_protection"

Request

{
  "delete": false
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_protection",
    "status": "success",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      }
    ],
    "error": null
  }
}

Change Type

Changes the type of a Storage Box.

Upgrades or downgrades a Storage Box to another Storage Box Type.

It is not possible to downgrade to a Storage Box Type that offers less disk space than you are currently using.

HTTP Request

POST /storage_boxes/{id}/actions/change_type

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

storage_box_typestring required
ID or Name of the Storage Box Type.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"storage_box_type":"bx20"}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions/change_type"

Request

{
  "storage_box_type": "bx20"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_type",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Reset Password

Reset the password of a Storage Box.

HTTP Request

POST /storage_boxes/{id}/actions/reset_password

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

passwordstring required
Password of the Storage Box.

For more details, see the Storage Boxes password policy.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"password":"string"}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions/reset_password"

Request

{
  "password": "string"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "reset_password",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Update Access Settings

Update access settings of a primary Storage Box account.

This endpoints supports partial updates. Omitted optional parameters do not result in any changes to the respective properties.

HTTP Request

POST /storage_boxes/{id}/actions/update_access_settings

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

reachable_externallyboolean
Whether access from outside the Hetzner network is allowed.
samba_enabledboolean
Whether the Samba subsystem is enabled.
ssh_enabledboolean
Whether the SSH subsystem is enabled.
webdav_enabledboolean
Whether the WebDAV subsystem is enabled.
zfs_enabledboolean
Whether the ZFS snapshot folder is visible.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"reachable_externally":false,"samba_enabled":false,"ssh_enabled":false,"webdav_enabled":false,"zfs_enabled":false}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions/update_access_settings"

Request

{
  "reachable_externally": false,
  "samba_enabled": false,
  "ssh_enabled": false,
  "webdav_enabled": false,
  "zfs_enabled": false
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "update_access_settings",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Rollback Snapshot

Rolls back a Storage Box to the given Storage Box Snapshot.

This will remove all newer Storage Box Snapshot and irrevocably delete all data that was since written to the Storage Box.

HTTP Request

POST /storage_boxes/{id}/actions/rollback_snapshot

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

snapshotstring required
ID or Name of the Storage Box Snapshot.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"snapshot":"my-snapshot"}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions/rollback_snapshot"

Request

{
  "snapshot": "my-snapshot"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "rollback_snapshot",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      },
      {
        "id": 42,
        "type": "snapshot"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Disable Snapshot Plan

Disables the active Snapshot Plan of a Storage Box.

Existing Storage Box Snapshots created by the Snapshot Plan will not be delete, they must be removed manually.

HTTP Request

POST /storage_boxes/{id}/actions/disable_snapshot_plan

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions/disable_snapshot_plan"

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "disable_snapshot_plan",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Enable Snapshot Plan

Enables a Snapshot Plan for a Storage Box.

Once enabled, a Snapshot Plan will create Snapshots at predefined intervals. There can only ever be one Snapshot Plan. The existing Snapshot Plan will be deleted before a new one is set up.

Automatic Snapshots are retained until explicitly deleted by the user or the maximum snapshot count for the plan ("max_snapshots") is exceeded.

You can choose the specific time (UTC timezone), day of the week, and day of the month. The time-related options are cron like. Some typical use cases include:

Interval	Request body
Every day at 3 o'clock	`{"max_snapshots":10,"minute":0,"hour":3}`
Every Friday at 3 o'clock	`{"max_snapshots":10,"minute":0,"hour":3,"day_of_week": 5}`
On the first of every month at half past 6	`{"max_snapshots":10,"minute":30,"hour":6,"day_of_month": 1}`

HTTP Request

POST /storage_boxes/{id}/actions/enable_snapshot_plan

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

max_snapshotsinteger required
Maximum amount of Snapshots that will be created by this Snapshot Plan.

Older Snapshots will be deleted.
minuteinteger required
Minute when the Snapshot Plan is executed (UTC).
hourinteger required
Hour when the Snapshot Plan is executed (UTC).
day_of_weekinteger – nullable
Day of the week when the Snapshot Plan is executed.

Starts at 1 for Monday til 7 for Sunday. Null means every day.
day_of_monthinteger – nullable
Day of the month when the Snapshot Plan is executed.

Null means every day.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"max_snapshots":10,"minute":30,"hour":3,"day_of_week":7,"day_of_month":null}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/actions/enable_snapshot_plan"

Request

{
  "max_snapshots": 10,
  "minute": 30,
  "hour": 3,
  "day_of_week": 7,
  "day_of_month": null
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "enable_snapshot_plan",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Storage Box Subaccounts

You can create additional users for a Storage Box. FTP, FTPS, SFTP, SCP, SMB/CIFS, HTTPS, and WebDAV are all available as protocols for these users. Additional Subaccounts can only access a sub-directory of the main user, and they use the storage space of the main user. The main user will have complete access to the directories of all Subaccounts.

To access a Subaccount, you use the Subaccount's username and the domain of the Subaccount (e.g uXXXXX-subX.your-storagebox.de) instead of the main account's username.

It is possible to grant a Subaccount only read-access to a directory which prevents it from uploading, deleting, and modifying files.

Please note that each Subaccount requires its own authorized_keys file. You can find more detailed instructions here.

You can only delete a Subaccount's home directory if you have already deleted the Subaccount itself.

List Subaccounts

Returns a list of Storage Box Subaccount.

HTTP Request

GET /storage_boxes/{id}/subaccounts

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Query Parameters

label_selectorstring
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
sortarray of strings
Allowed: id id:asc id:desc created created:asc created:desc
Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
usernamestring
Filter Storage Box Subaccounts by username. The response will only contain the resources matching exactly the specified username.

Response

subaccountsarray of objects required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/subaccounts"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "subaccounts": [
    {
      "id": 42,
      "username": "u1337-sub1",
      "server": "u1337-sub1.your-storagebox.de",
      "home_directory": "my_backups/host01.my.company",
      "access_settings": {
        "samba_enabled": false,
        "ssh_enabled": true,
        "webdav_enabled": false,
        "reachable_externally": true,
        "readonly": false
      },
      "description": "host01 backup",
      "created": "2025-02-22:00:02.000Z",
      "labels": {
        "environment": "prod",
        "example.com/my": "label",
        "just-a-key": null
      },
      "storage_box": 42
    }
  ]
}

Create a Subaccount

Creates a Storage Box Subaccount.

A Storage Box Subaccount will use a separate home directory.

HTTP Request

POST /storage_boxes/{id}/subaccounts

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

home_directorystring required
Home directory of the Storage Box Subaccount.

The directory will be created if it doesn't exist yet.
passwordstring required
Password of the Storage Box Subaccount.

For more details, see the Storage Boxes password policy.
access_settingsobject
descriptionstring
A description of Storage Box Subaccount.
labelsobject
User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".

Response

subaccountobject required
actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"home_directory":"my-backup/server01","password":"string","access_settings":{"reachable_externally":false,"samba_enabled":false,"ssh_enabled":false,"webdav_enabled":false,"readonly":false},"description":"my-backup-server01","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/subaccounts"

Request

{
  "home_directory": "my-backup/server01",
  "password": "string",
  "access_settings": {
    "reachable_externally": false,
    "samba_enabled": false,
    "ssh_enabled": false,
    "webdav_enabled": false,
    "readonly": false
  },
  "description": "my-backup-server01",
  "labels": {
    "environment": "prod",
    "example.com/my": "label",
    "just-a-key": ""
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "subaccount": {
    "id": 42,
    "storage_box": 43
  },
  "action": {
    "id": 13,
    "command": "create_subaccount",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      },
      {
        "id": 43,
        "type": "storage_box_subaccount"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Get a Subaccount

Returns a specific Storage Box Subaccount.

HTTP Request

GET /storage_boxes/{id}/subaccounts/{subaccount_id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.
subaccount_idinteger (int64) required
ID of the Storage Box Subaccount.

Response

subaccountobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/subaccounts/$SUBACCOUNT_ID"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "subaccount": {
    "id": 42,
    "description": "my-backup-server01",
    "username": "u1337-sub1",
    "home_directory": "my-backup/server01",
    "server": "u1337-sub1.your-storagebox.de",
    "access_settings": {
      "reachable_externally": false,
      "samba_enabled": false,
      "ssh_enabled": false,
      "webdav_enabled": false,
      "readonly": false
    },
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "created": "2016-01-30T23:55:00+00:00",
    "storage_box": 42
  }
}

Update a Subaccount

Updates a Storage Box Subaccount.

HTTP Request

PUT /storage_boxes/{id}/subaccounts/{subaccount_id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.
subaccount_idinteger (int64) required
ID of the Storage Box Subaccount.

Request

labelsobject
User-defined labels (key/value pairs) for the Resource.

Note that the set of Labels provided in the request will overwrite the existing one.

For more information, see "Labels".
descriptionstring
A description of Storage Box Subaccount.

Response

subaccountobject required

Example request

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"labels":{"environment":"prod","example.com/my":"label","just-a-key":""},"description":"my-backup-server01"}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/subaccounts/$SUBACCOUNT_ID"

Request

{
  "labels": {
    "environment": "prod",
    "example.com/my": "label",
    "just-a-key": ""
  },
  "description": "my-backup-server01"
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "subaccount": {
    "id": 42,
    "description": "my-backup-server01",
    "username": "u1337-sub1",
    "home_directory": "my-backup/server01",
    "server": "u1337-sub1.your-storagebox.de",
    "access_settings": {
      "reachable_externally": false,
      "samba_enabled": false,
      "ssh_enabled": false,
      "webdav_enabled": false,
      "readonly": false
    },
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "created": "2016-01-30T23:55:00+00:00",
    "storage_box": 42
  }
}

Delete a Subaccount

Deletes a Storage Box Subaccount.

HTTP Request

DELETE /storage_boxes/{id}/subaccounts/{subaccount_id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.
subaccount_idinteger (int64) required
ID of the Storage Box Subaccount.

Response

actionobject required

Example request

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/subaccounts/$SUBACCOUNT_ID"

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "delete_subaccount",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      },
      {
        "id": 42,
        "type": "storage_box_subaccount"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Storage Box Subaccount Actions

Change Home Directory

Change the home directory of a Storage Box Subaccount.

HTTP Request

POST /storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory

Path Parameters

idinteger (int64) required
ID of the Storage Box.
subaccount_idinteger (int64) required
ID of the Storage Box Subaccount.

Request

home_directorystring required
Home directory of the Storage Box Subaccount.

The directory will be created if it doesn't exist yet.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"home_directory":"my-backup/server01"}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/subaccounts/$SUBACCOUNT_ID/actions/change_home_directory"

Request

{
  "home_directory": "my-backup/server01"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "change_home_directory",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      },
      {
        "id": 42,
        "type": "storage_box_subaccount"
      }
    ],
    "error": null
  }
}

Reset Password

Reset the password of a Storage Box Subaccount.

HTTP Request

POST /storage_boxes/{id}/subaccounts/{subaccount_id}/actions/reset_subaccount_password

Path Parameters

idinteger (int64) required
ID of the Storage Box.
subaccount_idinteger (int64) required
ID of the Storage Box Subaccount.

Request

passwordstring required
Password of the Storage Box Subaccount.

For more details, see the Storage Boxes password policy.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"password":"string"}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/subaccounts/$SUBACCOUNT_ID/actions/reset_subaccount_password"

Request

{
  "password": "string"
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "reset_subaccount_password",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      },
      {
        "id": 42,
        "type": "storage_box_subaccount"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Update Access Settings

Updates the access settings of a Storage Box Subaccount.

This endpoints supports partial updates. Omitted optional parameters do not result in any changes to the respective properties.

HTTP Request

POST /storage_boxes/{id}/subaccounts/{subaccount_id}/actions/update_access_settings

Path Parameters

idinteger (int64) required
ID of the Storage Box.
subaccount_idinteger (int64) required
ID of the Storage Box Subaccount.

Request

readonlyboolean
Whether the Subaccount is read-only.
reachable_externallyboolean
Whether access from outside the Hetzner network is allowed.
samba_enabledboolean
Whether the Samba subsystem is enabled.
ssh_enabledboolean
Whether the SSH subsystem is enabled.
webdav_enabledboolean
Whether the WebDAV subsystem is enabled.

Response

actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"readonly":false,"reachable_externally":false,"samba_enabled":false,"ssh_enabled":false,"webdav_enabled":false}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/subaccounts/$SUBACCOUNT_ID/actions/update_access_settings"

Request

{
  "readonly": false,
  "reachable_externally": false,
  "samba_enabled": false,
  "ssh_enabled": false,
  "webdav_enabled": false
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "update_access_settings",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      },
      {
        "id": 42,
        "type": "storage_box_subaccount"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Storage Box Snapshots

List Snapshots

Returns a list of Storage Box Snapshot.

Both snapshots created manually and by the snapshot plan are returned.

HTTP Request

GET /storage_boxes/{id}/snapshots

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Query Parameters

namestring
Filter resources by their name. The response will only contain the resources matching exactly the specified name.
label_selectorstring
Filter resources by labels. The response will only contain resources matching the label selector. For more information, see "Label Selector".
sortarray of strings
Allowed: id id:asc id:desc name name:asc name:desc created created:asc created:desc
Sort resources by field and direction. Can be used multiple times. For more information, see "Sorting".
is_automaticboolean
Filter wether a Storage Box Snapshot is automatic.

Response

snapshotsarray of objects required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/snapshots"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "snapshots": [
    {
      "id": 1,
      "stats": {
        "size": 2097152,
        "size_filesystem": 1048576
      },
      "is_automatic": false,
      "name": "2025-02-12T11-35-19",
      "description": "my-description",
      "created": "2025-02-12T11:35:19.000Z",
      "storage_box": 42,
      "labels": {
        "environment": "prod",
        "example.com/my": "label",
        "just-a-key": null
      }
    },
    {
      "id": 2,
      "stats": {
        "size": 2097152,
        "size_filesystem": 1048576
      },
      "is_automatic": true,
      "name": "snapshot-daily--2025-02-12T22-00-02",
      "description": "",
      "created": "2025-02-22:00:02.000Z",
      "storage_box": 42,
      "labels": {
        "environment": "prod",
        "example.com/my": "label",
        "just-a-key": null
      }
    }
  ]
}

Create a Snapshot

Creates a Storage Box Snapshot.

HTTP Request

POST /storage_boxes/{id}/snapshots

Path Parameters

idinteger (int64) required
ID of the Storage Box.

Request

descriptionstring
Description of the Storage Box Snapshot.
labelsobject
User-defined labels (key/value pairs) for the Resource. For more information, see "Labels".

Response

snapshotobject required
actionobject required

Example request

curl \
	-X POST \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"description":"snapshot-0001","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/snapshots"

Request

{
  "description": "snapshot-0001",
  "labels": {
    "environment": "prod",
    "example.com/my": "label",
    "just-a-key": ""
  }
}

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "snapshot": {
    "id": 42,
    "storage_box": 43
  },
  "action": {
    "id": 13,
    "command": "create_snapshot",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      },
      {
        "id": 43,
        "type": "storage_box_snapshot"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Get a Snapshot

Returns a specific Storage Box Snapshot.

HTTP Request

GET /storage_boxes/{id}/snapshots/{snapshot_id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.
snapshot_idinteger (int64) required
ID of the Storage Box Snapshot.

Response

snapshotobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/snapshots/$SNAPSHOT_ID"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "snapshot": {
    "id": 42,
    "name": "my-snapshot",
    "description": "snapshot-0001",
    "stats": {
      "size": 0,
      "size_filesystem": 0
    },
    "is_automatic": false,
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "created": "2016-01-30T23:55:00+00:00",
    "storage_box": 42
  }
}

Update a Snapshot

Updates a Storage Box Snapshot.

HTTP Request

PUT /storage_boxes/{id}/snapshots/{snapshot_id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.
snapshot_idinteger (int64) required
ID of the Storage Box Snapshot.

Request

descriptionstring
Description of the Storage Box Snapshot.
labelsobject
User-defined labels (key/value pairs) for the Resource.

Note that the set of Labels provided in the request will overwrite the existing one.

For more information, see "Labels".

Response

snapshotobject required

Example request

curl \
	-X PUT \
	-H "Authorization: Bearer $API_TOKEN" \
	-H "Content-Type: application/json" \
	-d '{"description":"snapshot-0001","labels":{"environment":"prod","example.com/my":"label","just-a-key":""}}' \
	"https://api.hetzner.com/v1/storage_boxes/$ID/snapshots/$SNAPSHOT_ID"

Request

{
  "description": "snapshot-0001",
  "labels": {
    "environment": "prod",
    "example.com/my": "label",
    "just-a-key": ""
  }
}

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "snapshot": {
    "id": 42,
    "name": "my-snapshot",
    "description": "snapshot-0001",
    "stats": {
      "size": 0,
      "size_filesystem": 0
    },
    "is_automatic": false,
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "created": "2016-01-30T23:55:00+00:00",
    "storage_box": 42
  }
}

Delete a Snapshot

Deletes a Storage Box Snapshot.

HTTP Request

DELETE /storage_boxes/{id}/snapshots/{snapshot_id}

Path Parameters

idinteger (int64) required
ID of the Storage Box.
snapshot_idinteger (int64) required
ID of the Storage Box Snapshot.

Response

actionobject required

Example request

curl \
	-X DELETE \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_boxes/$ID/snapshots/$SNAPSHOT_ID"

Response headers

Content-Type: application/json
Status: 201

Response sample

{
  "action": {
    "id": 13,
    "command": "delete_snapshot",
    "status": "running",
    "progress": 0,
    "started": "2016-01-30T23:50:00+00:00",
    "finished": null,
    "resources": [
      {
        "id": 42,
        "type": "storage_box"
      },
      {
        "id": 42,
        "type": "storage_box_snapshot"
      }
    ],
    "error": {
      "code": "action_failed",
      "message": "Action failed"
    }
  }
}

Storage Box Types

Storage Box Types define storage products of different sizes. Each type has an hourly and a monthly cost. You will pay whichever cost is lower for your usage of this specific Storage Box. Costs may differ between Locations.

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

List Storage Box Types

Returns a paginated list of Storage Box Types.

HTTP Request

GET /storage_box_types

Query Parameters

namestring
Filter resources by their name. The response will only contain the resources matching exactly the specified name.
pageinteger (int64)
Default: 1
Page number to return. For more information, see "Pagination".
per_pageinteger (int64)
Default: 25
Maximum number of entries returned per page. For more information, see "Pagination".

Response

storage_box_typesarray of objects required
metaobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_box_types"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "storage_box_types": [
    {
      "id": 42,
      "name": "bx11",
      "description": "BX11",
      "snapshot_limit": 10,
      "automatic_snapshot_limit": 10,
      "subaccounts_limit": 200,
      "size": 1073741824,
      "prices": [
        {
          "location": "fsn1",
          "price_hourly": {
            "net": "1.0000",
            "gross": "1.1900"
          },
          "price_monthly": {
            "net": "1.0000",
            "gross": "1.1900"
          },
          "setup_fee": {
            "net": "1.0000",
            "gross": "1.1900"
          }
        }
      ],
      "deprecation": {
        "unavailable_after": "2023-09-01T00:00:00+00:00",
        "announced": "2023-06-01T00:00:00+00:00"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "next_page": 4,
      "last_page": 4,
      "total_entries": 100
    }
  }
}

Get a Storage Box Type

Returns a specific Storage Box Type.

HTTP Request

GET /storage_box_types/{id}

Path Parameters

idinteger (int64) required
ID of the Storage Box Type.

Response

storage_box_typeobject required

Example request

curl \
	-H "Authorization: Bearer $API_TOKEN" \
	"https://api.hetzner.com/v1/storage_box_types/$ID"

Response headers

Content-Type: application/json
Status: 200

Response sample

{
  "storage_box_type": {
    "id": 42,
    "name": "bx11",
    "description": "BX11",
    "snapshot_limit": 10,
    "automatic_snapshot_limit": 10,
    "subaccounts_limit": 200,
    "size": 1073741824,
    "prices": [
      {
        "location": "fsn1",
        "price_hourly": {
          "net": "1.0000",
          "gross": "1.1900"
        },
        "price_monthly": {
          "net": "1.0000",
          "gross": "1.1900"
        },
        "setup_fee": {
          "net": "1.0000",
          "gross": "1.1900"
        }
      }
    ],
    "deprecation": {
      "unavailable_after": "2023-09-01T00:00:00+00:00",
      "announced": "2023-06-01T00:00:00+00:00"
    }
  }
}