ShieldPlay HTTP API

Base URL and conventions

Production API base URL: https://api.shieldplay.it/api/v1. Paths below are relative to this base. Send JSON request bodies with Content-Type: application/json. Successful responses use standard 2xx HTTP status codes; validation, authentication, authorization and rate-limit failures use their corresponding 4xx status.

Health check

GET https://api.shieldplay.it/health

{ "status": "ok", "timestamp": 1780000000000 }

Dashboard authentication

Endpoint	Method	Use
/auth/register	POST	Create an account and organization.
/auth/login	POST	Start a dashboard session.
/auth/logout	POST	End the current dashboard session.
/auth/me	GET	Read the authenticated staff profile and organization context.
/auth/providers	GET	List enabled sign-in providers.
/auth/google/authorize	GET	Begin Google sign-in when enabled.
/auth/password-reset/request	POST	Request a password reset.
/auth/password-reset/confirm	POST	Complete a password reset.

Dashboard authentication supports the httpOnly ac_session cookie. Staff clients may also send the corresponding JWT as Authorization: Bearer <token>. Never embed either token in a public website.

Agent authentication

Minecraft agents authenticate with a server-specific key, not a staff session. Generate or rotate the key from the server management flow, store it only in the server config.yml and send it in the x-api-key header.

Agent request headers

x-api-key: YOUR_SERVER_SPECIFIC_KEY
content-type: application/json

Agent event ingestion

Minimal violation body

POST https://api.shieldplay.it/api/v1/events/violation

{
  "playerUuid": "00000000-0000-0000-0000-000000000000",
  "playerName": "ExamplePlayer",
  "checkName": "XRayCheck",
  "category": "movement",
  "severity": "MEDIUM",
  "points": 1,
  "metrics": { "review_only": true, "evidence_family": "xray_pattern" }
}

Endpoint	Method	Payload purpose
/events/heartbeat	POST	Update agent version, server runtime health and connection state.
/events/players/snapshot	POST	Submit a bounded live player snapshot; up to 500 players per request.
/events/player/join	POST	Record a player join.
/events/player/leave	POST	Record a player leave.
/events/violation	POST	Submit a check name, category, severity, points and structured metrics.
/events/staff-access	GET	Fetch staff UUIDs, per-check exemptions, GUI language and X-Ray material override.

The agent API accepts only combat, movement, interaction and network categories. A review_only metric explicitly prevents a submitted signal from qualifying as automatic punishment evidence.

Owner and staff management endpoints

Endpoint family	Capabilities
/servers and /servers/:id/rotate-key	Create, list and maintain server records; rotate a compromised connection key.
/staff-access	Read Minecraft staff access by server.
/staff-access/servers/:id	Owner/Admin roster update.
/staff-access/servers/:id/gui-language	Owner-only Italian/English agent GUI setting.
/staff-access/servers/:id/check-exemptions	Owner-only exact per-check staff exemptions.
/staff-access/servers/:id/xray-rare-ores	Owner-only monitored X-Ray material override.
/checks, /players, /live-players, /violations, /incidents, /punishments	Review and operations data exposed in the dashboard.

Notifications API

Use /webhooks to create, edit, delete and test organization outbound webhooks. Subscribing a Discord URL to xray.flagged delivers a native, mention-safe X-Ray review embed. Use /discord/channels for the separate managed Discord channel integration.

Outbound delivery is asynchronous. It never blocks a stored violation, and X-Ray Discord cooldowns suppress duplicate messages per webhook during the configured window.

Errors, limits and safe retries

Validate input before retrying a 400 response. Refresh staff credentials after a 401, verify organization ownership or staff role after a 403, and treat 404 as an unavailable or out-of-tenant resource. For 429, honor the retry window and apply exponential backoff with jitter. Agent requests use dedicated quotas; avoid tight loops, keep heartbeat intervals reasonable and preserve offline events for controlled replay.

Billing and Stripe webhooks

Dashboard billing uses /billing endpoints. The Stripe webhook is an internal server-side endpoint and must not be called by agents or browsers. Payment keys and webhook signing secrets belong only in production server environment variables.