# Plugins

URL: https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/developers/plugins).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/plugins` | [List plugins](https://docs.vaultpanel.net/api-reference/plugins#list-plugins) |
| GET | `/api/v1/plugins/pages` | [List plugin pages](https://docs.vaultpanel.net/api-reference/plugins#list-plugin-pages) |
| POST | `/api/v1/plugins/preview` | [Preview a manifest](https://docs.vaultpanel.net/api-reference/plugins#preview-a-manifest) |
| POST | `/api/v1/plugins` | [Install a plugin](https://docs.vaultpanel.net/api-reference/plugins#install-a-plugin) |
| GET | `/api/v1/plugins/:id` | [Get a plugin](https://docs.vaultpanel.net/api-reference/plugins#get-a-plugin) |
| PUT | `/api/v1/plugins/:id/manifest` | [Update a plugin](https://docs.vaultpanel.net/api-reference/plugins#update-a-plugin) |
| POST | `/api/v1/plugins/:id/enable` | [Turn a plugin on](https://docs.vaultpanel.net/api-reference/plugins#turn-a-plugin-on-or-off) |
| POST | `/api/v1/plugins/:id/disable` | [Turn a plugin off](https://docs.vaultpanel.net/api-reference/plugins#turn-a-plugin-on-or-off) |
| POST | `/api/v1/plugins/:id/rotate-credentials` | [Replace the credentials](https://docs.vaultpanel.net/api-reference/plugins#replace-the-credentials) |
| DELETE | `/api/v1/plugins/:id` | [Remove a plugin](https://docs.vaultpanel.net/api-reference/plugins#remove-a-plugin) |
| GET | `/api/v1/plugins/:id/deliveries` | [List event deliveries](https://docs.vaultpanel.net/api-reference/plugins#list-event-deliveries) |
| POST | `/api/v1/plugins/:id/test` | [Send a test event](https://docs.vaultpanel.net/api-reference/plugins#send-a-test-event) |
| POST | `/api/v1/plugins/:id/deliveries/:deliveryId/redeliver` | [Redeliver an event](https://docs.vaultpanel.net/api-reference/plugins#redeliver-an-event) |
| GET | `/api/v1/plugins/:id/launch` | [Open a plugin page](https://docs.vaultpanel.net/api-reference/plugins#open-a-plugin-page) |
| GET | `/api/v1/plugins/directory` | [List directory plugins](https://docs.vaultpanel.net/api-reference/plugins#list-directory-plugins) |
| POST | `/api/v1/plugins/directory/refresh` | [Read every directory again](https://docs.vaultpanel.net/api-reference/plugins#read-every-directory-again) |
| POST | `/api/v1/plugins/directory/sources` | [Add a directory](https://docs.vaultpanel.net/api-reference/plugins#add-a-directory) |
| POST | `/api/v1/plugins/directory/sources/:directoryId/refresh` | [Read a directory again](https://docs.vaultpanel.net/api-reference/plugins#read-a-directory-again) |
| DELETE | `/api/v1/plugins/directory/sources/:directoryId` | [Remove a directory](https://docs.vaultpanel.net/api-reference/plugins#remove-a-directory) |

## Plugin tokens

A plugin calls the API with its own token, sent like an API token:

```http
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](https://docs.vaultpanel.net/api-reference/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

`GET /api/v1/plugins` — Permission: plugins.manage — Token scope: full

Returns installed plugins by name, never their credentials, and `max` (50).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/plugins \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items, max } = await panel.plugins.list();
```

**Response** `200 OK`

```json
{
  "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

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**

```bash
curl https://panel.example.com/api/v1/plugins/pages \
  -b "vp_session=…"
```

**JavaScript**

```js
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` — 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.

| 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**

```bash
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" }'
```

**JavaScript**

```js
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

`POST /api/v1/plugins` — Auth: session — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `manifestUrl` or `manifest` | | Yes | As in [Preview a manifest](https://docs.vaultpanel.net/api-reference/plugins#preview-a-manifest). |
| `approvedPermissions` | string[] | Yes | The manifest's `permissions`, exactly. |

**Example request**

**cURL**

```bash
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"] }'
```

**JavaScript**

```js
// 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`

```json
{
  "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](https://docs.vaultpanel.net/api-reference/plugins#preview-a-manifest), or `approvedPermissions` does not match, or events its permissions do not cover. |

## Get a plugin

`GET /api/v1/plugins/:id` — Permission: plugins.manage — Token scope: full

Returns `{ plugin, manifest, review }`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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 — 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](https://docs.vaultpanel.net/api-reference/plugins#install-a-plugin).

**Response** `200 OK`: `{ plugin }`, message `Plugin updated`.

**Errors**: those of [Install a plugin](https://docs.vaultpanel.net/api-reference/plugins#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` — Permission: plugins.manage — Token scope: full

`POST /api/v1/plugins/:id/disable` — 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**

```bash
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/disable \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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 — 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` — Permission: plugins.manage — Token scope: full

Removes the plugin and its token, with its events webhook and that webhook's deliveries.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.plugins.remove(pluginId);
```

**Response** `200 OK`: `data` is `null`, message `Plugin removed`.

## List event deliveries

`GET /api/v1/plugins/:id/deliveries` — Permission: plugins.manage — Token scope: full

The events sent to the plugin, newest first, in the same shape as [webhook deliveries](https://docs.vaultpanel.net/api-reference/webhooks#list-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**

```bash
curl "https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/deliveries?status=failed" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.plugins.deliveries(pluginId, { status: 'failed' });
```

**Response** `200 OK`: `{ items, pagination }`.

## Send a test event

`POST /api/v1/plugins/:id/test` — Permission: plugins.manage — Token scope: full

Sends a test event to the plugin now and returns `{ delivery }` with the outcome.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/plugins/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d/test \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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` — Permission: plugins.manage — Token scope: full

Sends a finished delivery again and returns `{ delivery }`.

**Example request**

**cURL**

```bash
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"
```

**JavaScript**

```js
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

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](https://docs.vaultpanel.net/developers/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

`GET /api/v1/plugins/directory` — 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**

```bash
curl https://panel.example.com/api/v1/plugins/directory \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { directories, items } = await panel.plugins.directory();
```

**Response** `200 OK`.

## Read every directory again

`POST /api/v1/plugins/directory/refresh` — Permission: plugins.manage — Token scope: full

Reads every directory again and answers like [List directory plugins](https://docs.vaultpanel.net/api-reference/plugins#list-directory-plugins).

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/plugins/directory/refresh \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.plugins.refreshDirectories();
```

**Response** `200 OK`.

## Add a directory

`POST /api/v1/plugins/directory/sources` — Auth: session — 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](https://docs.vaultpanel.net/developers/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

`POST /api/v1/plugins/directory/sources/:directoryId/refresh` — 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**

```bash
curl https://panel.example.com/api/v1/plugins/directory/sources/8b9c0d1e-2f3a-4b4c-8d5e-6f7a8b9c0d1e/refresh \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.plugins.refreshDirectory(directoryId);
```

**Response** `200 OK`: `{ directory }`, message `Plugin directory read again`.

## Remove a directory

`DELETE /api/v1/plugins/directory/sources/:directoryId` — Permission: plugins.manage — Token scope: full

Removes the directory. Plugins installed from it stay installed.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/plugins/directory/sources/8b9c0d1e-2f3a-4b4c-8d5e-6f7a8b9c0d1e \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.plugins.removeDirectory(directoryId);
```

**Response** `200 OK`: `data` is `null`, message `Plugin directory removed`.
