{ "openapi": "3.0.3", "info": { "title": "HostHatch API", "version": "1.0.0", "description": "Manage your HostHatch projects, servers and their resources programmatically.\n\n**Authentication.** Create an API key on your profile page in the HostHatch console, https://console.hosthatch.com/users/profile/, and send it with every request as `Authorization: Bearer `. A key acts as the user who created it, in every project they belong to. A read-only key can read and poll; a request that would change something is `403 read_only_key`. An unknown or revoked key is `401 invalid_api_key`, an expired one `401 api_key_expired`, and changing your password revokes every key. After 20 failed key checks from one address within 10 minutes, every key it sends is refused with `429 rate_limited` until those 10 minutes are over.\n\n**Projects and roles.** Servers and everything around them belong to a project, addressed by its slug: `GET /projects/` lists your projects and your role in each. Projects, their members and invitations are managed in the HostHatch console. Every member can run the project's servers and manage its SSH keys, snapshots, ISOs and firewall groups. Only an owner or admin can order, upgrade or cancel servers, which is `403 insufficient_role` for a member. A project you are not a member of, and anything in it, is `404 not_found`, as if it did not exist.\n\n**Billing.** Orders go on the billing account of the project's owner, which holds the invoices, the account credit and a subscription for each server; the console shows them. Most of a project's endpoints need that account, and answer `403 billing_account_required` until the owner has set one up on their profile page, which also sets up their projects for servers. `403 project_not_ready` means that setup hasn't finished: try again shortly, and contact support if it lasts.\n\n**Asynchronous actions.** Power, reinstall, snapshot, ISO, password and network operations on a server take time. Starting one answers `202` with an action: poll `GET /projects/{project_slug}/actions/{id}/` every few seconds until its `status` is `success` or `error`. One power, reinstall, snapshot or ISO action runs on a server at a time; starting another meanwhile is `409 action_in_progress`, with the running action's id in `action_id`. One of those whose outcome is `unknown` keeps blocking the others until it is settled, usually within minutes; support looks at any still unknown after 30 minutes, or 4 hours for a snapshot.\n\n**Orders.** Ordering a server, an upgrade or extra bandwidth answers `201` with an order. It is paid from the owner's account credit when the credit covers the invoice; otherwise it waits in `awaiting_payment` until the owner pays the invoice at `invoice.url`, or the invoice is cancelled. Poll `GET /projects/{project_slug}/orders/{id}/` until its `status` is `completed`, `cancelled` or `failed`. An order can't be withdrawn through the API: contact support to cancel its invoice.\n\n**Retrying safely.** Send an `Idempotency-Key` header, 1 to 64 characters of your choosing, with each request that starts an action or places an order. A key belongs to the project, for as long as the project exists, and to the one request that recorded something with it: the same key with another request is `409 idempotency_key_reused`. Sending the same request with the same key again is always safe. When the first one recorded an action or an order, the answer is that action or order, whatever became of it, with status `200` and `Idempotent-Replayed: true`, even when the first answer was an error; use a new key to try again after a failure. A request refused before anything was recorded, as by validation, a role or a busy server, spends no key: the key can be sent again, with the same request or a corrected one. Two requests with one key at the same moment record one action or order, and both answer with it.\n\n**Upstream failures.** `502 upstream_error` means a service behind the API failed. On a read, nothing happened. A change may or may not have happened. When it started an action or placed an order, `action_id` or `order_id` says which: poll that rather than sending the request again. Any other change can be sent again as it is: a create that happened answers `409` with the object's id, a delete that happened answers `404`, and the rest set the same state again.\n\n**Lists** are paginated: `page` and `page_size` (50 by default, at most 100) choose the page, and the answer is `{count, next, previous, results}`.\n\n**Rate limits** are counted per API key and minute: 300 reads, 60 writes and 10 orders. Requests without a key are counted per address, 30 a minute. Over a limit the answer is `429 rate_limited`, with a `Retry-After` header giving the seconds to wait.\n\n**Errors** are RFC 9457 problem details (`application/problem+json`, whatever the request's `Accept` says) with a stable, machine-readable `code`. Each endpoint lists the codes it can answer with, and https://docs.hosthatch.com/api/errors explains them. A method an endpoint doesn't have is `405 method_not_allowed`. A `503` carries `Retry-After` too.\n\n**Format.** Requests and responses are JSON: send `Content-Type: application/json` with a body, and `Accept: application/json` or no `Accept` at all. A field marked nullable is null when it isn't set, doesn't apply, or can't be read just now. New fields, enum values and error codes may be added without a new version, so accept values you don't know." }, "paths": { "/me/": { "get": { "operationId": "me_retrieve", "description": "The user the API key belongs to: their name and email, their own billing account with its credit, and every project they belong to, by name, with their role in it. Every other endpoint addresses a project by its `slug`. `credit_balance` pays for the orders in the projects the user owns, and is null when it can't be read just now; a user without a billing account has only `exists: false`.", "summary": "Get the current user", "tags": [ "account" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUser" }, "examples": { "WithABillingAccount": { "value": { "id": 1042, "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "billing_account": { "exists": true, "credit_balance": "25.00", "currency": "USD" }, "projects": [ { "slug": "acme", "name": "Acme", "role": "owner" }, { "slug": "acme-staging", "name": "Acme staging", "role": "member" } ] }, "summary": "With a billing account" }, "WithoutABillingAccount": { "value": { "id": 1042, "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "billing_account": { "exists": false }, "projects": [ { "slug": "acme", "name": "Acme", "role": "member" } ] }, "summary": "Without a billing account" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" } } } }, "/projects/": { "get": { "operationId": "projects_list", "description": "The projects the API key's user belongs to, by name, with the user's role in each. Projects are created and managed in the HostHatch console, with their members and invitations. A user who belongs to no project gets an empty list.", "summary": "List projects", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } } ], "tags": [ "projects" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjectList" }, "examples": { "AProject": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 214, "name": "Acme", "slug": "acme", "ready": true, "role": "owner", "created_at": "2026-03-18T09:12:44.318521Z" } ] }, "summary": "A project" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" } } } }, "/projects/{project_slug}/": { "get": { "operationId": "projects_retrieve", "description": "One of the projects the API key's user belongs to, with the user's role in it. A project the user doesn't belong to is `404 not_found`, as if it did not exist.", "summary": "Get a project", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "projects" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "examples": { "Ready": { "value": { "id": 214, "name": "Acme", "slug": "acme", "ready": true, "role": "owner", "created_at": "2026-03-18T09:12:44.318521Z" } }, "BeingSetUp": { "value": { "id": 215, "name": "Acme staging", "slug": "acme-staging", "ready": false, "role": "admin", "created_at": "2026-10-21T08:40:03.774012Z" }, "summary": "Being set up" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" } } } }, "/projects/{project_slug}/actions/": { "get": { "operationId": "actions_list", "description": "The asynchronous operations started on the project's servers, through the API or the console, newest first, each as it was last seen: a list doesn't bring them up to date. Fetch an action for its current state. The query parameters narrow the list down; a value that isn't one of theirs is `400 validation_error`.", "summary": "List actions", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "query", "name": "resource_id", "schema": { "type": "string", "minLength": 1, "pattern": "^[0-9a-f]{1,32}$" }, "description": "Only actions on the resource with this id, such as a server's." }, { "in": "query", "name": "resource_type", "schema": { "enum": [ "server" ], "type": "string", "minLength": 1 }, "description": "Only actions on this kind of resource." }, { "in": "query", "name": "status", "schema": { "enum": [ "running", "unknown", "success", "error" ], "type": "string", "minLength": 1 }, "description": "Only actions with this status." }, { "in": "query", "name": "type", "schema": { "enum": [ "server.power_on", "server.power_off", "server.shutdown", "server.reboot", "server.reinstall", "server.reset_password", "server.restore_snapshot", "server.create_snapshot", "server.mount_iso", "server.unmount_iso", "server.enable_ipv6", "server.enable_private_network" ], "type": "string", "minLength": 1 }, "description": "Only actions of this type." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedActionList" }, "examples": { "ARebootThatSucceeded": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 5121, "type": "server.reboot", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} } ] }, "summary": "A reboot that succeeded" } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" } } } }, "/projects/{project_slug}/actions/{id}/": { "get": { "operationId": "actions_retrieve", "description": "One of the project's actions, brought up to date as it is read. Poll it after starting an action until its `status` is `success` or `error`. A `server.reset_password` that succeeded shows the new root password in `result.password` here, and only here, for 15 minutes, never to a read-only key.", "summary": "Get an action", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "The action's id, from the answer that started it or a list of actions.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Running": { "value": { "id": 5121, "type": "server.reboot", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } }, "Unknown": { "value": { "id": 5121, "type": "server.power_on", "status": "unknown", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } }, "ASnapshotTaken": { "value": { "id": 5121, "type": "server.create_snapshot", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": { "snapshot_id": 2958 } }, "summary": "A snapshot taken" }, "ANewRootPassword": { "value": { "id": 5121, "type": "server.reset_password", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": { "password": "vT7q2mRx9LpK" } }, "summary": "A new root password" }, "Failed": { "value": { "id": 5121, "type": "server.reinstall", "status": "error", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": { "code": "failed", "message": "The operation failed. Contact support if it keeps failing." }, "result": {} } } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" } } } }, "/projects/{project_slug}/firewall-groups/": { "get": { "operationId": "firewall_groups_list", "description": "The project's firewall groups, each with its rules and the ids of the servers it is attached to.", "summary": "List firewall groups", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "firewall-groups" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedFirewallGroupList" }, "examples": { "AGroupWithOneRule": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 412, "name": "web", "direction": "ingress", "servers": [ "8d41f0" ], "rules": [ { "id": 9002, "protocol": "tcp", "port_min": 443, "port_max": 443, "source_cidr": null, "destination_cidr": null, "priority": 1000, "comment": "HTTPS" } ], "created_at": "2026-10-19T10:00:00.000000Z" } ] }, "summary": "A group with one rule" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "post": { "operationId": "firewall_groups_create", "description": "Create an empty group, then add its rules. A group applies only to the servers it is attached to. Names are unique in a project, so a create whose response was lost can be sent again: if the group was created, the answer is `409 name_taken` with its id in `group_id` (left out only when the group could not be read back). Attach the group to servers with `PUT .../servers/{server_id}/firewall-groups/`.", "summary": "Create a firewall group", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "firewall-groups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallGroupRequest" }, "examples": { "InboundWebTraffic": { "value": { "name": "web", "direction": "ingress" }, "summary": "Inbound web traffic" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallGroup" }, "examples": { "Created": { "value": { "id": 412, "name": "web", "direction": "ingress", "servers": [], "rules": [], "created_at": "2026-10-19T10:00:00.000000Z" } } } } }, "description": "Created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "NameTaken": { "value": { "type": "https://docs.hosthatch.com/api/errors#name_taken", "title": "Name taken", "status": 409, "detail": "The name is already in use.", "code": "name_taken", "instance": "/api/v1/projects/acme/firewall-groups/", "group_id": 412 }, "summary": "Name taken" } } } }, "description": "`name_taken`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/firewall-groups/{group_id}/": { "get": { "operationId": "firewall_groups_retrieve", "description": "One of the project's firewall groups, with its rules and the servers it is attached to.", "summary": "Get a firewall group", "parameters": [ { "in": "path", "name": "group_id", "schema": { "type": "integer" }, "description": "The group's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "firewall-groups" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallGroup" }, "examples": { "AGroupWithOneRule": { "value": { "id": 412, "name": "web", "direction": "ingress", "servers": [ "8d41f0" ], "rules": [ { "id": 9002, "protocol": "tcp", "port_min": 443, "port_max": 443, "source_cidr": null, "destination_cidr": null, "priority": 1000, "comment": "HTTPS" } ], "created_at": "2026-10-19T10:00:00.000000Z" }, "summary": "A group with one rule" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "patch": { "operationId": "firewall_groups_rename", "description": "Change a group's name, the only property of a group that can change. Other fields are ignored, so a group read and sent back whole with a new name is a rename, except a `direction` other than the group's, which is `400 validation_error`: create a group with the other direction instead. A name another group of the project has is `409 name_taken`, with that group's id in `group_id` when it can be read back.", "summary": "Rename a firewall group", "parameters": [ { "in": "path", "name": "group_id", "schema": { "type": "integer" }, "description": "The group's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "firewall-groups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedFirewallGroupRenameRequest" }, "examples": { "NewName": { "value": { "name": "web-public" }, "summary": "New name" } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallGroup" }, "examples": { "Renamed": { "value": { "id": 412, "name": "web-public", "direction": "ingress", "servers": [ "8d41f0" ], "rules": [ { "id": 9002, "protocol": "tcp", "port_min": 443, "port_max": 443, "source_cidr": null, "destination_cidr": null, "priority": 1000, "comment": "HTTPS" } ], "created_at": "2026-10-19T10:00:00.000000Z" } } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "NameTaken": { "value": { "type": "https://docs.hosthatch.com/api/errors#name_taken", "title": "Name taken", "status": 409, "detail": "The name is already in use.", "code": "name_taken", "instance": "/api/v1/projects/acme/firewall-groups/412/", "group_id": 415 }, "summary": "Name taken" } } } }, "description": "`name_taken`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "delete": { "operationId": "firewall_groups_delete", "description": "Delete a group and its rules. A group still attached to servers answers `409 group_in_use` with their ids in `servers`: detach it from them first, since removing a group changes what those servers allow.", "summary": "Delete a firewall group", "parameters": [ { "in": "path", "name": "group_id", "schema": { "type": "integer" }, "description": "The group's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "firewall-groups" ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "GroupInUse": { "value": { "type": "https://docs.hosthatch.com/api/errors#group_in_use", "title": "Group in use", "status": 409, "detail": "The firewall group is still attached to servers.", "code": "group_in_use", "instance": "/api/v1/projects/acme/firewall-groups/412/", "servers": [ "8d41f0" ] }, "summary": "Group in use" } } } }, "description": "`group_in_use`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/firewall-groups/{group_id}/rules/": { "get": { "operationId": "firewall_rules_list", "description": "The rules of one of the project's firewall groups, lowest `priority` first.", "summary": "List a group's rules", "parameters": [ { "in": "path", "name": "group_id", "schema": { "type": "integer" }, "description": "The group's id.", "required": true }, { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "firewall-groups" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedFirewallRuleList" }, "examples": { "ARule": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 9002, "protocol": "tcp", "port_min": 443, "port_max": 443, "source_cidr": null, "destination_cidr": null, "priority": 1000, "comment": "HTTPS" } ] }, "summary": "A rule" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "post": { "operationId": "firewall_rules_create", "description": "Add a rule that allows the traffic it matches. Rules of an `ingress` group match on `source_cidr` and those of an `egress` group on `destination_cidr`; the other must be empty. A CIDR is answered in canonical form, and one with host bits set, such as `192.0.2.1/24`, is refused rather than read as `192.0.2.0/24`. A rule the group already has is `409 rule_exists` with that rule's id in `rule_id` (left out only when the group could not be read back), so a create whose response was lost can be sent again. Rules are the same when they have the same protocol, the same ports (no ports and 1 to 65535 both mean every port, and a `port_min` alone is that one port) and the same CIDR for the group's direction, however it is spelled.", "summary": "Add a rule to a group", "parameters": [ { "in": "path", "name": "group_id", "schema": { "type": "integer" }, "description": "The group's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "firewall-groups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallRuleRequest" }, "examples": { "HTTPSFromAnywhere": { "value": { "protocol": "tcp", "port_min": 443, "port_max": 443, "source_cidr": null, "destination_cidr": null, "priority": 1000, "comment": "HTTPS" }, "summary": "HTTPS from anywhere" }, "SSHFromOneNetwork": { "value": { "protocol": "tcp", "port_min": 22, "source_cidr": "198.51.100.0/24", "comment": "Office" }, "summary": "SSH from one network" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallRule" }, "examples": { "Created": { "value": { "id": 9002, "protocol": "tcp", "port_min": 443, "port_max": 443, "source_cidr": null, "destination_cidr": null, "priority": 1000, "comment": "HTTPS" } } } } }, "description": "Created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ValidationFailed": { "value": { "type": "https://docs.hosthatch.com/api/errors#validation_error", "title": "Validation failed", "status": 400, "detail": "One or more fields are invalid.", "code": "validation_error", "instance": "/api/v1/projects/acme/firewall-groups/412/rules/", "errors": [ { "field": "source_cidr", "code": "invalid", "message": "Enter the network address, such as 192.0.2.0/24 rather than 192.0.2.1/24, or a single address as /32 or /128." } ] }, "summary": "Validation failed" } } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "RuleExists": { "value": { "type": "https://docs.hosthatch.com/api/errors#rule_exists", "title": "Rule exists", "status": 409, "detail": "An identical rule is already in the group.", "code": "rule_exists", "instance": "/api/v1/projects/acme/firewall-groups/412/rules/", "rule_id": 9002 }, "summary": "Rule exists" } } } }, "description": "`rule_exists`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/firewall-groups/{group_id}/rules/{rule_id}/": { "get": { "operationId": "firewall_rules_retrieve", "description": "One rule of one of the project's firewall groups.", "summary": "Get a rule", "parameters": [ { "in": "path", "name": "group_id", "schema": { "type": "integer" }, "description": "The group's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "rule_id", "schema": { "type": "integer" }, "description": "The rule's id.", "required": true } ], "tags": [ "firewall-groups" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallRule" }, "examples": { "ARule": { "value": { "id": 9002, "protocol": "tcp", "port_min": 443, "port_max": 443, "source_cidr": null, "destination_cidr": null, "priority": 1000, "comment": "HTTPS" }, "summary": "A rule" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "patch": { "operationId": "firewall_rules_update", "description": "Change some of a rule's fields; the others keep their values. The rule that results is checked as a whole, so changing `protocol` to `icmp` or `any` also needs `port_min` and `port_max` set to null. Making it the same as another rule of the group is `409 rule_exists`, with that rule's id in `rule_id` when it can be read back.", "summary": "Change a rule", "parameters": [ { "in": "path", "name": "group_id", "schema": { "type": "integer" }, "description": "The group's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "rule_id", "schema": { "type": "integer" }, "description": "The rule's id.", "required": true } ], "tags": [ "firewall-groups" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedFirewallRuleRequest" }, "examples": { "ANarrowerSource": { "value": { "source_cidr": "203.0.113.0/24" }, "summary": "A narrower source" } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallRule" }, "examples": { "Changed": { "value": { "id": 9002, "protocol": "tcp", "port_min": 443, "port_max": 443, "source_cidr": "203.0.113.0/24", "destination_cidr": null, "priority": 1000, "comment": "HTTPS" } } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "RuleExists": { "value": { "type": "https://docs.hosthatch.com/api/errors#rule_exists", "title": "Rule exists", "status": 409, "detail": "An identical rule is already in the group.", "code": "rule_exists", "instance": "/api/v1/projects/acme/firewall-groups/412/rules/9002/", "rule_id": 9001 }, "summary": "Rule exists" } } } }, "description": "`rule_exists`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "delete": { "operationId": "firewall_rules_delete", "description": "Remove a rule from its group. The traffic it allowed is refused unless another rule allows it.", "summary": "Delete a rule", "parameters": [ { "in": "path", "name": "group_id", "schema": { "type": "integer" }, "description": "The group's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "rule_id", "schema": { "type": "integer" }, "description": "The rule's id.", "required": true } ], "tags": [ "firewall-groups" ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/images/": { "get": { "operationId": "images_list", "description": "The images a server can be installed or reinstalled with, by `name`. A reinstall takes any of them; a new server, one of those its product lists. Billing prices the catalogue for the project's owner, whose billing account orders are placed on, so it needs that billing account: `403 billing_account_required` until the owner has one.", "summary": "List images", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "catalogue" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedImageList" }, "examples": { "AnImage": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "name": "almalinux10", "distro": "AlmaLinux", "version": "10", "display_name": "AlmaLinux 10" } ] }, "summary": "An image" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/isos/": { "get": { "operationId": "isos_list", "description": "The ISOs the project's servers can boot from: the project's own `custom` ISO first, then HostHatch's `library`. Mount one with a server's `mount-iso` action.", "summary": "List ISOs", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "isos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedIsoList" }, "examples": { "ALibraryISO": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 5257, "name": "AlmaLinux-8.9-x86_64-minimal.iso", "type": "library", "status": "ready", "progress": 100, "created_at": "2024-01-15T10:00:00.000000Z" } ] }, "summary": "A library ISO" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "post": { "operationId": "isos_create", "description": "Uploading an ISO through the API is not available yet: until it is, the request is answered `400 feature_unavailable`. Then: give the URL of an ISO for HostHatch to download, and the answer is the project's `custom` ISO, `downloading` until it is `ready` to mount. A project holds one custom ISO; while it has one, an upload is `409 iso_limit_reached` with its id in `iso_id`, so an upload whose response was lost can be sent again. Delete the ISO to upload another. `url` errors carry the code `unreachable` when its host can't be reached or is not public, `redirect`, `not_the_file` when it answered a HEAD request with anything but 200, and `invalid` for anything else: the URL itself, a file over 10 GiB or of unknown size, or a file name the project's owner has an upload of already.", "summary": "Upload an ISO", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "isos" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsoUploadRequest" }, "examples": { "AnISOByURL": { "value": { "url": "https://repo.example.com/AlmaLinux-10.2-x86_64-dvd.iso" }, "summary": "An ISO by URL" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Iso" }, "examples": { "Uploaded,OnceUploadsAreAvailable": { "value": { "id": 8980, "name": "AlmaLinux-10.2-x86_64-dvd.iso", "type": "custom", "status": "downloading", "progress": 0, "created_at": "2026-10-07T14:09:24.678389Z" }, "summary": "Uploaded, once uploads are available" } } } }, "description": "Created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ValidationFailed": { "value": { "type": "https://docs.hosthatch.com/api/errors#validation_error", "title": "Validation failed", "status": 400, "detail": "One or more fields are invalid.", "code": "validation_error", "instance": "/api/v1/projects/acme/isos/", "errors": [ { "field": "url", "code": "redirect", "message": "The URL redirects. Use a direct link to the file." } ] }, "summary": "Validation failed" } } } }, "description": "`validation_error`, `feature_unavailable`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheProjectHasAnISOAlready": { "value": { "type": "https://docs.hosthatch.com/api/errors#iso_limit_reached", "title": "ISO limit reached", "status": 409, "detail": "The project already has a custom ISO.", "code": "iso_limit_reached", "instance": "/api/v1/projects/acme/isos/", "iso_id": 8980 }, "summary": "The project has an ISO already" } } } }, "description": "`iso_limit_reached`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/isos/{iso_id}/": { "get": { "operationId": "isos_retrieve", "description": "A library ISO, or the project's own. Poll a custom ISO while it is `downloading`.", "summary": "Get an ISO", "parameters": [ { "in": "path", "name": "iso_id", "schema": { "type": "integer" }, "description": "The ISO's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "isos" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Iso" }, "examples": { "AReadyCustomISO": { "value": { "id": 8980, "name": "AlmaLinux-10.2-x86_64-dvd.iso", "type": "custom", "status": "ready", "progress": 100, "created_at": "2026-10-07T14:09:24.678389Z" }, "summary": "A ready custom ISO" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "delete": { "operationId": "isos_delete", "description": "Delete the project's custom ISO. One still mounted on a server is `409 iso_mounted`: unmount it first. Library ISOs are shared by every project, so deleting one is `403 permission_denied`.", "summary": "Delete an ISO", "parameters": [ { "in": "path", "name": "iso_id", "schema": { "type": "integer" }, "description": "The ISO's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "isos" ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `permission_denied`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ISOMounted": { "value": { "type": "https://docs.hosthatch.com/api/errors#iso_mounted", "title": "ISO mounted", "status": 409, "detail": "The ISO is mounted on a server.", "code": "iso_mounted", "instance": "/api/v1/projects/acme/isos/8980/" }, "summary": "ISO mounted" } } } }, "description": "`iso_mounted`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/locations/": { "get": { "operationId": "locations_list", "description": "The locations some product can be ordered in. Each product's `locations` say where it is in stock. Billing prices the catalogue for the project's owner, whose billing account orders are placed on, so it needs that billing account: `403 billing_account_required` until the owner has one.", "summary": "List locations", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "catalogue" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedLocationList" }, "examples": { "ALocation": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "code": "AMS", "city": "Amsterdam", "country": "The Netherlands", "country_code": "NL" } ] }, "summary": "A location" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/orders/": { "get": { "operationId": "orders_list", "description": "The orders for new servers, upgrades and extra bandwidth placed in the project through the API, newest first, each as it was last seen: a list doesn't bring them up to date with billing. Fetch an order for its current state.", "summary": "List orders", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrderList" }, "examples": { "AServerOrderBeingSetUp": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 87, "type": "server", "status": "provisioning", "server_id": null, "request": { "hostname": "web-01.example.com", "product_id": 10, "location": "AMS", "image": "almalinux10", "billing_cycle": "monthly", "ipv4_additional": 0, "ipv6": true, "private_network": false, "ssh_keys": [ 3810 ], "snapshot_id": null, "promo_code": null, "has_user_data": false }, "invoice": { "id": 715020, "status": "paid", "total": "12.00", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715020/" }, "warnings": [], "created_at": "2026-10-21T09:12:03.418209Z", "updated_at": "2026-10-21T09:12:05.902114Z" } ] }, "summary": "A server order being set up" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" } } } }, "/projects/{project_slug}/orders/{id}/": { "get": { "operationId": "orders_retrieve", "description": "One of the project's orders, brought up to date with billing as it is read. Poll it after placing an order until its `status` is `completed`, `cancelled` or `failed`. An order in `awaiting_payment` waits for the project's owner to pay its invoice at `invoice.url`. One in `unknown` lost billing's answer: it is looked for in billing, never placed again, and settled by support if it can't be found.", "summary": "Get an order", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "The order's id, from the answer that placed it or a list of orders.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "orders" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "AServerOrderCompleted": { "value": { "id": 87, "type": "server", "status": "completed", "server_id": "8d41f0", "request": { "hostname": "web-01.example.com", "product_id": 10, "location": "AMS", "image": "almalinux10", "billing_cycle": "monthly", "ipv4_additional": 0, "ipv6": true, "private_network": false, "ssh_keys": [ 3810 ], "snapshot_id": null, "promo_code": null, "has_user_data": false }, "invoice": { "id": 715020, "status": "paid", "total": "12.00", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715020/" }, "warnings": [], "created_at": "2026-10-21T09:12:03.418209Z", "updated_at": "2026-10-21T09:15:41.120385Z" }, "summary": "A server order completed" }, "AnOrderAwaitingPayment": { "value": { "id": 87, "type": "server", "status": "awaiting_payment", "server_id": null, "request": { "hostname": "web-01.example.com", "product_id": 10, "location": "AMS", "image": "almalinux10", "billing_cycle": "monthly", "ipv4_additional": 0, "ipv6": true, "private_network": false, "ssh_keys": [ 3810 ], "snapshot_id": null, "promo_code": null, "has_user_data": false }, "invoice": { "id": 715020, "status": "unpaid", "total": "12.00", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715020/" }, "warnings": [], "created_at": "2026-10-21T09:12:03.418209Z", "updated_at": "2026-10-21T09:12:04.731560Z" }, "summary": "An order awaiting payment" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" } } } }, "/projects/{project_slug}/pricing/": { "get": { "operationId": "pricing_retrieve", "description": "What a server's extras cost, on top of its product's price: additional IPv4 addresses and IPv6, chosen when a server is ordered, and extra bandwidth, bought for a server with `POST .../servers/{server_id}/bandwidth/`. Billing prices the catalogue for the project's owner, whose billing account orders are placed on, so it needs that billing account: `403 billing_account_required` until the owner has one.", "summary": "Get the prices of extras", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "catalogue" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pricing" }, "examples": { "Extras": { "value": { "currency": "USD", "ipv4_additional": [ { "count": 0, "prices": { "monthly": "0.00", "annually": "0.00" }, "setup_fees": { "monthly": "0.00", "annually": "0.00" } }, { "count": 1, "prices": { "monthly": "2.00", "annually": "24.00" }, "setup_fees": { "monthly": "0.00", "annually": "0.00" } }, { "count": 2, "prices": { "monthly": "4.00", "annually": "48.00" }, "setup_fees": { "monthly": "0.00", "annually": "0.00" } } ], "ipv6": { "prices": { "monthly": "1.00", "annually": "12.00" }, "setup_fees": { "monthly": "0.00", "annually": "0.00" } }, "extra_bandwidth": [ { "size_gb": 500, "price": "2.00" }, { "size_gb": 1000, "price": "4.00" }, { "size_gb": 2000, "price": "8.00" }, { "size_gb": 3000, "price": "12.00" }, { "size_gb": 4000, "price": "16.00" }, { "size_gb": 5000, "price": "20.00" }, { "size_gb": 6000, "price": "24.00" }, { "size_gb": 7000, "price": "28.00" }, { "size_gb": 8000, "price": "32.00" }, { "size_gb": 9000, "price": "36.00" }, { "size_gb": 10000, "price": "40.00" }, { "size_gb": 11000, "price": "44.00" }, { "size_gb": 12000, "price": "48.00" }, { "size_gb": 13000, "price": "52.00" }, { "size_gb": 14000, "price": "56.00" }, { "size_gb": 15000, "price": "60.00" }, { "size_gb": 16000, "price": "64.00" }, { "size_gb": 17000, "price": "68.00" }, { "size_gb": 18000, "price": "72.00" }, { "size_gb": 19000, "price": "76.00" }, { "size_gb": 20000, "price": "80.00" } ] } } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/products/": { "get": { "operationId": "products_list", "description": "What can be ordered as a new server: each product's recurring prices and setup fees by billing cycle, the locations it is sold in, with whether it is in stock there for new servers and for upgrades, and the images it can be installed with. To order one, give its `id` as `product_id`, a location it is `in_stock` in as `location`, and one of its `images` as `image`. Billing prices the catalogue for the project's owner, whose billing account orders are placed on, so it needs that billing account: `403 billing_account_required` until the owner has one.", "summary": "List products", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "catalogue" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProductList" }, "examples": { "AProductSoldMonthlyAndAnnually": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 10, "name": "Cloud VPS 2x4", "category": "Cloud", "description": [ "2 vCPU cores", "4 GB RAM", "80 GB NVMe storage", "2 TB bandwidth" ], "prices": { "monthly": "12.00", "annually": "144.00" }, "setup_fees": { "monthly": "0.00", "annually": "0.00" }, "currency": "USD", "billing_cycles": [ "monthly", "annually" ], "default_billing_cycle": "monthly", "locations": [ { "code": "AMS", "in_stock": true, "upgrade_in_stock": true }, { "code": "NYC", "in_stock": false, "upgrade_in_stock": true } ], "images": [ "almalinux10", "almalinux9" ] } ] }, "summary": "A product sold monthly and annually" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/": { "get": { "operationId": "servers_list", "description": "The project's servers, as summaries: id, hostname, status, primary IPv4 address, location and plan. Fetch a server for its network, image, bandwidth, firewall groups and billing.", "summary": "List servers", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "servers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedServerSummaryList" }, "examples": { "ARunningServer": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": "8d41f0", "hostname": "web-01.example.com", "status": "running", "ipv4_primary": "203.0.113.24", "location": { "code": "AMS", "city": "Amsterdam", "country_code": "NL" }, "plan": { "name": "Cloud VPS 2x4" } } ] }, "summary": "A running server" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "post": { "operationId": "servers_create", "description": "Order a new server, installed with an image or deployed from one of the project's completed snapshots: give `image` or `snapshot_id`, not both. The product, its locations and its images come from the products endpoint, and `ssh_keys` from the project's SSH keys. The order is `completed` once the server exists, and its `server_id` then names the server, which may still be starting for the first time. Without SSH keys, log in with a root password set by the server's reset-password action. User data is not available yet: a request that sets `user_data` is `400 feature_unavailable`. The order goes on the project owner's billing account and is paid from its account credit when the credit covers the invoice; otherwise it waits in `awaiting_payment` until the owner pays the invoice at `invoice.url`. Poll it at `GET /projects/{project_slug}/orders/{id}/` until its `status` is `completed`, `cancelled` or `failed`. Owner or admin only. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the order it placed. A `502` whose body carries `order_id` means the order may have been placed: poll that order to see whether it was, rather than ordering again. It counts against the key's rate limit for orders.", "summary": "Order a server", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the order it placed, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "servers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerCreateRequest" }, "examples": { "InstalledWithAnImage": { "value": { "hostname": "web-01.example.com", "product_id": 10, "location": "AMS", "image": "almalinux10", "billing_cycle": "monthly", "ssh_keys": [ 3810 ], "ipv6": true }, "summary": "Installed with an image" }, "DeployedFromASnapshot": { "value": { "hostname": "web-02.example.com", "product_id": 10, "location": "AMS", "snapshot_id": 2958 }, "summary": "Deployed from a snapshot" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "PaidFromAccountCredit": { "value": { "id": 87, "type": "server", "status": "provisioning", "server_id": null, "request": { "hostname": "web-01.example.com", "product_id": 10, "location": "AMS", "image": "almalinux10", "billing_cycle": "monthly", "ipv4_additional": 0, "ipv6": true, "private_network": false, "ssh_keys": [ 3810 ], "snapshot_id": null, "promo_code": null, "has_user_data": false }, "invoice": { "id": 715020, "status": "paid", "total": "12.00", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715020/" }, "warnings": [], "created_at": "2026-10-21T09:12:03.418209Z", "updated_at": "2026-10-21T09:12:05.902114Z" }, "summary": "Paid from account credit" }, "WaitingForPayment": { "value": { "id": 87, "type": "server", "status": "awaiting_payment", "server_id": null, "request": { "hostname": "web-01.example.com", "product_id": 10, "location": "AMS", "image": "almalinux10", "billing_cycle": "monthly", "ipv4_additional": 0, "ipv6": true, "private_network": false, "ssh_keys": [ 3810 ], "snapshot_id": null, "promo_code": null, "has_user_data": false }, "invoice": { "id": 715020, "status": "unpaid", "total": "12.00", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715020/" }, "warnings": [], "created_at": "2026-10-21T09:12:03.418209Z", "updated_at": "2026-10-21T09:12:04.731560Z" }, "summary": "Waiting for payment" } } } }, "description": "Created" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "ReplayedOnceTheServerExists": { "value": { "id": 87, "type": "server", "status": "completed", "server_id": "8d41f0", "request": { "hostname": "web-01.example.com", "product_id": 10, "location": "AMS", "image": "almalinux10", "billing_cycle": "monthly", "ipv4_additional": 0, "ipv6": true, "private_network": false, "ssh_keys": [ 3810 ], "snapshot_id": null, "promo_code": null, "has_user_data": false }, "invoice": { "id": 715020, "status": "paid", "total": "12.00", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715020/" }, "warnings": [], "created_at": "2026-10-21T09:12:03.418209Z", "updated_at": "2026-10-21T09:15:41.120385Z" }, "summary": "Replayed once the server exists" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ValidationFailed": { "value": { "type": "https://docs.hosthatch.com/api/errors#validation_error", "title": "Validation failed", "status": 400, "detail": "One or more fields are invalid.", "code": "validation_error", "instance": "/api/v1/projects/acme/servers/", "errors": [ { "field": "location", "code": "invalid", "message": "This product can't be ordered in this location now." } ] }, "summary": "Validation failed" } } } }, "description": "`validation_error`, `feature_unavailable`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`insufficient_role`, `read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`idempotency_key_reused`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheOrderMayHaveBeenPlaced": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The order's outcome is not known yet. Poll the order for it, and do not order again.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/", "order_id": 87 }, "summary": "The order may have been placed" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/": { "get": { "operationId": "servers_retrieve", "description": "One of the project's servers: its status, location, image, plan, addresses, bandwidth this month, firewall groups, SSH keys, mounted ISO and billing. `firewall_groups` and `billing` are null when they could not be read just now; the rest of the server is still returned.", "summary": "Get a server", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Server" }, "examples": { "ARunningServer": { "value": { "id": "8d41f0", "hostname": "web-01.example.com", "status": "running", "pending_changes": false, "location": { "code": "AMS", "city": "Amsterdam", "country_code": "NL" }, "image": { "name": "almalinux10", "display_name": "AlmaLinux 10" }, "plan": { "name": "Cloud VPS 2x4", "category": "Cloud", "cpu_cores": 2, "ram_mb": 4096, "disk_gb": 80, "boot_disk_gb": 0 }, "network": { "ipv4": [ { "address": "203.0.113.24", "primary": true, "netmask": "255.255.255.0", "gateway": "203.0.113.1" }, { "address": "203.0.113.87", "primary": false, "netmask": "255.255.255.0", "gateway": null } ], "ipv6": [ { "subnet": "2001:db8:4f2a:17::/64" } ], "private_network": { "eligible": true, "enabled": false } }, "bandwidth": { "pooled": true, "allocated_gb": 2000, "extra_gb": 0, "used_gb": 143, "pool": { "allocated_gb": 4000, "extra_gb": 0, "used_gb": 286 } }, "firewall_groups": [ 412 ], "ssh_keys": [ 3810 ], "iso": null, "has_user_data": false, "billing": { "service_id": 190412, "status": "Active", "billing_cycle": "monthly", "next_due_date": "2026-11-13", "recurring_amount": "12.00", "currency": "USD", "upgradeable_to": [ 11, 12 ] }, "created_at": "2026-10-13T12:58:59.114113Z" }, "summary": "A running server" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "patch": { "operationId": "servers_update", "description": "Change the server's hostname, the only property of a server that can change here. Answers with the server as it is now.", "summary": "Rename a server", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedServerUpdateRequest" }, "examples": { "ANewHostname": { "value": { "hostname": "web-02.example.com" }, "summary": "A new hostname" } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Server" }, "examples": { "Renamed": { "value": { "id": "8d41f0", "hostname": "web-02.example.com", "status": "running", "pending_changes": false, "location": { "code": "AMS", "city": "Amsterdam", "country_code": "NL" }, "image": { "name": "almalinux10", "display_name": "AlmaLinux 10" }, "plan": { "name": "Cloud VPS 2x4", "category": "Cloud", "cpu_cores": 2, "ram_mb": 4096, "disk_gb": 80, "boot_disk_gb": 0 }, "network": { "ipv4": [ { "address": "203.0.113.24", "primary": true, "netmask": "255.255.255.0", "gateway": "203.0.113.1" }, { "address": "203.0.113.87", "primary": false, "netmask": "255.255.255.0", "gateway": null } ], "ipv6": [ { "subnet": "2001:db8:4f2a:17::/64" } ], "private_network": { "eligible": true, "enabled": false } }, "bandwidth": { "pooled": true, "allocated_gb": 2000, "extra_gb": 0, "used_gb": 143, "pool": { "allocated_gb": 4000, "extra_gb": 0, "used_gb": 286 } }, "firewall_groups": [ 412 ], "ssh_keys": [ 3810 ], "iso": null, "has_user_data": false, "billing": { "service_id": 190412, "status": "Active", "billing_cycle": "monthly", "next_due_date": "2026-11-13", "recurring_amount": "12.00", "currency": "USD", "upgradeable_to": [ 11, 12 ] }, "created_at": "2026-10-13T12:58:59.114113Z" } } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/": { "get": { "operationId": "servers_actions_list", "description": "The actions started on one of the project's servers, newest first, each as it was last seen: fetch an action for its current state.", "summary": "List a server's actions", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedActionList" }, "examples": { "ARebootThatSucceeded": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 5121, "type": "server.reboot", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} } ] }, "summary": "A reboot that succeeded" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/create-snapshot/": { "post": { "operationId": "servers_create_snapshot", "description": "Take a snapshot of the server's disk. It shows in the project's snapshots as `pending` while it is taken, and the action succeeds once it is `completed`, with its id in `result.snapshot_id`. When the snapshot can't be identified, `result` is empty: the project's snapshots list it, the newest of this server's. The project owner's account keeps a limited number of snapshots, across all its projects; at the limit the request is `409 snapshot_limit_reached`. Failed snapshots don't count, and deleting one frees its place. A server that came from HostHatch's older SolusVM platform can't be snapshotted: `409 not_eligible`. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Take a snapshot", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.create_snapshot", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.create_snapshot", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": { "snapshot_id": 2958 } }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/create-snapshot/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `snapshot_limit_reached`, `not_eligible`, `action_in_progress`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/create-snapshot/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/enable-ipv6/": { "post": { "operationId": "servers_enable_ipv6", "description": "Route an IPv6 /64 subnet to the server. The subnet is in the action's `result.subnet` as soon as it is assigned, as the server's `network.ipv6` lists it: the network in CIDR notation, such as `2001:db8:1:2::/64`. The action succeeds once the network is set up for it. It places no order and raises no invoice. A server that has IPv6 already is `409 already_enabled`, and one whose location has no subnet left `409 insufficient_capacity`. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Enable IPv6", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.enable_ipv6", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": { "subnet": "2001:db8:4f2a:17::/64" } } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.enable_ipv6", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": { "subnet": "2001:db8:4f2a:17::/64" } }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`idempotency_key_reused`, `already_enabled`, `insufficient_capacity`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/enable-ipv6/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/enable-private-network/": { "post": { "operationId": "servers_enable_private_network", "description": "Attach the server to the private network shared by your servers in its location. The action succeeds at once, but the interface appears on the server's next start or reboot through this API; configure its address inside the server. A server whose `network.private_network.eligible` is false is `409 not_eligible`, and one already attached `409 already_enabled`; when they are null, the server's host decides. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Enable the private network", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.enable_private_network", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:01.044903Z", "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.enable_private_network", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:01.044903Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`idempotency_key_reused`, `not_eligible`, `already_enabled`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/enable-private-network/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/mount-iso/": { "post": { "operationId": "servers_mount_iso", "description": "Attach an ISO to the server as a CD-ROM drive. The server is restarted to attach it, and the action succeeds once it has been. The ISO is a library ISO, or the project's own once it is `ready`: one still downloading, or whose download failed, is `409 conflict`. Any other ISO is `404 not_found`. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Mount an ISO", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MountIsoRequest" }, "examples": { "ALibraryISO": { "value": { "iso_id": 5257 }, "summary": "A library ISO" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.mount_iso", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.mount_iso", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/mount-iso/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `action_in_progress`, `conflict`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/mount-iso/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/power-off/": { "post": { "operationId": "servers_power_off", "description": "Cut the power at once, as pulling the plug would. Unsaved data in the server is lost. The action succeeds once the server is off. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Power off a server", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.power_off", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.power_off", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/power-off/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `action_in_progress`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/power-off/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/power-on/": { "post": { "operationId": "servers_power_on", "description": "Start the server. A server with `pending_changes` has them applied as it starts. The action succeeds once the server is running. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Power on a server", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.power_on", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.power_on", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/power-on/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `action_in_progress`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/power-on/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/reboot/": { "post": { "operationId": "servers_reboot", "description": "Restart the server, as a reset button would: the operating system is not asked to shut down first. A server with `pending_changes` has them applied by this reboot. The action succeeds once the server has been started again. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Reboot a server", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.reboot", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.reboot", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/reboot/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `action_in_progress`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/reboot/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/reinstall/": { "post": { "operationId": "servers_reinstall", "description": "Erase the server's disk and install an image on it, with the given SSH keys. Everything on the disk is lost. `image` is one of the images endpoint's names, and `ssh_keys` ids of the project's keys: either unknown is `400 validation_error`, and no action is started. A reinstall that ends in `error` may have erased the disk already. Without SSH keys, log in with a root password set by the reset-password action. User data is not available yet: a request that sets `user_data` is `400 feature_unavailable`. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Reinstall a server", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReinstallRequest" }, "examples": { "AnImageAndAKey": { "value": { "image": "almalinux10", "ssh_keys": [ 3810 ] }, "summary": "An image and a key" }, "KeepingTheKeys": { "value": { "image": "almalinux9" }, "summary": "Keeping the keys" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.reinstall", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.reinstall", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`, `feature_unavailable`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/reinstall/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `action_in_progress`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/reinstall/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/reset-password/": { "post": { "operationId": "servers_reset_password", "description": "Set a new random root password on the running server, through the guest agent in it (qemu-guest-agent): a server that isn't running, or has no guest agent, ends the action in `error`. Once the action succeeds, reading it (`GET .../actions/{id}/`) shows the password in `result.password` for 15 minutes, never to a read-only key, and only while it is still the server's; lists and replays leave it out. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Reset the root password", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.reset_password", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.reset_password", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`idempotency_key_reused`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/reset-password/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/restore-snapshot/": { "post": { "operationId": "servers_restore_snapshot", "description": "Replace the server's disk with a snapshot. Everything on the disk now is lost, and a restore that ends in `error` may have changed the disk already. The snapshot must be one of the project's and `completed`, and can be of this server or of another one; any other is `400 validation_error`. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Restore a snapshot", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSnapshotRequest" }, "examples": { "ACompletedSnapshot": { "value": { "snapshot_id": 2958 }, "summary": "A completed snapshot" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.restore_snapshot", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.restore_snapshot", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/restore-snapshot/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `action_in_progress`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/restore-snapshot/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/shutdown/": { "post": { "operationId": "servers_shutdown", "description": "Ask the operating system to shut down, as pressing the power button would. The action succeeds once the request has been delivered, without waiting for the operating system, which may also ignore it. To be sure the server is off, power it off. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Shut down a server", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.shutdown", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.shutdown", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/shutdown/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `action_in_progress`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/shutdown/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/actions/unmount-iso/": { "post": { "operationId": "servers_unmount_iso", "description": "Detach the server's ISO. The server is restarted to detach it, and the action succeeds once it has been. One power, reinstall, snapshot or ISO action runs on a server at a time: while one does, the request is `409 action_in_progress`, with that action's id in `action_id` when it was started in this project. While the server's host is in maintenance, the request is `503 node_maintenance`. It takes no body: send none, or `{}`, which count as the same request. Answers `202` with the action: poll it at `GET /projects/{project_slug}/actions/{id}/` until its `status` is `success` or `error`. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the action it started. A `502` whose body carries `action_id` means the action may have started: poll that action rather than starting another. It counts against the key's rate limit for writes.", "summary": "Unmount the ISO", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the action it started, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "actions" ], "security": [ { "bearerAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "Started": { "value": { "id": 5121, "type": "server.unmount_iso", "status": "running", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": null, "error": null, "result": {} } } } } }, "description": "Accepted" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" }, "examples": { "ReplayedAfterItSucceeded": { "value": { "id": 5121, "type": "server.unmount_iso", "status": "success", "resource": { "type": "server", "id": "8d41f0" }, "started_at": "2026-10-21T09:30:00.512830Z", "finished_at": "2026-10-21T09:30:41.207415Z", "error": null, "result": {} }, "summary": "Replayed after it succeeded" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ActionInProgress": { "value": { "type": "https://docs.hosthatch.com/api/errors#action_in_progress", "title": "Action in progress", "status": 409, "detail": "Another action is still running on this server.", "code": "action_in_progress", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/unmount-iso/", "action_id": 5118 }, "summary": "Action in progress" } } } }, "description": "`idempotency_key_reused`, `action_in_progress`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheActionMayHaveStarted": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The outcome is not known yet. Poll the action for it.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/actions/unmount-iso/", "action_id": 5121 }, "summary": "The action may have started" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `node_maintenance`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/bandwidth/": { "post": { "operationId": "servers_bandwidth", "description": "Add extra bandwidth to the server for its current billing month, priced as the pricing endpoint lists it. The order is `completed` once the bandwidth is granted, which follows payment at once. A server whose subscription can't be found in billing is `409 conflict`: contact support. The order goes on the project owner's billing account and is paid from its account credit when the credit covers the invoice; otherwise it waits in `awaiting_payment` until the owner pays the invoice at `invoice.url`. Poll it at `GET /projects/{project_slug}/orders/{id}/` until its `status` is `completed`, `cancelled` or `failed`. Owner or admin only. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the order it placed. A `502` whose body carries `order_id` means the order may have been placed: poll that order to see whether it was, rather than ordering again. It counts against the key's rate limit for orders.", "summary": "Buy extra bandwidth", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the order it placed, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BandwidthOrderRequest" }, "examples": { "OneTerabyte": { "value": { "size_gb": 1000 }, "summary": "One terabyte" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "PaidFromAccountCredit": { "value": { "id": 89, "type": "bandwidth", "status": "completed", "server_id": "8d41f0", "request": { "size_gb": 1000 }, "invoice": { "id": 715044, "status": "paid", "total": "4.00", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715044/" }, "warnings": [], "created_at": "2026-10-21T10:20:45.611802Z", "updated_at": "2026-10-21T10:20:47.095336Z" }, "summary": "Paid from account credit" } } } }, "description": "Created" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "Replayed": { "value": { "id": 89, "type": "bandwidth", "status": "completed", "server_id": "8d41f0", "request": { "size_gb": 1000 }, "invoice": { "id": 715044, "status": "paid", "total": "4.00", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715044/" }, "warnings": [], "created_at": "2026-10-21T10:20:45.611802Z", "updated_at": "2026-10-21T10:20:47.095336Z" } } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`insufficient_role`, `read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`idempotency_key_reused`, `conflict`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheOrderMayHaveBeenPlaced": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The order's outcome is not known yet. Poll the order for it, and do not order again.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/bandwidth/", "order_id": 89 }, "summary": "The order may have been placed" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/cancel/": { "post": { "operationId": "servers_cancel", "description": "Ask for the server to be cancelled, at the end of its paid term or immediately; an immediate cancellation deletes the server and everything on it. Owner or admin only. A server keeps one cancellation request: sending the same request again answers 200 and changes nothing, so a request whose answer was lost can simply be sent again, while a request of the other kind is `409 conflict`. Once billing has carried out an immediate cancellation the server is gone, and a repeat answers 404. Safe to repeat as it is, it takes no `Idempotency-Key`: one sent is ignored. It counts against the key's rate limit for writes.", "summary": "Cancel a server", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" }, "examples": { "AtTheEndOfTheTerm": { "value": { "when": "end_of_term", "reason": "Moving to a larger plan." }, "summary": "At the end of the term" }, "Immediately": { "value": { "when": "immediate" } } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cancellation" }, "examples": { "Requested": { "value": { "status": "cancellation_requested", "when": "end_of_term" } } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`insufficient_role`, `read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`conflict`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/firewall-groups/": { "put": { "operationId": "servers_firewall_groups_update", "description": "Set the firewall groups attached to the server: the list replaces the current one, and [] detaches every group. Each id must be one of the project's groups. With any group attached, the server refuses new inbound connections that no ingress rule allows, SSH included, and once it has an egress group, outbound traffic that no egress rule allows. Answers with the ids now attached; the server's firewall follows in the background, after the answer.", "summary": "Set a server's firewall groups", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerFirewallGroupsRequest" }, "examples": { "TwoGroups": { "value": { "firewall_groups": [ 412, 415 ] }, "summary": "Two groups" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerFirewallGroups" }, "examples": { "TwoGroups": { "value": { "firewall_groups": [ 412, 415 ] }, "summary": "Two groups" } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/reverse-dns/": { "get": { "operationId": "servers_reverse_dns_list", "description": "The reverse DNS (PTR) name of each of the server's IPv4 addresses, the primary first; `ptr` is null where none is set. The names of IPv6 addresses are set and cleared one address at a time, and not listed. While the reverse DNS service is down, the answer is `503 reverse_dns_unavailable`.", "summary": "List a server's reverse DNS", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedReverseDnsList" }, "examples": { "ANameSet": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "address": "203.0.113.24", "ptr": "web-01.example.com" } ] }, "summary": "A name set" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `reverse_dns_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/reverse-dns/{address}/": { "put": { "operationId": "servers_reverse_dns_set", "description": "Set the reverse DNS name of one of the server's addresses: one of its IPv4 addresses, or any address inside one of its IPv6 subnets. It replaces any name the address had. While the reverse DNS service is down, the answer is `503 reverse_dns_unavailable`. A change that fails otherwise is `502 upstream_error`: support has been told, and the request can be sent again; contact support if it keeps failing.", "summary": "Set an address's reverse DNS", "parameters": [ { "in": "path", "name": "address", "schema": { "type": "string", "pattern": "^[0-9a-fA-F.:]{2,45}$" }, "description": "One of the server's IPv4 addresses, or an IPv6 address inside one of its subnets. Any other address is `404 not_found`.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseDnsUpdateRequest" }, "examples": { "AName": { "value": { "ptr": "web-01.example.com" }, "summary": "A name" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseDns" }, "examples": { "Set": { "value": { "address": "203.0.113.24", "ptr": "web-01.example.com" } } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `reverse_dns_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "delete": { "operationId": "servers_reverse_dns_clear", "description": "Remove the reverse DNS name of one of the server's addresses: one of its IPv4 addresses, or an address inside one of its IPv6 subnets.", "summary": "Clear an address's reverse DNS", "parameters": [ { "in": "path", "name": "address", "schema": { "type": "string", "pattern": "^[0-9a-fA-F.:]{2,45}$" }, "description": "One of the server's IPv4 addresses, or an IPv6 address inside one of its subnets. Any other address is `404 not_found`.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`, `reverse_dns_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/upgrade/": { "post": { "operationId": "servers_upgrade", "description": "Upgrade the server to one of its upgrade options, keeping its billing cycle. Billing invoices what is left of the current term and applies the upgrade once the invoice is paid, when the order is `completed`. The server then shows `pending_changes`: its next start or reboot through this API brings the new plan into effect. A server takes one upgrade at a time: another, while one is unpaid or its outcome unknown, is `409 conflict`, with the open upgrade's id in `order_id` when it was ordered in this project. A product out of stock in the server's location is `409 insufficient_capacity`. The order goes on the project owner's billing account and is paid from its account credit when the credit covers the invoice; otherwise it waits in `awaiting_payment` until the owner pays the invoice at `invoice.url`. Poll it at `GET /projects/{project_slug}/orders/{id}/` until its `status` is `completed`, `cancelled` or `failed`. Owner or admin only. Send an `Idempotency-Key`: a request whose answer was lost can then be sent again, and is answered with the order it placed. A `502` whose body carries `order_id` means the order may have been placed: poll that order to see whether it was, rather than ordering again. It counts against the key's rate limit for orders.", "summary": "Upgrade a server", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "1 to 64 characters. Repeating a request with the same key and body answers with the order it placed, whatever state that reached, with status 200 and `Idempotent-Replayed: true`." }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpgradeRequest" }, "examples": { "ALargerPlanAndDisk": { "value": { "product_id": 11, "upgrade_disk": true }, "summary": "A larger plan and disk" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "WaitingForPayment": { "value": { "id": 88, "type": "upgrade", "status": "awaiting_payment", "server_id": "8d41f0", "request": { "product_id": 11, "upgrade_disk": true }, "invoice": { "id": 715031, "status": "unpaid", "total": "6.40", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715031/" }, "warnings": [], "created_at": "2026-10-21T10:02:11.004127Z", "updated_at": "2026-10-21T10:02:12.385901Z" }, "summary": "Waiting for payment" } } } }, "description": "Created" }, "200": { "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true`: this is the answer to an earlier request with the same `Idempotency-Key`." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "examples": { "ReplayedOnceItWasPaid": { "value": { "id": 88, "type": "upgrade", "status": "completed", "server_id": "8d41f0", "request": { "product_id": 11, "upgrade_disk": true }, "invoice": { "id": 715031, "status": "paid", "total": "6.40", "currency": "USD", "url": "https://console.hosthatch.com/billing/invoice/715031/" }, "warnings": [], "created_at": "2026-10-21T10:02:11.004127Z", "updated_at": "2026-10-21T10:41:37.218664Z" }, "summary": "Replayed once it was paid" } } } }, "description": "A replay of an earlier request with the same key." }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`insufficient_role`, `read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "AnUpgradeIsOpen": { "value": { "type": "https://docs.hosthatch.com/api/errors#conflict", "title": "Conflict", "status": 409, "detail": "This server has an upgrade that isn't paid or settled yet.", "code": "conflict", "instance": "/api/v1/projects/acme/servers/8d41f0/upgrade/", "order_id": 88 }, "summary": "An upgrade is open" } } } }, "description": "`idempotency_key_reused`, `conflict`, `insufficient_capacity`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "TheOrderMayHaveBeenPlaced": { "value": { "type": "https://docs.hosthatch.com/api/errors#upstream_error", "title": "Upstream error", "status": 502, "detail": "The order's outcome is not known yet. Poll the order for it, and do not order again.", "code": "upstream_error", "instance": "/api/v1/projects/acme/servers/8d41f0/upgrade/", "order_id": 88 }, "summary": "The order may have been placed" } } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/servers/{server_id}/upgrade-options/": { "get": { "operationId": "servers_upgrade_options_list", "description": "The products this server can be upgraded to, with their prices. An upgrade keeps the server's billing cycle. One not `in_stock` can't be ordered in the server's location now. Order an upgrade with `POST .../servers/{server_id}/upgrade/`. A server whose subscription can't be found in billing is `409 conflict`: contact support.", "summary": "List a server's upgrade options", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "server_id", "schema": { "type": "string", "pattern": "^[0-9a-f]{1,32}$" }, "required": true, "description": "The server's id, as the project's server list gives it." } ], "tags": [ "servers" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedUpgradeOptionList" }, "examples": { "ALargerPlan": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "product_id": 11, "name": "Cloud VPS 4x8", "prices": { "monthly": "24.00", "annually": "288.00" }, "currency": "USD", "in_stock": true } ] }, "summary": "A larger plan" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`conflict`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/snapshots/": { "get": { "operationId": "snapshots_list", "description": "The project's snapshots, oldest first. Take one with a server's `create-snapshot` action; restore one with `restore-snapshot`. A snapshot belongs to the project, so it can be restored onto any of the project's servers, and stays when the server it was taken of is gone.", "summary": "List snapshots", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "snapshots" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSnapshotList" }, "examples": { "ACompletedSnapshot": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 2958, "name": "before upgrade", "status": "completed", "state": "completed", "size_gb": 12.5, "server_id": "8d41f0", "image": "almalinux9", "created_at": "2026-10-19T10:00:00.000000Z", "error": null } ] }, "summary": "A completed snapshot" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/snapshots/{snapshot_id}/": { "get": { "operationId": "snapshots_retrieve", "description": "One of the project's snapshots. Poll it while its status is `pending`.", "summary": "Get a snapshot", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "snapshot_id", "schema": { "type": "integer" }, "description": "The snapshot's id.", "required": true } ], "tags": [ "snapshots" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snapshot" }, "examples": { "ACompletedSnapshot": { "value": { "id": 2958, "name": "before upgrade", "status": "completed", "state": "completed", "size_gb": 12.5, "server_id": "8d41f0", "image": "almalinux9", "created_at": "2026-10-19T10:00:00.000000Z", "error": null }, "summary": "A completed snapshot" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "patch": { "operationId": "snapshots_rename", "description": "Change the name a snapshot is shown by, 1 to 250 characters. Nothing else about it can change.", "summary": "Rename a snapshot", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "snapshot_id", "schema": { "type": "integer" }, "description": "The snapshot's id.", "required": true } ], "tags": [ "snapshots" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedSnapshotRenameRequest" }, "examples": { "NewName": { "value": { "name": "before upgrade" }, "summary": "New name" } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snapshot" }, "examples": { "Renamed": { "value": { "id": 2958, "name": "before upgrade", "status": "completed", "state": "completed", "size_gb": 12.5, "server_id": "8d41f0", "image": "almalinux9", "created_at": "2026-10-19T10:00:00.000000Z", "error": null } } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "delete": { "operationId": "snapshots_delete", "description": "Delete a snapshot for good. It stops counting against the snapshot limit of the project's owner.", "summary": "Delete a snapshot", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." }, { "in": "path", "name": "snapshot_id", "schema": { "type": "integer" }, "description": "The snapshot's id.", "required": true } ], "tags": [ "snapshots" ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/ssh-keys/": { "get": { "operationId": "ssh_keys_list", "description": "The project's SSH keys, which its servers can be ordered or reinstalled with, by their `id`. Any member of the project can use them.", "summary": "List SSH keys", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "A page number within the paginated result set. A page past the end, or one that is not a number, answers 404 not_found.", "schema": { "type": "integer" } }, { "name": "page_size", "required": false, "in": "query", "description": "Number of results per page: 50 by default. More than 100 is taken as 100, and anything but a positive number as 50.", "schema": { "type": "integer" } }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "ssh-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSshKeyList" }, "examples": { "AKey": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "id": 3810, "name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK6HPrFUki0dT8tIlriQ8qOFxjdeIh6bii6Dgy8hvvMy", "fingerprint": "SHA256:4+TOP9WbPUutgjZim07htat6rokPCOgBtDlvOx91pjg", "created_at": "2026-03-18T00:00:00Z" } ] }, "summary": "A key" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "post": { "operationId": "ssh_keys_create", "description": "Add a public key to the project, as one line of a .pub file. The comment after the key is not kept: `name` is the key's label. A key that is already in the project, whatever its comment, answers `409 key_exists` with the existing key's id in `key_id`, so a create whose response was lost can be sent again. While one create of a key is running, another create of the same key answers `409 conflict`.", "summary": "Add an SSH key", "parameters": [ { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "ssh-keys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKeyCreateRequest" }, "examples": { "AnEd25519Key": { "value": { "name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK6HPrFUki0dT8tIlriQ8qOFxjdeIh6bii6Dgy8hvvMy jane@laptop" }, "summary": "An Ed25519 key" } } } }, "required": true }, "security": [ { "bearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKey" }, "examples": { "Added": { "value": { "id": 3810, "name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK6HPrFUki0dT8tIlriQ8qOFxjdeIh6bii6Dgy8hvvMy", "fingerprint": "SHA256:4+TOP9WbPUutgjZim07htat6rokPCOgBtDlvOx91pjg", "created_at": "2026-03-18T00:00:00Z" } } } } }, "description": "Created" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "ValidationFailed": { "value": { "type": "https://docs.hosthatch.com/api/errors#validation_error", "title": "Validation failed", "status": 400, "detail": "One or more fields are invalid.", "code": "validation_error", "instance": "/api/v1/projects/acme/ssh-keys/", "errors": [ { "field": "public_key", "code": "invalid", "message": "RSA keys need at least 2048 bits; this one has 1024." } ] }, "summary": "Validation failed" } } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "examples": { "KeyExists": { "value": { "type": "https://docs.hosthatch.com/api/errors#key_exists", "title": "Key exists", "status": 409, "detail": "This public key is already in the project.", "code": "key_exists", "instance": "/api/v1/projects/acme/ssh-keys/", "key_id": 3810 }, "summary": "Key exists" } } } }, "description": "`key_exists`, `conflict`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } }, "/projects/{project_slug}/ssh-keys/{key_id}/": { "get": { "operationId": "ssh_keys_retrieve", "description": "One of the project's SSH keys.", "summary": "Get an SSH key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "integer" }, "description": "The key's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "ssh-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKey" }, "examples": { "AKey": { "value": { "id": 3810, "name": "laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK6HPrFUki0dT8tIlriQ8qOFxjdeIh6bii6Dgy8hvvMy", "fingerprint": "SHA256:4+TOP9WbPUutgjZim07htat6rokPCOgBtDlvOx91pjg", "created_at": "2026-03-18T00:00:00Z" }, "summary": "A key" } } } }, "description": "OK" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "patch": { "operationId": "ssh_keys_rename", "description": "Rename a key. The public key itself cannot change: add the new key and delete the old one.", "summary": "Rename an SSH key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "integer" }, "description": "The key's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "ssh-keys" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedSshKeyRenameRequest" }, "examples": { "ANewName": { "value": { "name": "work laptop" }, "summary": "A new name" } } } } }, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKey" }, "examples": { "Renamed": { "value": { "id": 3810, "name": "work laptop", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK6HPrFUki0dT8tIlriQ8qOFxjdeIh6bii6Dgy8hvvMy", "fingerprint": "SHA256:4+TOP9WbPUutgjZim07htat6rokPCOgBtDlvOx91pjg", "created_at": "2026-03-18T00:00:00Z" } } } } }, "description": "OK" }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`validation_error`" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "415": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`unsupported_media_type`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } }, "delete": { "operationId": "ssh_keys_delete", "description": "Delete a key from the project. Servers can no longer be ordered or reinstalled with it.", "summary": "Delete an SSH key", "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "integer" }, "description": "The key's id.", "required": true }, { "in": "path", "name": "project_slug", "schema": { "type": "string" }, "required": true, "description": "The project's slug. `GET /me/` lists the projects the API key can reach." } ], "tags": [ "ssh-keys" ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`authentication_required`, `invalid_api_key`, `api_key_expired`" }, "403": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`read_only_key`, `billing_account_required`, `project_not_ready`" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_found`" }, "406": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`not_acceptable`" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`rate_limited`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } }, "500": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`internal_error`" }, "502": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_error`" }, "503": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "`upstream_unavailable`", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "How many seconds to wait before sending the request again." } } } } } } }, "components": { "schemas": { "Action": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "type": { "allOf": [ { "$ref": "#/components/schemas/ActionTypeEnum" } ], "readOnly": true, "description": "What the action does, named after the endpoint that started it: `server.power_on` was started by `POST /projects/{project_slug}/servers/{server_id}/actions/power-on/`, `server.enable_ipv6` by `.../actions/enable-ipv6/`, and so on." }, "status": { "allOf": [ { "$ref": "#/components/schemas/ActionStatusEnum" } ], "readOnly": true, "description": "Where the action stands. `running`: started, and not finished yet. `unknown`: the request reached the server's host but its answer was lost, so whether it happened is being found out; it ends as `success` or `error`, through support if need be. Until then, a power, reinstall, snapshot or ISO action still blocks the others on its server. `success` and `error` are final: poll the action until it has one of them." }, "resource": { "$ref": "#/components/schemas/ActionResource" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When it became `success` or `error`; null until then." }, "error": { "allOf": [ { "$ref": "#/components/schemas/ActionError" } ], "nullable": true, "readOnly": true, "description": "Why the action failed; null unless its status is `error`." }, "result": { "type": "object", "additionalProperties": {}, "readOnly": true, "description": "What the action produced. `server.create_snapshot`: `snapshot_id` once it succeeded, when the snapshot can be identified. `server.enable_ipv6`: `subnet` as soon as it is assigned. `server.reset_password`: `password` once it succeeded, served for 15 minutes when the action itself is read, never in a list or a replay, nor to a read-only key. Empty otherwise." } }, "required": [ "error", "finished_at", "id", "resource", "result", "started_at", "status", "type" ] }, "ActionError": { "type": "object", "properties": { "code": { "type": "string", "description": "`failed`: the operation failed. `outcome_unknown`: whether it happened could not be confirmed, so check the server. `task_result_unavailable`: the server's host no longer has the operation's result, so check the server. `timeout`: it did not finish within 24 hours. `resource_moved`: the server was moved to another project before the result could be collected. Contact support if the server is not as you expect." }, "message": { "type": "string", "description": "A sentence for humans; it may change." } }, "required": [ "code", "message" ] }, "ActionResource": { "type": "object", "properties": { "type": { "type": "string", "description": "What the action runs on: `server`." }, "id": { "type": "string", "description": "Its id, such as the server's." } }, "required": [ "id", "type" ] }, "ActionStatusEnum": { "enum": [ "running", "unknown", "success", "error" ], "type": "string" }, "ActionTypeEnum": { "enum": [ "server.power_on", "server.power_off", "server.shutdown", "server.reboot", "server.reinstall", "server.reset_password", "server.restore_snapshot", "server.create_snapshot", "server.mount_iso", "server.unmount_iso", "server.enable_ipv6", "server.enable_private_network" ], "type": "string" }, "AdditionalIPv4Price": { "type": "object", "properties": { "count": { "type": "integer", "description": "IPv4 addresses beyond the server's own, as an order's `ipv4_additional`." }, "prices": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The recurring price by billing cycle." }, "setup_fees": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The setup fee by billing cycle." } }, "required": [ "count", "prices", "setup_fees" ] }, "Bandwidth": { "type": "object", "properties": { "pooled": { "type": "boolean", "description": "Shared with the other servers of the project's owner in the same location." }, "allocated_gb": { "type": "integer", "nullable": true, "description": "This server's monthly allowance." }, "extra_gb": { "type": "integer", "nullable": true, "description": "Extra bandwidth bought for this month." }, "used_gb": { "type": "integer", "nullable": true, "description": "Used this month." }, "pool": { "allOf": [ { "$ref": "#/components/schemas/BandwidthPool" } ], "nullable": true, "description": "The pool's totals; null when not pooled." } }, "required": [ "allocated_gb", "extra_gb", "pool", "pooled", "used_gb" ] }, "BandwidthOrderRequest": { "type": "object", "properties": { "size_gb": { "allOf": [ { "$ref": "#/components/schemas/SizeGbEnum" } ], "description": "How much extra bandwidth to add, in GB. The pricing endpoint lists the prices." } }, "required": [ "size_gb" ] }, "BandwidthPool": { "type": "object", "properties": { "allocated_gb": { "type": "integer", "nullable": true }, "extra_gb": { "type": "integer", "nullable": true }, "used_gb": { "type": "integer", "nullable": true } }, "required": [ "allocated_gb", "extra_gb", "used_gb" ] }, "BandwidthPrice": { "type": "object", "properties": { "size_gb": { "type": "integer", "description": "The `size_gb` a bandwidth order takes." }, "price": { "type": "string", "description": "Charged once, as a decimal string with two places." } }, "required": [ "price", "size_gb" ] }, "Billing": { "type": "object", "properties": { "service_id": { "type": "integer" }, "status": { "type": "string", "nullable": true, "description": "The subscription's status, as billing spells it: `Active`, `Suspended`, `Cancelled` and so on." }, "billing_cycle": { "type": "string", "nullable": true, "description": "monthly, quarterly, semiannually and so on." }, "next_due_date": { "type": "string", "format": "date", "nullable": true }, "recurring_amount": { "type": "string", "nullable": true, "description": "Decimal string with two places." }, "currency": { "type": "string", "description": "ISO 4217." }, "upgradeable_to": { "type": "array", "items": { "type": "integer" }, "description": "Product ids this server can be upgraded to." } }, "required": [ "billing_cycle", "currency", "next_due_date", "recurring_amount", "service_id", "status", "upgradeable_to" ] }, "BillingAccount": { "type": "object", "properties": { "exists": { "type": "boolean", "description": "Whether the user has set up billing; `credit_balance` and `currency` come with it." }, "credit_balance": { "type": "string", "nullable": true, "description": "Account credit, as a decimal string. It pays for orders in the projects the user owns; in another owner's project, that owner's credit pays. Null when it can't be read just now." }, "currency": { "type": "string", "description": "ISO 4217." } }, "required": [ "exists" ] }, "BillingCycleEnum": { "enum": [ "monthly", "quarterly", "semiannually", "annually", "biennially", "triennially" ], "type": "string" }, "CancelRequest": { "type": "object", "properties": { "when": { "allOf": [ { "$ref": "#/components/schemas/WhenEnum" } ], "description": "end_of_term: when the paid period ends; immediate: now, and the server is deleted." }, "reason": { "type": "string", "description": "Why. Required for end_of_term.", "maxLength": 1000 } }, "required": [ "when" ] }, "Cancellation": { "type": "object", "properties": { "status": { "allOf": [ { "$ref": "#/components/schemas/CancellationStatusEnum" } ], "description": "Always `cancellation_requested`: billing has the request, and carries it out when it is due." }, "when": { "allOf": [ { "$ref": "#/components/schemas/WhenEnum" } ], "description": "When the server is cancelled, as requested." } }, "required": [ "status", "when" ] }, "CancellationStatusEnum": { "enum": [ "cancellation_requested" ], "type": "string" }, "CurrentUser": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string", "format": "email" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "billing_account": { "$ref": "#/components/schemas/BillingAccount" }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectRef" } } }, "required": [ "billing_account", "email", "first_name", "id", "last_name", "projects" ] }, "DirectionEnum": { "enum": [ "ingress", "egress" ], "type": "string" }, "FirewallGroup": { "type": "object", "description": "A firewall group: rules that allow traffic, and the servers they apply to.", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "description": "Letters, digits, spaces, dots, underscores and hyphens, starting with a letter or digit. Unique in the project.", "maxLength": 255 }, "direction": { "allOf": [ { "$ref": "#/components/schemas/DirectionEnum" } ], "description": "`ingress` rules allow traffic to the servers, `egress` rules traffic from them. Fixed when the group is created." }, "servers": { "type": "array", "items": { "type": "string" }, "readOnly": true, "description": "The ids of the servers the group is attached to." }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallRule" }, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "direction", "id", "name", "rules", "servers" ] }, "FirewallGroupRequest": { "type": "object", "description": "A firewall group: rules that allow traffic, and the servers they apply to.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Letters, digits, spaces, dots, underscores and hyphens, starting with a letter or digit. Unique in the project.", "maxLength": 255 }, "direction": { "allOf": [ { "$ref": "#/components/schemas/DirectionEnum" } ], "description": "`ingress` rules allow traffic to the servers, `egress` rules traffic from them. Fixed when the group is created." } }, "required": [ "direction", "name" ] }, "FirewallRule": { "type": "object", "description": "A rule in a firewall group. Every field is present, and null where it is not set.", "properties": { "id": { "type": "integer", "readOnly": true }, "protocol": { "allOf": [ { "$ref": "#/components/schemas/ProtocolEnum" } ], "readOnly": true, "description": "`tcp`, `udp`, `icmp`, or `any` for every protocol. Only `tcp` and `udp` rules take ports." }, "port_min": { "type": "integer", "maximum": 65535, "minimum": 1, "readOnly": true, "nullable": true, "description": "The first port of the range, for `tcp` and `udp` only. Leave both ports empty to allow every port." }, "port_max": { "type": "integer", "maximum": 65535, "minimum": 1, "readOnly": true, "nullable": true, "description": "The last port of the range; empty for `port_min` alone. Needs `port_min`." }, "source_cidr": { "type": "string", "readOnly": true, "nullable": true, "description": "Where the traffic comes from, for rules of an `ingress` group. A network in CIDR notation, such as `192.0.2.0/24` or `2001:db8::/32`, or a single address, which is stored as a `/32` or `/128` prefix. Send the network address: `192.0.2.1/24` is refused rather than read as `192.0.2.0/24`, so a typo cannot change what the rule matches. A scope id, quotes and whitespace are refused. A network of one address family matches that family only, so `0.0.0.0/0` is every IPv4 address and no IPv6 one. Returned in canonical form. Empty or null means any address, IPv4 or IPv6, and is returned as null." }, "destination_cidr": { "type": "string", "readOnly": true, "nullable": true, "description": "Where the traffic goes, for rules of an `egress` group. A network in CIDR notation, such as `192.0.2.0/24` or `2001:db8::/32`, or a single address, which is stored as a `/32` or `/128` prefix. Send the network address: `192.0.2.1/24` is refused rather than read as `192.0.2.0/24`, so a typo cannot change what the rule matches. A scope id, quotes and whitespace are refused. A network of one address family matches that family only, so `0.0.0.0/0` is every IPv4 address and no IPv6 one. Returned in canonical form. Empty or null means any address, IPv4 or IPv6, and is returned as null." }, "priority": { "type": "integer", "maximum": 64996, "minimum": 1, "readOnly": true, "default": 1000, "description": "Orders the rules in a group, lowest first, from 1 to 64996. Every rule allows traffic, so the order never changes what is allowed." }, "comment": { "type": "string", "readOnly": true, "nullable": true, "description": "A note; it changes nothing.", "maxLength": 255 } }, "required": [ "comment", "destination_cidr", "id", "port_max", "port_min", "priority", "protocol", "source_cidr" ] }, "FirewallRuleRequest": { "type": "object", "description": "A rule allows the traffic it matches: a protocol, optionally ports, and an address range for its direction.", "properties": { "protocol": { "allOf": [ { "$ref": "#/components/schemas/ProtocolEnum" } ], "description": "`tcp`, `udp`, `icmp`, or `any` for every protocol. Only `tcp` and `udp` rules take ports." }, "port_min": { "type": "integer", "maximum": 65535, "minimum": 1, "nullable": true, "description": "The first port of the range, for `tcp` and `udp` only. Leave both ports empty to allow every port." }, "port_max": { "type": "integer", "maximum": 65535, "minimum": 1, "nullable": true, "description": "The last port of the range; empty for `port_min` alone. Needs `port_min`." }, "source_cidr": { "type": "string", "nullable": true, "description": "Where the traffic comes from, for rules of an `ingress` group. A network in CIDR notation, such as `192.0.2.0/24` or `2001:db8::/32`, or a single address, which is stored as a `/32` or `/128` prefix. Send the network address: `192.0.2.1/24` is refused rather than read as `192.0.2.0/24`, so a typo cannot change what the rule matches. A scope id, quotes and whitespace are refused. A network of one address family matches that family only, so `0.0.0.0/0` is every IPv4 address and no IPv6 one. Returned in canonical form. Empty or null means any address, IPv4 or IPv6, and is returned as null." }, "destination_cidr": { "type": "string", "nullable": true, "description": "Where the traffic goes, for rules of an `egress` group. A network in CIDR notation, such as `192.0.2.0/24` or `2001:db8::/32`, or a single address, which is stored as a `/32` or `/128` prefix. Send the network address: `192.0.2.1/24` is refused rather than read as `192.0.2.0/24`, so a typo cannot change what the rule matches. A scope id, quotes and whitespace are refused. A network of one address family matches that family only, so `0.0.0.0/0` is every IPv4 address and no IPv6 one. Returned in canonical form. Empty or null means any address, IPv4 or IPv6, and is returned as null." }, "priority": { "type": "integer", "maximum": 64996, "minimum": 1, "default": 1000, "description": "Orders the rules in a group, lowest first, from 1 to 64996. Every rule allows traffic, so the order never changes what is allowed." }, "comment": { "type": "string", "nullable": true, "description": "A note; it changes nothing.", "maxLength": 255 } }, "required": [ "protocol" ] }, "IPv4Address": { "type": "object", "properties": { "address": { "type": "string", "format": "ipv4" }, "primary": { "type": "boolean" }, "netmask": { "type": "string", "nullable": true }, "gateway": { "type": "string", "nullable": true, "description": "Set for the primary address only." } }, "required": [ "address", "gateway", "netmask", "primary" ] }, "IPv6Price": { "type": "object", "properties": { "prices": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The recurring price by billing cycle." }, "setup_fees": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The setup fee by billing cycle." } }, "required": [ "prices", "setup_fees" ] }, "IPv6Subnet": { "type": "object", "properties": { "subnet": { "type": "string", "description": "A subnet routed to the server: the network in CIDR notation, such as 2001:db8:1:2::/64." } }, "required": [ "subnet" ] }, "Image": { "type": "object", "properties": { "name": { "type": "string", "description": "The name an order or a reinstall takes." }, "distro": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true }, "display_name": { "type": "string", "nullable": true } }, "required": [ "display_name", "distro", "name", "version" ] }, "Iso": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "The ISO's file name." }, "type": { "allOf": [ { "$ref": "#/components/schemas/IsoTypeEnum" } ], "readOnly": true, "description": "`library`: HostHatch's, shared by every project. `custom`: uploaded to this project." }, "status": { "allOf": [ { "$ref": "#/components/schemas/IsoStatusEnum" } ], "readOnly": true, "description": "A `custom` ISO downloads to HostHatch's mirrors after its upload: `downloading` until it is `ready` to mount, or `failed`. A `library` ISO is always `ready`. `ready` and `failed` are final: delete a failed ISO to upload it again." }, "progress": { "type": "integer", "readOnly": true, "description": "How much of the download is done, from 0 to 100." }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "created_at", "id", "name", "progress", "status", "type" ] }, "IsoRef": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true } }, "required": [ "id", "name" ] }, "IsoStatusEnum": { "enum": [ "downloading", "ready", "failed" ], "type": "string" }, "IsoTypeEnum": { "enum": [ "library", "custom" ], "type": "string" }, "IsoUploadRequest": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "A direct http or https link to the file, ending in its name: letters, digits, dots, hyphens, underscores and plus signs, ending in .iso. No user name or password, query string or fragment. The host must be public, and the URL must answer a HEAD request with 200, without a redirect. At most 10 GiB, reporting its size, with a file name the project's owner has no upload of, in any of their projects.", "maxLength": 255 } }, "required": [ "url" ] }, "Location": { "type": "object", "properties": { "code": { "type": "string", "description": "The code an order takes." }, "city": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2, upper case." } }, "required": [ "city", "code", "country", "country_code" ] }, "LocationEnum": { "enum": [ "AMS", "STO", "LAX", "CHI", "NYC", "VIE", "LON", "ZRH", "HKG", "SGP", "TOK", "SYD", "OSL", "SEL" ], "type": "string" }, "MountIsoRequest": { "type": "object", "properties": { "iso_id": { "type": "integer", "minimum": 1, "description": "A library ISO, or the project's own ISO once its status is `ready`." } }, "required": [ "iso_id" ] }, "Network": { "type": "object", "properties": { "ipv4": { "type": "array", "items": { "$ref": "#/components/schemas/IPv4Address" }, "description": "The primary address first." }, "ipv6": { "type": "array", "items": { "$ref": "#/components/schemas/IPv6Subnet" } }, "private_network": { "allOf": [ { "$ref": "#/components/schemas/PrivateNetwork" } ], "nullable": true } }, "required": [ "ipv4", "ipv6", "private_network" ] }, "Order": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "type": { "allOf": [ { "$ref": "#/components/schemas/OrderTypeEnum" } ], "readOnly": true, "description": "`server`: a new server. `upgrade`: an existing server moved to another product. `bandwidth`: extra bandwidth for a server's current month." }, "status": { "allOf": [ { "$ref": "#/components/schemas/OrderStatusEnum" } ], "readOnly": true, "description": "Where the order stands. `submitting`: being placed with billing, for a moment. `awaiting_payment`: placed, and its invoice waits to be paid; the project's owner can pay it at `invoice.url`. `provisioning`: paid, and what was bought is being set up. `unknown`: billing's answer was lost; the order is looked for in billing, never placed again, and settled by support if it can't be found. `completed`: delivered, and for a new server `server_id` names it. `cancelled`: its invoice was cancelled or refunded, or the new server's subscription was cancelled. `failed`: billing refused or rejected it. `completed`, `cancelled` and `failed` are final." }, "server_id": { "type": "string", "nullable": true, "readOnly": true, "description": "The server the order is for: from the start for an upgrade or bandwidth, once it exists otherwise." }, "request": { "description": "What the order asked for: for a server, the create request, where `has_user_data` takes the place of `user_data`; for an upgrade, `product_id` and `upgrade_disk`; for bandwidth, `size_gb`." }, "invoice": { "allOf": [ { "$ref": "#/components/schemas/OrderInvoice" } ], "nullable": true, "readOnly": true, "description": "The order's invoice, as billing last showed it. Null until billing has made one, and for a free upgrade." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/OrderWarning" }, "description": "Something that went wrong after billing took the order. Support has been told." }, "created_at": { "type": "string", "format": "date-time", "description": "When the order was placed." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the order last changed." } }, "required": [ "created_at", "id", "invoice", "request", "server_id", "status", "type", "updated_at", "warnings" ] }, "OrderInvoice": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "nullable": true, "description": "As billing last showed it, in lower case: `unpaid` (or `draft`, `payment pending`, `collections`) while it waits for payment, `paid`, `cancelled` or `refunded`." }, "total": { "type": "string", "nullable": true, "description": "Decimal string with two places." }, "currency": { "type": "string", "description": "ISO 4217." }, "url": { "type": "string", "format": "uri", "description": "Where the project's owner can see and pay the invoice in the console." } }, "required": [ "currency", "id", "status", "total", "url" ] }, "OrderStatusEnum": { "enum": [ "submitting", "awaiting_payment", "provisioning", "completed", "cancelled", "failed", "unknown" ], "type": "string" }, "OrderTypeEnum": { "enum": [ "server", "upgrade", "bandwidth" ], "type": "string" }, "OrderWarning": { "type": "object", "properties": { "code": { "type": "string", "description": "`credit_unconfirmed`: paying the invoice from account credit could not be confirmed." }, "message": { "type": "string", "description": "A sentence for humans; it may change." } }, "required": [ "code", "message" ] }, "PaginatedActionList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } } }, "PaginatedFirewallGroupList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallGroup" } } } }, "PaginatedFirewallRuleList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FirewallRule" } } } }, "PaginatedImageList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } } } }, "PaginatedIsoList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Iso" } } } }, "PaginatedLocationList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } } } }, "PaginatedOrderList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } }, "PaginatedProductList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "PaginatedProjectList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } }, "PaginatedReverseDnsList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReverseDns" } } } }, "PaginatedServerSummaryList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ServerSummary" } } } }, "PaginatedSnapshotList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Snapshot" } } } }, "PaginatedSshKeyList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SshKey" } } } }, "PaginatedUpgradeOptionList": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "example": 1, "description": "How many items the list has, on every page together." }, "next": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The next page's URL, or null on the last page." }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": null, "description": "The previous page's URL, or null on the first page." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/UpgradeOption" } } } }, "PatchedFirewallGroupRenameRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Letters, digits, spaces, dots, underscores and hyphens, starting with a letter or digit. Unique in the project.", "maxLength": 255 } } }, "PatchedFirewallRuleRequest": { "type": "object", "description": "A rule allows the traffic it matches: a protocol, optionally ports, and an address range for its direction.", "properties": { "protocol": { "allOf": [ { "$ref": "#/components/schemas/ProtocolEnum" } ], "description": "`tcp`, `udp`, `icmp`, or `any` for every protocol. Only `tcp` and `udp` rules take ports." }, "port_min": { "type": "integer", "maximum": 65535, "minimum": 1, "nullable": true, "description": "The first port of the range, for `tcp` and `udp` only. Leave both ports empty to allow every port." }, "port_max": { "type": "integer", "maximum": 65535, "minimum": 1, "nullable": true, "description": "The last port of the range; empty for `port_min` alone. Needs `port_min`." }, "source_cidr": { "type": "string", "nullable": true, "description": "Where the traffic comes from, for rules of an `ingress` group. A network in CIDR notation, such as `192.0.2.0/24` or `2001:db8::/32`, or a single address, which is stored as a `/32` or `/128` prefix. Send the network address: `192.0.2.1/24` is refused rather than read as `192.0.2.0/24`, so a typo cannot change what the rule matches. A scope id, quotes and whitespace are refused. A network of one address family matches that family only, so `0.0.0.0/0` is every IPv4 address and no IPv6 one. Returned in canonical form. Empty or null means any address, IPv4 or IPv6, and is returned as null." }, "destination_cidr": { "type": "string", "nullable": true, "description": "Where the traffic goes, for rules of an `egress` group. A network in CIDR notation, such as `192.0.2.0/24` or `2001:db8::/32`, or a single address, which is stored as a `/32` or `/128` prefix. Send the network address: `192.0.2.1/24` is refused rather than read as `192.0.2.0/24`, so a typo cannot change what the rule matches. A scope id, quotes and whitespace are refused. A network of one address family matches that family only, so `0.0.0.0/0` is every IPv4 address and no IPv6 one. Returned in canonical form. Empty or null means any address, IPv4 or IPv6, and is returned as null." }, "priority": { "type": "integer", "maximum": 64996, "minimum": 1, "default": 1000, "description": "Orders the rules in a group, lowest first, from 1 to 64996. Every rule allows traffic, so the order never changes what is allowed." }, "comment": { "type": "string", "nullable": true, "description": "A note; it changes nothing.", "maxLength": 255 } } }, "PatchedServerUpdateRequest": { "type": "object", "properties": { "hostname": { "type": "string", "minLength": 2, "description": "Labels of letters, digits and hyphens joined by dots, such as `web-01.example.com` or `web-01`; each label starts and ends with a letter or digit.", "maxLength": 64 } } }, "PatchedSnapshotRenameRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name the snapshot is shown by.", "maxLength": 250 } } }, "PatchedSshKeyRenameRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Letters, digits, spaces, dots, `@`, underscores and hyphens.", "maxLength": 255 } } }, "Plan": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "cpu_cores": { "type": "integer", "nullable": true }, "ram_mb": { "type": "integer", "nullable": true }, "disk_gb": { "type": "integer", "nullable": true }, "boot_disk_gb": { "type": "integer", "nullable": true, "description": "The size of the plan's separate boot disk, on top of `disk_gb`; 0 when it has none." } }, "required": [ "boot_disk_gb", "category", "cpu_cores", "disk_gb", "name", "ram_mb" ] }, "Pricing": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217." }, "ipv4_additional": { "type": "array", "items": { "$ref": "#/components/schemas/AdditionalIPv4Price" }, "description": "What a server's additional IPv4 addresses cost, for each count an order can ask for. The prices are those of the first product that offers them; a product that prices them differently is charged its own price, which its order's invoice shows." }, "ipv6": { "allOf": [ { "$ref": "#/components/schemas/IPv6Price" } ], "nullable": true, "description": "What IPv6 costs, ordered with a new server, or null when no product offers it. The prices are those of the first product that offers it; a product that prices it differently is charged its own price, which its order's invoice shows." }, "extra_bandwidth": { "type": "array", "items": { "$ref": "#/components/schemas/BandwidthPrice" }, "description": "Every size a bandwidth order takes, with its price." } }, "required": [ "currency", "extra_bandwidth", "ipv4_additional", "ipv6" ] }, "PrivateNetwork": { "type": "object", "properties": { "eligible": { "type": "boolean", "nullable": true, "description": "Whether the server can join its location's private network; null when not known." }, "enabled": { "type": "boolean", "nullable": true, "description": "Whether it has joined; null when not known." } }, "required": [ "eligible", "enabled" ] }, "Product": { "type": "object", "properties": { "id": { "type": "integer", "description": "The `product_id` an order takes." }, "name": { "type": "string" }, "category": { "type": "string", "nullable": true, "description": "The group the catalogue lists the product in." }, "description": { "type": "array", "items": { "type": "string" }, "description": "The product's description, a line per item." }, "prices": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The recurring price by billing cycle, as a decimal string with two places." }, "setup_fees": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The one-time setup fee by billing cycle, as a decimal string with two places." }, "currency": { "type": "string", "description": "ISO 4217." }, "billing_cycles": { "type": "array", "items": { "$ref": "#/components/schemas/BillingCycleEnum" }, "description": "The billing cycles it is sold with." }, "default_billing_cycle": { "allOf": [ { "$ref": "#/components/schemas/BillingCycleEnum" } ], "description": "The billing cycle an order that names none gets." }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/ProductLocation" } }, "images": { "type": "array", "items": { "type": "string" }, "description": "The images a server of this product can be installed with, by name." } }, "required": [ "billing_cycles", "category", "currency", "default_billing_cycle", "description", "id", "images", "locations", "name", "prices", "setup_fees" ] }, "ProductLocation": { "type": "object", "properties": { "code": { "type": "string", "description": "A location code, as the locations endpoint lists them." }, "in_stock": { "type": "boolean", "description": "New servers of this product can be ordered here." }, "upgrade_in_stock": { "type": "boolean", "description": "Servers here can be upgraded to this product." } }, "required": [ "code", "in_stock", "upgrade_in_stock" ] }, "Project": { "type": "object", "properties": { "id": { "type": "integer", "description": "The project's id. Paths use its slug instead." }, "name": { "type": "string", "description": "The project's name. It never appears in paths." }, "slug": { "type": "string", "description": "Addresses the project in every path.", "pattern": "^[-a-zA-Z0-9_]+$" }, "ready": { "type": "boolean", "readOnly": true, "description": "Whether the project is set up for servers. Until it is, its servers and everything around them answer `403 project_not_ready`, or `403 billing_account_required` while its owner has no billing account." }, "role": { "allOf": [ { "$ref": "#/components/schemas/RoleEnum" } ], "description": "The user's role in the project. An owner or admin can order, upgrade and cancel; a member can run the servers." }, "created_at": { "type": "string", "format": "date-time", "description": "When the project was created." } }, "required": [ "created_at", "id", "name", "ready", "role", "slug" ] }, "ProjectRef": { "type": "object", "properties": { "slug": { "type": "string", "description": "Use this to address the project in every other endpoint.", "pattern": "^[-a-zA-Z0-9_]+$" }, "name": { "type": "string" }, "role": { "allOf": [ { "$ref": "#/components/schemas/RoleEnum" } ], "description": "An owner or admin can order, upgrade and cancel; a member can run the servers." } }, "required": [ "name", "role", "slug" ] }, "ProtocolEnum": { "enum": [ "tcp", "udp", "icmp", "any" ], "type": "string" }, "ReinstallRequest": { "type": "object", "properties": { "image": { "type": "string", "minLength": 1, "description": "An image's `name`, as the images endpoint lists them.", "maxLength": 255 }, "ssh_keys": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Ids of the project's SSH keys to install. Leave it out to keep the server's keys; [] removes them.", "maxItems": 100 }, "user_data": { "type": "string", "nullable": true, "minLength": 1, "description": "Cloud-init user data, starting with #cloud-config or #!. Not available yet.", "maxLength": 65536 } }, "required": [ "image" ] }, "RestoreSnapshotRequest": { "type": "object", "properties": { "snapshot_id": { "type": "integer", "minimum": 1, "description": "A `completed` snapshot of the project, of this server or another one." } }, "required": [ "snapshot_id" ] }, "ReverseDns": { "type": "object", "properties": { "address": { "type": "string", "description": "One of the server's addresses." }, "ptr": { "type": "string", "nullable": true, "description": "The reverse DNS name; null when none is set." } }, "required": [ "address", "ptr" ] }, "ReverseDnsUpdateRequest": { "type": "object", "properties": { "ptr": { "type": "string", "minLength": 1, "description": "A domain name in ASCII without a trailing dot, such as `web-01.example.com`.", "maxLength": 255 } }, "required": [ "ptr" ] }, "RoleEnum": { "enum": [ "owner", "admin", "member" ], "type": "string" }, "Server": { "type": "object", "properties": { "id": { "type": "string" }, "hostname": { "type": "string", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/ServerStatusEnum" } ], "description": "`running`: powered on. `stopped`: powered off. `suspended`: suspended by HostHatch; check the invoices of the project's owner, or contact support, to have it unsuspended. It changes with the server's power actions, so none is final." }, "pending_changes": { "type": "boolean", "description": "The server has changes, such as a new plan, that its next start or reboot through this API applies." }, "location": { "$ref": "#/components/schemas/ServerLocation" }, "image": { "$ref": "#/components/schemas/ServerImage" }, "plan": { "$ref": "#/components/schemas/Plan" }, "network": { "$ref": "#/components/schemas/Network" }, "bandwidth": { "allOf": [ { "$ref": "#/components/schemas/Bandwidth" } ], "nullable": true }, "firewall_groups": { "type": "array", "items": { "type": "integer" }, "nullable": true, "description": "Null when they could not be read just now." }, "ssh_keys": { "type": "array", "items": { "type": "integer" }, "description": "Ids of the project's SSH keys the server was installed with." }, "iso": { "allOf": [ { "$ref": "#/components/schemas/IsoRef" } ], "nullable": true, "description": "The mounted ISO, if any." }, "has_user_data": { "type": "boolean", "description": "The server was installed with cloud-init user data." }, "billing": { "allOf": [ { "$ref": "#/components/schemas/Billing" } ], "nullable": true, "description": "The server's subscription. Null when it has none, or billing could not be read just now." }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "bandwidth", "billing", "created_at", "firewall_groups", "has_user_data", "hostname", "id", "image", "iso", "location", "network", "pending_changes", "plan", "ssh_keys", "status" ] }, "ServerCreateRequest": { "type": "object", "description": "An order for a new server: a product, a location, and an image or a snapshot to install.", "properties": { "hostname": { "type": "string", "minLength": 2, "description": "Labels of letters, digits and hyphens joined by dots, such as `web-01.example.com` or `web-01`; each label starts and ends with a letter or digit.", "maxLength": 64 }, "product_id": { "type": "integer", "minimum": 1, "description": "A product's id, from the products endpoint." }, "location": { "allOf": [ { "$ref": "#/components/schemas/LocationEnum" } ], "description": "A location code the product is in stock in." }, "image": { "type": "string", "nullable": true, "minLength": 1, "description": "One of the images the product lists. Give this or `snapshot_id`.", "maxLength": 255 }, "snapshot_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "A completed snapshot of the project's to deploy, instead of an image." }, "billing_cycle": { "allOf": [ { "$ref": "#/components/schemas/BillingCycleEnum" } ], "description": "One of the product's. Leave it out for its default." }, "ssh_keys": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Ids of the project's SSH keys to install.", "maxItems": 100 }, "ipv4_additional": { "type": "integer", "minimum": 0, "default": 0, "description": "IPv4 addresses beyond the server's own, as the pricing endpoint counts them." }, "ipv6": { "type": "boolean", "default": false, "description": "Route an IPv6 /64 to the server." }, "private_network": { "type": "boolean", "default": false, "description": "Attach it to the location's private network." }, "promo_code": { "type": "string", "nullable": true, "minLength": 1, "description": "A promotion code: letters, digits, hyphens and underscores.", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, "user_data": { "type": "string", "nullable": true, "minLength": 1, "description": "Cloud-init user data, starting with #cloud-config or #!. Not available yet.", "maxLength": 65536 } }, "required": [ "hostname", "location", "product_id" ] }, "ServerFirewallGroups": { "type": "object", "properties": { "firewall_groups": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Ids of the project's firewall groups. They replace the server's groups; [] detaches them all.", "maxItems": 100 } }, "required": [ "firewall_groups" ] }, "ServerFirewallGroupsRequest": { "type": "object", "properties": { "firewall_groups": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Ids of the project's firewall groups. They replace the server's groups; [] detaches them all.", "maxItems": 100 } }, "required": [ "firewall_groups" ] }, "ServerImage": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "The image's name, as reinstall takes it." }, "display_name": { "type": "string", "nullable": true } }, "required": [ "display_name", "name" ] }, "ServerLocation": { "type": "object", "properties": { "code": { "type": "string", "nullable": true, "description": "HostHatch's location code, as in the order request." }, "city": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2, upper case." } }, "required": [ "city", "code", "country_code" ] }, "ServerStatusEnum": { "enum": [ "running", "stopped", "suspended" ], "type": "string" }, "ServerSummary": { "type": "object", "description": "A server in a list. Fetch the server for everything else.", "properties": { "id": { "type": "string" }, "hostname": { "type": "string", "nullable": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/ServerStatusEnum" } ], "description": "`running`: powered on. `stopped`: powered off. `suspended`: suspended by HostHatch; check the invoices of the project's owner, or contact support, to have it unsuspended. It changes with the server's power actions, so none is final." }, "ipv4_primary": { "type": "string", "format": "ipv4", "nullable": true }, "location": { "$ref": "#/components/schemas/ServerLocation" }, "plan": { "$ref": "#/components/schemas/ServerSummaryPlan" } }, "required": [ "hostname", "id", "ipv4_primary", "location", "plan", "status" ] }, "ServerSummaryPlan": { "type": "object", "properties": { "name": { "type": "string", "nullable": true } }, "required": [ "name" ] }, "SizeGbEnum": { "enum": [ 500, 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000, 11000, 12000, 13000, 14000, 15000, 16000, 17000, 18000, 19000, 20000 ], "type": "integer" }, "Snapshot": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "readOnly": true, "description": "The name it was given with a rename, else the name of its image file, such as `8d41f0_95bec6.qcow2`." }, "status": { "allOf": [ { "$ref": "#/components/schemas/SnapshotStatusEnum" } ], "description": "`pending`: being taken. `completed`: ready, and only a completed snapshot can be restored or deployed as a new server. `failed`: it could not be taken, and `error` says what to do. `completed` and `failed` are final." }, "state": { "type": "string", "nullable": true, "description": "Where a snapshot is in its pipeline: requested, preparing, converting, uploading, finalizing, completed or failed. More states may be added." }, "size_gb": { "type": "number", "format": "double", "nullable": true }, "server_id": { "type": "string", "nullable": true, "description": "The server the snapshot was taken of." }, "image": { "type": "string", "nullable": true, "description": "The image that server was installed with." }, "created_at": { "type": "string", "format": "date-time" }, "error": { "allOf": [ { "$ref": "#/components/schemas/SnapshotError" } ], "nullable": true, "readOnly": true, "description": "Why the snapshot failed; null unless its status is failed." } }, "required": [ "created_at", "error", "id", "image", "name", "server_id", "size_gb", "status" ] }, "SnapshotError": { "type": "object", "properties": { "code": { "allOf": [ { "$ref": "#/components/schemas/SnapshotErrorCodeEnum" } ], "description": "`failed` for now; codes may be added." }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "SnapshotErrorCodeEnum": { "enum": [ "failed" ], "type": "string" }, "SnapshotStatusEnum": { "enum": [ "pending", "completed", "failed" ], "type": "string" }, "SshKey": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "public_key": { "type": "string", "description": "The public key in OpenSSH format." }, "fingerprint": { "type": "string", "nullable": true, "readOnly": true, "description": "The SHA256 fingerprint, as `ssh-keygen -lf` prints it. Null for a key the API would refuse today, such as a DSA key added before keys were checked." }, "created_at": { "type": "string", "format": "date-time", "description": "When the key was added. Only the day is recorded, so the time is midnight UTC." } }, "required": [ "created_at", "fingerprint", "id", "name", "public_key" ] }, "SshKeyCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Letters, digits, spaces, dots, `@`, underscores and hyphens.", "maxLength": 255 }, "public_key": { "type": "string", "minLength": 1, "description": "One public key in OpenSSH format, as in a .pub file: ssh-ed25519, ecdsa-sha2-nistp256, -nistp384, -nistp521, or ssh-rsa of at least 2048 bits. The comment after the key is not kept; the name is the key's label.", "maxLength": 2048 } }, "required": [ "name", "public_key" ] }, "UpgradeOption": { "type": "object", "properties": { "product_id": { "type": "integer", "description": "The `product_id` an upgrade takes." }, "name": { "type": "string" }, "prices": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The recurring price by billing cycle, as a decimal string. The server keeps its own cycle." }, "currency": { "type": "string", "description": "ISO 4217." }, "in_stock": { "type": "boolean", "description": "Servers in this server's location can be upgraded to it now." } }, "required": [ "currency", "in_stock", "name", "prices", "product_id" ] }, "UpgradeRequest": { "type": "object", "properties": { "product_id": { "type": "integer", "minimum": 1, "description": "One of the server's upgrade options." }, "upgrade_disk": { "type": "boolean", "default": false, "description": "Grow the server's disk to the new product's size too, when the upgrade is applied. Left out or false, the disk keeps its size." } }, "required": [ "product_id" ] }, "WhenEnum": { "enum": [ "end_of_term", "immediate" ], "type": "string" }, "ProblemDetails": { "type": "object", "description": "An RFC 9457 problem details document. `code` is stable and machine-readable; `detail` is a sentence for humans and may change. Some errors add the members listed here, such as `action_id`.", "properties": { "type": { "type": "string", "format": "uri", "example": "https://docs.hosthatch.com/api/errors#not_found" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "action_in_progress", "already_enabled", "api_key_expired", "authentication_required", "billing_account_required", "conflict", "feature_unavailable", "group_in_use", "idempotency_key_reused", "insufficient_capacity", "insufficient_role", "internal_error", "invalid_api_key", "iso_limit_reached", "iso_mounted", "key_exists", "method_not_allowed", "name_taken", "node_maintenance", "not_acceptable", "not_eligible", "not_found", "permission_denied", "project_not_ready", "rate_limited", "read_only_key", "reverse_dns_unavailable", "rule_exists", "snapshot_limit_reached", "unsupported_media_type", "upstream_error", "upstream_unavailable", "validation_error" ] }, "instance": { "type": "string", "description": "The request path." }, "errors": { "type": "array", "description": "Present on `validation_error` only, one item per problem. `field` names the request field, with dots for nested fields and list positions (`ssh_keys.0`), or a header such as `Idempotency-Key`; it is null for errors about the whole request. `code` says what is wrong with it, such as `required`, `null`, `blank`, `invalid`, `invalid_choice`, `max_length`, `min_value` or `max_value`, and `message` says it in a sentence.", "items": { "type": "object", "properties": { "field": { "type": "string", "nullable": true }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "code", "message" ] } }, "action_id": { "type": "integer", "description": "On `action_in_progress`: the action running on the server, when it was started in this project. On `upstream_error` from a request that starts an action: the action, whose outcome is not known yet. Poll it." }, "order_id": { "type": "integer", "description": "On `upstream_error` from a request that places an order: the order, which may have been placed. On `conflict` from an upgrade: the server's open upgrade, when it was ordered in this project." }, "group_id": { "type": "integer", "description": "On `name_taken`: the project's firewall group of that name." }, "rule_id": { "type": "integer", "description": "On `rule_exists`: the group's rule that is the same rule." }, "key_id": { "type": "integer", "description": "On `key_exists`: the project's SSH key with that public key." }, "iso_id": { "type": "integer", "description": "On `iso_limit_reached`: the project's custom ISO." }, "servers": { "type": "array", "items": { "type": "string" }, "description": "On `group_in_use`: the ids of the servers the firewall group is attached to." } }, "required": [ "type", "title", "status", "code" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key from your profile page, sent as `Authorization: Bearer `." } } }, "servers": [ { "url": "https://console.hosthatch.com/api/v1" } ], "tags": [ { "name": "account", "description": "The user an API key belongs to." }, { "name": "projects", "description": "The projects the API key's user belongs to." }, { "name": "catalogue", "description": "What can be ordered: products, images, locations and prices." }, { "name": "servers", "description": "Servers in a project." }, { "name": "actions", "description": "Asynchronous operations on servers. Poll an action for its outcome." }, { "name": "orders", "description": "Orders for new servers, upgrades and extra bandwidth." }, { "name": "ssh-keys", "description": "SSH keys available to a project's servers." }, { "name": "snapshots", "description": "Snapshots of a project's servers." }, { "name": "firewall-groups", "description": "Firewall groups and their rules. Every rule allows traffic. A server with any group attached refuses new inbound connections that no ingress rule allows, and once it has an egress group, outbound traffic that no egress rule allows. Rules are stateful: replies to an allowed connection pass. Changes reach the servers in the background, after the request has been answered." }, { "name": "isos", "description": "ISO images that can be mounted on servers." } ], "security": [ { "bearerAuth": [] } ] }