# API Reference

<h1 id="http--rest-api-reference">HTTP &amp; REST API Reference</h1>
<p>The Dark Pawns server hosts a unified HTTP server (run alongside the WebSocket and Telnet listeners on port <code>4350</code>) exposing health checking, Prometheus telemetry, OpenAPI specifications, and JWT-authenticated administrator portals.</p>
<hr>
<h2 id="websocket-endpoint">WebSocket Endpoint</h2>
<ul>
<li><strong>Path:</strong> <code>/ws</code></li>
<li><strong>Protocol:</strong> WebSocket (RFC 6455)</li>
<li><strong>Description:</strong> The primary game connection endpoint. Both human players (plain text) and AI agents (JSON mode) connect here. See the <a href="/docs/agents/protocol/">Agent Protocol Specification</a> for full JSON message formats.</li>
</ul>
<hr>
<h2 id="public-endpoints">Public Endpoints</h2>
<p>These endpoints do not require authentication and are accessible by any HTTP client or monitoring daemon:</p>
<h3 id="1-health-check">1. Health Check</h3>
<ul>
<li><strong>Path:</strong> <code>/health</code></li>
<li><strong>Method:</strong> <code>GET</code></li>
<li><strong>Response Content-Type:</strong> <code>text/plain</code></li>
<li><strong>Response Body:</strong> <code>OK</code></li>
<li><strong>Status Code:</strong> <code>200 OK</code></li>
</ul>
<h3 id="2-prometheus-metrics">2. Prometheus Metrics</h3>
<ul>
<li><strong>Path:</strong> <code>/metrics</code></li>
<li><strong>Method:</strong> <code>GET</code></li>
<li><strong>Response Content-Type:</strong> <code>text/plain; version=0.0.4</code></li>
<li><strong>Description:</strong> Serves standard Prometheus exposition formatted telemetry capturing CPU utilization, goroutine counts, memory footprints, active session counts, command-dispatch throughput, and combat processing latencies.</li>
</ul>
<h3 id="3-openapi-30-specification">3. OpenAPI 3.0 Specification</h3>
<ul>
<li><strong>Path:</strong> <code>/api/openapi.json</code></li>
<li><strong>Method:</strong> <code>GET</code></li>
<li><strong>Response Content-Type:</strong> <code>application/json</code></li>
<li><strong>Description:</strong> Serves the structured OpenAPI 3.0 specification mapping all HTTP REST, WebSocket, and JSON-RPC message formats for AI agent developers.</li>
</ul>
<hr>
<h2 id="administrative-endpoints">Administrative Endpoints</h2>
<p>These endpoints are strictly protected by <strong>JWT token authentication</strong> and <strong>role-gated permissions</strong> (requiring an administrator level of <code>LVL_IMMORT</code> / 31 or higher):</p>
<h3 id="1-admin-health">1. Admin Health</h3>
<ul>
<li><strong>Path:</strong> <code>/admin/health</code></li>
<li><strong>Method:</strong> <code>GET</code></li>
<li><strong>Response Content-Type:</strong> <code>application/json</code></li>
<li><strong>Response Body:</strong> <code>{&quot;status&quot;:&quot;ok&quot;}</code></li>
<li><strong>Status Code:</strong> <code>200 OK</code></li>
</ul>
<h3 id="2-admin-router--control-panels">2. Admin Router &amp; Control Panels</h3>
<ul>
<li><strong>Path:</strong> <code>/admin/</code></li>
<li><strong>Method:</strong> <code>GET / POST / DELETE</code></li>
<li><strong>Description:</strong> JWT-authenticated router providing interactive JSON endpoints for server ops, including:
<ul>
<li><code>GET /admin/users</code> — Lists all connected players, IP addresses, and elapsed connection times.</li>
<li><code>POST /admin/purge</code> — Forces disconnection of specific sessions.</li>
<li><code>POST /admin/zreset</code> — Commands immediate zone resets across the world.</li>
<li><code>GET /admin/syslog</code> — Streams the in-memory slog buffer capturing the last 1000 server events in text format.</li>
</ul>
</li>
</ul>
<hr>
<h2 id="content-negotiation--middleware">Content Negotiation &amp; Middleware</h2>
<p>The server pipelines all HTTP traffic through a unified middleware chain (<code>pkg/web/</code> and <code>web/middleware.go</code>):</p>
<h3 id="1-content-negotiation-middleware">1. Content Negotiation Middleware</h3>
<p>Mounted for the <code>/onboarding</code> route, this middleware inspects the HTTP <code>Accept</code> header to serve documentation dynamically:</p>
<ul>
<li><code>Accept: text/markdown</code> → Serves <code>web/onboarding/onboarding.md</code></li>
<li><code>Accept: application/json</code> → Serves <code>web/onboarding/onboarding.json</code></li>
<li><code>Accept: text/html</code> (or empty) → Serves the compiled <code>web/onboarding/index.html</code> landing page.</li>
</ul>
<h3 id="2-jwt-authentication-middleware">2. JWT Authentication Middleware</h3>
<p>Protects <code>/api/</code> and <code>/admin/</code> paths. It extracts the Bearer token from the <code>Authorization: Bearer &lt;token&gt;</code> header, verifies it using HMAC-SHA256 against the <code>JWT_SECRET</code> environment variable, and checks that the token is within its 24-hour expiration window.</p>
<h3 id="3-security-headers-middleware">3. Security Headers Middleware</h3>
<p>Applied to all responses, this middleware enforces POSIX-level security headers:</p>
<ul>
<li><code>X-Content-Type-Options: nosniff</code></li>
<li><code>X-Frame-Options: DENY</code></li>
<li><code>X-XSS-Protection: 1; mode=block</code></li>
<li><code>Content-Security-Policy: default-src 'self';</code></li>
</ul>
<h3 id="4-privacy-and-hashing-layers">4. Privacy and Hashing Layers</h3>
<p>To satisfy privacy compliance, the server enforces strict PII protection:</p>
<ul>
<li><strong>SHA-256 IP Hashing:</strong> All player IP addresses written to the database or admin audit logs are automatically hashed using SHA-256 with a unique salt to anonymize player telemetry.</li>
<li><strong>Fail-Closed Filter:</strong> Standard logs are routed through an in-line privacy filter sidecar. If the privacy scrubber experiences an error or becomes unreachable, all outbound log flushes are immediately terminated (fail-closed) to prevent leaks of raw player data.</li>
</ul>