API Reference

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.

Last updated

/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.

MethodPathDescription
GET/api/v1/settings/panel-domainGet the panel domain
PUT/api/v1/settings/panel-domainPut the panel on a domain
PUT/api/v1/settings/panel-domain/addressUse the domain as the panel's address
DELETE/api/v1/settings/panel-domainTake the panel off its domain
GET/api/v1/settings/emailGet the email settings
PUT/api/v1/settings/emailSave the email settings
POST/api/v1/settings/email/testSend a test email
GET/api/v1/settings/email/messagesList sent email

Get the panel domain

GET/api/v1/settings/panel-domain
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

The 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:

FieldDescription
domainThe panel's domain, or null.
removingTaking it off the domain was asked and is not finished (or failed).
websiteThe website that serves the domain, with its certificate under ssl. Certificates are managed through Websites.
serverThis server: { id, name, status, publicIp, ipAddresses, webStack }, or null when it is not connected.
defaultPortThe 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

PUT/api/v1/settings/panel-domain
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Creates 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

FieldTypeRequiredDescription
domainstringYesSuch as cp.example.com.
proxyPortintegerNo1 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

StatusCodeWhen
409NO_LOCAL_SERVERThe panel's own server is not connected as This server.
409PANEL_WEBSITE_FAILEDSetting up the current domain failed: send the same domain to try again, or remove it first.
422VALIDATION_ERRORAn invalid domain or port, or the website could not be created with them.

Use the domain as the panel's address

PUT/api/v1/settings/panel-domain/address
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Makes 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

FieldTypeRequiredDescription
usebooleanYestrue 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

DELETE/api/v1/settings/panel-domain
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Removes 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

GET/api/v1/settings/email
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

The 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

PUT/api/v1/settings/email
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Saves any of the fields; the rest keep their values. Changing the host forgets the saved password unless a new one is given.

Request body

FieldTypeRequiredDescription
enabledbooleanNoSend email. Needs a host, port and from address (and a password with a username).
hoststringNoThe SMTP host name or IP address, without scheme or port.
portintegerNo1 to 65535.
securitystringNotls (encrypted from the start, usually 465), starttls (required upgrade, usually 587) or none (only for a mail server on the same machine or network).
usernamestring or nullNoUp to 254 characters.
passwordstring or nullNoSets the password; null or empty removes it; leaving it out keeps it.
fromAddressstringNoThe address emails come from.
fromNamestringNoUp to 100 characters. Default VaultPanel.
alertsobjectNoevents (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

POST/api/v1/settings/email/test
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Sends a test email now, with the saved settings or with settings being edited (merged over the saved ones, not saved).

Request body

FieldTypeRequiredDescription
tostringYesWho receives it.
settingsobjectNoAny 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

StatusCodeWhen
422EMAIL_NOT_SET_UPA setting is missing; the message says which.
502EMAIL_SEND_FAILEDThe mail server refused it or could not be reached; the message explains why.

List sent email

GET/api/v1/settings/email/messages
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

The 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

NameTypeRequiredDescription
limitintegerNo1 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": "…"
}