Hetzner Cloud API

https://docs.hetzner.cloud/reference/
Admin
Hetzner Cloud API is a RESTful API for managing cloud infrastructure including servers, storage...
Tokens:12,425
Snippets:77
Trust Score:9.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example Storage Boxes Response

Source: https://docs.hetzner.cloud/reference/hetzner

This is an example JSON response when retrieving a list of Storage Boxes. It includes an empty 'storage_boxes' array and pagination metadata.

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

--------------------------------

### Example Pagination Link header

Source: https://docs.hetzner.cloud/reference/hetzner

This example shows the format of the 'Link' header used for pagination in API responses. It includes URLs for previous, next, and last pages.

```http
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"

```

--------------------------------

### Example Labels for Resources

Source: https://docs.hetzner.cloud/reference/hetzner

Demonstrates the structure for attaching key/value labels to Hetzner Cloud resources. Ensure keys and values adhere to the specified format and length constraints.

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

```

--------------------------------

### Get Storage Boxes List

Source: https://docs.hetzner.cloud/reference/hetzner

Use this curl command to retrieve a list of all Storage Boxes within your Hetzner Cloud project. Ensure you replace the placeholder token with your actual API token.

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

--------------------------------

### Filter resources by label selector

Source: https://docs.hetzner.cloud/reference/hetzner

Use label selectors to filter resources based on their labels. Examples show how to include and exclude specific labels or combinations.

```text
env=production,type!=database
```

```text
env in (testing,staging)
```

```text
!type
```

--------------------------------

### Example JSON response with pagination

Source: https://docs.hetzner.cloud/reference/hetzner

This JSON structure illustrates how pagination information is included in the response body within the 'meta' object. It shows current page, items per page, and navigation links.

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

```

--------------------------------

### Get Storage Box by ID in Go

Source: https://docs.hetzner.cloud/reference/hetzner

Retrieves a specific Storage Box using its ID. Ensure the HCLOUD_TOKEN environment variable is set.

```Go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	storageBox, _, err := client.StorageBox.GetByID(ctx, 123)
}
```

--------------------------------

### resource_limit_exceeded Error Details

Source: https://docs.hetzner.cloud/reference/hetzner

Example of a 'resource_limit_exceeded' error, indicating that an account's limit for a specific resource has been reached.

```json
{
  "error": {
    "code": "resource_limit_exceeded",
    "message": "project limit exceeded",
    "details": {
      "limits": [
        {
          "name": "project_limit"
        }
      ]
    }
  }
}

```

--------------------------------

### Get Storage Box Subaccount Details

Source: https://docs.hetzner.cloud/reference/hetzner

Retrieves details of a specific subaccount for a Storage Box.

```APIDOC
## GET /storage_boxes/{id}/subaccounts/{subaccount_id}

### Description
Retrieves details of a specific subaccount for a Storage Box.

### Method
GET

### Endpoint
/storage_boxes/{id}/subaccounts/{subaccount_id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Storage Box.
- **subaccount_id** (string) - Required - The ID of the subaccount.
```

--------------------------------

### uniqueness_error Error Details

Source: https://docs.hetzner.cloud/reference/hetzner

Example of a 'uniqueness_error', returned when attempting to create a resource that violates a unique constraint.

```json
{
  "error": {
    "code": "uniqueness_error",
    "message": "SSH key with the same fingerprint already exists",
    "details": {
      "fields": [
        {
          "name": "public_key"
        }
      ]
    }
  }
}

```

--------------------------------

### Error Response Example

Source: https://docs.hetzner.cloud/reference/hetzner

API errors are indicated by HTTP status codes and include a JSON response with an error code, message, and optional details.

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

```

--------------------------------

### deprecated_api_endpoint Error Details

Source: https://docs.hetzner.cloud/reference/hetzner

Example of a 'deprecated_api_endpoint' error, signaling that the requested API endpoint has been removed or is no longer supported.

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

```

--------------------------------

### Get Storage Box by ID

Source: https://docs.hetzner.cloud/reference/hetzner

Retrieves a specific Storage Box by its unique identifier. This operation allows you to fetch details such as its name, type, location, access settings, and status.

```APIDOC
## GET /storage_boxes/{id}

### Description
Returns a specific Storage Box.

### Method
GET

### Endpoint
/storage_boxes/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the Storage Box.

### Responses
#### Success Response (200)
- **storage_box** (object) - Details of the Storage Box.
  - **id** (integer)
  - **name** (string)
  - **storage_box_type** (object)
  - **location** (object)
  - **access_settings** (object)
  - **snapshot_plan** (object)
  - **protection** (object)
  - **labels** (object)
  - **status** (string)
  - **username** (string)
  - **server** (string)
  - **system** (string)
  - **stats** (object)
  - **created** (string)

#### Response Example
```json
{
  "storage_box": {
    "id": 42,
    "name": "string",
    "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:00Z",
        "announced": "2023-06-01T00:00:00Z"
      }
    },
    "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": true,
      "samba_enabled": true,
      "ssh_enabled": true,
      "webdav_enabled": true,
      "zfs_enabled": true
    },
    "snapshot_plan": {
      "max_snapshots": 10,
      "minute": 30,
      "hour": 3,
      "day_of_week": 7,
      "day_of_month": null
    },
    "protection": {
      "delete": false
    },
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "status": "active",
    "username": "u12345",
    "server": "u1337.your-storagebox.de",
    "system": "FSN1-BX355",
    "stats": {
      "size": 1,
      "size_data": 1,
      "size_snapshots": 1
    },
    "created": "2016-01-30T23:55:00Z"
  }
}
```
```

--------------------------------

### Create Storage Box

Source: https://docs.hetzner.cloud/reference/hetzner

Creates a new Storage Box with specified name, location, type, labels, password, access settings, and SSH keys. The action is then waited upon for completion.

```go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	result, _, err := client.StorageBox.Create(ctx, hcloud.StorageBoxCreateOpts{
		Name:     "string",
		Location: &hcloud.Location{Name: "fsn1"},
		StorageBoxType: &hcloud.StorageBoxType{
			Name: "bx11",
		},
		Labels: map[string]string{
			"environment":    "prod",
			"example.com/my": "label",
			"just-a-key":     "",
		},
		Password: "my-password",
		AccessSettings: &hcloud.StorageBoxCreateOptsAccessSettings{
			ReachableExternally: hcloud.Ptr(false),
			SambaEnabled:        hcloud.Ptr(false),
			SSHEnabled:          hcloud.Ptr(false),
			WebDAVEnabled:       hcloud.Ptr(false),
			ZFSEnabled:          hcloud.Ptr(false),
		},
		SSHKeys: []*hcloud.SSHKey{
			{PublicKey: "ssh-rsa AAAjjk76kgf...Xt"},
		},
	})

	err = client.Action.WaitFor(ctx, result.Action)

	storageBox := result.StorageBox
}

```

--------------------------------

### List Storage Box Folders in Go

Source: https://docs.hetzner.cloud/reference/hetzner

Lists subfolders within a specified Storage Box. Requires the Storage Box ID and optionally a path. Ensure the HCLOUD_TOKEN environment variable is set.

```Go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	result, _, err := client.StorageBox.Folders(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxFoldersOpts{
		Path: ".",
	})

	folders := result.Folders
}
```

--------------------------------

### Create Storage Box

Source: https://docs.hetzner.cloud/reference/hetzner

Creates a new Storage Box with specified configuration including location, name, password, type, access settings, and SSH keys.

```APIDOC
## POST /storage/boxes

### Description
Creates a Storage Box.

### Method
POST

### Endpoint
/storage/boxes

### Parameters
#### Request Body
- **location** (string) - Required - ID or Name of Location.
- **name** (string) - Required - Name of the Storage Box.
- **password** (string) - Required - Password of the Storage Box.
- **storage_box_type** (string) - Required - ID or Name of the Storage Box Type.
- **access_settings** (object) - Optional - Access settings of the Storage Box.
- **labels** (object) - Optional - User-defined labels (`key/value` pairs) for the Resource.
- **ssh_keys** (array of strings) - Optional - SSH public keys in OpenSSH format to inject into the Storage Box.

### Request Example
```json
{
  "location": "fsn1",
  "name": "my-storage-box",
  "password": "my-secret-password",
  "storage_box_type": "bx20",
  "access_settings": {
    "ssh_enabled": true
  },
  "labels": {
    "environment": "production"
  },
  "ssh_keys": [
    "ssh-rsa AAAjjk76kgf...Xt"
  ]
}
```

### Response
#### Success Response (201)
- **storage_box** (object) - Details of the created Storage Box.
- **action** (object) - Details of the action performed.

#### Response Example
```json
{
  "storage_box": {
    "id": 42,
    "status": "initializing",
    "name": "my-resource",
    "username": "u45321",
    "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"
          }
        }
      ],
      "deprecation": null
    },
    "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": {
      "size": 0,
      "size_data": 0,
      "size_snapshots": 0
    },
    "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"
      }
    ],
    "error": null
  }
}
```
```

--------------------------------

### Go Code Snippet for Hetzner Cloud API

Source: https://docs.hetzner.cloud/reference/hetzner

This Go code snippet demonstrates how to interact with the Hetzner Cloud API. It includes placeholders for headers, query parameters, and response handling.

```Go
package main

import (
	"fmt"
	"net/http"
	"io/ioutil"
)

func main() {
	url := "YOUR_API_ENDPOINT"

	// Create a new HTTP client
	client := &http.Client{}

	// Create a new GET request
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	// Add headers
	req.Header.Add("Accept", "*/ * ")
	req.Header.Add("Key", "Value")

	// Add query parameters (example)
	query := req.URL.Query()
	query.Add("name", "Value")
	query.Add("label_selector", "Value")
	query.Add("sort", "Select a value")
	query.Add("page", "1")
	query.Add("per_page", "25")
	req.URL.RawQuery = query.Encode()

	// Send the request
	res, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer res.Body.Close()

	// Read the response body
	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println("Error reading response body:", err)
		return
	}

	// Print the response
	fmt.Println("Response Status:", res.Status)
	fmt.Println("Response Body:", string(body))
}

```

--------------------------------

### Sorting Storage Boxes by Multiple Fields

Source: https://docs.hetzner.cloud/reference/hetzner

Demonstrates sorting storage boxes by multiple fields: status in ascending order and command in descending order. This allows for more granular control over the returned data.

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

--------------------------------

### Storage Box Snapshots

Source: https://docs.hetzner.cloud/reference/hetzner

Manage Storage Box snapshots, including creating, retrieving, updating, and deleting them.

```APIDOC
## GET /storage_boxes/{id}/snapshots

### Description
Retrieves a list of all snapshots for a given Storage Box.

### Method
GET

### Endpoint
/storage_boxes/{id}/snapshots

## POST /storage_boxes/{id}/snapshots

### Description
Creates a new snapshot for a given Storage Box.

### Method
POST

### Endpoint
/storage_boxes/{id}/snapshots

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

### Description
Retrieves details of a specific Storage Box snapshot.

### Method
GET

### Endpoint
/storage_boxes/{id}/snapshots/{snapshot_id}

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

### Description
Updates a specific Storage Box snapshot.

### Method
PUT

### Endpoint
/storage_boxes/{id}/snapshots/{snapshot_id}

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

### Description
Deletes a specific Storage Box snapshot.

### Method
DELETE

### Endpoint
/storage_boxes/{id}/snapshots/{snapshot_id}
```

--------------------------------

### List Storage Boxes

Source: https://docs.hetzner.cloud/reference/hetzner

Retrieves a paginated list of all storage boxes associated with the account. Requires the HCLOUD_TOKEN environment variable to be set.

```go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	storageBoxes, err := client.StorageBox.All(ctx)
}
```

--------------------------------

### Query Parameters for Pagination

Source: https://docs.hetzner.cloud/reference/hetzner

Use query parameters like 'page' and 'page_size' to paginate API responses. Parameter names and values must be URI encoded.

```url
https://api.hetzner.com/v1/storage_boxes?page=1&page_size=12

```

--------------------------------

### List Storage Boxes

Source: https://docs.hetzner.cloud/reference/hetzner

This endpoint retrieves a list of all Storage Boxes associated with your Hetzner Cloud project. It requires an API token for authentication.

```APIDOC
## GET /v1/storage_boxes

### Description
Retrieves a list of all Storage Boxes in the project.

### Method
GET

### Endpoint
https://api.hetzner.com/v1/storage_boxes

### Parameters
#### Query Parameters
None explicitly documented.

#### Request Body
None.

### Request Example
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.hetzner.com/v1/storage_boxes
```

### Response
#### Success Response (200)
- **storage_boxes** (array) - A list of storage box objects.
- **meta** (object) - Contains pagination information.
  - **pagination** (object) - Pagination details.
    - **page** (integer) - Current page number.
    - **per_page** (integer) - Number of items per page.
    - **previous_page** (integer | null) - The previous page number or null if on the first page.
    - **next_page** (integer | null) - The next page number or null if on the last page.
    - **last_page** (integer) - The last page number.
    - **total_entries** (integer) - The total number of entries.

#### Response Example
```json
{
  "storage_boxes": [],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 25,
      "previous_page": null,
      "next_page": null,
      "last_page": 1,
      "total_entries": 0
    }
  }
}
```
```

--------------------------------

### List Storage Boxes

Source: https://docs.hetzner.cloud/reference/hetzner

Retrieves a list of all Storage Boxes associated with the project.

```APIDOC
## GET /storage_boxes

### Description
Lists all Storage Boxes for the project.

### Method
GET

### Endpoint
/storage_boxes

### Authentication
Required

### Auth Type
APIToken

### Bearer Token
Show Password
```

--------------------------------

### Sorting Storage Boxes by Status

Source: https://docs.hetzner.cloud/reference/hetzner

Demonstrates how to sort storage boxes by status in ascending order. Use this to retrieve a list of storage boxes ordered by their current status.

```http
https://api.hetzner.com/v1/storage_boxes?sort=status
```

--------------------------------

### Sorting Storage Boxes by Status (Descending)

Source: https://docs.hetzner.cloud/reference/hetzner

Illustrates how to sort storage boxes by status in descending order. Use this to see storage boxes with statuses that appear later in alphabetical or chronological order first.

```http
https://api.hetzner.com/v1/storage_boxes?sort=status:desc
```

--------------------------------

### Create Storage Box Subaccount

Source: https://docs.hetzner.cloud/reference/hetzner

Creates a new subaccount for a Storage Box.

```APIDOC
## POST /storage_boxes/{id}/subaccounts

### Description
Creates a new subaccount for a Storage Box.

### Method
POST

### Endpoint
/storage_boxes/{id}/subaccounts

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Storage Box.

#### Request Body
- **name** (string) - Required - The name of the subaccount.
- **password** (string) - Required - The password for the subaccount.
```

--------------------------------

### List Storage Boxes

Source: https://docs.hetzner.cloud/reference/hetzner

Returns a paginated list of Storage Boxes. You can filter by name, label selector, and sort the results. Pagination is supported via 'page' and 'per_page' query parameters.

```APIDOC
## GET /storage_boxes

### Description
Returns a paginated list of Storage Boxes.

### Method
GET

### Endpoint
/storage_boxes

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter resources by their name.
- **label_selector** (string) - Optional - Filter resources by labels.
- **sort** (array string[]) - Optional - Sort resources by field and direction. Possible values: `id`, `id:asc`, `id:desc`, `name`, `name:asc`, `name:desc`.
- **page** (integer) - Optional - Page number to return. Default: 1.
- **per_page** (integer) - Optional - Maximum number of entries returned per page. Default: 25.

### Response
#### Success Response (200)
- **storage_boxes** (array) - List of storage boxes.
- **meta** (object) - Pagination information.

#### Response Example
```json
{
  "storage_boxes": [
    {
      "id": 42,
      "name": "string",
      "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:00Z",
          "announced": "2023-06-01T00:00:00Z"
        }
      },
      "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": true,
        "samba_enabled": true,
        "ssh_enabled": true,
        "webdav_enabled": true,
        "zfs_enabled": true
      },
      "snapshot_plan": {
        "max_snapshots": 10,
        "minute": 30,
        "hour": 3,
        "day_of_week": 7,
        "day_of_month": null
      },
      "protection": {
        "delete": false
      },
      "labels": {
        "environment": "prod",
        "example.com/my": "label",
        "just-a-key": ""
      },
      "status": "active",
      "username": "u12345",
      "server": "u1337.your-storagebox.de",
      "system": "FSN1-BX355",
      "stats": {
        "size": 1,
        "size_data": 1,
        "size_snapshots": 1
      },
      "created": "2016-01-30T23:55:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 3,
      "per_page": 25,
      "previous_page": 2,
      "next_page": 4,
      "last_page": 4,
      "total_entries": 100
    }
  }
}
```
```

--------------------------------

### Sorting Storage Boxes by Status (Ascending)

Source: https://docs.hetzner.cloud/reference/hetzner

Shows how to explicitly sort storage boxes by status in ascending order. This is the default sort direction.

```http
https://api.hetzner.com/v1/storage_boxes?sort=status:asc
```

--------------------------------

### Storage Box Types

Source: https://docs.hetzner.cloud/reference/hetzner

Query available Storage Box types, including their costs and details.

```APIDOC
## GET /storage_box_types

### Description
Retrieves a list of all available Storage Box types.

### Method
GET

### Endpoint
/storage_box_types

## GET /storage_box_types/{id}

### Description
Retrieves details of a specific Storage Box type.

### Method
GET

### Endpoint
/storage_box_types/{id}
```

--------------------------------

### Storage Box Subaccount Actions

Source: https://docs.hetzner.cloud/reference/hetzner

Perform actions on Storage Box subaccounts, such as changing the home directory, resetting passwords, or updating access settings.

```APIDOC
## POST /storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory

### Description
Changes the home directory for a Storage Box subaccount.

### Method
POST

### Endpoint
/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory

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

### Description
Resets the password for a Storage Box subaccount.

### Method
POST

### Endpoint
/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/reset_subaccount_password

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

### Description
Updates the access settings for a Storage Box subaccount.

### Method
POST

### Endpoint
/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/update_access_settings
```

--------------------------------

### Query Parameters for Sorting

Source: https://docs.hetzner.cloud/reference/hetzner

Specify sorting criteria using the 'sort' query parameter. Multiple 'sort' parameters can be used for multi-level sorting.

```url
https://api.hetzner.com/v1/storage_boxes?sort=id&sort=name

```

--------------------------------

### Update a Storage Box

Source: https://docs.hetzner.cloud/reference/hetzner

Updates the name and labels of an existing Storage Box. Ensure the HCLOUD_TOKEN environment variable is set.

```Go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	storageBox, _, err := client.StorageBox.Update(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxUpdateOpts{
		Name: "string",
		Labels: map[string]string{
			"environment":    "prod",
			"example.com/my": "label",
			"just-a-key":     "",
		},
	})
}

```

--------------------------------

### List Storage Box Folders

Source: https://docs.hetzner.cloud/reference/hetzner

Retrieves a list of subfolders within a Storage Box. The location of the folders is determined by the `path` query parameter.

```APIDOC
## GET /storage_boxes/{id}/folders

### Description
Returns a list of (sub)folders in a Storage Box. The folder location is specified by the `path` query parameter.

### Method
GET

### Endpoint
/storage_boxes/{id}/folders

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the Storage Box.

#### Query Parameters
- **path** (string) - Optional - Relative path for which the listing is to be made. Defaults to ".".

### Response
#### Success Response (200)
- **folders** (array) - A list of folder names.

#### Response Example
```json
{
  "folders": [
    "offsite-backup",
    "photos"
  ]
}
```
```

--------------------------------

### Authentication

Source: https://docs.hetzner.cloud/reference/hetzner

All requests to the Hetzner API must be authenticated using an API token. Include your secret API token in the `Authorization` HTTP header as a Bearer token.

```APIDOC
## Authentication

All requests to the Hetzner API must be authenticated via an API token. Include your secret API token in every request you send to the API with the `Authorization` HTTP header.

**Example Authorization header**
```
Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj
```
```

--------------------------------

### List Storage Box Subaccounts

Source: https://docs.hetzner.cloud/reference/hetzner

Retrieves a list of all subaccounts associated with a specific Storage Box.

```APIDOC
## GET /storage_boxes/{id}/subaccounts

### Description
Retrieves a list of all subaccounts associated with a specific Storage Box.

### Method
GET

### Endpoint
/storage_boxes/{id}/subaccounts

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Storage Box.
```

--------------------------------

### Storage Box Response Schema

Source: https://docs.hetzner.cloud/reference/hetzner

This JSON schema represents a successful response (Status 201) when creating a Storage Box, detailing its properties, associated action, and configuration.

```json
{
  "storage_box": {
    "id": 42,
    "status": "initializing",
    "name": "my-resource",
    "username": "u45321",
    "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"
          }
        }
      ],
      "deprecation": null
    },
    "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": {
      "size": 0,
      "size_data": 0,
      "size_snapshots": 0
    },
    "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"
      }
    ],
    "error": null
  }
}

```

--------------------------------

### Query Parameters

Source: https://docs.hetzner.cloud/reference/hetzner

The API utilizes query parameters for sorting and filtering responses. Parameter names and values must be URI encoded. Parameters of type `array` can be used multiple times.

```APIDOC
## Query Parameters

The API makes use of query parameters to sort and filter responses. The parameter names and values must be URI encoded according to RFC2396. Query parameters of type `array` can be used multiple times:

**Example query parameters for pagination**
```
https://api.hetzner.com/v1/storage_boxes?page=1&page_size=12
```

**Example use of multiple values for a parameter**
```
https://api.hetzner.com/v1/storage_boxes?sort=id&sort=name
```

**Example use of an encoded parameter**
```
https://api.hetzner.com/v1/storage_boxes?label_selector=key%3Dvalue
```
```

--------------------------------

### Delete a Storage Box

Source: https://docs.hetzner.cloud/reference/hetzner

Deletes a specified Storage Box. The HCLOUD_TOKEN environment variable must be set. The operation waits for the deletion action to complete.

```Go
package examples

import (
	"context"
	"os"

	"github.com/hetznercloud/hcloud-go/v2/hcloud"
)

func main() {
	token := os.Getenv("HCLOUD_TOKEN")

	client := hcloud.NewClient(hcloud.WithToken(token))
	ctx := context.TODO()

	result, _, err := client.StorageBox.Delete(ctx, &hcloud.StorageBox{ID: 123})

	err = client.Action.WaitFor(ctx, result.Action)
}

```

--------------------------------

### API Authentication Header

Source: https://docs.hetzner.cloud/reference/hetzner

Include your secret API token in the Authorization HTTP header for all API requests.

```http
Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj

```

--------------------------------

### Update Storage Box Subaccount

Source: https://docs.hetzner.cloud/reference/hetzner

Updates an existing subaccount for a Storage Box. This can include changing the password or read-only permissions.

```APIDOC
## PUT /storage_boxes/{id}/subaccounts/{subaccount_id}

### Description
Updates an existing subaccount for a Storage Box. This can include changing the password or read-only permissions.

### Method
PUT

### Endpoint
/storage_boxes/{id}/subaccounts/{subaccount_id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Storage Box.
- **subaccount_id** (string) - Required - The ID of the subaccount.

#### Request Body
- **password** (string) - Optional - The new password for the subaccount.
- **read_only** (boolean) - Optional - Set to true to grant read-only access.
```

--------------------------------

### Storage Box JSON Schema

Source: https://docs.hetzner.cloud/reference/hetzner

Defines the structure of a Storage Box object returned by the API.

```JSON
{
  "storage_box": {
    "id": 42,
    "name": "string",
    "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:00Z",
        "announced": "2023-06-01T00:00:00Z"
      }
    },
    "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": true,
      "samba_enabled": true,
      "ssh_enabled": true,
      "webdav_enabled": true,
      "zfs_enabled": true
    },
    "snapshot_plan": {
      "max_snapshots": 10,
      "minute": 30,
      "hour": 3,
      "day_of_week": 7,
      "day_of_month": null
    },
    "protection": {
      "delete": false
    },
    "labels": {
      "environment": "prod",
      "example.com/my": "label",
      "just-a-key": ""
    },
    "status": "active",
    "username": "u12345",
    "server": "u1337.your-storagebox.de",
    "system": "FSN1-BX355",
    "stats": {
      "size": 1,
      "size_data": 1,
      "size_snapshots": 1
    },
    "created": "2016-01-30T23:55:00Z"
  }
}
```

--------------------------------

### Error Handling

Source: https://docs.hetzner.cloud/reference/hetzner

Errors are indicated by HTTP status codes. The response body contains an error code, message, and optional details. The schema of the error details object depends on the error code.

```APIDOC
## 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)  

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

### Error Codes

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

**invalid_input**
```json
{
  "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**
```json
{
  "error": {
    "code": "uniqueness_error",
    "message": "SSH key with the same fingerprint already exists",
    "details": {
      "fields": [
        {
          "name": "public_key"
        }
      ]
    }
  }
}
```

**resource_limit_exceeded**
```json
{
  "error": {
    "code": "resource_limit_exceeded",
    "message": "project limit exceeded",
    "details": {
      "limits": [
        {
          "name": "project_limit"
        }
      ]
    }
  }
}
```

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