HF PanelDocsv1.0.0

API reference

Every endpoint of the token API, who may call it, and the objects its answers share.

This page lists every endpoint of the token API, with links to the pages that describe each one in full. It also describes the objects the answers share, and the three general endpoints: the endpoint list, me and packages.

The base address is https://api.yourdomain.com:2087/v1. All examples use these two shell variables:

bash
A=https://api.yourdomain.com:2087/v1
H="Authorization: Bearer hf_xxx"

Who may call what

Word Meaning
any token any valid token: administrator, reseller or customer
staff an administrator's or reseller's token. A customer's token gets 403 "Only administrator and reseller tokens can do this."
admin an administrator's token only. Others get 403 "Only administrator tokens can do this."
per account works on one hosting account: the token's own account for a customer's token, or ?account=<username> for staff. Paths under /v1/accounts/{username}/… name the account in the path instead (see per-account endpoints)
write needs a Read & change token. A Read only token gets 403

All endpoints

Method Path Who Page
GET /v1 anyone, no token below
GET /v1/me any token below
GET /v1/packages staff below
GET /v1/accounts staff Accounts
POST /v1/accounts staff, write Accounts
GET /v1/accounts/{username} staff Accounts
DELETE /v1/accounts/{username} staff, write Accounts
POST /v1/accounts/{username}/suspend staff, write Accounts
POST /v1/accounts/{username}/unsuspend staff, write Accounts
POST, PUT /v1/accounts/{username}/package staff, write Accounts
POST, PUT /v1/accounts/{username}/password staff, write Accounts
POST /v1/accounts/{username}/login staff, write Accounts
GET /v1/accounts/{username}/usage staff Accounts
GET /v1/domains per account Domains, mail and databases
GET /v1/mailboxes per account Domains, mail and databases
GET /v1/databases per account Domains, mail and databases
GET /v1/mongo per account MongoDB
POST /v1/mongo per account, write MongoDB
DELETE /v1/mongo/{database} per account, write MongoDB
POST /v1/mongo/{database}/grant per account, write MongoDB
POST /v1/mongo/{database}/revoke per account, write MongoDB
POST /v1/mongo/users per account, write MongoDB
POST, PUT /v1/mongo/users/{user}/password per account, write MongoDB
DELETE /v1/mongo/users/{user} per account, write MongoDB
POST, PUT /v1/mongo/remote per account, write MongoDB
GET /v1/tunnels per account Tunnels
POST /v1/tunnels per account, write Tunnels
GET /v1/tunnels/{name}/client per account, write Tunnels
DELETE /v1/tunnels/{name} per account, write Tunnels
GET /v1/status any token Status and sync
GET /v1/sync/sites any token Status and sync
GET /v1/openapi.json anyone, no token API explorer
GET /v1/packages/{package} staff Packages and resellers
POST /v1/packages admin, write Packages and resellers
PATCH, PUT /v1/packages/{package} admin, write Packages and resellers
DELETE /v1/packages/{package} admin, write Packages and resellers
GET /v1/resellers admin Packages and resellers
GET /v1/resellers/{username} admin Packages and resellers
POST /v1/resellers admin, write Packages and resellers
POST /v1/resellers/{username}/suspend admin, write Packages and resellers
POST /v1/resellers/{username}/unsuspend admin, write Packages and resellers
POST, PUT /v1/resellers/{username}/limit admin, write Packages and resellers
DELETE /v1/resellers/{username} admin, write Packages and resellers
GET /v1/accounts/{username}/domains per account Domains
POST /v1/accounts/{username}/domains per account, write Domains
PATCH, PUT /v1/accounts/{username}/domains/{domain} per account, write Domains
DELETE /v1/accounts/{username}/domains/{domain} per account, write Domains
GET /v1/accounts/{username}/dns per account DNS
GET /v1/accounts/{username}/dns/{zone} per account DNS
POST /v1/accounts/{username}/dns/{zone}/records per account, write DNS
PATCH, PUT /v1/accounts/{username}/dns/{zone}/records/{id} per account, write DNS
DELETE /v1/accounts/{username}/dns/{zone}/records/{id} per account, write DNS
GET /v1/accounts/{username}/email/mailboxes per account Email
POST /v1/accounts/{username}/email/mailboxes per account, write Email
DELETE /v1/accounts/{username}/email/mailboxes/{address} per account, write Email
POST, PUT /v1/accounts/{username}/email/mailboxes/{address}/password per account, write Email
POST, PUT /v1/accounts/{username}/email/mailboxes/{address}/quota per account, write Email
POST, PUT, DELETE /v1/accounts/{username}/email/mailboxes/{address}/autoresponder per account, write Email
GET, POST /v1/accounts/{username}/email/forwarders per account (POST: write) Email
DELETE /v1/accounts/{username}/email/forwarders/{source} per account, write Email
GET /v1/accounts/{username}/mysql per account MySQL and PostgreSQL
POST /v1/accounts/{username}/mysql/databases per account, write MySQL and PostgreSQL
DELETE /v1/accounts/{username}/mysql/databases/{database} per account, write MySQL and PostgreSQL
POST /v1/accounts/{username}/mysql/databases/{database}/grant per account, write MySQL and PostgreSQL
POST /v1/accounts/{username}/mysql/databases/{database}/revoke per account, write MySQL and PostgreSQL
POST /v1/accounts/{username}/mysql/users per account, write MySQL and PostgreSQL
POST, PUT /v1/accounts/{username}/mysql/users/{user}/password per account, write MySQL and PostgreSQL
DELETE /v1/accounts/{username}/mysql/users/{user} per account, write MySQL and PostgreSQL
GET, POST /v1/accounts/{username}/postgres per account (POST: write) MySQL and PostgreSQL
POST, PUT /v1/accounts/{username}/postgres/{database}/password per account, write MySQL and PostgreSQL
DELETE /v1/accounts/{username}/postgres/{database} per account, write MySQL and PostgreSQL
GET /v1/accounts/{username}/ssl per account SSL and backups
POST /v1/accounts/{username}/ssl/{domain}/issue per account, write SSL and backups
POST /v1/accounts/{username}/ssl/{domain}/renew per account, write SSL and backups
POST, PUT /v1/accounts/{username}/ssl/{domain}/force-https per account, write SSL and backups
DELETE /v1/accounts/{username}/ssl/{domain} per account, write SSL and backups
POST /v1/ssl/autossl admin, write SSL and backups
GET, POST /v1/accounts/{username}/backups per account (POST: write) SSL and backups
POST /v1/accounts/{username}/backups/{backup}/restore per account, write SSL and backups
POST /v1/accounts/{username}/backups/{backup}/link per account, write SSL and backups
DELETE /v1/accounts/{username}/backups/{backup} per account, write SSL and backups
GET /v1/accounts/{username}/apps per account Apps and staging
GET /v1/accounts/{username}/apps/installs per account Apps and staging
GET, POST /v1/accounts/{username}/staging per account (POST: write) Apps and staging
POST /v1/accounts/{username}/staging/{id}/push per account, write Apps and staging
POST /v1/accounts/{username}/staging/{id}/pull per account, write Apps and staging
DELETE /v1/accounts/{username}/staging/{id} per account, write Apps and staging
GET, POST /v1/accounts/{username}/cron per account (POST: write) Cron jobs and FTP
DELETE /v1/accounts/{username}/cron/{id} per account, write Cron jobs and FTP
GET, POST /v1/accounts/{username}/ftp per account (POST: write) Cron jobs and FTP
POST, PUT /v1/accounts/{username}/ftp/{login}/password per account, write Cron jobs and FTP
DELETE /v1/accounts/{username}/ftp/{login} per account, write Cron jobs and FTP
GET /v1/server/services admin The server
POST /v1/server/services/{service}/restart admin, write The server
GET /v1/server/health admin The server
GET /v1/server/version admin The server
POST /v1/server/version/check admin, write The server
GET, POST, DELETE /v1/desktop/… no token; a device key Desktop app API

On the old address, put /api/v1 in place of /v1: GET https://panel.yourdomain.com:8443/api/v1/me.

Every change made through these endpoints runs the same code as the panel's own screens: the same checks, package limits, reseller privileges, approvals and activity log. The API explorer has the same list read from the OpenAPI description, and SDKs has clients for Go, Python and TypeScript.

GET /v1: the endpoint list

Lists the endpoints. Needs no token.

bash
curl -s $A

The answer is shown on the API overview.

GET /v1/me

Who the token belongs to, and its access. Who: any token.

bash
curl -s -H "$H" $A/me
json
{
    "ok": true,
    "data": {
        "username": "sarahbakes",
        "email": "sarah@example.com",
        "role": "client",
        "two_factor": false,
        "token": {
            "name": "Deploy script",
            "access": "read"
        }
    }
}
Field What it is
role admin, reseller or client (a hosting customer)
two_factor whether the login has two-factor login switched on
token.access read or write. A Read & change token of a read-only staff login shows read

GET /v1/packages

The hosting packages, cheapest first. Who: staff.

bash
curl -s -H "$H" $A/packages
json
{
    "ok": true,
    "data": [
        {
            "id": 1,
            "name": "Starter",
            "disk_mb": 5120,
            "max_domains": 1,
            "max_databases": 2,
            "max_mongo_databases": 0,
            "max_mailboxes": 5,
            "price_month": 3.5
        },
        {
            "id": 2,
            "name": "Business",
            "disk_mb": 20480,
            "max_domains": 10,
            "max_databases": 20,
            "max_mongo_databases": 5,
            "max_mailboxes": 50,
            "price_month": 9.99
        }
    ]
}

Objects

Account

Returned by the account endpoints.

Field Type What it is
username text the account's username
email text the contact email address
status text active or suspended
package text the package's name
disk_used_mb number disk space used, in MB
disk_limit_mb number the package's disk space, in MB
domains list of text every domain, subdomain and parked domain of the account
two_factor true/false whether two-factor login is on
server text the server the account lives on (the main server's name when it has no other)
created_at text when the account was made (UTC)
last_login_at text or null the last sign-in (UTC)

Package

Field Type What it is
id number the package's id; you can use it in place of the name
name text the package's name
disk_mb number disk space in MB
max_domains number domains allowed; 0 = no limit
max_databases number MySQL and PostgreSQL databases allowed, together; 0 = no limit
max_mongo_databases number MongoDB databases allowed; 0 = none
max_mailboxes number email accounts allowed; 0 = no limit
price_month number the monthly price

Reseller

See Packages and resellers.

DNS record

Field Type What it is
id number the record's id
name text @, or the part before the zone
type text A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA or NS
value text the value
ttl number seconds
priority number for MX and SRV

Mailbox

Field Type What it is
address text the address
quota_mb number the storage limit; 0 = no limit
used_mb number the space it uses
send_only true/false mail to it is refused
created_at text UTC

Cron job, FTP account and backup

See Cron jobs and FTP and SSL and backups.

MongoDB summary

Returned by GET /v1/mongo. See MongoDB.

Tunnel

Field Type What it is
name text the tunnel's name, which is also the first part of its address
url text its public address, https://<name>.<tunnel domain>
port number the local port it forwards to
online true/false whether a tunnel client is connected right now
created_at text when it was made (UTC)