Quickstart¶
This page takes you from an API key to a server you have ordered and rebooted, a curl command or two at a time.
1. Create an API key¶
On your profile page, under API Keys, give the key a name, choose when it expires, and select Create key. The console may ask for your password again first. Copy the key: it is shown only once.
Keep it in an environment variable rather than in your code:
export HOSTHATCH_API_KEY="paste-your-key-here"
export API="https://console.hosthatch.com/api/v1"
2. Check the key¶
curl "$API/me/" -H "Authorization: Bearer $HOSTHATCH_API_KEY"
{
"id": 1,
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"billing_account": {"exists": true, "credit_balance": "40.00", "currency": "USD"},
"projects": [{"slug": "acme", "name": "Acme", "role": "owner"}]
}
A 401 means the key is wrong, revoked or expired: see Authentication.
3. Choose a project¶
Everything you manage belongs to a project. Use the slug of one from projects, and list its servers:
export PROJECT="acme"
curl "$API/projects/$PROJECT/servers/" -H "Authorization: Bearer $HOSTHATCH_API_KEY"
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "774736",
"hostname": "web-01",
"status": "running",
"ipv4_primary": "203.0.113.10",
"location": {"code": "AMS", "city": "Amsterdam", "country_code": "NL"},
"plan": {"name": "Cloud VPS 2x4"}
}
]
}
4. Order a server¶
Find what you can order: products, images and locations.
curl "$API/projects/$PROJECT/products/" -H "Authorization: Bearer $HOSTHATCH_API_KEY"
Then order one. The Idempotency-Key makes the order safe to send again if you lose the answer: the same key returns the same order instead of placing a second one.
curl -X POST "$API/projects/$PROJECT/servers/" \
-H "Authorization: Bearer $HOSTHATCH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-web-02" \
-d '{"hostname": "web-02", "product_id": 123, "location": "AMS", "image": "almalinux10", "billing_cycle": "monthly", "ssh_keys": [3731]}'
The answer is an order. The project owner's account credit pays for it automatically, whoever places the order. Without enough credit it waits in awaiting_payment, with an invoice to pay in the console. Poll the order until it is completed; its server_id is your new server:
curl "$API/projects/$PROJECT/orders/55/" -H "Authorization: Bearer $HOSTHATCH_API_KEY"
5. Look at the server¶
export SERVER="774736"
curl "$API/projects/$PROJECT/servers/$SERVER/" -H "Authorization: Bearer $HOSTHATCH_API_KEY"
The answer is the full server: its status, addresses, plan, bandwidth and billing.
6. Reboot it¶
Operations on a server are actions. Starting one answers 202 at once, with the action to poll:
curl -X POST "$API/projects/$PROJECT/servers/$SERVER/actions/reboot/" \
-H "Authorization: Bearer $HOSTHATCH_API_KEY" \
-H "Idempotency-Key: reboot-web-01-0001"
{
"id": 9101,
"type": "server.reboot",
"status": "running",
"resource": {"type": "server", "id": "774736"},
"started_at": "2026-10-19T10:00:00Z",
"finished_at": null,
"error": null,
"result": {}
}
Poll it until status is success or error:
curl "$API/projects/$PROJECT/actions/9101/" -H "Authorization: Bearer $HOSTHATCH_API_KEY"
7. Cancel it¶
When you are done with a server, cancel it. end_of_term keeps it until the end of the period you paid for and needs a reason; immediate deletes it, and everything on it, now. Cancelling needs the admin or owner role.
curl -X POST "$API/projects/$PROJECT/servers/$SERVER/cancel/" \
-H "Authorization: Bearer $HOSTHATCH_API_KEY" \
-H "Content-Type: application/json" \
-d '{"when": "end_of_term", "reason": "No longer needed"}'
{"status": "cancellation_requested", "when": "end_of_term"}
A script in Python¶
This script reboots a server and waits for the outcome. It reads the error code from problem details, waits as long as a 429 asks, and repeats a request with the same Idempotency-Key, so a retried reboot can't happen twice.
import os
import time
import uuid
import requests
API = "https://console.hosthatch.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['HOSTHATCH_API_KEY']}"
def call(method, path, **kwargs):
for _ in range(5):
response = session.request(method, API + path, timeout=30, **kwargs)
if response.status_code != 429:
break
time.sleep(int(response.headers.get("Retry-After", 60)))
if response.headers.get("Content-Type", "").startswith("application/problem+json"):
problem = response.json()
raise RuntimeError(f"{problem['status']} {problem['code']}: {problem['detail']}")
response.raise_for_status()
return response.json() if response.content else None
def reboot(project, server_id, timeout=1800):
action = call(
"POST",
f"/projects/{project}/servers/{server_id}/actions/reboot/",
headers={"Idempotency-Key": str(uuid.uuid4())},
)
deadline = time.monotonic() + timeout
while action["status"] in ("running", "unknown") and time.monotonic() < deadline:
time.sleep(5)
action = call("GET", f"/projects/{project}/actions/{action['id']}/")
return action
print(reboot("acme", "774736"))