Plugins
API reference for installing, approving, updating and removing plugins, their event deliveries, their pages in the panel, and plugin directories.
Plugins add features and connect outside services without changing the panel. A plugin has a manifest that says what it is, which permissions it needs, which events it wants and whether it adds a page to the panel. An owner or admin reviews and approves it; the plugin then gets its own vpp_ token and a signing secret, works through the REST API with the approved scopes only, and receives events signed like webhooks.
Everything here needs plugins.manage (owners and admins), except listing and opening plugin pages. Installing, updating a plugin's manifest, replacing its credentials and adding a directory mint credentials, so they are done in the panel by a signed-in person: an API token gets 403 FORBIDDEN. How to write a plugin (the manifest, calling the API, verifying events and page links) is in Plugins.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/plugins | List plugins |
| GET | /api/v1/plugins/pages | List plugin pages |
| POST | /api/v1/plugins/preview | Preview a manifest |
| POST | /api/v1/plugins | Install a plugin |
| GET | /api/v1/plugins/:id | Get a plugin |
| PUT | /api/v1/plugins/:id/manifest | Update a plugin |
| POST | /api/v1/plugins/:id/enable | Turn a plugin on |
| POST | /api/v1/plugins/:id/disable | Turn a plugin off |
| POST | /api/v1/plugins/:id/rotate-credentials | Replace the credentials |
| DELETE | /api/v1/plugins/:id | Remove a plugin |
| GET | /api/v1/plugins/:id/deliveries | List event deliveries |
| POST | /api/v1/plugins/:id/test | Send a test event |
| POST | /api/v1/plugins/:id/deliveries/:deliveryId/redeliver | Redeliver an event |
| GET | /api/v1/plugins/:id/launch | Open a plugin page |
| GET | /api/v1/plugins/directory | List directory plugins |
| POST | /api/v1/plugins/directory/refresh | Read every directory again |
| POST | /api/v1/plugins/directory/sources | Add a directory |
| POST | /api/v1/plugins/directory/sources/:directoryId/refresh | Read a directory again |
| DELETE | /api/v1/plugins/directory/sources/:directoryId | Remove a directory |
Plugin tokens
A plugin calls the API with its own token, sent like an API token:
Authorization: Bearer vpp_…The token acts with the plugin's approved scopes only: read, logs, deploy, manage, servers or customers, never full, so a plugin can never manage users, roles, panel settings or other plugins. GET /api/v1/auth/me answers with plugin instead of user. A turned-off plugin's token is refused with 401 UNAUTHENTICATED. See API tokens for what each scope allows.
The plugin object
| Field | Type | Description |
|---|---|---|
id, slug | string | The installation, and the manifest's id. |
name, version, description, author, homepage | string | From the manifest. |
manifestUrl | string or null | Where the manifest was read from; null when it was pasted. |
scopes, permissionCount | The approved scopes, and how many permissions they cover. | |
events | string[] | The events it receives. |
webhook | object or null | { url, lastDelivery } when it receives events. |
page | object or null | { title, url, icon } when it adds a page. |
enabled | boolean | Turned off plugins get no events and their token is refused. |
tokenPrefix | string | The start of its token; the token itself is never returned again. |
installedBy, approvedAt | Who installed it and when its permissions were approved. | |
lastUsedAt, lastUsedIp, useCount | Its token's use. | |
update | object or null | { version, directory } when a directory lists a newer version. |
List plugins
/api/v1/pluginsReturns installed plugins by name, never their credentials, and max (50).
Example request
curl https://panel.example.com/api/v1/plugins \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items, max } = await panel.plugins.list();Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "2a3b4c5d-…",
"slug": "status-board",
"name": "Status Board",
"version": "1.1.0",
"manifestUrl": "https://status.example.com/manifest.json",
"scopes": ["read"],
"permissionCount": 16,
"events": ["server.offline", "server.online"],
"webhook": { "url": "https://status.example.com/events", "lastDelivery": { "at": "2026-11-10T09:55:01.000Z", "status": "succeeded" } },
"page": { "title": "Status Board", "url": "https://status.example.com/", "icon": "activity" },
"enabled": true,
"tokenPrefix": "vpp_3kQ9xT2a",
"update": null
}
],
"max": 50
},
"message": "OK",
"requestId": "…"
}List plugin pages
/api/v1/plugins/pagesAny signed-in staff member: the pages of turned-on plugins they may open, for the sidebar. A page is shown only to people who hold every permission the plugin's scopes cover, so nobody gains anything by going through a plugin's page. API tokens get an empty list; hosting customers cannot reach /plugins (403 FORBIDDEN).
Example request
curl https://panel.example.com/api/v1/plugins/pages \
-b "vp_session=…"const { items } = await fetch('/api/v1/plugins/pages', { credentials: 'include' })
.then((r) => r.json())
.then((r) => r.data);Response 200 OK: { items: [{ id, slug, name, title, icon }] }.
Preview a manifest
/api/v1/plugins/previewChecks a manifest and explains it before installing: which scopes and permissions it asks for, which of those your account does not have (notGranted), the events it wants and any its permissions do not cover, and warnings. installed is the plugin already installed with the same id, if any; listedIn lists the directory entries for the same id, with extraPermissions and extraEvents the manifest asks for beyond them.
Request body: give one of the two.
| Field | Type | Required | Description |
|---|---|---|---|
manifestUrl | string | One of | A full http or https URL the panel fetches (up to 64 KB). |
manifest | object | One of | The manifest itself. |
Example request
curl https://panel.example.com/api/v1/plugins/preview \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "manifestUrl": "https://status.example.com/manifest.json" }'const { manifest, review, installed } = await panel.plugins.preview({
manifestUrl: 'https://status.example.com/manifest.json',
});Response 200 OK: { manifest, manifestUrl, review: { scopes, permissions, notGranted, events, eventsNotCovered, warnings }, installed, listedIn }.
Errors
| Status | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | The manifest is invalid; fields are reported under manifest.. Both or neither of manifestUrl and manifest. |
| 422 | MANIFEST_UNREACHABLE | The manifest URL could not be fetched, is too large or resolves to an address plugins may not reach. |
Install a plugin
/api/v1/pluginsInstalls a plugin and approves its permissions. approvedPermissions must repeat exactly the manifest's permissions: you approve the whole request, not a part. The response holds the plugin's token and signing secret, the only time they are shown; give them to the plugin.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
manifestUrl or manifest | Yes | As in Preview a manifest. | |
approvedPermissions | string[] | Yes | The manifest's permissions, exactly. |
Example request
curl https://panel.example.com/api/v1/plugins \
-X POST \
-b "vp_session=…" \
-H "X-CSRF-Token: $CSRF_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "manifestUrl": "https://status.example.com/manifest.json", "approvedPermissions": ["read"] }'// In the panel, signed in: API tokens cannot install plugins.
const res = await fetch('/api/v1/plugins', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': csrfToken },
body: JSON.stringify({ manifestUrl: 'https://status.example.com/manifest.json', approvedPermissions: ['read'] }),
});
const { plugin, credentials } = (await res.json()).data;Response 201 Created
{
"success": true,
"data": {
"plugin": { "id": "2a3b4c5d-…", "slug": "status-board", "name": "Status Board", "enabled": true, "tokenPrefix": "vpp_3kQ9xT2a" },
"credentials": { "token": "vpp_…", "signingSecret": "whsec_…" }
},
"message": "Plugin installed. Copy its token and signing secret now: they are not shown again.",
"requestId": "…"
}Errors
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | Called with an API token, or approving permissions your own account does not have. |
| 409 | PLUGIN_INSTALLED | A plugin with the same id is installed: update it instead. |
| 409 | TOO_MANY_PLUGINS | 50 plugins are installed. |
| 422 | VALIDATION_ERROR, MANIFEST_UNREACHABLE | As in Preview a manifest, or approvedPermissions does not match, or events its permissions do not cover. |
Get a plugin
/api/v1/plugins/:idReturns { plugin, manifest, review }.
Example request
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { plugin, manifest, review } = await panel.plugins.get(pluginId);Response 200 OK. 404 NOT_FOUND when there is none.
Update a plugin
/api/v1/plugins/:id/manifestUpdates the plugin from a new manifest, with its permissions approved again. With neither manifestUrl nor manifest, the panel fetches the plugin's manifest URL again (a plugin installed from a pasted manifest needs the new one pasted). The manifest's id must stay the same.
Request body: manifestUrl or manifest (optional), and approvedPermissions (required), as in Install a plugin.
Response 200 OK: { plugin }, message Plugin updated.
Errors: those of Install a plugin, and 422 VALIDATION_ERROR when the manifest is for another plugin.
Turn a plugin on or off
/api/v1/plugins/:id/enable/api/v1/plugins/:id/disableA turned-off plugin receives no events, its page is hidden and its token is refused.
Example request
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/disable \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.plugins.disable(pluginId);
await panel.plugins.enable(pluginId);Response 200 OK: { plugin }, message Plugin turned on or Plugin turned off.
Replace the credentials
/api/v1/plugins/:id/rotate-credentialsMakes a new token and signing secret. The old ones stop working at once.
Response 200 OK: { plugin, credentials: { token, signingSecret } }, message New token and signing secret made. The old ones no longer work.
Errors: 403 FORBIDDEN with an API token.
Remove a plugin
/api/v1/plugins/:idRemoves the plugin and its token, with its events webhook and that webhook's deliveries.
Example request
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.plugins.remove(pluginId);Response 200 OK: data is null, message Plugin removed.
List event deliveries
/api/v1/plugins/:id/deliveriesThe events sent to the plugin, newest first, in the same shape as webhook deliveries. A plugin's events webhook does not appear on the Webhooks page, and changing it there answers 409 PLUGIN_WEBHOOK.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | No | pending, succeeded or failed. |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
Example request
curl "https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/deliveries?status=failed" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.plugins.deliveries(pluginId, { status: 'failed' });Response 200 OK: { items, pagination }.
Send a test event
/api/v1/plugins/:id/testSends a test event to the plugin now and returns { delivery } with the outcome.
Example request
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/test \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { delivery } = await panel.plugins.test(pluginId);Response 200 OK: { delivery }.
Errors: 409 PLUGIN_DISABLED for a turned-off plugin, 409 NO_EVENTS when its manifest has no webhookUrl or no events.
Redeliver an event
/api/v1/plugins/:id/deliveries/:deliveryId/redeliverSends a finished delivery again and returns { delivery }.
Example request
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/deliveries/9a0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d/redeliver \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.request('POST', `/plugins/${pluginId}/deliveries/${deliveryId}/redeliver`);Response 200 OK: { delivery }.
Errors: 404 NOT_FOUND, 409 PLUGIN_DISABLED, 409 DELIVERY_PENDING while it is still being tried.
Open a plugin page
/api/v1/plugins/:id/launchAny signed-in staff member who may see the plugin's page: the page's URL with vp_ parameters naming the viewer and a signature (vp_sig, HMAC-SHA256 with the plugin's signing secret), good for 5 minutes. The panel opens it in a frame. See Plugins for verifying it.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
theme | string | No | light (default) or dark, passed on as vp_theme. |
Response 200 OK: { plugin: { id, slug, name, title, icon }, url, origin }.
Errors: 404 NOT_FOUND when the plugin is off, has no page, or you may not see it.
List directory plugins
/api/v1/plugins/directoryPlugin directories are lists of plugins published as JSON by whoever maintains them. The panel reads each directory when it is added and again every 12 hours, keeping the last good copy. This returns { directories, items, categories, max }: each item is a directory entry with its directory, installed ({ id, version, enabled } or null) and updateAvailable. Up to 10 directories; none is built in.
Example request
curl https://panel.example.com/api/v1/plugins/directory \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { directories, items } = await panel.plugins.directory();Response 200 OK.
Read every directory again
/api/v1/plugins/directory/refreshReads every directory again and answers like List directory plugins.
Example request
curl https://panel.example.com/api/v1/plugins/directory/refresh \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.plugins.refreshDirectories();Response 200 OK.
Add a directory
/api/v1/plugins/directory/sourcesReads a directory and adds it. Nothing is saved when it cannot be read. The file may be up to 1 MB and lists up to 500 plugins; the format is in Plugins.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | A full http or https URL. |
Response 201 Created: { directory }, message Plugin directory added.
Errors
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | Called with an API token. |
| 409 | DIRECTORY_ADDED | It is already added. |
| 409 | TOO_MANY_DIRECTORIES | 10 directories are added. |
| 422 | DIRECTORY_UNREACHABLE, VALIDATION_ERROR | It could not be fetched, or is not a valid directory (fields under directory.). |
Read a directory again
/api/v1/plugins/directory/sources/:directoryId/refreshReads one directory again. When it cannot be read, the answer is 422 with the reason, and the last good copy stays.
Example request
curl https://panel.example.com/api/v1/plugins/directory/sources/8b9c0d1e-2f3a-4b4c-8d5e-6f7a8b9c0d1e/refresh \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.plugins.refreshDirectory(directoryId);Response 200 OK: { directory }, message Plugin directory read again.
Remove a directory
/api/v1/plugins/directory/sources/:directoryIdRemoves the directory. Plugins installed from it stay installed.
Example request
curl https://panel.example.com/api/v1/plugins/directory/sources/8b9c0d1e-2f3a-4b4c-8d5e-6f7a8b9c0d1e \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.plugins.removeDirectory(directoryId);Response 200 OK: data is null, message Plugin directory removed.
Billing API
API reference for billing systems such as WHMCS and Blesta - plans, creating, suspending, upgrading and removing hosting accounts, passwords and single sign-on links.
Agent protocol
How the VaultPanel agent talks to the panel - enrollment, Ed25519-signed requests, heartbeats, the job long poll, signed job envelopes and result reporting.