API overview

Requests

• Send bodies of POST, PUT and PATCH requests as JSON with Content-Type: application/json. A normal form post (application/x-www-form-urlencoded) works too.
• In JSON bodies, true counts as "1", and numbers may be sent as numbers or text.
• The older per-account endpoints (/v1/domains, /v1/mailboxes, /v1/databases, /v1/mongo, /v1/tunnels) take ?account=<username> in the query when you use an administrator's or reseller's token. With a customer's token they always use the token's own account.
• The newer ones name the account in the path: /v1/accounts/{username}/dns/…. A customer's token may only name its own account. Staff work in the account as Log in as does (see per-account endpoints).
• A body that is neither JSON nor a form answers 400 Send the body as JSON, e.g. {"username":"param"}.

Answers

Every answer is pretty-printed JSON with Content-Type: application/json; charset=utf-8, and is never cached (Cache-Control: no-store).

{
    "ok": true,
    "data": {}
}

{
    "ok": false,
    "error": "No such account."
}

error is a plain sentence you can show to a person. When a change was made but something around it was not (for example "Saved, but Stripe was not updated: …"), the answer is still "ok": true and also has a warnings list. Times such as created_at are UTC, written YYYY-MM-DD HH:MM:SS. A value that is not known is null.

Status codes

Common error messages

Idempotency-Key: safe retries

A billing system that sends a POST and loses the answer (a time-out, a dropped connection) cannot know whether the account was made. Send an Idempotency-Key header with every POST that makes something, and send the same request again with the same key:

curl -s -X POST -H "$H" -H "Idempotency-Key: order-1001" -H "Content-Type: application/json" \
  -d '{"username":"sarahbakes","email":"sarah@example.com","package":"Starter"}' $A/accounts

The kept answer is encrypted with the server's key, because it may hold a new password. The key works on POST only; GET, PUT, PATCH and DELETE are safe to repeat anyway.

Rate limits and lock-out

Each token may make 600 requests a minute (the server's administrator can change this with api_rate_limit in /etc/hostfog/config.json; 0 switches the limit off). Every answer to a token says where it stands:

One request more answers 429 "Too many requests with this token: 600 a minute. Try again in N seconds." with a Retry-After header (seconds). Each token has its own minute.

The token API also shares the sign-in page's lock-out:

• A request with no token, a malformed token, or an unknown or deleted token counts as a failed sign-in for your IP address.
• After 8 failed attempts in 15 minutes, every request from that address answers 429 "Too many failed attempts from this IP. Try again in 15 minutes." until the 15 minutes have passed, even with a good token. This answer has no Retry-After.
• IPv4 addresses are counted one by one. IPv6 addresses are counted by their /64 network.

Tip: if a script suddenly gets 429 without Retry-After, check that it sends the full token with the word Bearer and a space in front of it. Fix the script, then wait 15 minutes.

Pagination

The token API does not page its lists. GET /v1/accounts, GET /v1/domains and the other lists return every item the token may see in one answer.

Approvals

When the administrators have set an action to need a second administrator's approval, the token API cannot wait for one. DELETE /v1/accounts/{username}, DELETE /v1/resellers/{username} and a whole restore (POST /v1/accounts/{username}/backups/{backup}/restore) then answer 403 and the action must be done in the panel, where it is sent for approval. The same goes for a reseller whose deletes and restores wait for an administrator. When approvals ask only for your password, the token itself is enough.

The interface's own API

The panels, HF Mail, HF Files and HF Studio are browser apps. They call /api/v1/… on their own address (for example https://panel.yourdomain.com:8443/api/v1/domains) with a session cookie. That interface API is not meant for your scripts, and it has stricter rules:

• Every call, GET included, must send the session's CSRF token in the X-CSRF-Token header. The token comes from GET /api/v1/_boot (data.csrf) and in the csrf field of every answer; always keep the newest. A wrong or missing token answers 403 with a fresh csrf.
• Calls from another site are refused (403): the Origin must be the same host and Sec-Fetch-Site must be same-origin or none.

On the panel's address, a request with Authorization: Bearer hf_… is answered by the token API instead, with no cookie and no CSRF token. On api.yourdomain.com only the token API answers: a request that brings only a session cookie gets the token API's 401.

Tip: for scripts, always use an API token. It does not expire with a session and needs no CSRF token.

Related

• API reference
• API explorer
• SDKs
• Billing integration
• HF Files and HF Studio API