Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AZhur771/pivpn-web/llms.txt

Use this file to discover all available pages before exploring further.

PiVPN Web includes a JSON REST API built on Express.js. Every response body is JSON, all write operations are guarded by session-cookie authentication, and the server runs on port 3001 by default. The same API endpoints power the built-in Vue.js dashboard — anything the UI can do, you can do programmatically.

​
Base URL

http://<host>:3001/api
If you place PiVPN Web behind a TLS-terminating reverse proxy, use https:// instead. The PORT environment variable overrides the default 3001.

​
Content-Type

All requests that include a body must set the Content-Type header to application/json. Requests without a body (e.g. GET and DELETE requests that carry no payload) do not need to set this header. 
Content-Type: application/json

​
Authentication

All endpoints except POST /api/session require a valid session cookie. Unauthenticated requests receive a 401 response. See the Authentication page for the full login flow, session lifetime details, and role-based access rules.

​
Endpoint Summary

MethodPathAuth RequiredAdmin RequiredDescription
GET/api/sessionNoNoGet current session info
POST/api/sessionNoNoLog in and create a session
DELETE/api/sessionYesNoLog out and destroy the session
GET/api/wireguard/clientYesNoList all WireGuard clients
GET/api/wireguard/client-statusYesNoList clients with live connection status
GET/api/wireguard/client/:nameYesNoGet a specific client by name
POST/api/wireguard/client/:nameYesYesCreate a new client
DELETE/api/wireguard/client/:nameYesYesDelete a client
POST/api/wireguard/client/:name/enableYesYesEnable a client
POST/api/wireguard/client/:name/disableYesYesDisable a client
GET/api/wireguard/client/:name/qrcode.svgYesNoGet client QR code as an SVG image
GET/api/wireguard/client/:name/configurationYesNoDownload the client .conf file

​
Response Format

​
Successful responses

Endpoints that return data respond with HTTP 200 and a JSON body. Endpoints that perform mutations but have no meaningful return value — such as POST /api/session and DELETE /api/session — respond with 204 No Content and an empty body. The /api/wireguard/client-status endpoint returns enriched objects that include live WireGuard connection data (endpoint IP, transfer bytes, latest handshake time) alongside the base client fields: 
[
  {
    "name": "alice",
    "publicKey": "abc123...",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "iface": "wg0",
    "enabled": true,
    "banned": false,
    "endpoint": "203.0.113.42:51820",
    "allowedIps": "10.6.0.2/32",
    "latestHandshake": "2024-06-01T08:12:00.000Z",
    "transferRx": 1048576,
    "transferTx": 524288,
    "persistentKeepalive": "off"
  }
]

​
Error responses

All errors return a JSON object with an error field containing a human-readable message and a stack field with the server-side stack trace: 
{
  "error": "Error message here",
  "stack": "Error: Error message here\n    at ..."
}
StatusMeaning
401Not authenticated — no valid session cookie is present
403Authenticated but not an admin — the operation requires elevated privileges
500Server-side error — includes validation failures (missing fields, invalid client name, wrong credentials) and unexpected server errors
Client names are validated against the pattern [a-z0-9 .,_-] (case-insensitive). Names containing other characters return a 500 error with the message Invalid Client Name: <name>.
The API is consumed directly by the PiVPN Web frontend — a Vue.js single-page application served from the same Express process. Every action available in the dashboard (listing clients, toggling enabled state, downloading configs, viewing QR codes) maps 1:1 to one of the endpoints listed above. This means you can script or automate any dashboard action using the same API.

Build docs developers (and LLMs) love

Get started for freeTalk to us