StackRegent REST API reference

Base URL and transport#

The StackRegent REST API is served by the panel itself:

https://SERVER:9443/api/

SERVER is the panel's host name or IP address. 9443 is the default HTTPS port; if it was changed at install time (-HttpsPort) or later with stackregent panel-port, use that port. The panel's HTTP port (9080 by default) only redirects to HTTPS, so always call the HTTPS address. The Examples card on Tools & Settings › Remote API (REST), and on Account › API Keys for resellers and customers, shows the base address of your own server.

A fresh panel uses a self-signed certificate. Install a trusted certificate for the panel before you point a billing system at it, so that clients can verify the connection instead of skipping the check. Skipping certificate checks (curl -k, -SkipCertificateCheck) is acceptable only for a first test.

Authentication#

Every call except sign-in and GET /api/health needs an API key. Keys start with sr_ and are created in the panel; see API keys. Send the key in either header:

Authorization: Bearer sr_0123456789abcdef...
X-API-Key: sr_0123456789abcdef...

If both are present, X-API-Key is used. A key acts exactly as the account that created it: an administrator, a reseller or a customer. There are no per-key scopes. Calls made with a key need no session cookie and no CSRF token.

A key is refused with 401 invalid API key when it is wrong, has expired, is used from an address outside its Allowed from list, or belongs to an account that is no longer active. Administrator keys also obey IP Access Restriction Management. Reseller and customer keys stop working as soon as their plan loses the REST API permission, because that permission is checked on every call.

First call with curl#

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

First call with PowerShell#

[Net.ServicePointManager]::SecurityProtocol = 'Tls12'
$base = 'https://panel.example.com:9443/api'
$h = @{ Authorization = 'Bearer sr_...' }
Invoke-RestMethod -Uri "$base/subscriptions" -Headers $h

The first line makes Windows PowerShell 5.1 use TLS 1.2; PowerShell 7 does not need it.

Requests and responses#

• Methods. GET reads, POST creates or starts an action, PUT changes, DELETE removes.
• Bodies. Send JSON with Content-Type: application/json. Ordinary bodies are limited to 1 MiB; file uploads have their own endpoints.
• Unknown fields are refused. The panel decodes request bodies strictly: a field it does not know, or a value of the wrong type, gives 400 invalid request. Check field names and types against the OpenAPI description (see below) when that happens.
• Answers. JSON objects with status 200, or 202 for a few calls that only queue work. Download endpoints, such as backup and log downloads, return the file itself.
• IDs. Objects are addressed by numeric IDs: /api/subscriptions/12, /api/websites/31. A website ID is the domain's ID, which you find in the domains list of GET /api/subscriptions/{id} or in GET /api/domains.

Tasks: work that runs in the background#

Creating, changing and removing hosting objects touches IIS, Windows accounts, NTFS permissions, DNS and mail. That work runs in the StackRegent task service, so the API answers quickly with a task ID:

POST /api/subscriptions            ->  {"id": 12, "task_id": 345}
POST /api/subscriptions/12/status  ->  {"task_id": 346}
POST /api/backups                  ->  {"id": 88, "task": 347}

Note that the backup call names the field task. Follow a task with GET /api/tasks/{id}. Its status is queued, running, success or failure; progress is a percentage and log holds what the task wrote. A finished task can be queued again with POST /api/tasks/{id}/retry. Administrators can list tasks with GET /api/tasks?status=failure&page=1&size=50; resellers and customers see their own recent tasks in GET /api/my/tasks and can read a single task they started.

Errors#

Errors use the HTTP status code and a JSON body with an error message. Validation errors also name the fields that failed:

HTTP/1.1 400 Bad Request
{"error": "Please correct the highlighted fields.", "fields": ["contact_name", "login"]}

While the license is restricted, administrator keys can still read and set the license (GET and PUT /api/license, POST /api/license/check) and nothing else. Reseller and customer keys keep working, though nothing new can be created until the license is in order. Websites, mail and DNS are never affected.

Rate limits#

API keys have no request quota, and authenticated calls are not counted. The only limit in the API is on failed sign-ins at the login endpoint. Be considerate anyway: run bulk jobs one call at a time and wait for each task before starting the next large one, because the task service runs two workers.

Pagination and search#

List endpoints for customers, subscriptions and domains take page (from 1) and size (1 to 1000, default 25), plus a search term q:

GET /api/clients?type=customer&q=example&page=2&size=100
GET /api/subscriptions?client=7&page=1&size=50
GET /api/domains?subscription=12

They answer with one page and the total count:

{"items": [ ... ], "total": 214}

GET /api/clients lists customers by default; add type=reseller for resellers and owner=ID for one reseller's customers. There q matches the contact name, company, login and email address. In GET /api/subscriptions, client=ID limits the list to one customer, and q matches the subscription name, the customer's name and the system user. The task list takes page and size up to 100.

OpenAPI description#

GET /api/openapi.json returns an OpenAPI 3.0 document of every endpoint with its parameters. It needs a key or a signed-in session, like any other call:

curl -s -H "Authorization: Bearer sr_..." https://panel.example.com:9443/api/openapi.json -o stackregent-openapi.json

Load it into an OpenAPI tool to browse the endpoints or generate a client. The panel has no built-in playground: use curl, your OpenAPI tool, or stackregent api on the server.

Endpoint reference#

The tables below list every route the panel registers, grouped by area. The columns say which kind of key may call it:

• Admin: an administrator's key. Restricted administrators are further limited by Restricted Mode Settings.
• Reseller: a reseller's key, limited to the reseller's own customers, plans, subscriptions and IP pool.
• Customer: a customer's key, limited to the customer's own subscriptions.

Where a reseller or customer call changes something, the subscription's plan must also allow it; the permission is named in brackets as it appears in the service plan. Parameters and fields are in the OpenAPI description. Placeholders such as {id} are numeric IDs.

Sign-in and health#

These answer without a key. The panel's own login page uses the auth endpoints; GET /api/health answers {"ok": true, "time": "..."} and suits an uptime monitor.

Customers and resellers#

Service plans#

Subscriptions#

Websites and domains#

SSL/TLS certificates#

DNS#

File Manager#

FTP and the system user#

Databases and ODBC#

Mail#

Applications, WordPress, Laravel and Git#

Scheduled tasks#

Backups, transfer and migration#

Statistics, monitoring and diagnostics#

Tasks and the action log#

Security#

Administrators, profile and API keys#

Server management#

Branding, languages and interface#

Reseller and customer account (/api/my)#

These answer for reseller and customer keys only. The rows marked no in every column (key management, password changes, logging in as a customer and returning from it) work only in a signed-in panel session, never with a key.

Related pages#

• API keys: who a key acts as and how to limit it
• Command line: stackregent api calls these endpoints on the server without a key of your own
• Automation examples: complete scripts for provisioning, suspension and backups