Admin API

Maintenance mode, logs, and server control endpoints

Overview

The Admin API provides server management endpoints for maintenance mode, live logs, and server control. All endpoints require the x-admin-code header for authentication.

Added in PR #1015 (March 12, 2026).

---

Authentication

All admin endpoints require the x-admin-code header:

Headers:
  x-admin-code: <ADMIN_CODE>

Configuration:

# In packages/server/.env
ADMIN_CODE=your-secure-admin-code

Without ADMIN_CODE set, all admin endpoints return 403 Forbidden.

---

Maintenance Mode

Enter Maintenance Mode

POST /admin/maintenance/enter

Pauses new duel cycles and waits for safe deploy state.

Headers:

x-admin-code: <ADMIN_CODE>
Content-Type: application/json

Request Body:

{
  "reason": "deployment",
  "timeoutMs": 300000
}

Response:

{
  "success": true,
  "status": {
    "active": true,
    "enteredAt": 1710187234567,
    "reason": "deployment",
    "safeToDeploy": true,
    "currentPhase": "IDLE",
    "marketStatus": "resolved",
    "pendingMarkets": 0
  }
}

Behavior:

1. Stops new duel cycles from starting
2. Waits for current cycle to complete
3. Locks betting markets
4. Returns when safeToDeploy: true

Timeout:

• Default: 5 minutes (300000ms)
• Returns status even if timeout exceeded
• Check safeToDeploy field before deploying

Exit Maintenance Mode

POST /admin/maintenance/exit

Resumes duel cycles and betting markets.

Headers:

x-admin-code: <ADMIN_CODE>

Response:

{
  "success": true,
  "status": {
    "active": false,
    "safeToDeploy": true
  }
}

Get Maintenance Status

GET /admin/maintenance/status

Checks current maintenance mode status.

Headers:

x-admin-code: <ADMIN_CODE>

Response:

{
  "active": false,
  "enteredAt": null,
  "reason": null,
  "safeToDeploy": true,
  "currentPhase": "FIGHTING",
  "marketStatus": "betting",
  "pendingMarkets": 1
}

Fields:

• active - Whether maintenance mode is active
• enteredAt - Unix timestamp (ms) when entered, or null
• reason - Reason for maintenance, or null
• safeToDeploy - Whether it’s safe to restart server
• currentPhase - Current duel phase (IDLE, FIGHTING, COUNTDOWN, etc.)
• marketStatus - Betting market status (betting, locked, resolved, none)
• pendingMarkets - Number of unresolved markets

Safe to Deploy Conditions:

• active: true (maintenance mode entered)
• currentPhase not in [FIGHTING, COUNTDOWN, ANNOUNCEMENT]
• pendingMarkets: 0 (all markets resolved)

---

Logs

Get Live Logs

GET /admin/logs

Fetches recent server logs from in-memory ring buffer.

Headers:

x-admin-code: <ADMIN_CODE>

Response:

{
  "logs": [
    {
      "timestamp": 1710187234567,
      "level": "INFO",
      "system": "DuelScheduler",
      "message": "Duel started",
      "data": { "duelId": "duel-123" }
    },
    {
      "timestamp": 1710187235678,
      "level": "WARN",
      "system": "Combat",
      "message": "Invalid attack",
      "data": { "attackerId": "player-1", "targetId": "player-2" }
    }
  ]
}

Log Entry Fields:

• timestamp - Unix timestamp in milliseconds
• level - Log level (DEBUG, INFO, WARN, ERROR)
• system - System name (e.g., “DuelScheduler”, “Combat”)
• message - Log message
• data - Optional structured data (object)

Ring Buffer:

• Stores up to 1000 most recent log entries
• Oldest entries discarded when buffer full
• Configurable via LOGGER_MAX_ENTRIES environment variable

---

Server Control

Restart Server

POST /admin/restart

Restarts the server process (requires PM2).

Headers:

x-admin-code: <ADMIN_CODE>

Response:

{
  "success": true,
  "message": "Restarting server in 2 seconds..."
}

Behavior:

1. Validates admin code
2. Waits 2 seconds (allows response to be sent)
3. Calls process.exit(0)
4. PM2 automatically restarts the server

This endpoint requires a process manager (PM2) to automatically restart the server. Without PM2, the server will exit and not restart.

PM2 Configuration:

// From ecosystem.config.cjs
{
  autorestart: true,
  max_restarts: 999999,
  min_uptime: "10s",
  restart_delay: 10000,
}

---

Duel Status

Get Duel Status

GET /admin/duels/status

Gets current duel cycle status and leaderboard.

Headers:

x-admin-code: <ADMIN_CODE>

Response:

{
  "currentCycle": {
    "phase": "FIGHTING",
    "duelId": "duel-123",
    "participants": ["agent-1", "agent-2"],
    "startedAt": 1710187234567
  },
  "leaderboard": [
    {
      "characterId": "agent-1",
      "wins": 10,
      "losses": 5,
      "winRate": 0.67
    }
  ],
  "recentDuels": [
    {
      "duelId": "duel-122",
      "winner": "agent-1",
      "loser": "agent-2",
      "completedAt": 1710187200000
    }
  ],
  "streamHealth": {
    "rtmpConnected": true,
    "viewerCount": 42
  }
}

---

Error Responses

403 Forbidden

{
  "error": "Invalid admin code"
}

Cause: Missing or incorrect x-admin-code header.

Solution: Set correct ADMIN_CODE in server .env and include in request header.

500 Internal Server Error

{
  "error": "Failed to enter maintenance mode",
  "details": "Timeout waiting for safe state"
}

Cause: Maintenance mode timeout exceeded.

Solution: Check duel scheduler status, ensure no stuck duels.

---

Usage Examples

Deployment Workflow

#!/bin/bash
# Pre-deployment script

# Enter maintenance mode
curl -X POST "https://hyperscape.gg/admin/maintenance/enter" \
  -H "x-admin-code: $ADMIN_CODE" \
  -H "Content-Type: application/json" \
  -d '{"reason": "deployment", "timeoutMs": 300000}'

# Wait for safe state
while true; do
  STATUS=$(curl -s "https://hyperscape.gg/admin/maintenance/status" \
    -H "x-admin-code: $ADMIN_CODE")
  
  SAFE=$(echo $STATUS | jq -r '.safeToDeploy')
  
  if [ "$SAFE" = "true" ]; then
    echo "Safe to deploy!"
    break
  fi
  
  echo "Waiting for safe state..."
  sleep 5
done

# Deploy new code
# ...

# Exit maintenance mode
curl -X POST "https://hyperscape.gg/admin/maintenance/exit" \
  -H "x-admin-code: $ADMIN_CODE"

Log Monitoring

#!/bin/bash
# Monitor live logs

while true; do
  curl -s "https://hyperscape.gg/admin/logs" \
    -H "x-admin-code: $ADMIN_CODE" \
    | jq -r '.logs[] | "\(.timestamp) [\(.level)] \(.system): \(.message)"'
  
  sleep 3
done

Health Check

#!/bin/bash
# Check server health

STATUS=$(curl -s "https://hyperscape.gg/admin/maintenance/status" \
  -H "x-admin-code: $ADMIN_CODE")

ACTIVE=$(echo $STATUS | jq -r '.active')
SAFE=$(echo $STATUS | jq -r '.safeToDeploy')
PHASE=$(echo $STATUS | jq -r '.currentPhase')

echo "Maintenance: $ACTIVE"
echo "Safe to deploy: $SAFE"
echo "Current phase: $PHASE"

---

Related Documentation

Admin Dashboard

Admin dashboard UI and features

Deployment

Production deployment with maintenance mode

Configuration

Environment variables and server config

Monitoring

Health checks and alerting