REST API and command line – Administrator Guide

The REST API offers every action of the panel. Scripts and billing systems call it over HTTPS with an API key. On the server itself, stackregent.exe can call the same API and has commands for recovery and maintenance.

Create an API key#

Go to Tools & Settings › Remote API (REST) (under Server Management).
Click Create key.
Enter a Name, for example billing system.
Under Allowed from, you can enter IP addresses or networks, separated by commas, for example 203.0.113.10, 198.51.100.0/24. Empty means anywhere. IP Access Restriction Management still applies.
Under Expires, enter after how many days the key stops working. 0 means never.
Click Create. The key starts with sr_ and is shown once. Copy it now.

The API keys list shows each key's name, the start of the key, Acts as, Allowed from, Last used and Expires. Click the bin icon to delete a key. Scripts that use it stop working at once.

What a key may do#

Key	Created under	Rights
Administrator	Tools & Settings › Remote API (REST)	The same as the administrator who created it. If that administrator is restricted, restricted mode applies to the key too.
Reseller	Account › API Keys in the reseller's panel	The same as the reseller's login. Needs the reseller plan permission Use the REST API.
Customer	Account › API Keys in the customer's panel	The same as the customer's login. Needs the plan permission Ability to use the REST API on one of their subscriptions.

Only the account owner sees the API Keys tab. Customer and reseller keys cannot log in as other accounts, change passwords or manage API keys.

Call the API#

Send the key in the Authorization header as a bearer token, or in an X-API-Key header. Requests and answers are JSON.

curl -H "Authorization: Bearer sr_..." https://panel.example.com:9443/api/subscriptions

curl -X POST -H "Authorization: Bearer sr_..." -H "Content-Type: application/json" \
     -d '{"status":"suspended"}' https://panel.example.com:9443/api/subscriptions/12/status

The Examples card on the Remote API page shows these calls with your server's address filled in.

OpenAPI description#

Click OpenAPI description on the Remote API page, or request /api/openapi.json. The request needs a logged-in session or an API key. The file is an OpenAPI 3 description of every endpoint, with its parameters. Load it into an OpenAPI tool to browse the endpoints or generate a client. The panel has no built-in API playground; use curl, your OpenAPI tool, or stackregent api on the server.

Errors come back with an HTTP status of 400 or above and a JSON body with an error message. For form-style calls, the body may also list the fields that failed.

The stackregent command#

stackregent.exe is in the bin folder of the installation, normally C:\Program Files\StackRegent\bin. Run it in an administrator command prompt or PowerShell on the server.

Everyday and recovery commands#

Command	What it does
`stackregent version`	Prints the version.
`stackregent api GET /api/subscriptions`	Calls the REST API as the main administrator. The method is GET, POST, PUT or DELETE. For POST and PUT, add a JSON body, or `@file.json` to read it from a file. For each call, a key is made that lasts one minute and works only from the server itself; it is removed after the call.
`stackregent admin-password`	Sets a new random password for `admin` and prints it. Use `-login NAME` for another administrator. It also turns off two-factor authentication and closes that administrator's sessions.
`stackregent admin-add LOGIN`	Adds a support administrator and prints its password once.
`stackregent admin-remove LOGIN`	Removes an administrator. You cannot remove the main administrator.
`stackregent sessions-purge`	Logs out everyone who is logged in to the panel.
`stackregent ip-access-reset`	Lets administrators log in from any address again, after an IP access restriction locks you out.
`stackregent firewall-reset`	Turns off Panic Mode and access limits, and disables your own firewall rules.
`stackregent panel-url-reset`	Clears Customize Panel URL, so the panel answers on every host name again.
`stackregent panel-port HTTPS [HTTP]`	Moves the panel to other ports (1024–65535). It checks that the ports are free, updates the firewall rules and restarts the panel.
`stackregent license-set KEY`	Sets the licence key. You can also put the key in `STACKREGENT_LICENSE_KEY` and leave the argument out.
`stackregent license-check`	Checks the licence now and prints its state.
`stackregent website-apply DOMAIN`	Applies one website's hosting settings again and prints the task log.
`stackregent run-task KIND [JSON]`	Queues a panel task, waits for it and prints its log. JSON parameters can also come from `@file`.
`stackregent site-run ID PROGRAM [ARGS]`	Runs a program as a website's subscription user. `ID` is the domain's ID. It prints the output.
`stackregent dkim-verify FILE [DNS-SERVER]`	Checks the DKIM signatures of a saved message.

Migration agent#

stackregent migration-agent --allow NEW-SERVER-IP runs on a Plesk for Windows server so that a StackRegent server can migrate from it. Other options are --port (default 9445) and --key, which keeps a fixed key. See Migration.

Commands used by the installer and services#

The installer and the Windows services use setup, migrate (updates the panel database schema), service-install, service-remove, service-restart NAME, web, task and guard. You normally do not run these yourself. To upgrade, re-run the installer instead.

Troubleshooting#

401 "invalid API key": the key is wrong, has expired, or is used from an address outside Allowed from.
A customer cannot create keys: none of their subscriptions' plans has Ability to use the REST API.
stackregent api fails to connect: check that the StackRegent service is running (see Monitoring and troubleshooting).