System API

API endpoints for system management.

Monitor and manage the Supascale system.

Endpoints Overview

Method	Endpoint	Description
GET	/system/resources	Get system metrics
POST	/system/resources	Kill process
GET	/system/resources/history	Metrics history
GET	/system/logs	Get PM2 logs
DELETE	/system/logs	Flush logs
GET	/system/activity	Activity log
GET	/system/updates	Check for updates
POST	/system/updates	Force update check
POST	/system/updates/download	Download update
POST	/system/updates/apply	Apply update
GET	/license/status	License status
POST	/license/validate	Validate license

Get System Resources

GET /api/v1/system/resources

Permission: system:read

Query Parameters:

Parameter	Description
`processes`	Include process list
`info`	Include system info
`sortBy`	Sort processes (cpu, memory)
`limit`	Process list limit

Response:

{
  "cpu": {
    "usage": 25.5,
    "cores": 4,
    "model": "Intel Core i7-9700",
    "loadAverage": [1.2, 0.8, 0.6]
  },
  "memory": {
    "total": 8589934592,
    "used": 4294967296,
    "free": 4294967296,
    "usagePercent": 50
  },
  "disk": {
    "total": 107374182400,
    "used": 53687091200,
    "free": 53687091200,
    "usagePercent": 50
  },
  "network": {
    "bytesIn": 1073741824,
    "bytesOut": 536870912
  }
}

With processes=true:

{
  "cpu": { ... },
  "memory": { ... },
  "processes": [
    {
      "pid": 1234,
      "name": "node",
      "cpu": 5.2,
      "memory": 256000000,
      "memoryPercent": 3.0
    }
  ]
}

Kill Process

POST /api/v1/system/resources

Permission: system:write

Request:

{
  "action": "kill",
  "pid": 1234,
  "signal": "SIGTERM"
}

Signals:

SIGTERM - Graceful shutdown
SIGKILL - Force kill

Response:

{
  "success": true,
  "message": "Process 1234 terminated"
}

Get Metrics History

GET /api/v1/system/resources/history

Permission: system:read

Query Parameters:

Parameter	Description
`hours`	Hours of history (default: 24)
`interval`	Data point interval

Response:

{
  "history": [
    {
      "timestamp": "2026-01-19T00:00:00Z",
      "cpu": 25.5,
      "memory": 50.2,
      "disk": 48.1
    }
  ]
}

Get PM2 Logs

GET /api/v1/system/logs

Permission: system:read

Query Parameters:

Parameter	Description
`lines`	Number of lines (default: 100)
`type`	Log type (out, err, all)
`process`	Filter by process

Response:

{
  "logs": [
    {
      "timestamp": "2026-01-19T12:00:00Z",
      "type": "out",
      "process": "supascale-web",
      "message": "Server started on port 3000"
    }
  ],
  "processes": ["supascale-web"]
}

Flush Logs

DELETE /api/v1/system/logs

Permission: system:write

Query Parameters:

Parameter	Description
`process`	Specific process (optional)

Response:

{
  "success": true,
  "message": "Logs flushed"
}

Get Activity Log

GET /api/v1/system/activity

Permission: system:read

Response:

{
  "activities": [
    {
      "id": "act-123",
      "type": "project",
      "action": "created",
      "target": "my-project",
      "user": "admin",
      "timestamp": "2026-01-19T12:00:00Z",
      "details": {}
    }
  ]
}

Check for Updates

GET /api/v1/system/updates

Permission: system:read

Query Parameters:

Parameter	Description
`force`	Bypass cache

Response (update available):

{
  "currentVersion": "1.0.0",
  "latestVersion": "1.1.0",
  "updateAvailable": true,
  "releaseDate": "2026-01-15T00:00:00Z",
  "releaseNotes": "## What's New\n- Feature X",
  "downloadSize": 52428800
}

Response (up to date):

{
  "currentVersion": "1.1.0",
  "latestVersion": "1.1.0",
  "updateAvailable": false
}

Force Update Check

POST /api/v1/system/updates

Permission: system:read

Same response as GET.

Download Update

POST /api/v1/system/updates/download

Permission: system:write

Response:

{
  "success": true,
  "version": "1.1.0",
  "downloadPath": "/tmp/supascale-update-1.1.0.tar.gz",
  "checksum": "sha256:abc123..."
}

Apply Update

POST /api/v1/system/updates/apply

Permission: system:write

Returns Server-Sent Events:

event: progress
data: {"step": "downloading", "progress": 50}

event: progress
data: {"step": "applying", "progress": 90}

event: complete
data: {"success": true, "version": "1.1.0"}

License Status

GET /api/v1/license/status

Response:

{
  "valid": true,
  "email": "user@example.com",
  "updatesExpireAt": "2027-01-19T00:00:00Z",
  "updatesActive": true
}

Validate License

POST /api/v1/license/validate

Request:

{
  "email": "user@example.com",
  "licenseKey": "XXXX-XXXX-XXXX-XXXX"
}

Response:

{
  "valid": true,
  "message": "License validated",
  "updatesExpireAt": "2027-01-19T00:00:00Z"
}

Error Responses

Updates Expired

{
  "success": false,
  "error": "Updates expired. Please renew your license."
}

Status: 403

Invalid License

{
  "success": false,
  "error": "Invalid license key"
}

Status: 401