API Reference

Plugins

API reference for installing, approving, updating and removing plugins, their event deliveries, their pages in the panel, and plugin directories.

Last updated

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.

MethodPathDescription
GET/api/v1/pluginsList plugins
GET/api/v1/plugins/pagesList plugin pages
POST/api/v1/plugins/previewPreview a manifest
POST/api/v1/pluginsInstall a plugin
GET/api/v1/plugins/:idGet a plugin
PUT/api/v1/plugins/:id/manifestUpdate a plugin
POST/api/v1/plugins/:id/enableTurn a plugin on
POST/api/v1/plugins/:id/disableTurn a plugin off
POST/api/v1/plugins/:id/rotate-credentialsReplace the credentials
DELETE/api/v1/plugins/:idRemove a plugin
GET/api/v1/plugins/:id/deliveriesList event deliveries
POST/api/v1/plugins/:id/testSend a test event
POST/api/v1/plugins/:id/deliveries/:deliveryId/redeliverRedeliver an event
GET/api/v1/plugins/:id/launchOpen a plugin page
GET/api/v1/plugins/directoryList directory plugins
POST/api/v1/plugins/directory/refreshRead every directory again
POST/api/v1/plugins/directory/sourcesAdd a directory
POST/api/v1/plugins/directory/sources/:directoryId/refreshRead a directory again
DELETE/api/v1/plugins/directory/sources/:directoryIdRemove 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

FieldTypeDescription
id, slugstringThe installation, and the manifest's id.
name, version, description, author, homepagestringFrom the manifest.
manifestUrlstring or nullWhere the manifest was read from; null when it was pasted.
scopes, permissionCountThe approved scopes, and how many permissions they cover.
eventsstring[]The events it receives.
webhookobject or null{ url, lastDelivery } when it receives events.
pageobject or null{ title, url, icon } when it adds a page.
enabledbooleanTurned off plugins get no events and their token is refused.
tokenPrefixstringThe start of its token; the token itself is never returned again.
installedBy, approvedAtWho installed it and when its permissions were approved.
lastUsedAt, lastUsedIp, useCountIts token's use.
updateobject or null{ version, directory } when a directory lists a newer version.

List plugins

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

Returns 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

GET/api/v1/plugins/pages
Auth
Session cookie only (API tokens are refused)

Any 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

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

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

FieldTypeRequiredDescription
manifestUrlstringOne ofA full http or https URL the panel fetches (up to 64 KB).
manifestobjectOne ofThe 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

StatusCodeWhen
422VALIDATION_ERRORThe manifest is invalid; fields are reported under manifest.. Both or neither of manifestUrl and manifest.
422MANIFEST_UNREACHABLEThe manifest URL could not be fetched, is too large or resolves to an address plugins may not reach.

Install a plugin

POST/api/v1/plugins
Auth
Session cookie only (API tokens are refused)
Permission
plugins.manage

Installs 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

FieldTypeRequiredDescription
manifestUrl or manifestYesAs in Preview a manifest.
approvedPermissionsstring[]YesThe 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

StatusCodeWhen
403FORBIDDENCalled with an API token, or approving permissions your own account does not have.
409PLUGIN_INSTALLEDA plugin with the same id is installed: update it instead.
409TOO_MANY_PLUGINS50 plugins are installed.
422VALIDATION_ERROR, MANIFEST_UNREACHABLEAs in Preview a manifest, or approvedPermissions does not match, or events its permissions do not cover.

Get a plugin

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

Returns { 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

PUT/api/v1/plugins/:id/manifest
Auth
Session cookie only (API tokens are refused)
Permission
plugins.manage

Updates 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

POST/api/v1/plugins/:id/enable
Auth
Session cookie (+ CSRF token) or API token
Permission
plugins.manage
Token scope
full
POST/api/v1/plugins/:id/disable
Auth
Session cookie (+ CSRF token) or API token
Permission
plugins.manage
Token scope
full

A 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

POST/api/v1/plugins/:id/rotate-credentials
Auth
Session cookie only (API tokens are refused)
Permission
plugins.manage

Makes 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

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

Removes 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

GET/api/v1/plugins/:id/deliveries
Auth
Session cookie (+ CSRF token) or API token
Permission
plugins.manage
Token scope
full

The 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

NameTypeRequiredDescription
statusstringNopending, succeeded or failed.
page, pageSizeintegerNoPage 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

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

Sends 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

POST/api/v1/plugins/:id/deliveries/:deliveryId/redeliver
Auth
Session cookie (+ CSRF token) or API token
Permission
plugins.manage
Token scope
full

Sends 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

GET/api/v1/plugins/:id/launch
Auth
Session cookie only (API tokens are refused)

Any 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

NameTypeRequiredDescription
themestringNolight (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

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

Plugin 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

POST/api/v1/plugins/directory/refresh
Auth
Session cookie (+ CSRF token) or API token
Permission
plugins.manage
Token scope
full

Reads 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

POST/api/v1/plugins/directory/sources
Auth
Session cookie only (API tokens are refused)
Permission
plugins.manage

Reads 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

FieldTypeRequiredDescription
urlstringYesA full http or https URL.

Response 201 Created: { directory }, message Plugin directory added.

Errors

StatusCodeWhen
403FORBIDDENCalled with an API token.
409DIRECTORY_ADDEDIt is already added.
409TOO_MANY_DIRECTORIES10 directories are added.
422DIRECTORY_UNREACHABLE, VALIDATION_ERRORIt could not be fetched, or is not a valid directory (fields under directory.).

Read a directory again

POST/api/v1/plugins/directory/sources/:directoryId/refresh
Auth
Session cookie (+ CSRF token) or API token
Permission
plugins.manage
Token scope
full

Reads 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

DELETE/api/v1/plugins/directory/sources/:directoryId
Auth
Session cookie (+ CSRF token) or API token
Permission
plugins.manage
Token scope
full

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