REST API

Scripts and other programs can manage a Reqad server over HTTPS: list, create, change and delete hosting accounts, databases and mailboxes, start Git deployments, and read what needs attention. They send JSON, get JSON back and use the same code as the panel and the command line, so an account created through the API is set up the same way as one created in the browser.

To manage the server from an AI assistant, you do not need the API: see AI assistants (MCP).

Access tokens

Each request carries a token in the Authorization header. The panel login is never used, so the API keeps working with two-factor authentication, passkeys and browser sessions as they are. Make tokens under Settings > API access > New token, after confirming your password, or with reqad api new. A token has:

The token is shown only once, when you make it. The server keeps a fingerprint of the token, not the token itself, so it cannot show it again. If you lose a token, revoke it and make a new one. Revoke takes effect at once.

First request

TOKEN=rqd_...    # the token from Settings > API access
curl -H "Authorization: Bearer $TOKEN" https://server.example.com:2087/api/v1/

The reply describes the server and your token, and lists every endpoint. Every reply has the same shape, the same as reqad ... --json on the command line:

{
    "ok": true,
    "message": "Account bob successfully created.",
    "warnings": [],
    "error": "",
    "data": { ... }
}

When ok is false, error says why. A change that went through but needs attention, for example a certificate that could not be issued yet, comes back with ok: true and a note in warnings.

Endpoints

All paths start with https://<your server>:2087/api/v1. Send request bodies as JSON or as form fields.

server means a token for the whole server is required. A token for one account gets 403.

Passwords: when you create an account, database or mailbox, or set a database user's password, and leave password out, the server generates a strong password and returns it once in data.password.

Examples

API=https://server.example.com:2087/api/v1
AUTH="Authorization: Bearer $TOKEN"

# create an account with a generated password, PHP 8.3 and a certificate
curl -H "$AUTH" -d '{"user":"bob","domain":"bob.example","php":"8.3","letsencrypt":true}' $API/accounts

# a database for it
curl -H "$AUTH" -d '{"account":"bob","name":"wp"}' $API/databases

# a mailbox, then block its login
curl -H "$AUTH" -d '{"email":"info@bob.example"}' $API/mailboxes
curl -H "$AUTH" -X PATCH -d '{"enabled":false}' $API/mailboxes/info@bob.example

# anything critical? (for monitoring)
curl -s -H "$AUTH" $API/health | jq '.data.counts.critical'

Status codes

Security

• A wrong token counts as a failed login. After 5, the address is locked out of the API and the panel login for 15 minutes; after more, the firewall blocks it, as for the login page. A revoked or expired token is refused without counting, so a forgotten script does not get your own address blocked.
• The API accepts tokens only, never browser cookies. A web page you visit while logged in to the panel cannot use your session to call the API.
• Each address may make about 120 requests a minute.
• Settings > API access shows the latest calls (kept for 30 days) and when and from where each token was last used. The security log records tokens being made and revoked, wrong tokens, and a token used from a new address.
• When the panel's IP restriction is on (Settings > Security), port 2087 answers only the listed addresses. Add the addresses your scripts call from.
• Give each program its own token with the fewest permissions it needs. Use an account token when a program works for one customer.

On the command line

reqad api status                     # on or off, the address, active tokens
reqad api on                         # or: off
reqad api new monitoring             # read-only, expires in 90 days
reqad api new billing --write --days=365 --ip=203.0.113.7
reqad api new bob-deploy --account=bob --write
reqad api tokens                     # --all also lists revoked tokens
reqad api revoke billing
reqad api log --lines=50

See Command line (CLI) for every option.

Need a hand? Create a free account or contact us.