Proxmox Traffic Monitor

Proxmox Traffic Monitor API

Complete REST API reference for managing Proxmox VM traffic monitoring, alerts, and automation.

Base URL

https://monitor.trynxt.com/api

Authentication

All endpoints require uuid and auth_token in the request body or query parameters.

Content-Type

application/json

GET REQUESTS

GET/api/alerts/list

List Alerts

Retrieves all alerts for a UUID or specific VM

Query Parameters

Parameter	Type	Required	Description
`uuid`	string	Required	Authentication UUID
`auth_token`	string	Required	Authentication token
`vmid`	integer		Specific VM ID (optional)

Example Request

GET /api/alerts/list?uuid=abc-123&auth_token=token-456&vmid=101

Response

{
  "alerts": [
    {
      "id": 123,
      "uuid": "abc123-def456-ghi789",
      "vmid": 101,
      "alert_name": "High Traffic Protection",
      "trigger_type": "traffic_percent",
      "trigger_operator": ">",
      "trigger_value": "80",
      "enabled": true,
      "cooldown_minutes": 60,
      "trigger_limit": 5,
      "last_triggered": "2026-01-01T12:30:00.000Z",
      "trigger_count": 2,
      "actions": [
        {
          "id": 456,
          "action_type": "throttle_vm",
          "config": {
            "throttle_limit": "1",
            "throttle_unit": "mbit",
            "auto_restore_on_reset": true
          },
          "execution_order": 0
        }
      ]
    }
  ]
}

POST REQUESTS

POST/api/monitor/create-authentication

Create Authentication

Creates a new Proxmox server authentication for monitoring

Request Body

Parameter	Type	Required	Description
`host`	string	Required	Proxmox host URL with port (e.g., https://proxmox.example.com:8006)
`token`	string	Required	Proxmox API token in format: PVEAPIToken=user@realm!tokenid=uuid
`node`	string	Required	Proxmox node name (e.g., pve, pve01)
`auth_key`	string	Required	Your monitor authentication key from your account

Proxmox Token Format

The token must be in the following format:

PVEAPIToken=user@pam!tokenid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example: PVEAPIToken=root@pam!monitoring=12345678-1234-1234-1234-123456789abc

Request

{
  "host": "https://proxmox.example.com:8006",
  "token": "PVEAPIToken=user@pve!tokenid=xxxxxxxx",
  "node": "pve",
  "auth_key": "your-monitor-auth-key"
}

Response

{
  "status": "authentication_created",
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token"
}

POST/api/monitor/delete-authentication

Delete Authentication

Deletes an authentication and all associated monitors

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "auth_key": "your-monitor-auth-key"
}

Response

{
  "status": "authentication_deleted"
}

POST/api/monitor/create-monitor

Create Monitor

Adds a VM to be monitored under an existing authentication

Request Body

Parameter	Type	Required	Description
`uuid`	string	Required	Authentication UUID
`auth_token`	string	Required	Authentication token
`vmid`	integer	Required	VM ID to monitor
`days`	integer		Monitoring period in days (default: 30). Traffic resets automatically after this period.

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "vmid": 101,
  "days": 30
}

Response

{
  "status": "monitor_created",
  "vmid": 101,
  "days": 30,
  "expire_at": "2026-01-31T12:00:00.000Z"
}

Response Fields

status - Always "monitor_created"

vmid - VM ID that was added to monitoring

days - Monitoring period in days

expire_at - Expiration date (ISO format). Traffic counters will reset automatically on this date.

POST/api/monitor/delete-monitor

Delete Monitor

Removes a specific VM from monitoring

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "vmid": 101
}

Response

{
  "status": "monitor_deleted"
}

POST/api/monitor/reset-vm

Reset VM Traffic

Resets traffic counters for a VM to zero and sets new expiration date. If VM is throttled, automatically restores original speed.

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "vmid": 101
}

Response

{
  "status": "vm_reset",
  "vmid": 101,
  "new_expire_at": "2026-01-31T12:00:00.000Z",
  "throttle_restored": true
}

Response Fields

status - Always "vm_reset"

vmid - VM ID that was reset

new_expire_at - New expiration date

throttle_restored - true if VM speed was automatically restored, false otherwise

POST/api/monitor/update-monitor

Update Monitoring Period (All VMs)

Updates the monitoring period for ALL VMs under an authentication

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "days": 60
}

Response

{
  "status": "updated",
  "new_days": 60
}

POST/api/monitor/update-single

Update Single Monitor

Updates monitoring settings for a single VM (days and/or expire date)

Request Body

Parameter	Type	Required	Description
`uuid`	string	Required	Authentication UUID
`auth_token`	string	Required	Authentication token
`vmid`	integer	Required	VM ID
`days`	integer		New monitoring period in days (optional)
`expire_at`	string		New expiration date in ISO format: YYYY-MM-DDTHH:mm:ss (optional)

Note

Both days and expire_at are optional. You can update just one or both fields.

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "vmid": 101,
  "days": 30,
  "expire_at": "2026-02-15T12:00:00"
}

Response

{
  "status": "monitor_updated",
  "vmid": 101,
  "days": 30,
  "expire_at": "2026-02-15T12:00:00"
}

POST/api/alerts/create

Create Alert

Creates a new alert with trigger conditions and actions

Request Body

Parameter	Type	Required	Description
`uuid`	string	Required	Authentication UUID
`auth_token`	string	Required	Authentication token
`vmid`	integer	Required	VM ID
`alert_name`	string	Required	Alert name
`trigger_type`	string	Required	See trigger types below
`trigger_operator`	string	Required	See operators below
`trigger_value`	string	Required	Threshold value
`cooldown_minutes`	integer		Cooldown between triggers (default: 60)
`trigger_limit`	integer		Max trigger count (null = unlimited)
`enabled`	boolean		Enable immediately (default: true)
`actions`	array	Required	Array of action objects - see available action types below

Trigger Types

traffic_percentPercentage of expected traffic (0-100%). Useful for monitoring relative traffic usage based on the monitoring period.

traffic_absoluteAbsolute traffic in GB. Useful for hard limits regardless of monitoring period.

Operators

>Greater than

>=Greater or equal

<Less than

<=Less or equal

Available Action Types

throttle_vmThrottle Internet Speed

throttle_limit (string, required) - Speed limit value

throttle_unit (string) - Unit: "mbit" (default)

auto_restore_on_reset (boolean) - Auto-restore on trigger reset (default: true)

interface (string) - Network interface (default: "net0")

discordDiscord Notification

webhook_url (string, required) - Discord webhook URL

message (string, required) - Message text (supports placeholders: {vmid}, {traffic}, {uuid}, {alert_name})

webhookCall Webhook

url (string, required) - Webhook URL

method (string) - HTTP method: "POST" or "GET" (default: "POST")

headers (object) - Custom HTTP headers

body (object) - Request body (supports placeholders)

stop_vmStop VM

config (object) - Empty object: {}

restart_vmRestart VM

config (object) - Empty object: {}

reset_trafficReset Traffic Counter

config (object) - Empty object: {}

Request Example (Complete)

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "vmid": 101,
  "alert_name": "High Traffic Protection",
  "trigger_type": "traffic_percent",
  "trigger_operator": ">",
  "trigger_value": "80",
  "cooldown_minutes": 60,
  "trigger_limit": 5,
  "enabled": true,
  "actions": [
    {
      "action_type": "throttle_vm",
      "config": {
        "throttle_limit": "1",
        "throttle_unit": "mbit",
        "auto_restore_on_reset": true,
        "interface": "net0"
      }
    },
    {
      "action_type": "discord",
      "config": {
        "webhook_url": "https://discord.com/api/webhooks/...",
        "message": "Alert! VM {vmid} traffic: {traffic}GB"
      }
    }
  ]
}

Response

{
  "status": "alert_created",
  "alert_id": 123
}

POST/api/alerts/reset-trigger

Reset Alert Trigger

Resets the trigger counter and last triggered timestamp. If alert has throttle_vm action with auto_restore enabled, automatically restores VM speed.

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "alert_id": 123
}

Response

{
  "status": "trigger_reset",
  "alert_id": 123,
  "throttle_restored": true
}

Response Fields

status - Always "trigger_reset"

alert_id - Alert ID that was reset

throttle_restored - true if VM speed was automatically restored (when alert has throttle_vm action with auto_restore_on_reset: true), false otherwise

PUT REQUESTS

PUT/api/alerts/update

Update Alert

Updates an existing alert including trigger conditions and actions

Request Body

Parameter	Type	Required	Description
`uuid`	string	Required	Authentication UUID
`auth_token`	string	Required	Authentication token
`alert_id`	integer	Required	Alert ID to update
`alert_name`	string	Required	Alert name
`trigger_type`	string	Required	Trigger type: 'traffic_percent' or 'traffic_absolute'
`trigger_operator`	string	Required	Operator: '>', '>=', '<', '<='
`trigger_value`	string	Required	Threshold value
`cooldown_minutes`	integer	Required	Cooldown between triggers
`trigger_limit`	integer		Max trigger count (null = unlimited)
`enabled`	boolean	Required	Enable/disable alert
`actions`	array	Required	Array of action objects - see Create Alert for available action types

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "alert_id": 123,
  "alert_name": "Updated Alert Name",
  "trigger_type": "traffic_percent",
  "trigger_operator": ">",
  "trigger_value": "90",
  "cooldown_minutes": 120,
  "trigger_limit": 10,
  "enabled": true,
  "actions": [
    {
      "action_type": "discord",
      "config": {
        "webhook_url": "https://discord.com/api/webhooks/...",
        "message": "Updated message"
      }
    }
  ]
}

Response

{
  "status": "alert_updated",
  "alert_id": 123
}

PATCH REQUESTS

PATCH/api/alerts/manage

Toggle Alert (Enable/Disable)

Enable or disable an alert without deleting it

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "alert_id": 123,
  "enabled": false
}

Response

{
  "status": "alert_updated",
  "enabled": false
}

DELETE REQUESTS

DELETE/api/alerts/manage

Delete Alert

Deletes an alert

Request

{
  "uuid": "abc123-def456-ghi789",
  "auth_token": "generated-auth-token",
  "alert_id": 123
}

Response

{
  "status": "alert_deleted"
}

ALERT ACTION TYPES

Throttle VM

throttle_vm

Limits VM bandwidth to specified rate

{
  "action_type": "throttle_vm",
  "config": {
    "throttle_limit": "1",
    "throttle_unit": "mbit",
    "auto_restore_on_reset": true,
    "interface": "net0"
  }
}Configuration Options
Parameter Type Required Description
throttle_limit string Required Speed limit value
throttle_unit string Unit: 'mbit' (default)
auto_restore_on_reset boolean Auto-restore on trigger reset (default: true)
interface string Network interface (default: 'net0')

Parameter	Type	Required	Description
`throttle_limit`	string	Required	Speed limit value
`throttle_unit`	string		Unit: 'mbit' (default)
`auto_restore_on_reset`	boolean		Auto-restore on trigger reset (default: true)
`interface`	string		Network interface (default: 'net0')

Discord Notification

discord

Sends notification to Discord webhook

{
  "action_type": "discord",
  "config": {
    "webhook_url": "https://discord.com/api/webhooks/...",
    "message": "Alert! VM {vmid} traffic: {traffic}GB"
  }
}Configuration Options
Parameter Type Required Description
webhook_url string Required Discord webhook URL
message string Required Message text (supports placeholders)

Parameter	Type	Required	Description
`webhook_url`	string	Required	Discord webhook URL
`message`	string	Required	Message text (supports placeholders)

Webhook

webhook

Calls HTTP webhook with custom payload

{
  "action_type": "webhook",
  "config": {
    "url": "https://api.example.com/alert",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer token"
    },
    "body": {
      "vmid": "{vmid}",
      "traffic": "{traffic}"
    }
  }
}Configuration Options
Parameter Type Required Description
url string Required Webhook URL
method string HTTP method: 'POST' or 'GET' (default: 'POST')
headers object Custom HTTP headers
body object Request body (supports placeholders)

Parameter	Type	Required	Description
`url`	string	Required	Webhook URL
`method`	string		HTTP method: 'POST' or 'GET' (default: 'POST')
`headers`	object		Custom HTTP headers
`body`	object		Request body (supports placeholders)

Stop VM

stop_vm

Stops the VM immediately

{
  "action_type": "stop_vm",
  "config": {}
}

Restart VM

restart_vm

Restarts the VM

{
  "action_type": "restart_vm",
  "config": {}
}

Reset Traffic

reset_traffic

Resets traffic counters to zero

{
  "action_type": "reset_traffic",
  "config": {}
}

Variable Placeholders

Use these placeholders in Discord messages and webhook bodies:

{vmid}VM ID

{traffic}Current traffic in GB

{uuid}Authentication UUID

{alert_name}Alert name

ERROR CODES

200Request successful

400Bad Request - Missing or invalid parameters

401Unauthorized - Invalid authentication

404Not Found - Resource doesn't exist

500Internal Server Error

Important Notes

•All API endpoints expect Content-Type: application/json
•Authentication is done via uuid and auth_token
•Worker runs automatically every 5 seconds and checks alerts
•Traffic data accumulates until expiration date, then resets automatically
•Alert cooldowns prevent spam-triggering (recommended: 60+ minutes)
•Actions execute in order - place critical actions first
•Throttle actions with auto_restore_on_reset: true automatically restore VM speed on trigger reset