API Reference

Hosting

API reference for hosting plans, customer accounts, quotas, suspending and removing accounts, the financial report, billing API keys and a customer's own account.

Last updated

Hosting plans set what a customer may have: websites, subdomains, apps, databases, database users, cron jobs, disk space, and caps on each app's CPU and memory. Customers sign in to a panel that shows only their own account. The staff endpoints under /hosting manage plans, customers and the API keys billing systems use; /hosting/me is for the signed-in customer.

Billing systems manage accounts through the separate Billing API. For the concepts, see Hosting plans and customers.

MethodPathDescription
GET/api/v1/hosting/meGet your account
GET/api/v1/hosting/me/dnsGet your DNS
POST/api/v1/hosting/me/dns/zones/:id/checkCheck one of your zones
GET/api/v1/hosting/plansList plans
POST/api/v1/hosting/plansCreate a plan
GET/api/v1/hosting/plans/:idGet a plan
PATCH/api/v1/hosting/plans/:idUpdate a plan
DELETE/api/v1/hosting/plans/:idDelete a plan
GET/api/v1/hosting/customersList customers
POST/api/v1/hosting/customersCreate a customer
GET/api/v1/hosting/customers/:idGet a customer
PATCH/api/v1/hosting/customers/:idUpdate a customer
POST/api/v1/hosting/customers/:id/planChange the plan
POST/api/v1/hosting/customers/:id/suspendSuspend an account
POST/api/v1/hosting/customers/:id/unsuspendUnsuspend an account
POST/api/v1/hosting/customers/:id/terminateRemove an account
POST/api/v1/hosting/customers/:id/password-resetCreate a password reset link
POST/api/v1/hosting/customers/:id/resourcesMove a resource to a customer
DELETE/api/v1/hosting/customers/:id/resources/:type/:resourceIdTake a resource back
GET/api/v1/hosting/reports/financialGet the financial report
GET/api/v1/hosting/api-keysList billing API keys
POST/api/v1/hosting/api-keysCreate a billing API key
POST/api/v1/hosting/api-keys/:id/revokeRevoke a billing API key

Hosting customers and the API

A hosting customer (role customer) can reach only /auth, /api-tokens, /hosting/me, and the website, subdomain, domain, certificate, app, deployment, CMS, database, database user, backup, backup schedule, cron job and job routes; everything else answers 403 FORBIDDEN. There they see and change only what their account owns (anything else is 404). Their creates are checked against their plan:

StatusCodeWhen
409QUOTA_REACHEDThe plan's limit is reached (details: { kind, limit, used }), or the account is over its disk space.
409NO_SERVERThe account has no server.
403ACCOUNT_SUSPENDEDSigning in to a suspended or removed account.

Get your account

GET/api/v1/hosting/me
Auth
Session cookie (+ CSRF token) or API token

The signed-in customer's account: customer, plan (with its limits and appCaps), usage, appCaps, ports (the account's own app ports, each with the app on it or null) and server (its name, status, host name, addresses, time zone and installed software). Staff get 404.

Example request

curl https://panel.example.com/api/v1/hosting/me \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { customer, plan, usage, ports } = await panel.hosting.me();

Response 200 OK

{
  "success": true,
  "data": {
    "customer": { "id": "c1d2e3f4-…", "name": "Ada Customer", "company": "Example Ltd", "email": "ada@example.org", "status": "active", "createdAt": "2026-10-05T10:00:00.000Z" },
    "plan": {
      "id": "a0b1c2d3-…",
      "name": "Starter",
      "priceCents": 900,
      "currency": "USD",
      "billingCycle": "monthly",
      "limits": { "websites": 5, "subdomains": 10, "applications": 2, "databases": 5, "databaseUsers": 5, "cronJobs": 10, "diskMb": 10240 },
      "appCaps": { "appMemoryMb": 512, "appCpuPercent": 100 }
    },
    "usage": {
      "websites": 2,
      "subdomains": 1,
      "applications": 1,
      "databases": 2,
      "databaseUsers": 2,
      "cronJobs": 1,
      "diskMb": 812,
      "diskBytes": 851443712,
      "disk": { "websites": 402653184, "applications": 314572800, "databases": 134217728 },
      "limits": { "websites": 5, "subdomains": 10, "applications": 2, "databases": 5, "databaseUsers": 5, "cronJobs": 10, "diskMb": 10240 },
      "over": []
    },
    "appCaps": { "appMemoryMb": 512, "appCpuPercent": 100 },
    "ports": [{ "port": 3001, "serverId": "9b2e7c1a-…", "application": { "id": "3e4f5a6b-…", "name": "shop-api" } }],
    "server": { "id": "9b2e7c1a-…", "name": "web-1", "status": "online", "hostname": "web-1", "publicIp": "203.0.113.10" }
  },
  "message": "OK",
  "requestId": "…"
}

Get your DNS

GET/api/v1/hosting/me/dns
Auth
Session cookie (+ CSRF token) or API token

The name servers to set at the registrar, whether new domains get a zone automatically, and the account's domains this panel answers for, with their name servers and last public DNS check. See DNS for the zone fields. Staff get 404.

Example request

curl https://panel.example.com/api/v1/hosting/me/dns \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { nameservers, autoZones, zones } = await panel.request('GET', '/hosting/me/dns');

Response 200 OK

{
  "success": true,
  "data": {
    "nameservers": ["ns1.example.net", "ns2.example.net"],
    "autoZones": true,
    "zones": [
      {
        "id": "4f0c2a8e-…",
        "domain": "example.org",
        "status": "active",
        "nameservers": [{ "host": "ns1.example.net", "inZone": false, "addresses": [] }],
        "delegation": { "status": "ok", "nameservers": ["ns1.example.net", "ns2.example.net"], "detail": null, "checkedAt": "2026-11-10T09:00:00.000Z" }
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

Check one of your zones

POST/api/v1/hosting/me/dns/zones/:id/check
Auth
Session cookie (+ CSRF token) or API token

Checks one of the account's zones against public DNS, like Check name servers in public DNS, and returns { zone } in the shape above.

Example request

curl https://panel.example.com/api/v1/hosting/me/dns/zones/4f0c2a8e-5b1d-4c47-9a53-1c2f3b4d5e6f/check \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { zone } = await panel.request('POST', `/hosting/me/dns/zones/${zoneId}/check`);

Response 200 OK: { zone }.

Errors: 404 NOT_FOUND for a zone that is not the account's.

The plan object

FieldTypeDescription
id, name, descriptionstringThe plan.
isActivebooleanOffered to new customers.
priceCents, currency, billingCycleThe price per cycle (monthly, quarterly, yearly or free). VaultPanel stores it to show it and hand it to billing systems; it takes no payments.
serverGroupobject or nullNew accounts go on a server of this group.
limitsobjectwebsites, subdomains, applications, databases, databaseUsers, cronJobs and diskMb. null is unlimited.
appCapsobjectappMemoryMb (64 to 262144) and appCpuPercent (10 to 6400; 100 is one core) for each app. null is no cap.
customerCountintegerCustomers on the plan.

List plans

GET/api/v1/hosting/plans
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.read
Token scope
read

Returns every plan, by name.

Example request

curl https://panel.example.com/api/v1/hosting/plans \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.hosting.plans();

Response 200 OK: { items } of plans.

Create a plan

POST/api/v1/hosting/plans
Auth
Session cookie (+ CSRF token) or API token
Permission
plans.manage
Token scope
customers

Request body

FieldTypeRequiredDescription
namestringYesUp to 60 letters, numbers, spaces and . _ - + ( ) &. Unique.
descriptionstringNoUp to 300 characters.
isActivebooleanNoOffered to new customers. Default true.
priceCentsinteger or nullNo0 to 100000000. Default null (no price).
currencystringNoA 3-letter code. Default USD.
billingCyclestringNomonthly (default), quarterly, yearly or free.
serverGroupIdstring (UUID) or nullNoPut new accounts on a server of this group.
limitsobjectNoAny of the limits; 0 to 10000 (diskMb up to 100000000), or null for unlimited.
appCapsobjectNoappMemoryMb and appCpuPercent, or null.

Example request

curl https://panel.example.com/api/v1/hosting/plans \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Starter",
    "priceCents": 900,
    "currency": "USD",
    "billingCycle": "monthly",
    "limits": { "websites": 5, "applications": 2, "databases": 5, "diskMb": 10240 },
    "appCaps": { "appMemoryMb": 512, "appCpuPercent": 100 }
  }'
const plan = await panel.hosting.createPlan({
  name: 'Starter',
  priceCents: 900,
  limits: { websites: 5, applications: 2, databases: 5, diskMb: 10240 },
  appCaps: { appMemoryMb: 512, appCpuPercent: 100 },
});

Response 201 Created: the plan, message Plan created.

Errors: 422 VALIDATION_ERROR for a name another plan has, an unknown server group, or another invalid field.

Get a plan

GET/api/v1/hosting/plans/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.read
Token scope
read

Example request

curl https://panel.example.com/api/v1/hosting/plans/a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const plan = await panel.request('GET', `/hosting/plans/${planId}`);

Response 200 OK: the plan. 404 NOT_FOUND when there is none.

Update a plan

PATCH/api/v1/hosting/plans/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
plans.manage
Token scope
customers

Changes any of the fields of Create a plan (send at least one). New app caps reach each of the plan's apps on its next deploy or apply; appsCapped says how many apps are affected.

Example request

curl https://panel.example.com/api/v1/hosting/plans/a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limits": { "websites": 10 } }'
const { plan, appsCapped } = await panel.hosting.updatePlan(planId, { limits: { websites: 10 } });

Response 200 OK: { plan, appsCapped }, message Plan saved. (plus how many apps get the new cap).

Delete a plan

DELETE/api/v1/hosting/plans/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
plans.manage
Token scope
customers

Deletes a plan no customer is on (removed accounts included). To stop offering a plan that has customers, set isActive to false instead.

Example request

curl https://panel.example.com/api/v1/hosting/plans/a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
await panel.hosting.removePlan(planId);

Response 200 OK: data is null, message Plan deleted.

Errors: 404 NOT_FOUND, and 409 PLAN_IN_USE while customers are on it.

The customer object

FieldTypeDescription
id, name, company, emailstringThe account.
externalIdstring or nullThe billing system's id for it (a WHMCS service id…).
statusstringactive, suspended or terminated (removed; kept for the record).
suspendReason, suspendedAtWhy and when it was suspended.
suspendedResourcesobject or nullHow many websites, applications and cronJobs suspending turned off.
terminatedAt, notes, createdViacreatedVia is panel or api.
planobject{ id, name }.
serverobject or null{ id, name, status }: where new websites and apps go.
userId, userThe sign-in account: { id, email, isActive, twoFactorEnabled, lastLoginAt } on single-customer responses.
usageobjectCounts, diskBytes, diskMb, disk per kind, the plan's limits, and over: the limits it is over (for example after moving to a smaller plan; nothing is deleted, new things are refused).

List customers

GET/api/v1/hosting/customers
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.read
Token scope
read

Returns customers a page at a time, with their usage. Removed accounts are listed only with status=terminated.

Query parameters

NameTypeRequiredDescription
searchstringNoPart of the name, email, company or external id.
statusstringNoactive, suspended or terminated.
planId, serverIdstring (UUID)NoOnly customers on this plan or server.
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
sort, orderstringNocreatedAt (default) or name; desc (default) or asc.

Example request

curl "https://panel.example.com/api/v1/hosting/customers?status=suspended" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.hosting.customers({ status: 'suspended' });

Response 200 OK: { items, pagination } of customers.

Create a customer

POST/api/v1/hosting/customers
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Creates the account and its sign-in. Without a password, an invite link is returned (and emailed when panel email is set up) so the customer chooses one. Without a server, the panel picks one: a connected server of the plan's server group (or any server), online first, then the one with the fewest customers.

Request body

FieldTypeRequiredDescription
namestringYesUp to 120 characters.
emailstringYesUnique among accounts.
planIdstring (UUID)YesA plan offered to new customers.
companystringNoUp to 120 characters.
serverIdstring (UUID) or nullNoA connected server.
externalIdstringNoThe billing system's id: letters, digits and . _ : -, up to 100. Unique.
passwordstringNoThe account's password.
notesstringNoUp to 1000 characters, for staff.

Example request

curl https://panel.example.com/api/v1/hosting/customers \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ada Customer", "email": "ada@example.org", "planId": "a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d" }'
const { customer, inviteUrl } = await panel.hosting.createCustomer({
  name: 'Ada Customer',
  email: 'ada@example.org',
  planId: 'a0b1c2d3-e4f5-4a6b-8c7d-8e9f0a1b2c3d',
});

Response 201 Created

{
  "success": true,
  "data": {
    "customer": { "id": "c1d2e3f4-…", "name": "Ada Customer", "email": "ada@example.org", "status": "active", "plan": { "id": "a0b1c2d3-…", "name": "Starter" } },
    "inviteUrl": "https://panel.example.com/reset-password#token=…",
    "inviteExpiresAt": "2026-11-17T12:00:00.000Z",
    "email": { "sent": true, "to": "ada@example.org" }
  },
  "message": "Customer created. The invite link was emailed to ada@example.org.",
  "requestId": "…"
}

Errors

StatusCodeWhen
409EXTERNAL_ID_TAKENAnother customer has this external id (details.customerId).
409NO_SERVERNo connected server to put the account on.
409CONFLICTThe email or external id was just taken.
422VALIDATION_ERRORThe email is taken, the plan is not offered to new customers, the server is not connected, or another invalid field.

Get a customer

GET/api/v1/hosting/customers/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.read
Token scope
read

Returns the customer with planDetail (the full plan), resources (its websites, applications, databases and databaseUsers, up to 500 each) and ports (its app ports).

Example request

curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const customer = await panel.hosting.customer(customerId);

Response 200 OK: the customer with planDetail, resources and ports. 404 NOT_FOUND when there is none.

Update a customer

PATCH/api/v1/hosting/customers/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Changes any of name, email, company, serverId, externalId and notes (send at least one). The name and email also change on the sign-in account. Moving to another server moves the account's free app ports there. A removed account can change only its notes.

Example request

curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "company": "Example Holdings Ltd" }'
await panel.hosting.updateCustomer(customerId, { company: 'Example Holdings Ltd' });

Response 200 OK: the customer, message Customer saved.

Errors: 409 CUSTOMER_REMOVED, 409 EXTERNAL_ID_TAKEN, 422 VALIDATION_ERROR.

Change the plan

POST/api/v1/hosting/customers/:id/plan
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Moves the account to another plan. Nothing is deleted when the account is over the new plan's limits: over lists them, and new things are refused until it is back under.

Request body

FieldTypeRequiredDescription
planIdstring (UUID)YesThe new plan.

Example request

curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/plan \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "planId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e" }'
const { customer, over, appsCapped } = await panel.hosting.changePlan(customerId, newPlanId);

Response 200 OK: { customer, over, appsCapped }, message Plan changed.

Errors: 409 CUSTOMER_REMOVED, 422 VALIDATION_ERROR for an unknown plan.

Suspend an account

POST/api/v1/hosting/customers/:id/suspend
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Signs the account out and refuses its sign-in, turns its websites off, stops its apps and pauses its cron jobs. Suspending again catches what was busy the first time. warnings lists anything that could not be turned off.

Request body

FieldTypeRequiredDescription
reasonstringNoUp to 300 characters.

Example request

curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/suspend \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Invoice overdue" }'
const { customer, warnings } = await panel.hosting.suspend(customerId, 'Invoice overdue');

Response 200 OK: { customer, warnings }, message Account suspended.

Errors: 409 CUSTOMER_REMOVED.

Unsuspend an account

POST/api/v1/hosting/customers/:id/unsuspend
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Lets the account sign in again and turns back on exactly what suspending turned off.

Example request

curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/unsuspend \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { customer, warnings } = await panel.hosting.unsuspend(customerId);

Response 200 OK: { customer, warnings }, message Account unsuspended.

Errors: 409 NOT_SUSPENDED.

Remove an account

POST/api/v1/hosting/customers/:id/terminate
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Closes the account's sign-in and deletes every cron job, app, website, database user, database and backup it owns (with their files), its backup schedules and the DNS zones added for it. The account record is kept with status terminated. Calling it again retries anything left.

Example request

curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/terminate \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { queued, warnings } = await panel.hosting.terminate(customerId);

Response 200 OK

{
  "success": true,
  "data": {
    "customer": { "id": "c1d2e3f4-…", "status": "terminated", "terminatedAt": "2026-11-10T13:00:00.000Z" },
    "queued": { "cronJobs": 1, "applications": 1, "websites": 2, "databaseUsers": 2, "databases": 2, "backups": 6 },
    "warnings": []
  },
  "message": "Account removed. Its websites, apps and databases are being deleted.",
  "requestId": "…"
}
POST/api/v1/hosting/customers/:id/password-reset
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Creates a link for the customer to set a new password, emailed when panel email is set up.

Example request

curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/password-reset \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { resetUrl, expiresAt } = await panel.request('POST', `/hosting/customers/${customerId}/password-reset`);

Response 200 OK: { resetUrl, expiresAt, email }.

Errors: 409 CUSTOMER_REMOVED.

Move a resource to a customer

POST/api/v1/hosting/customers/:id/resources
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Gives an existing website, app, database or database user to the account, with what hangs off it (cron jobs, backups, schedules). Move an app rather than its website: the website goes with it.

Request body

FieldTypeRequiredDescription
typestringYeswebsite, application, database or database_user.
resourceIdstring (UUID)YesIts id.

Example request

curl https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/resources \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "website", "resourceId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" }'
await panel.request('POST', `/hosting/customers/${customerId}/resources`, {
  body: { type: 'website', resourceId: '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d' },
});

Response 200 OK: { customer }, message Moved to this customer.

Errors

StatusCodeWhen
404NOT_FOUNDNo such resource.
409CUSTOMER_REMOVEDThe account was removed.
409RESOURCE_OWNEDIt belongs to another customer: take it from that account first.
409WEBSITE_OWNED_BY_APPThe website serves an app: move the app instead.
409PANEL_WEBSITEThe website puts VaultPanel itself on its domain.
422VALIDATION_ERRORA database user with access to another account's database, or an app on another customer's port.

Take a resource back

DELETE/api/v1/hosting/customers/:id/resources/:type/:resourceId
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.manage
Token scope
customers

Takes a website, app, database or database user back from the account to staff.

Example request

curl -X DELETE \
  https://panel.example.com/api/v1/hosting/customers/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/resources/website/1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
await panel.request('DELETE', `/hosting/customers/${customerId}/resources/website/${websiteId}`);

Response 200 OK: { customer }, message Taken back from this customer.

Errors: 404 NOT_FOUND when it is not this customer's, 409 WEBSITE_OWNED_BY_APP.

Get the financial report

GET/api/v1/hosting/reports/financial
Auth
Session cookie (+ CSRF token) or API token
Permission
customers.read
Token scope
read

What accounts are worth at their plans' prices: expected amounts, never payments (VaultPanel takes none). Currencies are never mixed. See Financial report.

Query parameters

NameTypeRequiredDescription
monthsintegerNo1 to 36. Default 12.

Example request

curl "https://panel.example.com/api/v1/hosting/reports/financial?months=6" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const report = await panel.request('GET', '/hosting/reports/financial', { query: { months: 6 } });

Response 200 OK

{
  "success": true,
  "data": {
    "generatedAt": "2026-11-10T13:00:00.000Z",
    "months": 6,
    "from": "2026-06-01T00:00:00.000Z",
    "summary": {
      "activeAccounts": 42,
      "suspendedAccounts": 3,
      "unpricedAccounts": 1,
      "newAccounts": 12,
      "removedAccounts": 2,
      "byCurrency": [{ "currency": "USD", "monthlyCents": 37800, "yearlyCents": 453600, "atRiskCents": 2700, "payingAccounts": 41 }]
    },
    "plans": [
      {
        "id": "a0b1c2d3-…",
        "name": "Starter",
        "isActive": true,
        "billingCycle": "monthly",
        "priceCents": 900,
        "currency": "USD",
        "monthlyCents": 900,
        "activeAccounts": 42,
        "suspendedAccounts": 3,
        "monthlyTotalCents": 37800,
        "atRiskCents": 2700
      }
    ],
    "history": [
      { "month": "2026-11", "newAccounts": 2, "removedAccounts": 0, "suspensions": 1, "accountsAtEnd": 45, "monthlyByCurrency": { "USD": 40500 } }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

monthlyCents spreads a plan's price over one month (0 for free plans, null without a price). atRiskCents is what suspended accounts would bring. monthlyByCurrency prices the accounts at the end of each month at their current plan.

List billing API keys

GET/api/v1/hosting/api-keys
Auth
Session cookie (+ CSRF token) or API token
Permission
billing.manage
Token scope
full

Returns the vpk_ keys billing systems use with the Billing API, active ones first. The key itself is never returned again, only its prefix.

Example request

curl https://panel.example.com/api/v1/hosting/api-keys \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const { items } = await panel.request('GET', '/hosting/api-keys');

Response 200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "e5f6a7b8-…",
        "name": "WHMCS",
        "prefix": "vpk_Xr8kQ2mN",
        "scopes": ["billing"],
        "createdBy": { "id": "3c4d5e6f-…", "email": "owner@example.com" },
        "lastUsedAt": "2026-11-10T12:58:00.000Z",
        "lastUsedIp": "198.51.100.20",
        "revokedAt": null,
        "createdAt": "2026-10-05T09:00:00.000Z"
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}

Create a billing API key

POST/api/v1/hosting/api-keys
Auth
Session cookie (+ CSRF token) or API token
Permission
billing.manage
Token scope
full

Creates a key. The key (vpk_…) is in this response only; the panel keeps only its hash. Up to 50 active keys.

Request body

FieldTypeRequiredDescription
namestringYesUp to 100 characters.
scopesstring[]No["billing"] (the default and only scope): list plans, and create, suspend, unsuspend, change the plan of and remove customer accounts.

Example request

curl https://panel.example.com/api/v1/hosting/api-keys \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "WHMCS" }'
const { apiKey, key } = await panel.request('POST', '/hosting/api-keys', { body: { name: 'WHMCS' } });

Response 201 Created: { apiKey, key }, message API key created. Copy it now: it is not shown again.

Errors: 409 TOO_MANY_KEYS with 50 active keys.

Revoke a billing API key

POST/api/v1/hosting/api-keys/:id/revoke
Auth
Session cookie (+ CSRF token) or API token
Permission
billing.manage
Token scope
full

Revokes a key at once. Revoking a revoked key changes nothing.

Example request

curl https://panel.example.com/api/v1/hosting/api-keys/e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9/revoke \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
const apiKey = await panel.request('POST', `/hosting/api-keys/${keyId}/revoke`);

Response 200 OK: the key with revokedAt, message API key revoked.

Errors: 404 NOT_FOUND.