01 / CONTRACT
One analysis route, one health route.
The Fabric client calls only POST /v1/insights. Its JSON body contains the player UUID, one of the five supported goals, and a boolean refresh flag. The response is transformed profile data: signals, checkpoints, recommendations, and a small Bazaar summary. The UUID is not included in the response.
The Hypixel key exists only in the backend process environment. It is sent as the official API-Key header and never as a URL query parameter, client setting, response field, or log value.
02 / ENDPOINTS
Authenticated upstream calls actually used.
The client cannot choose an upstream path, pass arbitrary query parameters, or use this service as a generic API proxy. The backend allow-list rejects every other path.
03 / CACHING
Short-lived memory, clear purpose.
The v0.1.0 cache is process-local and non-persistent. A matching request already in flight is shared with later identical requests; once it completes, the in-flight entry is removed. There is no Redis or database integration in this release.
04 / REQUEST BEHAVIOR
Manual analysis and manual refresh.
Normal analysis
Opening the screen does not call the backend. The player chooses ANALYZE NOW or runs /insights refresh. The client enforces a 120-second minimum between requests by default, and the backend allows six analysis requests per direct connection address in a 60-second window.
Refresh flag
A refresh request invalidates that UUID's profile cache and the shared Bazaar cache before fetching. Skill thresholds retain their six-hour cache because they are reference data. All manual refreshes still pass through the rate limiter.
Deduplication
Concurrent requests for the same normalized UUID and goal share one in-flight computation. The backend does not enqueue a background refresh or continue polling after the response.
05 / SECURITY
Credentials and identity stay out of the product surface.
- HYPIXEL_API_KEY is read only from the backend environment.
- Requests use a fixed User-Agent and the official API-Key header.
- Responses are marked no-store and contain transformed fields, not upstream JSON.
- Rate limiting uses the direct connection address only and is held in memory.
- UUIDs are used only to fetch/cache the requested snapshot; no history or account directory is written.
06 / BOUNDARIES
What this service is not.
SkyScope Player Insights is an independent third-party project and is not affiliated with, sponsored by, or endorsed by Hypixel.
View Source on GitHub