REST API overview: authentication, requests and responses
On this page
The server has a JSON API for your own scripts and integrations. Administrators and resellers use it to create and manage hosting accounts; each hosting customer can use their own part of it (customer API) for mailboxes, databases, DNS and cron jobs.
Base URL
https://<server>:2087/api/v1
Use the server's hostname so the certificate matches. Customer endpoints are under https://<server>:2083/api/v1/me.
Authentication
Every request sends an API token in the Authorization header:
Authorization: Bearer YOUR_TOKEN
Create the token in the admin panel under API Tokens (section Account). See create an API token. There are no cookies or sessions.
Requests
- Read with
GET, change withPOST. There are noPUTorDELETErequests. - Send the body as JSON (
Content-Type: application/json) or as form fields (application/x-www-form-urlencoded). Both work the same.
Responses
Every answer is JSON with an envelope:
{"status": 1, "data": { ... }}
On failure:
{"status": 0, "error": "Package not found."}
| HTTP status | Meaning |
|---|---|
200 | Success, status is 1. |
401 | No token, a wrong or expired token, or a token not allowed from your address. error says which. |
403 | Your IP is blocked after failed attempts, a read-only token tried to change something, or a reseller lacks the privilege. |
422 | The request was understood but refused, for example an invalid username. error explains why. |
Endpoints for administrators and resellers
| Method and path | What it does | Body |
|---|---|---|
GET /api/v1/accounts | List accounts (optional ?search=) | — |
POST /api/v1/accounts | Create an account | username, domain, email, password, package |
GET /api/v1/accounts/{username} | One account | — |
POST /api/v1/accounts/{username}/suspend | Suspend | reason (optional) |
POST /api/v1/accounts/{username}/unsuspend | Unsuspend | — |
POST /api/v1/accounts/{username}/password | Change the password | password |
POST /api/v1/accounts/{username}/package | Change the package | package |
POST /api/v1/accounts/{username}/terminate | Delete the account for good | — |
POST /api/v1/accounts/{username}/login | One-time sign-in link (60 seconds) | — |
GET /api/v1/packages | List packages | — |
GET /api/v1/jobs/{id} | Status of a server task | — |
GET /api/v1/server/status | Load, memory, disk, services, version (administrators only) | — |
POST /api/v1/dns/secondary is used between servers of a DNS cluster; you do not call it yourself.
A first request
curl -s -H "Authorization: Bearer $TOKEN" \
https://server1.example.com:2087/api/v1/packages
Good to know
- A reseller's token sees and changes only the reseller's own accounts and packages, within the reseller's privileges.
- Wrong tokens count as failed logins: too many from one address block it. See API errors.
- To be told when something happens instead of asking, use webhooks.
Thank you — this helps us improve the article.
Still stuck?
Ask the AI about your exact situation — it answers from this knowledge base — or contact us.
Related articles
- How to create an API token for scripts and billing
Create an API token in the admin panel or the control panel for the REST API or a billing system, copy it once, see when it was last used, and revoke it.
- How to create a hosting account with the API
Create a hosting account with POST /api/v1/accounts: the required fields, a complete curl example, the account object you get back and the errors to expect.
- Suspend, change package, password or terminate via the API
Manage hosting accounts with the REST API: list, suspend, unsuspend, change password or package, terminate, list packages, task and server status.
- Customer API: automate mailboxes, databases, DNS and cron
Use your hosting account's own API token to manage mailboxes, forwarders, MySQL databases, DNS records and cron jobs from scripts, with curl examples.
- API returns 401 Unauthorized, 403 or IP blocked
Fix API errors: 401 Unauthorized, expired token, address not allowed, IP blocked after failed attempts, read-only token, missing privilege and 422.