Panel settings
API reference for the panel's own settings - putting the panel on a domain, its address, and the email it sends for invites, password resets and alerts.
/settings holds the settings of the panel itself: the domain it is served on and the email it sends. Everything here needs settings.manage (owners and admins); with an API token, only the full scope grants it. Other panel-wide settings live with their feature: panel access, the two-factor policy and sessions, backup storage and the AI assistant.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/settings/panel-domain | Get the panel domain |
| PUT | /api/v1/settings/panel-domain | Put the panel on a domain |
| PUT | /api/v1/settings/panel-domain/address | Use the domain as the panel's address |
| DELETE | /api/v1/settings/panel-domain | Take the panel off its domain |
| GET | /api/v1/settings/email | Get the email settings |
| PUT | /api/v1/settings/email | Save the email settings |
| POST | /api/v1/settings/email/test | Send a test email |
| GET | /api/v1/settings/email/messages | List sent email |
Get the panel domain
/api/v1/settings/panel-domainThe panel is put on a domain by a reverse-proxy website on This server, the server the panel runs on, which sends the domain's requests to the panel's port (its plain HTTP loopback port when the panel serves HTTPS itself). This returns that state:
| Field | Description |
|---|---|
domain | The panel's domain, or null. |
removing | Taking it off the domain was asked and is not finished (or failed). |
website | The website that serves the domain, with its certificate under ssl. Certificates are managed through Websites. |
server | This server: { id, name, status, publicIp, ipAddresses, webStack }, or null when it is not connected. |
defaultPort | The port the website proxies to unless another is given. |
address | { current, environment, usesDomain, canUseDomain }: the panel's address now, the one in its .env, whether the domain is the address, and whether it can be (the website is active with a trusted, non-staging certificate). |
Example request
curl https://panel.example.com/api/v1/settings/panel-domain \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const state = await panel.request('GET', '/settings/panel-domain');Response 200 OK
{
"success": true,
"data": {
"domain": "cp.example.com",
"removing": false,
"website": { "id": "5d6e7f8a-…", "type": "proxy", "primaryDomain": "cp.example.com", "proxyPort": 8091, "status": "active" },
"server": { "id": "9b2e7c1a-…", "name": "This server", "status": "online", "publicIp": "203.0.113.10", "ipAddresses": ["203.0.113.10"], "webStack": {} },
"defaultPort": 8091,
"address": {
"current": "https://203.0.113.10:8090",
"environment": "https://203.0.113.10:8090",
"usesDomain": false,
"canUseDomain": true
}
},
"message": "OK",
"requestId": "…"
}Put the panel on a domain
/api/v1/settings/panel-domainCreates the panel's website on This server for the domain, or moves it to another domain or port. Point the domain's DNS at the server first, and install the web stack (NGINX and Certbot) on it. Moving to another domain sets the panel's address back to the one in .env until the new domain has a certificate. Then issue a certificate for the website and use the domain as the address. See Panel HTTPS and domain.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Such as cp.example.com. |
proxyPort | integer | No | 1 to 65535. Default defaultPort. |
Example request
curl https://panel.example.com/api/v1/settings/panel-domain \
-X PUT \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "domain": "cp.example.com" }'const { job } = await panel.request('PUT', '/settings/panel-domain', { body: { domain: 'cp.example.com' } });
if (job) await panel.jobs.wait(job.id);Response 202 Accepted with the state and the website's job (message The agent is putting the panel on the domain), or 200 OK with job: null when nothing changed (message Nothing to change).
Errors
| Status | Code | When |
|---|---|---|
| 409 | NO_LOCAL_SERVER | The panel's own server is not connected as This server. |
| 409 | PANEL_WEBSITE_FAILED | Setting up the current domain failed: send the same domain to try again, or remove it first. |
| 422 | VALIDATION_ERROR | An invalid domain or port, or the website could not be created with them. |
Use the domain as the panel's address
/api/v1/settings/panel-domain/addressMakes https://<domain> the panel's address, so agent install commands, password reset links and deploy webhooks use it; or goes back to the address in .env. The IP address keeps working either way.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
use | boolean | Yes | true uses the domain; false goes back to the .env address. |
Example request
curl https://panel.example.com/api/v1/settings/panel-domain/address \
-X PUT \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "use": true }'await panel.request('PUT', '/settings/panel-domain/address', { body: { use: true } });Response 200 OK: the state, message The panel's address is now ….
Errors: 409 PANEL_DOMAIN_NOT_READY when the domain has no trusted certificate yet (a staging one does not count: agents on other servers refuse untrusted certificates).
Take the panel off its domain
/api/v1/settings/panel-domainRemoves the panel's website (its NGINX configuration and certificate) from This server and sets the address back to the one in .env. The IP address keeps working.
Example request
curl https://panel.example.com/api/v1/settings/panel-domain \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.request('DELETE', '/settings/panel-domain');Response 200 OK: the state with removing: true and the website's job, message The panel is being taken off its domain.
Get the email settings
/api/v1/settings/emailThe SMTP server the panel sends its own email through: invites, password reset links and alert emails. The password is never returned (hasPassword). missing says what is still needed, and ready whether email is on and complete. See Panel email.
Example request
curl https://panel.example.com/api/v1/settings/email \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const settings = await panel.request('GET', '/settings/email');Response 200 OK
{
"success": true,
"data": {
"enabled": true,
"host": "smtp.example.com",
"port": 587,
"security": "starttls",
"username": "panel@example.com",
"hasPassword": true,
"fromAddress": "panel@example.com",
"fromName": "VaultPanel",
"alerts": {
"events": ["backup.failed", "restore.failed", "cron.failed", "deployment.failed", "alert.firing", "server.offline"],
"toAdmins": true,
"extra": []
},
"missing": null,
"ready": true,
"updatedAt": "2026-11-08T10:00:00.000Z"
},
"message": "OK",
"requestId": "…"
}Save the email settings
/api/v1/settings/emailSaves any of the fields; the rest keep their values. Changing the host forgets the saved password unless a new one is given.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Send email. Needs a host, port and from address (and a password with a username). |
host | string | No | The SMTP host name or IP address, without scheme or port. |
port | integer | No | 1 to 65535. |
security | string | No | tls (encrypted from the start, usually 465), starttls (required upgrade, usually 587) or none (only for a mail server on the same machine or network). |
username | string or null | No | Up to 254 characters. |
password | string or null | No | Sets the password; null or empty removes it; leaving it out keeps it. |
fromAddress | string | No | The address emails come from. |
fromName | string | No | Up to 100 characters. Default VaultPanel. |
alerts | object | No | events (the webhook events to email), toAdmins (send them to owners and admins) and extra (up to 10 more addresses). |
Example request
curl https://panel.example.com/api/v1/settings/email \
-X PUT \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"host": "smtp.example.com",
"port": 587,
"security": "starttls",
"username": "panel@example.com",
"password": "'"$SMTP_PASSWORD"'",
"fromAddress": "panel@example.com"
}'await panel.request('PUT', '/settings/email', {
body: { alerts: { events: ['backup.failed', 'server.offline'], extra: ['oncall@example.com'] } },
});Response 200 OK: the settings, message Email settings saved.
Errors: 422 VALIDATION_ERROR when turning email on with a setting missing, or an invalid field.
Send a test email
/api/v1/settings/email/testSends a test email now, with the saved settings or with settings being edited (merged over the saved ones, not saved).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Who receives it. |
settings | object | No | Any of host, port, security, username, password, fromAddress and fromName to try. |
Example request
curl https://panel.example.com/api/v1/settings/email/test \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "to": "owner@example.com" }'const { message } = await panel.request('POST', '/settings/email/test', { body: { to: 'owner@example.com' } });Response 200 OK: { message }, the sent email (as in List sent email), message Test email sent to owner@example.com.
Errors
| Status | Code | When |
|---|---|---|
| 422 | EMAIL_NOT_SET_UP | A setting is missing; the message says which. |
| 502 | EMAIL_SEND_FAILED | The mail server refused it or could not be reached; the message explains why. |
List sent email
/api/v1/settings/email/messagesThe most recent email the panel sent or is trying to send, newest first. Messages that fail are retried after 1, 5 and 30 minutes, and are kept for 30 days.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | 1 to 200. Default 50. |
Example request
curl "https://panel.example.com/api/v1/settings/email/messages?limit=20" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.request('GET', '/settings/email/messages', { query: { limit: 20 } });Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "f1e2d3c4-…",
"to": "ada@example.org",
"subject": "Your VaultPanel account",
"purpose": "invite",
"event": null,
"status": "sent",
"attempts": 1,
"error": null,
"nextAttemptAt": null,
"sentAt": "2026-11-10T12:00:03.000Z",
"createdAt": "2026-11-10T12:00:02.000Z"
}
]
},
"message": "OK",
"requestId": "…"
}Users and roles
API reference for panel users (invite, update, deactivate, reset links and two-factor resets), the built-in roles and the audit log.
Servers
API reference for servers, enrollment tokens and agent install commands, metrics history, agent updates, terminal sessions and the dashboard summary.