API Endpoints

Health Check


GET /health

Returns API health status.

Response:


{
  "ok": true
}

Ingest Batch


POST /ingest
Authorization: Bearer <SERVER_TOKEN>
Content-Type: application/x-ndjson
Content-Encoding: gzip
X-Server-Id: <server_id>
X-Session-Id: <session_id>

Upload a gzipped NDJSON batch of packets.

Headers:

Header	Required	Description
`Authorization`	Yes	Bearer token (`api.token` from the plugin)
`X-Server-Id`	Yes	Unique server identifier
`X-Session-Id`	Yes	Session identifier
`Content-Type`	Yes	Must be `application/x-ndjson`
`Content-Encoding`	Yes	Must be `gzip`

Response:


{
  "ok": true,
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "s3_key": "events/<server_id>/<YYYY-MM-DD>/<session_id>/<batch_id>.ndjson.gz"
}

The S3 key format includes a date partition for efficient lifecycle management and prefix listing.

List Modules


GET /servers/:server_id/modules
Authorization: Bearer <INGEST_TOKEN>

List all registered modules for a server.

Response:


[
  {
    "id": "uuid",
    "server_id": "my-server",
    "name": "Movement Module",
    "base_url": "https://module.example.com",
    "enabled": true,
    "transform": "movement_events_v1_ndjson_gz",
    "last_healthcheck_ok": true,
    "last_error": null
  }
]

Register Module


POST /servers/:server_id/modules
Authorization: Bearer <INGEST_TOKEN>
Content-Type: application/json

Body:


{
  "name": "Movement Module",
  "base_url": "https://module.example.com",
  "enabled": true,
  "transform": "raw_ndjson_gz"
}

Transforms:

Transform	Description
`raw_ndjson_gz`	Raw packets, gzipped NDJSON
`movement_events_v1_ndjson_gz`	Pre-processed movement events

Submit Findings


POST /callbacks/findings
Authorization: Bearer <MODULE_CALLBACK_TOKEN>
Content-Type: application/json

Module endpoint to report detected violations.

Body:


{
  "server_id": "my-server",
  "session_id": "session-uuid",
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "findings": [
    {
      "player_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "detector_name": "movement_core_speed_blatant",
      "detector_version": "1.0.0",
      "severity": "high",
      "title": "Speed violation detected",
      "description": "Player moving faster than allowed threshold",
      "evidence_json": {
        "expected_speed": 0.2,
        "actual_speed": 0.8
      }
    }
  ]
}

Fields:

Field	Required	Description
`server_id`	Yes	Server identifier
`session_id`	No	Session identifier
`batch_id`	No	Batch that triggered this finding
`findings[].player_uuid`	No	Player UUID
`findings[].detector_name`	Yes	Check/detector name (e.g., `combat_core_killaura_multi`)
`findings[].detector_version`	No	Version of the detector
`findings[].severity`	No	Severity level: `low`, `medium`, `high`, `critical` (default: `low`)
`findings[].title`	Yes	Short description of the finding
`findings[].description`	No	Detailed description
`findings[].evidence_s3_key`	No	S3 key to related batch data
`findings[].evidence_json`	No	Structured evidence data

Response:


{
  "ok": true,
  "inserted": 1
}

Dashboard Endpoints

These require user authentication via Supabase:


GET /dashboard/servers
GET /dashboard/servers/:id/findings
GET /dashboard/servers/:id/modules
GET /dashboard/servers/:id/stats

See the dashboard integration guide for details.