API: Complete Endpoint Reference

This is the full reference for the WireGuard REST API: every endpoint, the status and error codes, and the bandwidth and DNS-over-TLS endpoints. To get started with keys and authentication, see WireGuard REST API: Getting Started.

All endpoints

Base URL: https://portal.premiervpn.net/api/wg

• {assignment_id}: the assignment_id from GET /servers (not the server's id).
• {user_id}: the user's id from the users list or the create response.
• {port_forward_id}: the id of a port forward.

Examples for users and status are in API: Managing Servers and Users. Port forwarding is in API: Port Forwarding.

Headers

Authorization: Bearer wg_your_api_key_here
Accept: application/json
Content-Type: application/json

Send Content-Type on POST and PUT requests with a JSON body. Always send Accept: application/json. Without it, validation errors may come back as a redirect instead of JSON.

Create keys in the portal under WireGuard › Manage Server › API Keys & Documentation. You can have up to 5 active keys, and each key works for all your servers. If you want separate keys for different apps or environments, such as production and testing, create one for each.

Rate limit

60 requests per minute per key. Over that, you get 429 with the code rate_limited.

Status codes

Error codes

Most errors return {"error": "...", "code": "..."}.

Validation errors (422) use a different shape: a message plus an errors object listing each problem field. Bandwidth and DNS endpoints return only an error message, without a code.

Bandwidth limits

Set a download and upload speed limit for one user. Limits apply straight away and are reapplied when the server restarts.

Set a limit

PUT /users/{user_id}/bandwidth

curl -s -X PUT \
  -H "Authorization: Bearer wg_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"down_mbps": 10, "up_mbps": 5}' \
  https://portal.premiervpn.net/api/wg/users/42/bandwidth

Send both a download and an upload value, in Mbps or Kbps. Each must be between 100 Kbps and 1,000,000 Kbps (1 Gbps). Anything outside that returns 422.

Response:

{
  "success": true,
  "client_name": "phone",
  "bandwidth_down_kbps": 10000,
  "bandwidth_up_kbps": 5000,
  "bandwidth_down_mbps": 10.0,
  "bandwidth_up_mbps": 5.0
}

Check a limit

GET /users/{user_id}/bandwidth

{
  "user_id": 42,
  "client_name": "phone",
  "client_ip": "10.66.66.4",
  "bandwidth_down_kbps": 10000,
  "bandwidth_up_kbps": 5000,
  "bandwidth_down_mbps": 10.0,
  "bandwidth_up_mbps": 5.0,
  "limited": true
}

A user with no limit has "limited": false and null values.

Remove a limit

DELETE /users/{user_id}/bandwidth

{
  "success": true,
  "message": "Bandwidth limit removed."
}

Remove a user's limit before you delete the user. Otherwise the limit can stay on the server and apply to the next user given the same internal IP.

DNS-over-TLS

These endpoints set up DNS-over-TLS (using Stubby) for your server's own DNS lookups. Stubby is installed on the server the first time you use them.

Your devices keep using the DNS servers in their config files (the DNS line). Changing these settings doesn't change the DNS your devices use. To change that, download a new config with the Custom Config Builder in the portal.

Set resolvers

PUT /servers/{assignment_id}/dns

curl -s -X PUT \
  -H "Authorization: Bearer wg_YOUR_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"resolvers": [
    {"address": "1.1.1.1", "name": "cloudflare-dns.com"},
    {"address": "9.9.9.9", "name": "dns.quad9.net"}
  ]}' \
  https://portal.premiervpn.net/api/wg/servers/5/dns

Response:

{
  "success": true,
  "message": "DoT configured with 2 resolver(s).",
  "resolvers": [
    {"address": "1.1.1.1", "name": "cloudflare-dns.com"},
    {"address": "9.9.9.9", "name": "dns.quad9.net"}
  ]
}

Check DNS settings

GET /servers/{assignment_id}/dns

With DNS-over-TLS on:

{
  "mode": "dot",
  "stubby_active": true,
  "resolvers": [
    {"address": "1.1.1.1", "port": 853, "name": "cloudflare-dns.com", "type": "dot"}
  ]
}

With it off, mode is plain and each resolver has "type": "plain".

Go back to plain DNS

DELETE /servers/{assignment_id}/dns

{
  "success": true,
  "message": "DoT removed. Reverted to plain DNS."
}

Common DNS-over-TLS resolvers

Example: full workflow

# 1. List servers to get the assignment_id
curl -s -H "Authorization: Bearer wg_YOUR_KEY" -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/servers

# 2. Create a user on assignment 5 (note the returned user id)
curl -s -X POST -H "Authorization: Bearer wg_YOUR_KEY" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "web-server"}' \
  https://portal.premiervpn.net/api/wg/servers/5/users

# 3. Get the user's config and save it as a .conf file
curl -s -H "Authorization: Bearer wg_YOUR_KEY" -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/users/USER_ID

# 4. Forward HTTPS to the new user
curl -s -X POST -H "Authorization: Bearer wg_YOUR_KEY" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"external_port": 443, "internal_port": 443, "protocol": "tcp"}' \
  https://portal.premiervpn.net/api/wg/users/USER_ID/port-forwards

# 5. Check the device is online
curl -s -H "Authorization: Bearer wg_YOUR_KEY" -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/servers/5/status

# 6. Clean up: remove the port forward, then the user
curl -s -X DELETE -H "Authorization: Bearer wg_YOUR_KEY" -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/port-forwards/PORT_FORWARD_ID
curl -s -X DELETE -H "Authorization: Bearer wg_YOUR_KEY" -H "Accept: application/json" \
  https://portal.premiervpn.net/api/wg/users/USER_ID