{ "openapi": "3.0.3", "info": { "title": "Hetzner API", "version": "1.0.0", "x-summary": "Manage Hetzner services and resources linked to them, such as Storage Boxes.\n", "description": "# Overview\n\nThis is the official documentation for the Hetzner API.\n\n## Introduction\n\nThe 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.\n\n### Open source credits\n\nIf 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](https://console.hetzner.com/support) and let us know the following:\n\n- The name of the project you are working on\n- A short description of the project\n- Link to the project website or repo where the project is hosted\n- Affiliation with / role in the project (e.g. project maintainer)\n- Link to some other open-source work you have already done (if you have done so)\n\n**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.\n\n## Getting Started\n\nTo get started using the API you first need an API token. Sign in into the [Hetzner Console](https://console.hetzner.com/) 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`.\n\nYou’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](https://curl.se/).\n\nMake 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](#description/pagination).\n\n**Example Request**\n\n```shell\ncurl -H \"Authorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj\" \\\n https://api.hetzner.com/v1/storage_boxes\n```\n\n**Example Response**\n\n```json\n{\n \"storage_boxes\": [],\n \"meta\": {\n \"pagination\": {\n \"page\": 1,\n \"per_page\": 25,\n \"previous_page\": null,\n \"next_page\": null,\n \"last_page\": 1,\n \"total_entries\": 0\n }\n }\n}\n```\n\n## Authentication\n\nAll 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.\n\nTo create a new API token for your Project, switch into the [Hetzner Console](https://console.hetzner.com/) choose a Project, go to `Security` → `API Tokens`, and generate a new token.\n\n**Example Authorization header**\n\n```http\nAuthorization: Bearer LRK9DAWQ1ZAEFSrCNEEzLCUwhYX1U3g7wMg4dTlkkDC96fyDuyJ39nVbVjCKSDfj\n```\n\n## Query Parameters\n\nThe API makes use of query parameters to sort and filter responses. The parameter names and values must be URI encoded according to [RFC2396](https://datatracker.ietf.org/doc/html/rfc2396). Query parameters of type `array` can be used multiple times:\n\n**Example query parameters for pagination**\n\n```\nhttps://api.hetzner.com/v1/storage_boxes?page=1&page_size=12\n```\n\n**Example use of multiple values for a parameter**\n\n```\nhttps://api.hetzner.com/v1/storage_boxes?sort=id&sort=name\n```\n\n**Example use of an encoded parameter**\n\n```\nhttps://api.hetzner.com/v1/storage_boxes?label_selector=key%3Dvalue\n```\n\n## Errors\n\nErrors 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.\n\nThe error response contains the following keys:\n\n| Keys | Meaning |\n| --------- | --------------------------------------------------------------------- |\n| `code` | Short string indicating the type of error (machine-parsable) |\n| `message` | Textual description on what has gone wrong |\n| `details` | An object providing for details on the error (schema depends on code) |\n\n**Example response**\n\n```json\n{\n \"error\": {\n \"code\": \"invalid_input\",\n \"message\": \"invalid input in field 'broken_field': is too long\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"broken_field\",\n \"messages\": [\"is too long\"]\n }\n ]\n }\n }\n}\n```\n\n### Error Codes\n\n| Status | Code | Description |\n| --- | --- | --- |\n| `400` | `json_error` | Invalid JSON input in your request. |\n| `401` | `unauthorized` | Request was made with an invalid or unknown token. |\n| `401` | `token_readonly` | The token is only allowed to perform GET requests. |\n| `403` | `forbidden` | Insufficient permissions for this request. |\n| `403` | `maintenance` | Cannot perform operation due to maintenance. |\n| `403` | `resource_limit_exceeded` | Error when exceeding the maximum quantity of a resource for an account. |\n| `404` | `not_found` | Entity not found. |\n| `405` | `method_not_allowed` | The request method is not allowed |\n| `409` | `uniqueness_error` | One or more of the objects fields must be unique. |\n| `409` | `conflict` | The resource has changed during the request, please retry. |\n| `410` | `deprecated_api_endpoint` | The API endpoint functionality was removed. |\n| `412` | `resource_unavailable` | The requested resource is currently unavailable (e.g. not available for order). |\n| `422` | `invalid_input` | Error while parsing or processing the input. |\n| `422` | `service_error` | Error within a service. |\n| `422` | `unsupported_error` | The corresponding resource does not support the Action. |\n| `423` | `locked` | The item you are trying to access is locked (there is already an Action running). |\n| `423` | `protected` | The Action you are trying to start is protected for this resource. |\n| `429` | `rate_limit_exceeded` | Error when sending too many requests. |\n| `500` | `server_error` | Error within the API backend. |\n| `503` | `unavailable` | A service or product is currently not available. |\n| `504` | `timeout` | The request could not be answered in time, please retry. |\n\n**invalid_input**\n\n```json\n{\n \"error\": {\n \"code\": \"invalid_input\",\n \"message\": \"invalid input in field 'broken_field': is too long\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"broken_field\",\n \"messages\": [\"is too long\"]\n }\n ]\n }\n }\n}\n```\n\n**uniqueness_error**\n\n```json\n{\n \"error\": {\n \"code\": \"uniqueness_error\",\n \"message\": \"SSH key with the same fingerprint already exists\",\n \"details\": {\n \"fields\": [\n {\n \"name\": \"public_key\"\n }\n ]\n }\n }\n}\n```\n\n**resource_limit_exceeded**\n\n```json\n{\n \"error\": {\n \"code\": \"resource_limit_exceeded\",\n \"message\": \"project limit exceeded\",\n \"details\": {\n \"limits\": [\n {\n \"name\": \"project_limit\"\n }\n ]\n }\n }\n}\n```\n\n**deprecated_api_endpoint**\n\n```json\n{\n \"error\": {\n \"code\": \"deprecated_api_endpoint\",\n \"message\": \"API functionality was removed\",\n \"details\": {\n \"announcement\": \"https://docs.hetzner.cloud/changelog#2023-07-20-foo-endpoint-is-deprecated\"\n }\n }\n}\n```\n\n## Actions\n\nActions represent asynchronous tasks within the API, targeting one or more resources. Triggering changes in the API may return a `running` action.\n\nAn action should be waited upon, until it reaches either the `success` or `error` state. Avoid polling the action's state too frequently to reduce the risk of exhausting your API requests and hitting the [rate limit](#description/rate-limiting).\n\nIf an action fails, it will contain details about the underlying error.\n\nOnce the asynchronous tasks have completed and the targeted resources are in a consistent state, the action is marked as succeeded.\n\nIn some cases, you may trigger multiple changes at once, and only wait for the returned actions at a later stage.\n\n## Labels\n\nLabels are `key/value` pairs that can be attached to all resources.\n\nValid 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 (`/`).\n\nValid 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.\n\nThe `hetzner.cloud/` prefix is reserved and cannot be used.\n\n**Example Labels**\n\n```json\n{\n \"labels\": {\n \"environment\": \"development\",\n \"service\": \"backend\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\"\n }\n}\n```\n\n## Label Selector\n\nFor resources with labels, you can filter resources by their labels using the label selector query language.\n\n| Expression | Meaning |\n| -------------------- | ---------------------------------------------------- |\n| `k==v` / `k=v` | Value of key `k` does equal value `v` |\n| `k!=v` | Value of key `k` does not equal value `v` |\n| `k` | Key `k` is present |\n| `!k` | Key `k` is not present |\n| `k in (v1,v2,v3)` | Value of key `k` is `v1`, `v2`, or `v3` |\n| `k notin (v1,v2,v3)` | Value of key `k` is neither `v1`, nor `v2`, nor `v3` |\n| `k1==v,!k2` | Value of key `k1` is `v` and key `k2` is not present |\n\n### Examples\n\n- Returns all resources that have a `env=production` label and that don't have a `type=database` label:\n\n `env=production,type!=database`\n\n- Returns all resources that have a `env=testing` or `env=staging` label:\n\n `env in (testing,staging)`\n\n- Returns all resources that don't have a `type` label:\n\n `!type`\n\n## Pagination\n\nResponses which return multiple items support pagination. If they do support pagination, it can be controlled with following query string parameters:\n\n- A `page` parameter specifies the page to fetch. The number of the first page is 1.\n- 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.\n\nResponses contain a `Link` header with pagination information.\n\nAdditionally, 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:\n\n**Example Pagination**\n\n```json\n{\n \"storage_boxes\": [...],\n \"meta\": {\n \"pagination\": {\n \"page\": 2,\n \"per_page\": 25,\n \"previous_page\": 1,\n \"next_page\": 3,\n \"last_page\": 4,\n \"total_entries\": 100\n }\n }\n}\n```\n\nThe 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.\n\n**Example Pagination Link header**\n\n```http\nLink: ; rel=\"prev\",\n ; rel=\"next\",\n ; rel=\"last\"\n```\n\nLine breaks have been added for display purposes only and responses may only contain some of the above `rel` values.\n\n## Rate Limiting\n\nAll 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.\n\n- The `RateLimit-Limit` header contains the total number of requests you can perform per hour.\n- The `RateLimit-Remaining` header contains the number of requests remaining in the current rate limit time frame.\n- 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.\n\nThe 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.\n\n## Sorting\n\nSome 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.\n\n**Example: Sorting**\n\n```\nhttps://api.hetzner.com/v1/storage_boxes?sort=status\nhttps://api.hetzner.com/v1/storage_boxes?sort=status:asc\nhttps://api.hetzner.com/v1/storage_boxes?sort=status:desc\nhttps://api.hetzner.com/v1/storage_boxes?sort=status:asc&sort=command:desc\n```\n\n## Deprecation Notices\n\nYou can find all announced deprecations in our [Changelog](/changelog).\n" }, "servers": [ { "url": "https://api.hetzner.com/v1" } ], "security": [ { "APIToken": [] } ], "tags": [ { "name": "Storage Boxes", "description": "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.\n\nPlease see [Hetzner Docs](https://docs.hetzner.com/storage/storage-box) for more details about Storage Boxes.\n\n

Password policy

\n\nThis policy applies to both Storage Boxes and Storage Box Subaccounts.\n\n- The password must be between 12 and 128 characters long\n- The password can only contain these characters: `a-z A-Z Ä Ö Ü ä ö ü ß 0-9 ^ ° ! § $ % / ( ) = ? + # - . , ; : ~ * @ { } _ &`\n- The password must contain at least one upper case letter, one lower case letter, one number, and a special character\n- The password must not have appeared in any known data breach\n" }, { "name": "Storage Box Actions" }, { "name": "Storage Box Subaccounts", "description": "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.\n\nTo 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.\n\nIt is possible to grant a Subaccount only read-access to a directory which prevents it from uploading, deleting, and modifying files.\n\nPlease note that each Subaccount requires its own `authorized_keys` file. You can find more detailed instructions [here](https://docs.hetzner.com/storage/storage-box/backup-space-ssh-keys/).\n\nThe home directory of a Subaccount may only contain the following characters: `a‑z`, `A‑Z`, `0‑9`, dots (`.`), slashes (`/`), underscores (`_`) and minus signs (`-`). It must also not begin with a slash. Nested sub‑directories are supported. Any required directories are created automatically if they do not yet exist. Please note that you can only delete a Subaccount's home directory if you have already deleted the Subaccount itself.\n" }, { "name": "Storage Box Subaccount Actions" }, { "name": "Storage Box Snapshots" }, { "name": "Storage Box Types", "description": "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.\n\nAll prices are displayed in the currency of the project owner's account.\n" } ], "paths": { "/storage_boxes": { "get": { "operationId": "list_storage_boxes", "summary": "List Storage Boxes", "description": "Returns a paginated list of [Storage Boxes](#tag/storage-boxes).\n", "tags": [ "Storage Boxes" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "name": "sort", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "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" ] } } }, { "description": "Page number to return. For more information, see \"[Pagination](#description/pagination)\".", "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 1, "example": 1 } }, { "description": "Maximum number of entries returned per page. For more information, see \"[Pagination](#description/pagination)\".", "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 25, "example": 25 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_boxes": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box](#tag/storage-boxes).\n", "type": "string" }, "storage_box_type": { "description": "Type of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "id": { "description": "ID of the [Storage Box Type](#tag/storage-box-types).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "bx11" }, "description": { "description": "Description of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "BX11" }, "snapshot_limit": { "description": "Maximum number of allowed manual snapshots.", "type": "integer", "nullable": true, "example": 10 }, "automatic_snapshot_limit": { "description": "Maximum number of snapshots created automatically by a snapshot plan.", "type": "integer", "nullable": true, "example": 10 }, "subaccounts_limit": { "description": "Maximum number of subaccounts.", "type": "integer", "example": 200 }, "size": { "description": "Available storage in bytes.", "type": "integer", "format": "int64", "example": 1073741824 }, "prices": { "description": "Price per [Location](#tag/locations).", "type": "array", "items": { "type": "object", "properties": { "location": { "description": "Name of the [Location](#tag/locations) the price is for.", "type": "string", "example": "fsn1" }, "price_hourly": { "description": "Hourly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "price_monthly": { "description": "Monthly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "setup_fee": { "description": "Setup fee in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] } }, "required": [ "location", "price_hourly", "price_monthly", "setup_fee" ] } }, "deprecation": { "title": "DeprecationInfo", "description": "Describes if, when and how the resource is deprecated. If this field is\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] } }, "required": [ "id", "name", "description", "snapshot_limit", "automatic_snapshot_limit", "subaccounts_limit", "size", "prices", "deprecation" ] }, "location": { "description": "Location of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "id": { "description": "ID of the [Location](#tag/locations).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Unique identifier of the [Location](#tag/locations).", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1" }, "description": { "description": "Human readable description of the [Location](#tag/locations).", "type": "string", "example": "Falkenstein DC Park 1" }, "country": { "description": "Country the [Location](#tag/locations) resides in.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "type": "string", "example": "Falkenstein" }, "latitude": { "description": "Latitude of the city closest to the [Location](#tag/locations).", "type": "number", "format": "double", "example": 50.47612 }, "longitude": { "description": "Longitude of the city closest to the [Location](#tag/locations).", "type": "number", "format": "double", "example": 12.370071 }, "network_zone": { "description": "Name of the Network Zone this [Location](#tag/locations) resides in.", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "eu-central" } }, "required": [ "id", "name", "description", "country", "city", "latitude", "longitude", "network_zone" ] }, "access_settings": { "description": "Access settings of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "zfs_enabled": { "description": "Whether the ZFS snapshot folder is visible.", "type": "boolean" } }, "required": [ "reachable_externally", "samba_enabled", "ssh_enabled", "webdav_enabled", "zfs_enabled" ] }, "snapshot_plan": { "description": "Details of the active snapshot plan.\n\nNot available if the `status` is `initializing`.\n", "type": "object", "properties": { "max_snapshots": { "description": "Maximum amount of Snapshots that will be created by this Snapshot Plan.\n\nOlder Snapshots will be deleted.\n", "type": "integer", "minimum": 1, "example": 10 }, "minute": { "description": "Minute when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 59, "example": 30 }, "hour": { "description": "Hour when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 23, "example": 3 }, "day_of_week": { "description": "Day of the week when the Snapshot Plan is executed.\n\nStarts at 1 for Monday til 7 for Sunday. Null means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 7, "example": 7 }, "day_of_month": { "description": "Day of the month when the Snapshot Plan is executed.\n\nNull means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 31, "example": null } }, "required": [ "max_snapshots", "minute", "hour", "day_of_week", "day_of_month" ], "nullable": true }, "protection": { "description": "Protection configuration for the Resource.", "type": "object", "properties": { "delete": { "description": "Prevent the Resource from being deleted.", "type": "boolean", "example": false } }, "required": [ "delete" ] }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "status": { "description": "Status of the [Storage Box](#tag/storage-boxes).", "type": "string", "enum": [ "active", "initializing", "locked" ] }, "username": { "description": "Primary username of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "u12345" }, "server": { "description": "FQDN of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "u1337.your-storagebox.de" }, "system": { "description": "Host system of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "FSN1-BX355" }, "stats": { "description": "Statistics of the [Storage Box](#tag/storage-boxes).\n", "type": "object", "properties": { "size": { "description": "Current disk usage in bytes.", "type": "integer", "format": "int64" }, "size_data": { "description": "Current disk usage for data in bytes.", "type": "integer", "format": "int64" }, "size_snapshots": { "description": "Current disk usage for snapshots in bytes.", "type": "integer", "format": "int64" } }, "required": [ "size", "size_data", "size_snapshots" ] }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "id", "name", "storage_box_type", "location", "access_settings", "snapshot_plan", "protection", "labels", "status", "username", "server", "system", "stats", "created" ] } }, "meta": { "title": "ListMeta", "type": "object", "properties": { "pagination": { "description": "See \"[Pagination](#description/pagination)\" for more information.", "type": "object", "properties": { "page": { "description": "Current page number.", "type": "integer", "format": "int64", "example": 3 }, "per_page": { "description": "Maximum number of entries returned per page.", "type": "integer", "format": "int64", "example": 25 }, "previous_page": { "description": "Page number of the previous page. Can be null if the current page is the first one.", "type": "integer", "format": "int64", "nullable": true, "example": 2 }, "next_page": { "description": "Page number of the next page. Can be null if the current page is the last one.", "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "last_page": { "description": "Page number of the last page available. Can be null if the current page is the last one.", "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "total_entries": { "description": "Total number of entries that exist for this query. Can be null if unknown.", "type": "integer", "format": "int64", "nullable": true, "example": 100 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "storage_boxes", "meta" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBoxes, err := client.StorageBox.All(ctx)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_boxes = client.storage_boxes.get_all()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box list" } ] }, "post": { "operationId": "create_storage_box", "summary": "Create a Storage Box", "description": "Creates a [Storage Box](#tag/storage-boxes).\n", "tags": [ "Storage Boxes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Name of the [Storage Box](#tag/storage-boxes).\n", "type": "string" }, "location": { "description": "ID or Name of [Location](#tag/locations).", "type": "string", "example": "fsn1" }, "storage_box_type": { "description": "ID or Name of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "bx20" }, "password": { "description": "Password of the [Storage Box](#tag/storage-boxes).\n\nFor more details, see the [Storage Boxes password policy](#tag/storage-boxes/password-policy).\n", "type": "string" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "ssh_keys": { "description": "SSH public keys in OpenSSH format to inject into the [Storage Box](#tag/storage-boxes).", "type": "array", "items": { "type": "string", "example": "ssh-rsa AAAjjk76kgf...Xt" } }, "access_settings": { "required": [], "description": "Access settings of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "zfs_enabled": { "description": "Whether the ZFS snapshot folder is visible.", "type": "boolean" } } } }, "required": [ "storage_box_type", "location", "name", "password" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_box": { "type": "object", "properties": { "id": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box](#tag/storage-boxes).\n", "type": "string" }, "storage_box_type": { "description": "Type of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "id": { "description": "ID of the [Storage Box Type](#tag/storage-box-types).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "bx11" }, "description": { "description": "Description of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "BX11" }, "snapshot_limit": { "description": "Maximum number of allowed manual snapshots.", "type": "integer", "nullable": true, "example": 10 }, "automatic_snapshot_limit": { "description": "Maximum number of snapshots created automatically by a snapshot plan.", "type": "integer", "nullable": true, "example": 10 }, "subaccounts_limit": { "description": "Maximum number of subaccounts.", "type": "integer", "example": 200 }, "size": { "description": "Available storage in bytes.", "type": "integer", "format": "int64", "example": 1073741824 }, "prices": { "description": "Price per [Location](#tag/locations).", "type": "array", "items": { "type": "object", "properties": { "location": { "description": "Name of the [Location](#tag/locations) the price is for.", "type": "string", "example": "fsn1" }, "price_hourly": { "description": "Hourly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "price_monthly": { "description": "Monthly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "setup_fee": { "description": "Setup fee in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] } }, "required": [ "location", "price_hourly", "price_monthly", "setup_fee" ] } }, "deprecation": { "title": "DeprecationInfo", "description": "Describes if, when and how the resource is deprecated. If this field is\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] } }, "required": [ "id", "name", "description", "snapshot_limit", "automatic_snapshot_limit", "subaccounts_limit", "size", "prices", "deprecation" ] }, "location": { "description": "Location of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "id": { "description": "ID of the [Location](#tag/locations).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Unique identifier of the [Location](#tag/locations).", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1" }, "description": { "description": "Human readable description of the [Location](#tag/locations).", "type": "string", "example": "Falkenstein DC Park 1" }, "country": { "description": "Country the [Location](#tag/locations) resides in.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "type": "string", "example": "Falkenstein" }, "latitude": { "description": "Latitude of the city closest to the [Location](#tag/locations).", "type": "number", "format": "double", "example": 50.47612 }, "longitude": { "description": "Longitude of the city closest to the [Location](#tag/locations).", "type": "number", "format": "double", "example": 12.370071 }, "network_zone": { "description": "Name of the Network Zone this [Location](#tag/locations) resides in.", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "eu-central" } }, "required": [ "id", "name", "description", "country", "city", "latitude", "longitude", "network_zone" ] }, "access_settings": { "description": "Access settings of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "zfs_enabled": { "description": "Whether the ZFS snapshot folder is visible.", "type": "boolean" } }, "required": [ "reachable_externally", "samba_enabled", "ssh_enabled", "webdav_enabled", "zfs_enabled" ] }, "snapshot_plan": { "description": "Details of the active snapshot plan.\n\nNot available if the `status` is `initializing`.\n", "type": "object", "properties": { "max_snapshots": { "description": "Maximum amount of Snapshots that will be created by this Snapshot Plan.\n\nOlder Snapshots will be deleted.\n", "type": "integer", "minimum": 1, "example": 10 }, "minute": { "description": "Minute when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 59, "example": 30 }, "hour": { "description": "Hour when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 23, "example": 3 }, "day_of_week": { "description": "Day of the week when the Snapshot Plan is executed.\n\nStarts at 1 for Monday til 7 for Sunday. Null means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 7, "example": 7 }, "day_of_month": { "description": "Day of the month when the Snapshot Plan is executed.\n\nNull means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 31, "example": null } }, "required": [ "max_snapshots", "minute", "hour", "day_of_week", "day_of_month" ], "nullable": true }, "protection": { "description": "Protection configuration for the Resource.", "type": "object", "properties": { "delete": { "description": "Prevent the Resource from being deleted.", "type": "boolean", "example": false } }, "required": [ "delete" ] }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "status": { "description": "Status of the [Storage Box](#tag/storage-boxes).", "type": "string", "enum": [ "active", "initializing", "locked" ] }, "username": { "description": "Primary username of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "u12345" }, "server": { "description": "FQDN of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "u1337.your-storagebox.de" }, "system": { "description": "Host system of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "FSN1-BX355" }, "stats": { "description": "Statistics of the [Storage Box](#tag/storage-boxes).\n", "type": "object", "properties": { "size": { "description": "Current disk usage in bytes.", "type": "integer", "format": "int64" }, "size_data": { "description": "Current disk usage for data in bytes.", "type": "integer", "format": "int64" }, "size_snapshots": { "description": "Current disk usage for snapshots in bytes.", "type": "integer", "format": "int64" } }, "required": [ "size", "size_data", "size_snapshots" ] }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "id", "name", "storage_box_type", "location", "access_settings", "snapshot_plan", "protection", "labels", "status", "username", "server", "system", "stats", "created" ] }, "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "storage_box", "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "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 } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.StorageBox.Create(ctx, hcloud.StorageBoxCreateOpts{\n\t\tName: \"string\",\n\t\tLocation: &hcloud.Location{Name: \"fsn1\"},\n\t\tStorageBoxType: &hcloud.StorageBoxType{\n\t\t\tName: \"bx11\",\n\t\t},\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t\tPassword: \"my-password\",\n\t\tAccessSettings: &hcloud.StorageBoxCreateOptsAccessSettings{\n\t\t\tReachableExternally: hcloud.Ptr(false),\n\t\t\tSambaEnabled: hcloud.Ptr(false),\n\t\t\tSSHEnabled: hcloud.Ptr(false),\n\t\t\tWebDAVEnabled: hcloud.Ptr(false),\n\t\t\tZFSEnabled: hcloud.Ptr(false),\n\t\t},\n\t\tSSHKeys: []*hcloud.SSHKey{\n\t\t\t{PublicKey: \"ssh-rsa AAAjjk76kgf...Xt\"},\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tstorageBox := result.StorageBox\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.locations import Location\nfrom hcloud.ssh_keys import SSHKey\nfrom hcloud.storage_box_types import StorageBoxType\nfrom hcloud.storage_boxes import StorageBoxAccessSettings\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.create(\n name=\"string\",\n location=Location(name=\"fsn1\"),\n storage_box_type=StorageBoxType(name=\"bx11\"),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n password=\"my-password\",\n access_settings=StorageBoxAccessSettings(\n reachable_externally=False,\n samba_enabled=False,\n ssh_enabled=False,\n webdav_enabled=False,\n zfs_enabled=False,\n ),\n ssh_keys=[SSHKey(public_key=\"ssh-rsa AAAjjk76kgf...Xt\")],\n)\n\nresponse.action.wait_until_finished()\n\nstorage_box = response.storage_box" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box create \\\n --name \"string\" \\\n --location \"fsn1\" \\\n --type \"bx21\" \\\n --password \"string\" \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\" \\\n --ssh-key \"some-ssh-key\" \\\n --ssh-key \"ssh-rsa AAAjjk76kgf...Xt\" \\\n --reachable-externally \\\n --enable-samba=false \\\n --enable-ssh=true \\\n --enable-webdav \\\n --enable-zfs" } ] } }, "/storage_boxes/{id}": { "get": { "operationId": "get_storage_box", "summary": "Get a Storage Box", "description": "Returns a specific [Storage Box](#tag/storage-boxes).\n", "tags": [ "Storage Boxes" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_box": { "type": "object", "properties": { "id": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box](#tag/storage-boxes).\n", "type": "string" }, "storage_box_type": { "description": "Type of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "id": { "description": "ID of the [Storage Box Type](#tag/storage-box-types).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "bx11" }, "description": { "description": "Description of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "BX11" }, "snapshot_limit": { "description": "Maximum number of allowed manual snapshots.", "type": "integer", "nullable": true, "example": 10 }, "automatic_snapshot_limit": { "description": "Maximum number of snapshots created automatically by a snapshot plan.", "type": "integer", "nullable": true, "example": 10 }, "subaccounts_limit": { "description": "Maximum number of subaccounts.", "type": "integer", "example": 200 }, "size": { "description": "Available storage in bytes.", "type": "integer", "format": "int64", "example": 1073741824 }, "prices": { "description": "Price per [Location](#tag/locations).", "type": "array", "items": { "type": "object", "properties": { "location": { "description": "Name of the [Location](#tag/locations) the price is for.", "type": "string", "example": "fsn1" }, "price_hourly": { "description": "Hourly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "price_monthly": { "description": "Monthly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "setup_fee": { "description": "Setup fee in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] } }, "required": [ "location", "price_hourly", "price_monthly", "setup_fee" ] } }, "deprecation": { "title": "DeprecationInfo", "description": "Describes if, when and how the resource is deprecated. If this field is\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] } }, "required": [ "id", "name", "description", "snapshot_limit", "automatic_snapshot_limit", "subaccounts_limit", "size", "prices", "deprecation" ] }, "location": { "description": "Location of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "id": { "description": "ID of the [Location](#tag/locations).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Unique identifier of the [Location](#tag/locations).", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1" }, "description": { "description": "Human readable description of the [Location](#tag/locations).", "type": "string", "example": "Falkenstein DC Park 1" }, "country": { "description": "Country the [Location](#tag/locations) resides in.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "type": "string", "example": "Falkenstein" }, "latitude": { "description": "Latitude of the city closest to the [Location](#tag/locations).", "type": "number", "format": "double", "example": 50.47612 }, "longitude": { "description": "Longitude of the city closest to the [Location](#tag/locations).", "type": "number", "format": "double", "example": 12.370071 }, "network_zone": { "description": "Name of the Network Zone this [Location](#tag/locations) resides in.", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "eu-central" } }, "required": [ "id", "name", "description", "country", "city", "latitude", "longitude", "network_zone" ] }, "access_settings": { "description": "Access settings of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "zfs_enabled": { "description": "Whether the ZFS snapshot folder is visible.", "type": "boolean" } }, "required": [ "reachable_externally", "samba_enabled", "ssh_enabled", "webdav_enabled", "zfs_enabled" ] }, "snapshot_plan": { "description": "Details of the active snapshot plan.\n\nNot available if the `status` is `initializing`.\n", "type": "object", "properties": { "max_snapshots": { "description": "Maximum amount of Snapshots that will be created by this Snapshot Plan.\n\nOlder Snapshots will be deleted.\n", "type": "integer", "minimum": 1, "example": 10 }, "minute": { "description": "Minute when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 59, "example": 30 }, "hour": { "description": "Hour when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 23, "example": 3 }, "day_of_week": { "description": "Day of the week when the Snapshot Plan is executed.\n\nStarts at 1 for Monday til 7 for Sunday. Null means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 7, "example": 7 }, "day_of_month": { "description": "Day of the month when the Snapshot Plan is executed.\n\nNull means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 31, "example": null } }, "required": [ "max_snapshots", "minute", "hour", "day_of_week", "day_of_month" ], "nullable": true }, "protection": { "description": "Protection configuration for the Resource.", "type": "object", "properties": { "delete": { "description": "Prevent the Resource from being deleted.", "type": "boolean", "example": false } }, "required": [ "delete" ] }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "status": { "description": "Status of the [Storage Box](#tag/storage-boxes).", "type": "string", "enum": [ "active", "initializing", "locked" ] }, "username": { "description": "Primary username of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "u12345" }, "server": { "description": "FQDN of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "u1337.your-storagebox.de" }, "system": { "description": "Host system of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "FSN1-BX355" }, "stats": { "description": "Statistics of the [Storage Box](#tag/storage-boxes).\n", "type": "object", "properties": { "size": { "description": "Current disk usage in bytes.", "type": "integer", "format": "int64" }, "size_data": { "description": "Current disk usage for data in bytes.", "type": "integer", "format": "int64" }, "size_snapshots": { "description": "Current disk usage for snapshots in bytes.", "type": "integer", "format": "int64" } }, "required": [ "size", "size_data", "size_snapshots" ] }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "id", "name", "storage_box_type", "location", "access_settings", "snapshot_plan", "protection", "labels", "status", "username", "server", "system", "stats", "created" ] } }, "required": [ "storage_box" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBox, _, err := client.StorageBox.GetByID(ctx, 123)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box = client.storage_boxes.get_by_id(123)" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box describe $STORAGEBOX" } ] }, "put": { "operationId": "update_storage_box", "summary": "Update a Storage Box", "description": "Updates a [Storage Box](#tag/storage-boxes).\n", "tags": [ "Storage Boxes" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Name of the [Storage Box](#tag/storage-boxes).\n", "type": "string" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } } } } } } }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_box": { "type": "object", "properties": { "id": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box](#tag/storage-boxes).\n", "type": "string" }, "storage_box_type": { "description": "Type of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "id": { "description": "ID of the [Storage Box Type](#tag/storage-box-types).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "bx11" }, "description": { "description": "Description of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "BX11" }, "snapshot_limit": { "description": "Maximum number of allowed manual snapshots.", "type": "integer", "nullable": true, "example": 10 }, "automatic_snapshot_limit": { "description": "Maximum number of snapshots created automatically by a snapshot plan.", "type": "integer", "nullable": true, "example": 10 }, "subaccounts_limit": { "description": "Maximum number of subaccounts.", "type": "integer", "example": 200 }, "size": { "description": "Available storage in bytes.", "type": "integer", "format": "int64", "example": 1073741824 }, "prices": { "description": "Price per [Location](#tag/locations).", "type": "array", "items": { "type": "object", "properties": { "location": { "description": "Name of the [Location](#tag/locations) the price is for.", "type": "string", "example": "fsn1" }, "price_hourly": { "description": "Hourly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "price_monthly": { "description": "Monthly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "setup_fee": { "description": "Setup fee in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] } }, "required": [ "location", "price_hourly", "price_monthly", "setup_fee" ] } }, "deprecation": { "title": "DeprecationInfo", "description": "Describes if, when and how the resource is deprecated. If this field is\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] } }, "required": [ "id", "name", "description", "snapshot_limit", "automatic_snapshot_limit", "subaccounts_limit", "size", "prices", "deprecation" ] }, "location": { "description": "Location of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "id": { "description": "ID of the [Location](#tag/locations).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Unique identifier of the [Location](#tag/locations).", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "fsn1" }, "description": { "description": "Human readable description of the [Location](#tag/locations).", "type": "string", "example": "Falkenstein DC Park 1" }, "country": { "description": "Country the [Location](#tag/locations) resides in.\n\nISO 3166-1 alpha-2 code of the country.\n", "type": "string", "example": "DE" }, "city": { "description": "Name of the closest city to the [Location](#tag/locations).\n\nCity name or city name and state in short form. E.g. `Falkenstein` or `Ashburn, VA`.\n", "type": "string", "example": "Falkenstein" }, "latitude": { "description": "Latitude of the city closest to the [Location](#tag/locations).", "type": "number", "format": "double", "example": 50.47612 }, "longitude": { "description": "Longitude of the city closest to the [Location](#tag/locations).", "type": "number", "format": "double", "example": 12.370071 }, "network_zone": { "description": "Name of the Network Zone this [Location](#tag/locations) resides in.", "type": "string", "pattern": "^[a-z0-9]+(-?[a-z0-9]*)*$", "example": "eu-central" } }, "required": [ "id", "name", "description", "country", "city", "latitude", "longitude", "network_zone" ] }, "access_settings": { "description": "Access settings of the [Storage Box](#tag/storage-boxes).", "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "zfs_enabled": { "description": "Whether the ZFS snapshot folder is visible.", "type": "boolean" } }, "required": [ "reachable_externally", "samba_enabled", "ssh_enabled", "webdav_enabled", "zfs_enabled" ] }, "snapshot_plan": { "description": "Details of the active snapshot plan.\n\nNot available if the `status` is `initializing`.\n", "type": "object", "properties": { "max_snapshots": { "description": "Maximum amount of Snapshots that will be created by this Snapshot Plan.\n\nOlder Snapshots will be deleted.\n", "type": "integer", "minimum": 1, "example": 10 }, "minute": { "description": "Minute when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 59, "example": 30 }, "hour": { "description": "Hour when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 23, "example": 3 }, "day_of_week": { "description": "Day of the week when the Snapshot Plan is executed.\n\nStarts at 1 for Monday til 7 for Sunday. Null means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 7, "example": 7 }, "day_of_month": { "description": "Day of the month when the Snapshot Plan is executed.\n\nNull means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 31, "example": null } }, "required": [ "max_snapshots", "minute", "hour", "day_of_week", "day_of_month" ], "nullable": true }, "protection": { "description": "Protection configuration for the Resource.", "type": "object", "properties": { "delete": { "description": "Prevent the Resource from being deleted.", "type": "boolean", "example": false } }, "required": [ "delete" ] }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "status": { "description": "Status of the [Storage Box](#tag/storage-boxes).", "type": "string", "enum": [ "active", "initializing", "locked" ] }, "username": { "description": "Primary username of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "u12345" }, "server": { "description": "FQDN of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "u1337.your-storagebox.de" }, "system": { "description": "Host system of the [Storage Box](#tag/storage-boxes).\n\nNot available if the `status` is `initializing`.\n", "type": "string", "nullable": true, "example": "FSN1-BX355" }, "stats": { "description": "Statistics of the [Storage Box](#tag/storage-boxes).\n", "type": "object", "properties": { "size": { "description": "Current disk usage in bytes.", "type": "integer", "format": "int64" }, "size_data": { "description": "Current disk usage for data in bytes.", "type": "integer", "format": "int64" }, "size_snapshots": { "description": "Current disk usage for snapshots in bytes.", "type": "integer", "format": "int64" } }, "required": [ "size", "size_data", "size_snapshots" ] }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "id", "name", "storage_box_type", "location", "access_settings", "snapshot_plan", "protection", "labels", "status", "username", "server", "system", "stats", "created" ] } }, "required": [ "storage_box" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBox, _, err := client.StorageBox.Update(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxUpdateOpts{\n\t\tName: \"string\",\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t})\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box = client.storage_boxes.update(\n storage_box=StorageBox(id=123),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n name=\"string\",\n)" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box update $STORAGEBOX --name \"My Storage Box\"\nhcloud storage-box add-label --overwrite $STORAGEBOX \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud storage-box remove-label $STORAGEBOX \\\n \"environment\" \"example.com\" \"just-a-key\"" } ] }, "delete": { "operationId": "delete_storage_box", "summary": "Delete a Storage Box", "description": "Deletes a [Storage Box](#tag/storage-boxes).\n", "tags": [ "Storage Boxes" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "delete", "status": "success", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": null } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.StorageBox.Delete(ctx, &hcloud.StorageBox{ID: 123})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.delete(\n storage_box=StorageBox(id=123),\n)\n\nresponse.action.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box delete $STORAGEBOX" } ] } }, "/storage_boxes/{id}/folders": { "get": { "operationId": "list_storage_box_folders", "summary": "List folders of a Storage Box", "description": "Returns a list of (sub)folders in a [Storage Box](#tag/storage-boxes).\n\nThe folder location is specified by the `path` query parameter.\n", "tags": [ "Storage Boxes" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "Relative path for which the listing is to be made.", "name": "path", "in": "query", "required": false, "schema": { "type": "string", "default": ".", "example": "./documents" } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "string" } } }, "required": [ "folders" ] }, "examples": { "default": { "description": "A list of directories the Storage Box contains.", "value": { "folders": [ "offsite-backup", "photos" ] } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.StorageBox.Folders(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxFoldersOpts{\n\t\tPath: \".\",\n\t})\n\n\tfolders := result.Folders\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.get_folders(\n storage_box=StorageBox(id=123),\n)\n\nfolders = response.folders" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box folders --path \"subfolder\" $STORAGEBOX" } ] } }, "/storage_boxes/actions": { "get": { "operationId": "list_storage_boxes_actions", "summary": "List Actions", "description": "Returns all Action objects.\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "Filter the actions by ID. May be used multiple times.\n\nThe response will only contain actions matching the specified IDs.\n", "name": "id", "in": "query", "required": false, "schema": { "type": "array", "items": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } }, { "description": "Sort actions by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "name": "sort", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "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" ] } } }, { "description": "Filter the actions by status. May be used multiple times.\n\nThe response will only contain actions matching the specified statuses.\n", "name": "status", "in": "query", "required": false, "schema": { "type": "array", "items": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] } } }, { "description": "Page number to return. For more information, see \"[Pagination](#description/pagination)\".", "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 1, "example": 1 } }, { "description": "Maximum number of entries returned per page. For more information, see \"[Pagination](#description/pagination)\".", "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 25, "example": 25 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionListResponseWithMeta", "type": "object", "properties": { "actions": { "type": "array", "items": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "meta": { "title": "ListMeta", "type": "object", "properties": { "pagination": { "description": "See \"[Pagination](#description/pagination)\" for more information.", "type": "object", "properties": { "page": { "description": "Current page number.", "type": "integer", "format": "int64", "example": 3 }, "per_page": { "description": "Maximum number of entries returned per page.", "type": "integer", "format": "int64", "example": 25 }, "previous_page": { "description": "Page number of the previous page. Can be null if the current page is the first one.", "type": "integer", "format": "int64", "nullable": true, "example": 2 }, "next_page": { "description": "Page number of the next page. Can be null if the current page is the last one.", "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "last_page": { "description": "Page number of the last page available. Can be null if the current page is the last one.", "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "total_entries": { "description": "Total number of entries that exist for this query. Can be null if unknown.", "type": "integer", "format": "int64", "nullable": true, "example": 100 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "actions", "meta" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tactions, err := client.StorageBox.Action.All(ctx, hcloud.ActionListOpts{})\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nactions = client.storage_boxes.actions.get_all()" } ] } }, "/storage_boxes/actions/{id}": { "get": { "operationId": "get_storage_boxes_action", "summary": "Get an Action", "description": "Returns a specific Action object.\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Action.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.Action.GetByID(ctx, 123)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.actions.get_by_id(123)" } ] } }, "/storage_boxes/{id}/actions": { "get": { "operationId": "list_storage_box_actions", "summary": "List Actions for a Storage Box", "description": "List all Actions related to a specific Storage Box.\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "Sort actions by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "name": "sort", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "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" ] } } }, { "description": "Filter the actions by status. May be used multiple times.\n\nThe response will only contain actions matching the specified statuses.\n", "name": "status", "in": "query", "required": false, "schema": { "type": "array", "items": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] } } }, { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "Page number to return. For more information, see \"[Pagination](#description/pagination)\".", "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 1, "example": 1 } }, { "description": "Maximum number of entries returned per page. For more information, see \"[Pagination](#description/pagination)\".", "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 25, "example": 25 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionListResponseWithMeta", "type": "object", "properties": { "actions": { "type": "array", "items": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "meta": { "title": "ListMeta", "type": "object", "properties": { "pagination": { "description": "See \"[Pagination](#description/pagination)\" for more information.", "type": "object", "properties": { "page": { "description": "Current page number.", "type": "integer", "format": "int64", "example": 3 }, "per_page": { "description": "Maximum number of entries returned per page.", "type": "integer", "format": "int64", "example": 25 }, "previous_page": { "description": "Page number of the previous page. Can be null if the current page is the first one.", "type": "integer", "format": "int64", "nullable": true, "example": 2 }, "next_page": { "description": "Page number of the next page. Can be null if the current page is the last one.", "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "last_page": { "description": "Page number of the last page available. Can be null if the current page is the last one.", "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "total_entries": { "description": "Total number of entries that exist for this query. Can be null if unknown.", "type": "integer", "format": "int64", "nullable": true, "example": 100 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "actions", "meta" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ] } }, "/storage_boxes/{id}/actions/{action_id}": { "get": { "operationId": "get_storage_box_action", "summary": "Get an Action for a Storage Box", "description": "Returns a specific Action object for a Storage Box.\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Action.", "name": "action_id", "in": "path", "required": true, "schema": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ] } }, "/storage_boxes/{id}/actions/change_protection": { "post": { "operationId": "change_storage_box_protection", "summary": "Change Protection", "description": "Changes the protection configuration of a [Storage Box](#tag/storage-boxes).\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Protection configuration for the Resource.", "type": "object", "properties": { "delete": { "description": "Prevent the Resource from being deleted.", "type": "boolean", "example": false } } } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "change_protection", "status": "success", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": null } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.ChangeProtection(ctx, &hcloud.StorageBox{ID: 123},\n\t\thcloud.StorageBoxChangeProtectionOpts{Delete: hcloud.Ptr(true)})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.change_protection(\n storage_box=StorageBox(id=123),\n delete=True,\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box enable-protection $STORAGEBOX delete\nhcloud storage-box disable-protection $STORAGEBOX delete" } ] } }, "/storage_boxes/{id}/actions/change_type": { "post": { "operationId": "change_storage_box_type", "summary": "Change Type", "description": "Changes the type of a [Storage Box](#tag/storage-boxes).\n\nUpgrades or downgrades a [Storage Box](#tag/storage-boxes) to another [Storage Box Type](#tag/storage-box-types).\n\nIt is not possible to downgrade to a [Storage Box Type](#tag/storage-box-types) that offers less disk space\nthan you are currently using.\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_box_type": { "description": "ID or Name of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "bx20" } }, "required": [ "storage_box_type" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "change_type", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.ChangeType(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxChangeTypeOpts{\n\t\tStorageBoxType: &hcloud.StorageBoxType{Name: \"bx21\"},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_box_types import StorageBoxType\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.change_type(\n storage_box=StorageBox(id=123), storage_box_type=StorageBoxType(name=\"bx21\")\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box change-type $STORAGEBOX bx21" } ] } }, "/storage_boxes/{id}/actions/reset_password": { "post": { "operationId": "reset_storage_box_password", "summary": "Reset Password", "description": "Reset the password of a [Storage Box](#tag/storage-boxes).\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "description": "Password of the [Storage Box](#tag/storage-boxes).\n\nFor more details, see the [Storage Boxes password policy](#tag/storage-boxes/password-policy).\n", "type": "string" } }, "required": [ "password" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "reset_password", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.ResetPassword(ctx, &hcloud.StorageBox{ID: 123},\n\t\thcloud.StorageBoxResetPasswordOpts{Password: \"string\"})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.reset_password(\n storage_box=StorageBox(id=123), password=\"string\"\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box reset-password --password \"new-password\" $STORAGEBOX" } ] } }, "/storage_boxes/{id}/actions/update_access_settings": { "post": { "operationId": "update_storage_box_access_settings", "summary": "Update Access Settings", "description": "Update access settings of a primary [Storage Box](#tag/storage-boxes) account.\n\nThis endpoints supports partial updates. Omitted optional parameters do not result in any changes to the respective properties.\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "zfs_enabled": { "description": "Whether the ZFS snapshot folder is visible.", "type": "boolean" } } } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "update_access_settings", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.UpdateAccessSettings(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxUpdateAccessSettingsOpts{\n\t\tReachableExternally: hcloud.Ptr(false),\n\t\tSambaEnabled: hcloud.Ptr(false),\n\t\tSSHEnabled: hcloud.Ptr(false),\n\t\tWebDAVEnabled: hcloud.Ptr(false),\n\t\tZFSEnabled: hcloud.Ptr(false),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxAccessSettings\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.update_access_settings(\n storage_box=StorageBox(id=123),\n access_settings=StorageBoxAccessSettings(\n reachable_externally=False,\n samba_enabled=False,\n ssh_enabled=False,\n webdav_enabled=False,\n zfs_enabled=False,\n ),\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box update-access-settings $STORAGEBOX \\\n --reachable-externally \\\n --enable-samba=false \\\n --enable-ssh=true \\\n --enable-webdav \\\n --enable-zfs" } ] } }, "/storage_boxes/{id}/actions/rollback_snapshot": { "post": { "operationId": "rollback_storage_box_snapshot", "summary": "Rollback Snapshot", "description": "Rolls back a [Storage Box](#tag/storage-boxes) to the given [Storage Box Snapshot](#tag/storage-box-snapshots).\n\nThis will remove all newer [Storage Box Snapshot](#tag/storage-box-snapshots) and\nirrevocably delete all data that was since written to the [Storage Box](#tag/storage-boxes).\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot": { "description": "ID or Name of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "example": "my-snapshot" } }, "required": [ "snapshot" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "rollback_snapshot", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" }, { "id": 42, "type": "snapshot" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.RollbackSnapshot(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxRollbackSnapshotOpts{\n\t\tSnapshot: &hcloud.StorageBoxSnapshot{Name: \"my-snapshot\"},\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSnapshot\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.rollback_snapshot(\n storage_box=StorageBox(id=123), snapshot=StorageBoxSnapshot(name=\"my-snapshot\")\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box rollback-snapshot --snapshot \"my-snapshot\" $STORAGEBOX" } ] } }, "/storage_boxes/{id}/actions/disable_snapshot_plan": { "post": { "operationId": "disable_storage_box_snapshot_plan", "summary": "Disable Snapshot Plan", "description": "Disables the active Snapshot Plan of a [Storage Box](#tag/storage-boxes).\n\nExisting [Storage Box Snapshots](#tag/storage-box-snapshots) created by the Snapshot\nPlan will not be delete, they must be removed manually.\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "disable_snapshot_plan", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.DisableSnapshotPlan(ctx, &hcloud.StorageBox{ID: 123})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.disable_snapshot_plan(\n storage_box=StorageBox(id=123),\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box disable-snapshot-plan $STORAGEBOX" } ] } }, "/storage_boxes/{id}/actions/enable_snapshot_plan": { "post": { "operationId": "enable_storage_box_snapshot_plan", "summary": "Enable Snapshot Plan", "description": "Enables a Snapshot Plan for a [Storage Box](#tag/storage-boxes).\n\nOnce enabled, a Snapshot Plan will create Snapshots at predefined intervals.\nThere can only ever be one Snapshot Plan. The existing Snapshot Plan will be deleted before a new one is set up.\n\nAutomatic Snapshots are retained until explicitly deleted by the user or the maximum snapshot count for the plan (\"max_snapshots\") is exceeded.\n\nYou 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:\n\n| Interval | Request body |\n| ------------------------------------------ | ------------------------------------------------------------- |\n| Every day at 3 o'clock | `{\"max_snapshots\":10,\"minute\":0,\"hour\":3}` |\n| Every Friday at 3 o'clock | `{\"max_snapshots\":10,\"minute\":0,\"hour\":3,\"day_of_week\": 5}` |\n| On the first of every month at half past 6 | `{\"max_snapshots\":10,\"minute\":30,\"hour\":6,\"day_of_month\": 1}` |\n", "tags": [ "Storage Box Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_snapshots": { "description": "Maximum amount of Snapshots that will be created by this Snapshot Plan.\n\nOlder Snapshots will be deleted.\n", "type": "integer", "minimum": 1, "example": 10 }, "minute": { "description": "Minute when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 59, "example": 30 }, "hour": { "description": "Hour when the Snapshot Plan is executed (UTC).\n", "type": "integer", "minimum": 0, "maximum": 23, "example": 3 }, "day_of_week": { "description": "Day of the week when the Snapshot Plan is executed.\n\nStarts at 1 for Monday til 7 for Sunday. Null means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 7, "example": 7 }, "day_of_month": { "description": "Day of the month when the Snapshot Plan is executed.\n\nNull means every day.\n", "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 31, "example": null } }, "required": [ "max_snapshots", "minute", "hour" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "enable_snapshot_plan", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\t\"time\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.EnableSnapshotPlan(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxEnableSnapshotPlanOpts{\n\t\tMaxSnapshots: 10,\n\t\tMinute: 30,\n\t\tHour: 3,\n\t\tDayOfWeek: hcloud.Ptr(time.Sunday),\n\t\tDayOfMonth: nil,\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSnapshotPlan\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.enable_snapshot_plan(\n storage_box=StorageBox(id=123),\n snapshot_plan=StorageBoxSnapshotPlan(\n max_snapshots=10,\n minute=30,\n hour=3,\n day_of_week=7,\n day_of_month=None,\n ),\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box enable-snapshot-plan $STORAGEBOX \\\n --max-snapshots 10 \\\n --minute 30 \\\n --hour 3 \\\n --day-of-week 7" } ] } }, "/storage_boxes/{id}/subaccounts": { "get": { "operationId": "list_storage_box_subaccounts", "summary": "List Subaccounts", "description": "Returns a list of [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "tags": [ "Storage Box Subaccounts" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "name": "sort", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "id:asc", "id:desc", "created", "created:asc", "created:desc" ] } } }, { "description": "Filter [Storage Box Subaccounts](#tag/storage-box-subaccounts) by username.\n\nThe response will only contain the resources matching exactly the specified username.\n", "name": "username", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subaccounts": { "type": "array", "items": { "type": "object", "properties": { "storage_box": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "id": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "minLength": 1, "maxLength": 50, "example": "my-name" }, "home_directory": { "description": "Home directory of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "minLength": 1, "maxLength": 999, "pattern": "^[a-zA-Z0-9 ./_-]+$", "example": "my-backup/server01" }, "access_settings": { "description": "Access settings for the [Subaccount](#tag/storage-box-subaccounts).\n", "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "readonly": { "description": "Whether the [Subaccount](#tag/storage-box-subaccounts) is read-only.", "type": "boolean" } }, "required": [ "reachable_externally", "samba_enabled", "ssh_enabled", "webdav_enabled", "readonly" ] }, "description": { "description": "A description of [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "maxLength": 1000, "example": "my-backup-server01" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "username": { "description": "Username of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "string", "example": "u1337-sub1" }, "server": { "description": "FQDN of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "string", "example": "u1337-sub1.your-storagebox.de" }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "storage_box", "id", "name", "home_directory", "access_settings", "description", "labels", "username", "server", "created" ] } } }, "required": [ "subaccounts" ] }, "examples": { "default": { "value": { "subaccounts": [ { "id": 42, "name": "my-name", "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-22T00:02:00Z", "labels": { "environment": "prod", "example.com/my": "label", "just-a-key": "" }, "storage_box": 42 } ] } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccounts, err := client.StorageBox.AllSubaccounts(ctx, &hcloud.StorageBox{ID: 123})\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nsubaccounts = client.storage_boxes.get_subaccount_all(storage_box=StorageBox(id=123))" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box subaccount list $STORAGEBOX" } ] }, "post": { "operationId": "create_storage_box_subaccount", "summary": "Create a Subaccount", "description": "Creates a [Storage Box Subaccount](#tag/storage-box-subaccounts).\n\nA [Storage Box Subaccount](#tag/storage-box-subaccounts) will use a separate home directory.\n", "tags": [ "Storage Box Subaccounts" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "home_directory": { "description": "Home directory of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n\nThe directory will be created if it doesn't exist yet.\n", "type": "string", "minLength": 1, "maxLength": 999, "pattern": "^[a-zA-Z0-9 ./_-]+$", "example": "my-backup/server01" }, "password": { "description": "Password of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n\nFor more details, see the [Storage Boxes password policy](#tag/storage-boxes/password-policy).\n", "type": "string" }, "access_settings": { "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "readonly": { "description": "Whether the [Subaccount](#tag/storage-box-subaccounts) is read-only.", "type": "boolean" } } }, "name": { "description": "Name of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n\nDefaults to the [Storage Box Subaccount](#tag/storage-box-subaccounts) `username`.\n", "type": "string", "minLength": 1, "maxLength": 50, "example": "my-name" }, "description": { "description": "A description of [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "maxLength": 1000, "example": "my-backup-server01" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } } }, "required": [ "home_directory", "password" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subaccount": { "type": "object", "properties": { "id": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "storage_box": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, "required": [ "id", "storage_box" ] }, "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "subaccount", "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "subaccount": { "id": 42, "storage_box": 43 }, "action": { "id": 13, "command": "create_subaccount", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" }, { "id": 43, "type": "storage_box_subaccount" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.StorageBox.CreateSubaccount(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxSubaccountCreateOpts{\n\t\tHomeDirectory: \"my-backup/server01\",\n\t\tPassword: \"string\",\n\t\tAccessSettings: &hcloud.StorageBoxSubaccountCreateOptsAccessSettings{\n\t\t\tReachableExternally: hcloud.Ptr(false),\n\t\t\tReadonly: hcloud.Ptr(false),\n\t\t\tSambaEnabled: hcloud.Ptr(false),\n\t\t\tSSHEnabled: hcloud.Ptr(false),\n\t\t\tWebDAVEnabled: hcloud.Ptr(false),\n\t\t},\n\t\tDescription: \"my-backup-server01\",\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tsubaccount := result.Subaccount\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccountAccessSettings\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.create_subaccount(\n storage_box=StorageBox(id=123),\n home_directory=\"my-backup/server01\",\n password=\"string\",\n access_settings=StorageBoxSubaccountAccessSettings(\n reachable_externally=False,\n readonly=False,\n samba_enabled=False,\n ssh_enabled=False,\n webdav_enabled=False,\n ),\n description=\"my-backup-server01\",\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n)\n\nresponse.action.wait_until_finished()\n\nsubaccount = response.subaccount" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box subaccount create $STORAGEBOX \\\n --home-directory \"my-backup/server01\" \\\n --password \"string\" \\\n --reachable-externally \\\n --enable-samba=true \\\n --enable-ssh=false \\\n --enable-webdav=false \\\n --readonly \\\n --description \"my-backup-server01\" \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\"" } ] } }, "/storage_boxes/{id}/subaccounts/{subaccount_id}": { "get": { "operationId": "get_storage_box_subaccount", "summary": "Get a Subaccount", "description": "Returns a specific [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "tags": [ "Storage Box Subaccounts" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Subaccount.", "name": "subaccount_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subaccount": { "type": "object", "properties": { "storage_box": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "id": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "minLength": 1, "maxLength": 50, "example": "my-name" }, "home_directory": { "description": "Home directory of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "minLength": 1, "maxLength": 999, "pattern": "^[a-zA-Z0-9 ./_-]+$", "example": "my-backup/server01" }, "access_settings": { "description": "Access settings for the [Subaccount](#tag/storage-box-subaccounts).\n", "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "readonly": { "description": "Whether the [Subaccount](#tag/storage-box-subaccounts) is read-only.", "type": "boolean" } }, "required": [ "reachable_externally", "samba_enabled", "ssh_enabled", "webdav_enabled", "readonly" ] }, "description": { "description": "A description of [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "maxLength": 1000, "example": "my-backup-server01" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "username": { "description": "Username of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "string", "example": "u1337-sub1" }, "server": { "description": "FQDN of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "string", "example": "u1337-sub1.your-storagebox.de" }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "storage_box", "id", "name", "home_directory", "access_settings", "description", "labels", "username", "server", "created" ] } }, "required": [ "subaccount" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccount, _, err := client.StorageBox.GetSubaccount(ctx, &hcloud.StorageBox{ID: 123}, \"my-subaccount\")\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nsubaccount = client.storage_boxes.get_subaccount_by_id(\n storage_box=StorageBox(id=123),\n id=456,\n)" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box subaccount describe $SUBACCOUNT" } ] }, "put": { "operationId": "update_storage_box_subaccount", "summary": "Update a Subaccount", "description": "Updates a [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "tags": [ "Storage Box Subaccounts" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Subaccount.", "name": "subaccount_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Name of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "minLength": 1, "maxLength": 50, "example": "my-name" }, "description": { "description": "A description of [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "maxLength": 1000, "example": "my-backup-server01" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } } } } } } }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subaccount": { "type": "object", "properties": { "storage_box": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "id": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "minLength": 1, "maxLength": 50, "example": "my-name" }, "home_directory": { "description": "Home directory of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "minLength": 1, "maxLength": 999, "pattern": "^[a-zA-Z0-9 ./_-]+$", "example": "my-backup/server01" }, "access_settings": { "description": "Access settings for the [Subaccount](#tag/storage-box-subaccounts).\n", "type": "object", "properties": { "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" }, "readonly": { "description": "Whether the [Subaccount](#tag/storage-box-subaccounts) is read-only.", "type": "boolean" } }, "required": [ "reachable_externally", "samba_enabled", "ssh_enabled", "webdav_enabled", "readonly" ] }, "description": { "description": "A description of [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "type": "string", "maxLength": 1000, "example": "my-backup-server01" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "username": { "description": "Username of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "string", "example": "u1337-sub1" }, "server": { "description": "FQDN of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "string", "example": "u1337-sub1.your-storagebox.de" }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "storage_box", "id", "name", "home_directory", "access_settings", "description", "labels", "username", "server", "created" ] } }, "required": [ "subaccount" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccount, _, err := client.StorageBox.UpdateSubaccount(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSubaccountUpdateOpts{\n\t\tDescription: hcloud.Ptr(\"my-backup-server01\"),\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t})\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccount\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box = client.storage_boxes.update_subaccount(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n description=\"my-backup-server01\",\n)" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box subaccount update $STORAGEBOX $SUBACCOUNT --description \"my-backup-server01\"\nhcloud storage-box subaccount add-label --overwrite $STORAGEBOX $SUBACCOUNT \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud storage-box subaccount remove-label $STORAGEBOX $SUBACCOUNT \\\n \"environment\" \"example.com\" \"just-a-key\"" } ] }, "delete": { "operationId": "delete_storage_box_subaccount", "summary": "Delete a Subaccount", "description": "Deletes a [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "tags": [ "Storage Box Subaccounts" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Subaccount.", "name": "subaccount_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "delete_subaccount", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" }, { "id": 42, "type": "storage_box_subaccount" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.StorageBox.DeleteSubaccount(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccount\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.delete_subaccount(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n )\n)\n\nresponse.action.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box subaccount delete $SUBACCOUNT" } ] } }, "/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/change_home_directory": { "post": { "operationId": "change_storage_box_subaccount_home_directory", "summary": "Change Home Directory", "description": "Change the home directory of a [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "tags": [ "Storage Box Subaccount Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Subaccount.", "name": "subaccount_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "home_directory": { "description": "Home directory of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n\nThe directory will be created if it doesn't exist yet.\n", "type": "string", "minLength": 1, "maxLength": 999, "pattern": "^[a-zA-Z0-9 ./_-]+$", "example": "my-backup/server01" } }, "required": [ "home_directory" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "change_home_directory", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" }, { "id": 42, "type": "storage_box_subaccount" } ], "error": null } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.ChangeSubaccountHomeDirectory(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSubaccountChangeHomeDirectoryOpts{\n\t\tHomeDirectory: \"my-backup/server01\",\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccount\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.change_subaccount_home_directory(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n home_directory=\"my-backup/server01\",\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box subaccount change-home-directory --home-directory \"my-backup/server01\" $STORAGEBOX $SUBACCOUNT" } ] } }, "/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/reset_subaccount_password": { "post": { "operationId": "reset_storage_box_subaccount_password", "summary": "Reset Password", "description": "Reset the password of a [Storage Box Subaccount](#tag/storage-box-subaccounts).\n", "tags": [ "Storage Box Subaccount Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Subaccount.", "name": "subaccount_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "description": "Password of the [Storage Box Subaccount](#tag/storage-box-subaccounts).\n\nFor more details, see the [Storage Boxes password policy](#tag/storage-boxes/password-policy).\n", "type": "string" } }, "required": [ "password" ] } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "reset_subaccount_password", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" }, { "id": 42, "type": "storage_box_subaccount" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.ResetSubaccountPassword(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSubaccountResetPasswordOpts{\n\t\tPassword: \"string\",\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSubaccount\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.reset_subaccount_password(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n password=\"string\",\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box subaccount reset-password --password \"string\" $STORAGEBOX $SUBACCOUNT" } ] } }, "/storage_boxes/{id}/subaccounts/{subaccount_id}/actions/update_access_settings": { "post": { "operationId": "update_storage_box_subaccount_access_settings", "summary": "Update Access Settings", "description": "Updates the access settings of a [Storage Box Subaccount](#tag/storage-box-subaccounts).\n\nThis endpoints supports partial updates. Omitted optional parameters do not result in any changes to the respective properties.\n", "tags": [ "Storage Box Subaccount Actions" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Subaccount.", "name": "subaccount_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Subaccount](#tag/storage-box-subaccounts).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "readonly": { "description": "Whether the [Subaccount](#tag/storage-box-subaccounts) is read-only.", "type": "boolean" }, "reachable_externally": { "description": "Whether access from outside the Hetzner network is allowed.", "type": "boolean" }, "samba_enabled": { "description": "Whether the Samba subsystem is enabled.", "type": "boolean" }, "ssh_enabled": { "description": "Whether the SSH subsystem is enabled.", "type": "boolean" }, "webdav_enabled": { "description": "Whether the WebDAV subsystem is enabled.", "type": "boolean" } } } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "description": "Response for a created [Action](#description/actions).\n\nMake sure to wait for the [Action](#description/actions) completion to ensure your changes are applied.\n", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "update_access_settings", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" }, { "id": 42, "type": "storage_box_subaccount" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\taction, _, err := client.StorageBox.UpdateSubaccountAccessSettings(ctx, &hcloud.StorageBoxSubaccount{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSubaccountUpdateAccessSettingsOpts{\n\t\tReachableExternally: hcloud.Ptr(false),\n\t\tReadonly: hcloud.Ptr(false),\n\t\tSambaEnabled: hcloud.Ptr(false),\n\t\tSSHEnabled: hcloud.Ptr(false),\n\t\tWebDAVEnabled: hcloud.Ptr(false),\n\t})\n\n\terr = client.Action.WaitFor(ctx, action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import (\n StorageBox,\n StorageBoxSubaccount,\n StorageBoxSubaccountAccessSettings,\n)\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\naction = client.storage_boxes.update_subaccount_access_settings(\n subaccount=StorageBoxSubaccount(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n access_settings=StorageBoxSubaccountAccessSettings(\n reachable_externally=False,\n readonly=False,\n samba_enabled=False,\n ssh_enabled=False,\n webdav_enabled=False,\n ),\n)\n\naction.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box subaccount update-access-settings $STORAGEBOX $SUBACCOUNT \\\n --reachable-externally \\\n --enable-samba=true \\\n --enable-ssh=false \\\n --enable-webdav=false \\\n --readonly" } ] } }, "/storage_boxes/{id}/snapshots": { "get": { "operationId": "list_storage_box_snapshots", "summary": "List Snapshots", "description": "Returns a list of [Storage Box Snapshot](#tag/storage-box-snapshots).\n\nBoth snapshots created manually and by the snapshot plan are returned.\n", "tags": [ "Storage Box Snapshots" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Filter resources by labels.\n\nThe response will only contain resources matching the label selector.\nFor more information, see \"[Label Selector](#description/label-selector)\".\n", "name": "label_selector", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Sort resources by field and direction. May be used multiple times.\n\nFor more information, see \"[Sorting](#description/sorting)\".\n", "name": "sort", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "id:asc", "id:desc", "name", "name:asc", "name:desc", "created", "created:asc", "created:desc" ] } } }, { "description": "Filter wether a [Storage Box Snapshot](#tag/storage-box-snapshots) is automatic.\n", "name": "is_automatic", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshots": { "type": "array", "items": { "type": "object", "properties": { "storage_box": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "id": { "description": "ID of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "example": "my-snapshot" }, "description": { "description": "Description of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "maxLength": 1000, "pattern": "[a-zA-Z0-9-_,:<>+#!\\(\\)\\[\\]\\{\\} ]*", "example": "snapshot-0001" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "stats": { "description": "Statistics of the [Storage Box Snapshot](#tag/storage-box-snapshots).\n", "type": "object", "properties": { "size": { "description": "Current storage requirements of the Snapshot in bytes.", "type": "integer", "format": "int64" }, "size_filesystem": { "description": "Size of the compressed file system contained in the Snapshot in bytes.", "type": "integer", "format": "int64" } }, "required": [ "size", "size_filesystem" ] }, "is_automatic": { "description": "Whether the [Storage Box Snapshot](#tag/storage-box-snapshots) was created automatically.", "type": "boolean" }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "storage_box", "id", "name", "description", "labels", "stats", "is_automatic", "created" ] } } }, "required": [ "snapshots" ] }, "examples": { "default": { "value": { "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": "" } }, { "id": 2, "stats": { "size": 2097152, "size_filesystem": 1048576 }, "is_automatic": true, "name": "snapshot-daily--2025-02-12T22-00-02", "description": "", "created": "2025-02-22T01:00:30Z", "storage_box": 42, "labels": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } } ] } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsnapshots, err := client.StorageBox.AllSnapshots(ctx, &hcloud.StorageBox{ID: 123})\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nsnapshots = client.storage_boxes.get_snapshot_all(storage_box=StorageBox(id=123))" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box snapshot list $STORAGEBOX" } ] }, "post": { "operationId": "create_storage_box_snapshot", "summary": "Create a Snapshot", "description": "Creates a [Storage Box Snapshot](#tag/storage-box-snapshots).\n", "tags": [ "Storage Box Snapshots" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "Description of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "maxLength": 1000, "pattern": "[a-zA-Z0-9-_,:<>+#!\\(\\)\\[\\]\\{\\} ]*", "example": "snapshot-0001" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } } } } } } }, "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "id": { "description": "ID of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "storage_box": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, "required": [ "id", "storage_box" ] }, "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "snapshot", "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "snapshot": { "id": 42, "storage_box": 43 }, "action": { "id": 13, "command": "create_snapshot", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" }, { "id": 43, "type": "storage_box_snapshot" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.StorageBox.CreateSnapshot(ctx, &hcloud.StorageBox{ID: 123}, hcloud.StorageBoxSnapshotCreateOpts{\n\t\tDescription: \"snapshot-0001\",\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n\n\tsnapshot := result.Snapshot\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.create_snapshot(\n storage_box=StorageBox(id=123),\n description=\"snapshot-0001\",\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n)\n\nresponse.action.wait_until_finished()\n\nsnapshot = response.snapshot" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box snapshot create $STORAGEBOX \\\n --description \"snapshot-0001\" \\\n --label \"environment=prod\" \\\n --label \"example.com/my=label\" \\\n --label \"just-a-key=\"" } ] } }, "/storage_boxes/{id}/snapshots/{snapshot_id}": { "get": { "operationId": "get_storage_box_snapshot", "summary": "Get a Snapshot", "description": "Returns a specific [Storage Box Snapshot](#tag/storage-box-snapshots).\n", "tags": [ "Storage Box Snapshots" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Snapshot.", "name": "snapshot_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "storage_box": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "id": { "description": "ID of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "example": "my-snapshot" }, "description": { "description": "Description of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "maxLength": 1000, "pattern": "[a-zA-Z0-9-_,:<>+#!\\(\\)\\[\\]\\{\\} ]*", "example": "snapshot-0001" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "stats": { "description": "Statistics of the [Storage Box Snapshot](#tag/storage-box-snapshots).\n", "type": "object", "properties": { "size": { "description": "Current storage requirements of the Snapshot in bytes.", "type": "integer", "format": "int64" }, "size_filesystem": { "description": "Size of the compressed file system contained in the Snapshot in bytes.", "type": "integer", "format": "int64" } }, "required": [ "size", "size_filesystem" ] }, "is_automatic": { "description": "Whether the [Storage Box Snapshot](#tag/storage-box-snapshots) was created automatically.", "type": "boolean" }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "storage_box", "id", "name", "description", "labels", "stats", "is_automatic", "created" ] } }, "required": [ "snapshot" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccount, _, err := client.StorageBox.GetSnapshot(ctx, &hcloud.StorageBox{ID: 123}, \"my-snapshot\")\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nsnapshot = client.storage_boxes.get_snapshot_by_id(\n storage_box=StorageBox(id=123),\n id=456,\n)" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box snapshot describe $STORAGEBOX $SNAPSHOT" } ] }, "put": { "operationId": "update_storage_box_snapshot", "summary": "Update a Snapshot", "description": "Updates a [Storage Box Snapshot](#tag/storage-box-snapshots).\n", "tags": [ "Storage Box Snapshots" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Snapshot.", "name": "snapshot_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "description": "Description of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "maxLength": 1000, "pattern": "[a-zA-Z0-9-_,:<>+#!\\(\\)\\[\\]\\{\\} ]*", "example": "snapshot-0001" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\n\nNote that the set of [Labels](#description/labels) provided in the request will overwrite the\nexisting one.\n\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } } } } } } }, "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "storage_box": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "id": { "description": "ID of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "example": "my-snapshot" }, "description": { "description": "Description of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "string", "maxLength": 1000, "pattern": "[a-zA-Z0-9-_,:<>+#!\\(\\)\\[\\]\\{\\} ]*", "example": "snapshot-0001" }, "labels": { "description": "User-defined labels (`key/value` pairs) for the Resource.\nFor more information, see \"[Labels](#description/labels)\".\n", "type": "object", "additionalProperties": { "type": "string" }, "example": { "environment": "prod", "example.com/my": "label", "just-a-key": "" } }, "stats": { "description": "Statistics of the [Storage Box Snapshot](#tag/storage-box-snapshots).\n", "type": "object", "properties": { "size": { "description": "Current storage requirements of the Snapshot in bytes.", "type": "integer", "format": "int64" }, "size_filesystem": { "description": "Size of the compressed file system contained in the Snapshot in bytes.", "type": "integer", "format": "int64" } }, "required": [ "size", "size_filesystem" ] }, "is_automatic": { "description": "Whether the [Storage Box Snapshot](#tag/storage-box-snapshots) was created automatically.", "type": "boolean" }, "created": { "description": "Point in time when the Resource was created (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" } }, "required": [ "storage_box", "id", "name", "description", "labels", "stats", "is_automatic", "created" ] } }, "required": [ "snapshot" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tsubaccount, _, err := client.StorageBox.UpdateSnapshot(ctx, &hcloud.StorageBoxSnapshot{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t}, hcloud.StorageBoxSnapshotUpdateOpts{\n\t\tDescription: hcloud.Ptr(\"snapshot-0001\"),\n\t\tLabels: map[string]string{\n\t\t\t\"environment\": \"prod\",\n\t\t\t\"example.com/my\": \"label\",\n\t\t\t\"just-a-key\": \"\",\n\t\t},\n\t})\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSnapshot\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box = client.storage_boxes.update_snapshot(\n snapshot=StorageBoxSnapshot(\n storage_box=StorageBox(id=123),\n id=456,\n ),\n labels={\n \"environment\": \"prod\",\n \"example.com/my\": \"label\",\n \"just-a-key\": \"\",\n },\n description=\"snapshot-0001\",\n)" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box snapshot update $STORAGEBOX $SNAPSHOT --name \"My Storage Box\"\nhcloud storage-box snapshot add-label --overwrite $STORAGEBOX $SNAPSHOT \\\n \"environment=prod\" \"example.com/my=label\" \"just-a-key=\"\nhcloud storage-box snapshot remove-label $STORAGEBOX $SNAPSHOT \\\n \"environment\" \"example.com\" \"just-a-key\"" } ] }, "delete": { "operationId": "delete_storage_box_snapshot", "summary": "Delete a Snapshot", "description": "Deletes a [Storage Box Snapshot](#tag/storage-box-snapshots).\n", "tags": [ "Storage Box Snapshots" ], "parameters": [ { "description": "ID of the Storage Box.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box](#tag/storage-boxes).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } }, { "description": "ID of the Storage Box Snapshot.", "name": "snapshot_id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Snapshot](#tag/storage-box-snapshots).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "201": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "title": "ActionResponse", "type": "object", "properties": { "action": { "title": "Action", "type": "object", "properties": { "id": { "description": "ID of the [Action](#description/actions).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "command": { "description": "Command executed in the Action.", "type": "string", "example": "start_resource" }, "status": { "description": "Status of the Action.", "type": "string", "enum": [ "running", "success", "error" ] }, "started": { "description": "Point in time when the Action was started (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format).", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z" }, "finished": { "description": "Point in time when the Action was finished (in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) format). Only set if the Action is finished otherwise null.", "type": "string", "format": "date-time", "example": "2016-01-30T23:55:00Z", "nullable": true }, "progress": { "description": "Progress of the Action in percent.", "type": "integer", "format": "int32", "example": 100 }, "resources": { "description": "Resources the Action relates to.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the Resource.", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "type": { "description": "Type of the Resource.", "type": "string", "example": "server" } }, "required": [ "id", "type" ] } }, "error": { "description": "Error message for the Action if an error occurred, otherwise null.", "type": "object", "nullable": true, "properties": { "code": { "description": "Fixed error code for machines.", "type": "string", "example": "action_failed" }, "message": { "description": "Error message for humans.", "type": "string", "example": "Action failed" } }, "required": [ "code", "message" ] } }, "required": [ "id", "command", "status", "progress", "started", "finished", "resources", "error" ] } }, "required": [ "action" ] }, "examples": { "default": { "description": "Action successfully created.", "value": { "action": { "id": 13, "command": "delete_snapshot", "status": "running", "progress": 0, "started": "2016-01-30T23:50:00Z", "finished": null, "resources": [ { "id": 42, "type": "storage_box" }, { "id": 42, "type": "storage_box_snapshot" } ], "error": { "code": "action_failed", "message": "Action failed" } } } } } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tresult, _, err := client.StorageBox.DeleteSnapshot(ctx, &hcloud.StorageBoxSnapshot{\n\t\tStorageBox: &hcloud.StorageBox{ID: 123},\n\t\tID: 456,\n\t})\n\n\terr = client.Action.WaitFor(ctx, result.Action)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\nfrom hcloud.storage_boxes import StorageBox, StorageBoxSnapshot\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nresponse = client.storage_boxes.delete_snapshot(\n snapshot=StorageBoxSnapshot(\n storage_box=StorageBox(id=123),\n id=456,\n )\n)\n\nresponse.action.wait_until_finished()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box snapshot delete $STORAGEBOX $SNAPSHOT" } ] } }, "/storage_box_types": { "get": { "operationId": "list_storage_box_types", "summary": "List Storage Box Types", "description": "Returns a paginated list of [Storage Box Types](#tag/storage-box-types).\n", "tags": [ "Storage Box Types" ], "parameters": [ { "description": "Filter resources by their name.\n\nThe response will only contain the resources\nmatching exactly the specified name.\n", "name": "name", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "Page number to return. For more information, see \"[Pagination](#description/pagination)\".", "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 1, "example": 1 } }, { "description": "Maximum number of entries returned per page. For more information, see \"[Pagination](#description/pagination)\".", "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "default": 25, "example": 25 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_box_types": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "ID of the [Storage Box Type](#tag/storage-box-types).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "bx11" }, "description": { "description": "Description of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "BX11" }, "snapshot_limit": { "description": "Maximum number of allowed manual snapshots.", "type": "integer", "nullable": true, "example": 10 }, "automatic_snapshot_limit": { "description": "Maximum number of snapshots created automatically by a snapshot plan.", "type": "integer", "nullable": true, "example": 10 }, "subaccounts_limit": { "description": "Maximum number of subaccounts.", "type": "integer", "example": 200 }, "size": { "description": "Available storage in bytes.", "type": "integer", "format": "int64", "example": 1073741824 }, "prices": { "description": "Price per [Location](#tag/locations).", "type": "array", "items": { "type": "object", "properties": { "location": { "description": "Name of the [Location](#tag/locations) the price is for.", "type": "string", "example": "fsn1" }, "price_hourly": { "description": "Hourly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "price_monthly": { "description": "Monthly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "setup_fee": { "description": "Setup fee in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] } }, "required": [ "location", "price_hourly", "price_monthly", "setup_fee" ] } }, "deprecation": { "title": "DeprecationInfo", "description": "Describes if, when and how the resource is deprecated. If this field is\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] } }, "required": [ "id", "name", "description", "snapshot_limit", "automatic_snapshot_limit", "subaccounts_limit", "size", "prices", "deprecation" ] } }, "meta": { "title": "ListMeta", "type": "object", "properties": { "pagination": { "description": "See \"[Pagination](#description/pagination)\" for more information.", "type": "object", "properties": { "page": { "description": "Current page number.", "type": "integer", "format": "int64", "example": 3 }, "per_page": { "description": "Maximum number of entries returned per page.", "type": "integer", "format": "int64", "example": 25 }, "previous_page": { "description": "Page number of the previous page. Can be null if the current page is the first one.", "type": "integer", "format": "int64", "nullable": true, "example": 2 }, "next_page": { "description": "Page number of the next page. Can be null if the current page is the last one.", "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "last_page": { "description": "Page number of the last page available. Can be null if the current page is the last one.", "type": "integer", "format": "int64", "nullable": true, "example": 4 }, "total_entries": { "description": "Total number of entries that exist for this query. Can be null if unknown.", "type": "integer", "format": "int64", "nullable": true, "example": 100 } }, "required": [ "page", "per_page", "previous_page", "next_page", "last_page", "total_entries" ] } }, "required": [ "pagination" ] } }, "required": [ "storage_box_types", "meta" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBoxTypes, err := client.StorageBoxType.All(ctx)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box_types = client.storage_box_types.get_all()" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box-type list" } ] } }, "/storage_box_types/{id}": { "get": { "operationId": "get_storage_box_type", "summary": "Get a Storage Box Type", "description": "Returns a specific [Storage Box Type](#tag/storage-box-types).\n", "tags": [ "Storage Box Types" ], "parameters": [ { "description": "ID of the Storage Box Type.", "name": "id", "in": "path", "required": true, "schema": { "description": "ID of the [Storage Box Type](#tag/storage-box-types).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 } } ], "responses": { "200": { "description": "Request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "storage_box_type": { "type": "object", "properties": { "id": { "description": "ID of the [Storage Box Type](#tag/storage-box-types).", "type": "integer", "format": "int64", "minimum": 1, "maximum": 9007199254740991, "example": 42 }, "name": { "description": "Name of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "bx11" }, "description": { "description": "Description of the [Storage Box Type](#tag/storage-box-types).", "type": "string", "example": "BX11" }, "snapshot_limit": { "description": "Maximum number of allowed manual snapshots.", "type": "integer", "nullable": true, "example": 10 }, "automatic_snapshot_limit": { "description": "Maximum number of snapshots created automatically by a snapshot plan.", "type": "integer", "nullable": true, "example": 10 }, "subaccounts_limit": { "description": "Maximum number of subaccounts.", "type": "integer", "example": 200 }, "size": { "description": "Available storage in bytes.", "type": "integer", "format": "int64", "example": 1073741824 }, "prices": { "description": "Price per [Location](#tag/locations).", "type": "array", "items": { "type": "object", "properties": { "location": { "description": "Name of the [Location](#tag/locations) the price is for.", "type": "string", "example": "fsn1" }, "price_hourly": { "description": "Hourly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "price_monthly": { "description": "Monthly price in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] }, "setup_fee": { "description": "Setup fee in this [Location](#tag/locations).", "type": "object", "properties": { "net": { "description": "Price without VAT.", "type": "string", "format": "decimal", "example": "1.0000" }, "gross": { "description": "Price with VAT added.", "type": "string", "format": "decimal", "example": "1.1900" } }, "required": [ "net", "gross" ] } }, "required": [ "location", "price_hourly", "price_monthly", "setup_fee" ] } }, "deprecation": { "title": "DeprecationInfo", "description": "Describes if, when and how the resource is deprecated. If this field is\nset to `null` the resource is not deprecated. If a value is set, it is\nconsidered deprecated.\n", "type": "object", "nullable": true, "properties": { "unavailable_after": { "description": "Date of the deprecated resource removal.\n\nOnce this date is reached, the resource will not be returned\nby resource type \"list\" endpoint, and the resource can not be\nused to create new resources. For example, if this is an\nimage, you can not create new servers with this image after\nthe mentioned date.\n", "type": "string", "format": "date-time", "example": "2023-09-01T00:00:00Z" }, "announced": { "description": "Date of the deprecation announcement.\n", "type": "string", "format": "date-time", "example": "2023-06-01T00:00:00Z" } }, "required": [ "unavailable_after", "announced" ] } }, "required": [ "id", "name", "description", "snapshot_limit", "automatic_snapshot_limit", "subaccounts_limit", "size", "prices", "deprecation" ] } }, "required": [ "storage_box_type" ] } } } }, "4xx": { "description": "Request failed with a user error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "unauthorized", "message": "unable to authenticate", "details": null } } } } } }, "5xx": { "description": "Request failed with a server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "description": "Error code for machines.", "type": "string" }, "message": { "description": "Error message for humans.", "type": "string" }, "details": { "description": "Details about the error.", "type": "object", "nullable": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "example": { "error": { "code": "timeout", "message": "request timeout", "details": null } } } } } } }, "security": [ { "APIToken": [] } ], "x-codeSamples": [ { "lang": "Go", "label": "Go", "source": "package examples\n\nimport (\n\t\"context\"\n\t\"os\"\n\n\t\"github.com/hetznercloud/hcloud-go/v2/hcloud\"\n)\n\nfunc main() {\n\ttoken := os.Getenv(\"HCLOUD_TOKEN\")\n\n\tclient := hcloud.NewClient(hcloud.WithToken(token))\n\tctx := context.TODO()\n\n\tstorageBoxType, _, err := client.StorageBoxType.GetByID(ctx, 123)\n}" }, { "lang": "Python", "label": "Python", "source": "from __future__ import annotations\n\nfrom os import environ\n\nfrom hcloud import Client\n\ntoken = environ[\"HCLOUD_TOKEN\"]\nclient = Client(token=token)\n\nstorage_box_type = client.storage_box_types.get_by_id(123)" }, { "lang": "Shell", "label": "CLI", "source": "hcloud storage-box-type describe $STORAGEBOXTYPE" } ] } } }, "components": { "securitySchemes": { "APIToken": { "type": "http", "scheme": "bearer" } } }, "x-tagGroups": [ { "name": "Storage Boxes", "tags": [ "Storage Boxes", "Storage Box Actions", "Storage Box Subaccounts", "Storage Box Subaccount Actions", "Storage Box Snapshots", "Storage Box Types" ] } ] }