HostHatch API¶
The HostHatch API lets your code, scripts and AI agents do what you do in the console: order servers and pay for them with account credit, power and reinstall them, take snapshots, set up firewalls, mount ISOs, and manage SSH keys and reverse DNS. You create projects and manage their members in the console.
curl https://console.hosthatch.com/api/v1/me/ \
-H "Authorization: Bearer $HOSTHATCH_API_KEY"
New here? The quickstart goes from an API key to a rebooted server in a few calls. Using the Peregrine API at cloud.hosthatch.com? Its documentation is on the Legacy API page.
Base URL¶
https://console.hosthatch.com/api/v1
Every path in these docs is relative to it. Paths end with a slash: /me/, not /me.
Conventions¶
Authentication. Send an API key as Authorization: Bearer <key>. See Authentication.
JSON only. Send request bodies as JSON with Content-Type: application/json. Responses are application/json, and errors are application/problem+json. Text is UTF-8.
Projects. Everything you manage belongs to a project, and paths address the project by its slug: /projects/acme/servers/. The API lists and reads your projects; you create and manage them in the console. See Projects and roles.
Identifiers. Server ids are lowercase hexadecimal strings, such as "774736". Every other id is an integer.
Names and units. Fields are snake_case and paths are kebab-case. Sizes are integers with the unit in the name: ram_mb, disk_gb, used_gb. Money is a decimal string with two places, such as "12.00", next to a currency field in ISO 4217. Timestamps are ISO 8601 in UTC, with a Z: 2026-10-19T10:00:00Z.
Responses to changes. A change to a property (PATCH or PUT) answers 200 with the updated resource. An operation on a server, such as a reboot, answers 202 with an action to poll. Anything that bills you answers 201 with an order. DELETE answers 204 with no body.
Retries. Send an Idempotency-Key header with every POST that starts an action or creates an order, so that a request you repeat after a lost answer can't happen twice. See Idempotency.
Lists. Lists are paginated. Use ?page= and ?page_size=: 50 per page by default, at most 100. next and previous link to the neighbouring pages, and are null at either end. A page past the end answers 404.
{
"count": 120,
"next": "https://console.hosthatch.com/api/v1/projects/acme/actions/?page=2",
"previous": null,
"results": []
}
Errors. Errors are problem details documents with a stable code. See Errors.
{
"type": "https://docs.hosthatch.com/api/errors#not_found",
"title": "Not found",
"status": 404,
"detail": "The resource does not exist, or you do not have access to it.",
"code": "not_found",
"instance": "/api/v1/projects/acme/servers/abc123/"
}
Rate limits. Each key has a budget per minute for reads, writes and orders. See Rate limits.
Versioning¶
The version is in the path: /api/v1. Within v1, changes are additive: new endpoints, new optional request fields, new response fields, and new values in enumerations, such as a new action type or error code. Write clients that ignore fields and values they don't know.
A breaking change, such as removing or renaming a field, comes as a new version at /api/v2/. Every change is listed in the changelog.
For AI agents¶
These docs are written for people and for agents alike. Besides the pages:
/llms.txtlists every page, and/llms-full.txthas them all in one Markdown file.- Each page that
/llms.txtlists is also served as Markdown: addindex.mdto its address, for example/api/servers/index.md. - The OpenAPI document is at
/api/openapi.json, and the reference renders it.
An agent that changes things should send an Idempotency-Key with every action and order, poll actions instead of assuming they finished, act on the error code rather than on detail, and wait as long as Retry-After says.
Get the OpenAPI document¶
GET /
The API serves its own OpenAPI document, without a key.
Every endpoint¶
Account¶
| Endpoint | What it does |
|---|---|
GET / |
Get the current user |
Projects¶
| Endpoint | What it does |
|---|---|
GET / |
List projects |
GET / |
Get a project |
Catalogue¶
| Endpoint | What it does |
|---|---|
GET / |
List products |
GET / |
List images |
GET / |
List locations |
GET / |
Get pricing |
Servers¶
| Endpoint | What it does |
|---|---|
GET / |
List servers |
POST / |
Order a server |
GET / |
Get a server |
PATCH / |
Rename a server |
GET / |
List reverse DNS names |
PUT / |
Set a reverse DNS name |
DELETE / |
Clear a reverse DNS name |
GET / |
List upgrade options |
POST / |
Upgrade a server |
POST / |
Buy extra bandwidth |
POST / |
Cancel a server |
Actions¶
| Endpoint | What it does |
|---|---|
GET / |
List actions |
GET / |
Get an action |
GET / |
List a server's actions |
POST / |
Power on |
POST / |
Shut down |
POST / |
Power off |
POST / |
Reboot |
POST / |
Reinstall |
POST / |
Reset the root password |
POST / |
Enable IPv6 |
POST / |
Enable the private network |
POST / |
Take a snapshot |
POST / |
Restore a snapshot |
POST / |
Mount an ISO |
POST / |
Unmount an ISO |
Orders¶
| Endpoint | What it does |
|---|---|
GET / |
List orders |
GET / |
Get an order |
SSH keys¶
| Endpoint | What it does |
|---|---|
GET / |
List SSH keys |
POST / |
Add an SSH key |
GET / |
Get an SSH key |
PATCH / |
Rename an SSH key |
DELETE / |
Delete an SSH key |
Snapshots¶
| Endpoint | What it does |
|---|---|
GET / |
List snapshots |
GET / |
Get a snapshot |
PATCH / |
Rename a snapshot |
DELETE / |
Delete a snapshot |
Firewalls¶
| Endpoint | What it does |
|---|---|
GET / |
List firewall groups |
POST / |
Create a firewall group |
GET / |
Get a firewall group |
PATCH / |
Rename a firewall group |
DELETE / |
Delete a firewall group |
GET / |
List a group's rules |
POST / |
Add a rule |
GET / |
Get a rule |
PATCH / |
Change a rule |
DELETE / |
Delete a rule |
PUT / |
Set a server's firewall groups |
ISOs¶
| Endpoint | What it does |
|---|---|
GET / |
List ISOs |
POST / |
Upload an ISO |
GET / |
Get an ISO |
DELETE / |
Delete an ISO |
OpenAPI document¶
| Endpoint | What it does |
|---|---|
GET / |
Get the OpenAPI document |