REST API Reference

🌐 REST API & Web Observability

ChestLogger includes an embedded, zero-dependency HTTP server running on port 8080 by default. It provides a real-time web dashboard and JSON/CSV endpoints for server networks and custom integrations.

---

🔌 API Endpoints

1. Telemetry & Metrics

Returns live queue throughput, memory buffer utilization, and indexing statistics.

• Method: GET
• Path: /api/v1/telemetry
• Response Format: JSON

Example Response:

{
  "queueDepth": 0,
  "queueCapacity": 65536,
  "totalProcessed": 14280,
  "activeSegments": 3,
  "indexedEntries": 14280,
  "uptimeSeconds": 7200
}

---

2. Query Logs

Fetches filtered transaction records.

• Method: GET
• Path: /api/v1/logs
• Query Parameters:
  • x, y, z — Container block coordinates (integers).
  • dimension — Dimension key (e.g. minecraft:overworld).
  • player — Player name or UUID string filter.
  • itemId — Item identifier (e.g. minecraft:diamond).
  • limit — Maximum results to return (default: 50, max: 500).
• Response Format: JSON

Example Request:

curl "http://localhost:8080/api/v1/logs?x=120&y=64&z=-350&limit=10"

Example Response:

[
  {
    "sequenceId": 1042,
    "timestampMs": 1723901234567,
    "actionType": "SHIFT_CLICK_EXTRACT",
    "actorType": "PLAYER",
    "actorName": "Steve",
    "actorUuid": "85638e6b-69c5-49c0-988b-1d6db7072c47",
    "dimension": "minecraft:overworld",
    "x": 120,
    "y": 64,
    "z": -350,
    "slot": 4,
    "itemId": "minecraft:diamond",
    "delta": -16,
    "prevCount": 64,
    "newCount": 48
  }
]

---

3. Export Audit Logs (CSV / JSON)

Exports filtered transactions as a downloadable spreadsheet or JSON dump.

• Method: GET
• Paths:
  • /api/v1/logs/export.csv — Comma-Separated Values (Excel / Google Sheets compatible).
  • /api/v1/logs/export.json — Raw JSON array.

Example Request:

curl -o container_audit.csv "http://localhost:8080/api/v1/logs/export.csv?x=120&y=64&z=-350"

---

⚙️ Security & Port Configuration

• Default Port: 8080 (Configurable in config/chestlogger.json or Paper config.yml).
• Binding: Binds to 0.0.0.0 by default. For public servers, restrict access via firewall / reverse proxy (e.g., Nginx or Cloudflare Tunnel) if you do not want public access to container metrics.