Plugin API Reference

The Storra plugin talks to a small set of HTTP endpoints under /api/v1/plugin/. The plugin handles auth, retries, and command execution; this reference is for anyone building a custom integration.

Auth

Every request requires:

• X-Server-Id: <your-server-id> — the public UUID Storra generated when you added the server.
• X-Signature: <hmac-sha256> — HMAC-SHA256 of the request body using the server's pairing secret.

Endpoints

• POST /api/v1/plugin/heartbeat — periodic health check + telemetry (player count, TPS, plugin version, memory)
• GET /api/v1/plugin/pending — fetch up to 10 pending command deliveries (rate-limited 60/min)
• POST /api/v1/plugin/confirm — mark a command as delivered (body: { "commandId": "..." })
• POST /api/v1/plugin/fail — report a failed command (body: { "commandId": "...", "reason": "..." }); retried with exponential backoff
• GET /api/v1/plugin/subscribe — Server-Sent Events stream that pings when new commands are available (so you can poll on-demand instead of every N seconds)
• POST /api/v1/plugin/events — report player session events (join, leave, death, kill) for the player analytics dashboard

Polling pattern

1. Open the /subscribe SSE stream and listen for data: new_commands
2. On ping (or as a fallback every 30 seconds), call GET /pending to fetch commands
3. For each command, run it on your server
4. On success: POST /confirm. On failure: POST /fail with the reason.

Retry behavior

If you POST /fail, Storra schedules a retry with exponential backoff (30s × 2^attempts, capped at 1 hour). After 10 attempts the command is dead-lettered — it won't be returned by /pending anymore, and the dashboard shows the failure for manual investigation.