Veil API Reference

Overview

The Veil API is a REST API that returns JSON. All requests go to the base URL below. There are two authentication contexts: session-based (for dashboard routes accessed by logged-in users) and Bearer token (for agent-to-server and bot integrations).

Base URL

https://veilmgmt.com/api

Format

JSON (application/json)

Auth

Session cookie or Bearer token

Version

v1 — stable

⚠️ Rate limiting

API routes are protected by session auth. External integrations must use a valid Bearer token. Repeated failed auth attempts will result in a temporary block.

Authentication

Session auth (dashboard)

All /api/servers/[id]/* routes require a valid user session cookie set at login. These are used by the dashboard UI — if you're building a custom integration you'll need Bearer token auth instead.

Bearer token auth (agent & bot)

Agent routes (/api/agent/*) and bot routes (/api/bot/*) use a static Bearer token in the Authorization header.

Authorization:Bearer your_token_here

The Veil Agent uses the server's agentAuthToken from the database. The Discord bot uses the static BOT_API_KEY environment variable.

Authorization checks

All server-scoped routes run isAuthorizedToServer(userId, serverId) — your user session must have permission for the specific server you're accessing. Server owners and team members with the appropriate role pass this check.

Servers

GET /api/servers

Returns all servers the authenticated user has access to.

Response

[
  {
    "id": "sv_vmsk_...",
    "name": "Main RP Server",
    "status": "online",
    "players": 127,
    "maxPlayer": 150,
    "cpu": 45.2,
    "ram": 8.4,
    "ramMax": 16.0,
    "uptime": 1209600000,
    "resources": 42,
    "alerts": 2,
    "lastPing": "2025-01-20T16:44:30Z"
  }
]

GET /api/servers/[id]

Returns full detail for a single server including settings.

Response

{
  "id": "sv_vmsk_...",
  "name": "Main RP Server",
  "ownerId": "user_...",
  "serverKeyToken": "vmsk_...",
  "endpoint": "68.229.5.212:30120",
  "agentSocketPort": "8080",
  "lastPing": "2025-01-20T16:44:30Z",
  "createdAt": "2025-01-15T10:00:00Z",
  "settings": { ... }
}

GET /api/servers/[id]/ping

Pings the server and returns the response time in milliseconds.

Response

{ "ping": 42 }

GET /api/servers/[id]/metrics

Returns recent system metrics (CPU, RAM, player count, uptime) as a time series.

Response

[
  {
    "id": "metric_...",
    "cpuUsage": 45.2,
    "ramUsage": 8.4,
    "ramTotal": 16.0,
    "playerCount": 127,
    "maxPlayers": 150,
    "uptime": 1209600,
    "timestamp": "2025-01-20T16:44:30Z"
  }
]

GET /api/servers/get-port

Returns the agent endpoint and socket port for a server. Used internally by the dashboard to establish WebSocket connections.

Parameters

serverId query The server ID

Response

{ "endpoint": "68.229.5.212", "port": "8080" }

Players

GET /api/servers/[id]/players

Returns all currently online players on the server, fetched live from the FiveM server via the agent.

Response

[
  {
    "license": "license:abc123...",
    "name": "PlayerName",
    "ip": "1.2.3.4",
    "discord": "discord:123456789",
    "steam": "steam:110000...",
    "fivem": "fivem:123456",
    "job": "police",
    "gang": "none",
    "coords": { "x": 123.4, "y": -567.8, "z": 28.1 }
  }
]

GET /api/servers/[id]/players/[license]

Returns a single player's full profile including their history. Works for both online and offline players.

Response

{
  "player": {
    "license": "license:abc123...",
    "name": "PlayerName",
    "ip": "1.2.3.4",
    "discord": "discord:...",
    "online": true,
    "job": "police",
    "coords": { "x": 123.4, "y": -567.8, "z": 28.1 }
  },
  "history": [
    {
      "id": "hist_...",
      "history_type": "ban" | "warning" | "kick" | "note",
      "reason": "Cheating",
      "createdAt": "2025-01-15T10:00:00Z",
      "createdBy": "admin_license"
    }
  ]
}

POST /api/servers/[id]/players/[license]/kick

Kicks the player from the server with a reason.

Request Body

{ "reason": "AFK too long" }

Response

{ "ok": true }

POST /api/servers/[id]/players/[license]/warn

Issues a formal warning to the player and records it in their history.

Request Body

{ "reason": "Disrespectful behavior" }

Response

{ "ok": true }

POST /api/servers/[id]/players/check-ban

Checks if a player is banned by any of their identifiers. Used by veil-monitor on player connect.

Request Body

{
  "license": "license:abc123...",
  "ip": "1.2.3.4",
  "discord": "discord:123456789",
  "steam": "steam:110000...",
  "fivem": "fivem:123456",
  "license2": "license2:def456..."
}

Response

// Banned
{ "banned": true, "reason": "Cheating detected" }

// Not banned
{ "banned": false }

Bans

GET /api/servers/[id]/bans

Returns all bans for the server.

Response

[
  {
    "id": "ban_...",
    "serverId": "sv_vmsk_...",
    "license": "license:abc123...",
    "name": "PlayerName",
    "ip": "1.2.3.4",
    "reason": "Cheating detected",
    "bannedAt": "2025-01-15T10:00:00Z",
    "bannedBy": "license:adminlicense..."
  }
]

POST /api/servers/[id]/bans

Bans a player. Syncs the ban to the FiveM server so they are kicked immediately if online.

Request Body

{
  "license": "license:abc123...",
  "name": "PlayerName",
  "ip": "1.2.3.4",
  "reason": "Cheating",
  "discord": "discord:...",
  "steam": "steam:...",
  "fivem": "fivem:..."
}

Response

{ "ok": true, "ban": { "id": "ban_...", ... } }

DELETE /api/servers/[id]/bans/[banId]

Removes a ban by its ID.

Response

{ "ok": true }

Performance

GET /api/servers/[id]/performance/resources

Returns per-resource performance data with historical trends, aggregated stats, thread breakdowns, and active alerts.

Parameters

range query "1h" | "6h" | "24h" | "7d" — default "24h"

Response

{
  "resources": [
    {
      "name": "es_extended",
      "avgDurationMs": 1.24,
      "minDurationMs": 0.8,
      "maxDurationMs": 4.2,
      "tickCount": 3600,
      "frameSharePct": 0.012,
      "threads": [
        { "name": "server", "avgMs": 0.9 },
        { "name": "client", "avgMs": 0.34 }
      ],
      "history": [
        { "timestamp": "2025-01-20T10:00:00Z", "avgMs": 1.1 }
      ]
    }
  ],
  "alerts": [
    {
      "id": "alert_...",
      "resourceName": "my_script",
      "durationMs": 8.4,
      "thresholdMs": 2.0,
      "acknowledged": false,
      "timestamp": "2025-01-20T16:30:00Z"
    }
  ],
  "topIssues": ["my_script", "heavy_resource"]
}

POST /api/servers/[id]/performance/resources/[alertId]/acknowledge

Marks a resource performance alert as acknowledged.

Response

{ "ok": true }

Analytics

GET /api/servers/[id]/analytics/daily

Returns daily analytics aggregates for a server.

Response

{
  "date": "2025-01-20",
  "peakPlayers": 127,
  "peakTime": "2025-01-20T20:30:00Z",
  "avgPlayers": 89.5,
  "minPlayers": 12,
  "uniquePlayers": 342,
  "newPlayers": 23,
  "returningPlayers": 319,
  "totalSessions": 456,
  "avgSessionDuration": 3600,
  "bounceRate": 0.15,
  "growthRate": 0.125,
  "retention1Day": 0.65,
  "retention7Day": 0.42,
  "uptime": 86400
}

GET /api/servers/[id]/analytics/weekly

Returns weekly growth and analytics summary.

Response

{
  "weekStart": "2025-01-13",
  "weekEnd": "2025-01-20",
  "newPlayers": 156,
  "totalPlayers": 2134,
  "avgDailyPlayers": 305.0,
  "growthPercentage": 12.5,
  "previousWeekRetention": 0.68,
  "monthlyActiveUsers": 4523,
  "avgPlayTime": 4200,
  "totalPlayTime": 8964000,
  "weekPeakPlayers": 142,
  "weekPeakTime": "2025-01-18T21:00:00Z"
}

Economy

GET /api/servers/[id]/economy

Returns economy overview — top balances, totals, and recent transaction activity. Requires veil-monitor with a supported framework (ESX, QBCore, QBox, or Custom).

Response

{
  "players": [
    {
      "license": "license:abc123...",
      "name": "RichPlayer",
      "cash": 50000,
      "bank": 1200000,
      "total": 1250000
    }
  ],
  "totals": {
    "cash": 4500000,
    "bank": 98000000
  },
  "lastUpdated": "2025-01-20T16:44:30Z"
}

Logs & Activity

GET /api/servers/[id]/logs

Returns server logs — structured events recorded by veil-monitor and the dashboard.

Response

[
  {
    "id": "log_...",
    "serverId": "sv_vmsk_...",
    "title": "Resource Started",
    "message": "veil-monitor started successfully",
    "type": "info" | "warn" | "error" | "success",
    "timestamp": "2025-01-20T10:30:00Z"
  }
]

GET /api/servers/[id]/activity

Returns the server activity feed — anti-cheat detections, restarts, shutdowns, and other notable events.

Response

[
  {
    "id": "act_...",
    "serverId": "sv_vmsk_...",
    "activity": {
      "type": "cheater_detected",
      "message": "Player banned automatically",
      "timestamp": "2025-01-20T16:30:00Z",
      "severity": "high"
    }
  }
]

DELETE /api/servers/[id]/activity

Removes a single activity entry from the feed.

Request Body

{ "activityId": "act_..." }

Response

{ "ok": true }

POST /api/servers/[id]/activity/clear

Clears all activity entries from the feed for this server.

Response

{ "ok": true }

Agent Routes

⚙️ Internal use

These routes are called by the Veil Agent binary, not by external developers. They require Authorization: Bearer {agentAuthToken} where the token is the server's agentAuthToken from the database.

POST /api/agent/server-data

Submits a system metrics snapshot (CPU, RAM, players, uptime). Called by the agent on a regular interval.

Request Body

{
  "cpu_usage": 45.2,
  "ram_usage": 8.4,
  "ram_total": 16.0,
  "player_count": 127,
  "uptime": 1209600,
  "timestamp": "2025-01-20T16:44:30Z"
}

Response

{ "ok": true }

POST /api/agent/performance/resources

Submits a performance profile — a full breakdown of all resource tick times from a profiling window. The API applies threshold filtering and stores alerts.

Request Body

{
  "metrics": {
    "resources": [
      {
        "name": "es_extended",
        "avg_ms": 1.24,
        "min_ms": 0.8,
        "max_ms": 4.2,
        "tick_count": 3600,
        "frame_share_pct": 0.012,
        "threads": [
          { "name": "server", "avg_ms": 0.9 }
        ]
      }
    ],
    "summary": {
      "profile_duration_ms": 5000,
      "frame_count": 3600
    }
  }
}

Response

{ "ok": true, "stored": 42, "alerts": 1 }

GET /api/agent/settings

Returns the server settings that the agent uses — alert thresholds, analytics config, profiling interval, etc.

Response

{
  "alerts": {
    "enabled": true,
    "thresholds": {
      "cpu": { "enabled": true, "warning": 70, "critical": 90 },
      "ram": { "enabled": true, "warning": 75, "critical": 95 },
      "resource": { "enabled": true, "duration": 2000, "interval": 5 }
    }
  },
  "analytics": {
    "enabled": true,
    "collectInterval": 5
  }
}

System

GET /api/system/health

Returns the health status of the API and database. No auth required. Used by the footer status indicator.

Response

{
  "apiStatus": "healthy" | "degraded" | "down",
  "databaseStatus": "healthy" | "degraded" | "down"
}

Error Handling

All errors return a JSON object with a single error key:

{ "error": "Error message here" }

400

Bad Request

Missing or invalid request body / query parameters.

401

Unauthorized

Missing or invalid session / Bearer token.

403

Forbidden

Your account does not have permission to access this server.

404

Not Found

The requested resource does not exist.

500

Internal Server Error

Something went wrong on our end. If this persists, contact support.