Admin Operations API

Live — Deployed 2026-02-19

All endpoints are production-ready on the admin API at port 3002.

Overview

The Admin Operations API eliminates the need for SSH access to manage the VitaraVox platform. Every operational task — deploying code, pushing Vapi prompts, checking system health, reading logs, managing PM2 — is available as a secured REST endpoint.

All operations endpoints require vitara_admin role authentication.

Authorization: Bearer <admin-jwt-token>
Base URL: https://api-dev.vitaravox.ca/api/admin/ops

---

Endpoints

GET /api/admin/ops/status — System Status

Returns full platform health: PM2 processes, disk usage, memory, OS info.

Response:

{
  "success": true,
  "data": {
    "timestamp": "2026-02-19T18:18:37.871Z",
    "hostname": "instance-20251030-1238",
    "platform": "Linux 6.14.0-1017-oracle (arm64)",
    "uptime": {
      "system": 1138625,
      "process": 134
    },
    "memory": {
      "totalMB": 23978,
      "usedMB": 2843,
      "freeMB": 21135,
      "usedPercent": 12,
      "processRSS_MB": 120,
      "processHeap_MB": 21
    },
    "disk": {
      "total": "45G",
      "used": "23G",
      "available": "22G",
      "usedPercent": "53%"
    },
    "pm2": [
      {
        "name": "vitara-admin-api",
        "pid": 4167916,
        "status": "online",
        "cpu": 0.1,
        "memory": 75702272,
        "restarts": 6674,
        "uptime": 136
      }
    ],
    "node": "v18.19.1"
  }
}

---

POST /api/admin/ops/deploy — Deploy Code

Runs TypeScript build + PM2 graceful restart. Returns step-by-step results.

Self-Terminating

This endpoint triggers a PM2 restart, which means the current process will exit after returning the response. The response includes build output so you can verify the build succeeded before the restart takes effect.

Response:

{
  "success": true,
  "data": {
    "output": "Deploy completed",
    "durationMs": 12450,
    "steps": {
      "build": {
        "success": true,
        "output": "",
        "durationMs": 11200
      },
      "restart": {
        "success": true,
        "output": "[PM2] vitara-admin-api restarted",
        "durationMs": 1250
      }
    }
  }
}

---

POST /api/admin/ops/vapi-push — Push Vapi GitOps

Executes npm run push:dev in the vapi-gitops/ directory to sync all assistant prompts, tools, and squad configuration to the Vapi API.

Response:

{
  "success": true,
  "data": {
    "output": "Pushed 9 assistants, 14 tools, 1 squad to Vapi",
    "durationMs": 8500
  }
}

---

POST /api/admin/ops/pm2/:action — PM2 Management

Controls the PM2 process. Valid actions: restart, reload, stop.

Action	Behavior
restart	Kill + restart (brief downtime)
reload	Graceful reload (zero-downtime if cluster mode)
stop	Stop the process (manual restart required)

Example: POST /api/admin/ops/pm2/restart

---

POST /api/admin/ops/soap-warmup — SOAP Client Warmup

Pre-fetches WSDL definitions for all clinics configured with oscar-soap EMR type. This eliminates the cold-start penalty (2-4s) on the first voice call after a restart.

Response:

{
  "success": true,
  "data": {
    "clinicsWarmed": 3,
    "errors": []
  }
}

Post-Deploy Automation

Call this endpoint after every deploy to warm SOAP clients immediately.

---

GET /api/admin/ops/logs?lines=100 — PM2 Logs

Tails recent PM2 logs (combined stdout + stderr). lines parameter controls how many lines to return (10-500, default 100).

Query Parameters:

Parameter	Type	Default	Description
lines	number	100	Number of log lines (10-500)

---

GET /api/admin/ops/backups — Backup Inventory

Lists the contents of the backups/ directory with timestamps and sizes.

Response:

{
  "success": true,
  "data": {
    "backups": [
      {
        "name": "vapi-20260210",
        "sizeBytes": 0,
        "modifiedAt": "2026-02-18T14:52:06.080Z"
      }
    ]
  }
}

---

POST /api/admin/ops/deploy-docs — Deploy Documentation

Builds the MkDocs documentation site and deploys it to the nginx-served directory. Equivalent to:

source /tmp/mkdocs-env/bin/activate && \
  mkdocs build --site-dir /tmp/vitdocs-site && \
  cp -r /tmp/vitdocs-site/* /home/ubuntu/vitaravox-docs/site/ && \
  sudo nginx -s reload

---

Authentication

All ops endpoints use the same JWT authentication as the admin dashboard:

# Login to get a token
curl -X POST https://api-dev.vitaravox.ca/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@vitaravox.ca", "password": "..."}'

# Use the accessToken from the response
curl -H "Authorization: Bearer <token>" \
  https://api-dev.vitaravox.ca/api/admin/ops/status

Only users with role: vitara_admin can access these endpoints. Clinic managers will receive a 403 Forbidden response.

---

Audit Trail

All mutating operations (deploy, vapi-push, pm2 actions, soap-warmup, deploy-docs) are logged with:

• User ID from JWT
• Timestamp
• Operation name
• Success/failure

Logs are visible in PM2 output and queryable via GET /api/admin/audit.

---

Existing Admin Endpoints (Reference)

These were already available before the ops API:

Endpoint	Purpose
GET /api/admin/health	Basic system health
GET /api/admin/health/detailed	DB + OSCAR + Vapi health checks
GET/POST /api/admin/debug	Toggle VITARA_DEBUG mode (4h auto-expiry)
GET /api/admin/clinics	List all clinics
POST /api/admin/clinics	Create new clinic + manager account
PUT /api/admin/clinics/:id/activate	Activate a clinic
GET /api/admin/audit	Query audit logs
POST /api/admin/data-retention/run	Trigger data retention job

---

Typical Workflows

After Code Changes

1. POST /api/admin/ops/deploy          → Build + restart
2. GET  /api/admin/ops/status          → Verify process is online
3. POST /api/admin/ops/soap-warmup     → Warm SOAP clients
4. GET  /api/admin/health/detailed     → Verify all services healthy

After Prompt Changes

1. POST /api/admin/ops/vapi-push       → Sync prompts to Vapi
2. GET  /api/admin/ops/logs?lines=20   → Check for push errors

Troubleshooting

1. GET  /api/admin/ops/status          → Check memory, disk, PM2 restarts
2. GET  /api/admin/ops/logs?lines=200  → Read recent logs
3. GET/POST /api/admin/debug           → Enable verbose logging if needed
4. GET  /api/admin/health/detailed     → Check DB/OSCAR/Vapi connectivity