MG
MyGecko API
All-in-One API

Developer Documentation

Comprehensive guide for My Gecko API. The sections below are auto-generated from the project's API routes.

Introduction

This documentation is made for the source routes under /api. Examples show typical responses inferred from the implementation.

Base URL: https://api.ziggymc.me
Authentication: API routes either require a server session (NextAuth) or an API key in the Authorization header: Authorization: Bearer YOUR_API_KEY. Rate limiting is enforced server-side.

User Routes

GET /api/zavro/user/:id

Description: Fetch public user profile linked to Discord, BeatLeader, and Minecraft.
Auth: API key required (server validates & consumes rate limit)
Params: Path param id (Discord ID)
Response:
{
  "discord": { "id": "123456", "username": "someUser" },
  "beatleader": { "connected": true, "userId": "bl_123", "username": "blUser" },
  "minecraft": { "connected": false, "username": null, "uuid": null }
}

GET /api/zavro/patreon?userId=...

Description: Check Patreon/supporter status for a user via query parameter.
Auth: API key required
Params: Query param userId
Response:
{ "active": true|false, "tier": "roleName" | null }

GET /api/zavro/patreon/:id

Description: Same as above but accepts a path param for the user id.
Auth: API key required
Response: { "active": true|false, "tier": "roleName" | null }

BeatLeader Routes

GET /api/beatleader/profile/:id

Description: Returns a normalized BeatLeader player profile (name, rank, pp, avatar).
Auth: API key required
Response:
{ "name": "...", "rank": ..., "countryRank": ..., "pp": 1234, "avatar": "..." }

GET /api/beatleader/player/:id

Description: Proxy to BeatLeader's player endpoint — returns the provider response as-is.
Auth: API key required

GET /api/beatleader/stats/:id

Description: Aggregates a player's scores to provide totalPP, avgAccuracy, playCount and rankedScores.
Auth: API key required
{ "totalPP": 12345, "avgAccuracy": 97.5, "playCount": 100, "rankedScores": 85 }

GET /api/beatleader/recent/:id

Description: Returns a simplified list of recent plays (song, difficulty, pp, accuracy, rank, replay).
Auth: API key required
{ "recent": [{ "song": "...", "difficulty": "...", "pp": 123, "accuracy": 98.5, "rank": 1, "replay": "..." }] }

GET /api/beatleader/top/:id

Description: Returns the player's top scores (normalized).
Auth: API key required
{ "top": [ /* simplified top score objects */ ] }

GET /api/beatleader/pinned/:id

Description: Returns pinned scores for a player (limited slice applied server-side).
Auth: API key required
{ "pinned": [ /* pinned score objects */ ] }

Minecraft Routes

GET /api/minecraft/uuid/:username

Description: Looks up a Minecraft Java Edition player's UUID by username via the Mojang API. The UUID is returned in standard hyphenated format.
Auth: API key required
Params: Path param username (Minecraft Java Edition username)
Response:
{ "username": "Notch", "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5" }
Error responses:
400 — Missing username  |  404 — Player not found  |  503 — Mojang API unavailable

GET /api/hypixel/player/:uuid

Description: Fetches Hypixel player data using a primary key (Hypixel) and optional secondary provider; returns a normalized payload.
Auth: API key required
Response (example):
{ "uuid": "...", "username": "...", "online": null, "stats": { /* provider stats */ }, "source": "primary|secondary" }

MyGecko Platform Route

This route is just a util for your use. They require an active login session (NextAuth) rather than an API key in the Authorization header.

GET /api/mygecko/usage

Description: Returns detailed usage timestamps for your API key over the last 5-minute window.
Auth: Login session required
Response:
{ "used": 5, "limit": 100, "windowStart": 1700000000000, "windowDuration": 300000, "timestamps": [1700000001000, ...] }

Utility & Misc Routes

GET /api/health

Description: Simple health check that also requires a valid API key (consumes a rate-limit point).
Response:
{ "status": "ok", "uptime": 1670000000000 }

GET /api/hello

Description: Minimal hello endpoint used for quick checks (requires API key).
{ "message": "Hello from mygecko-api" }

Live Tester

Try It Out

No response yet. Enter an endpoint and API key, then click Send Request.
Note: Missing or invalid API key will result in a 401 Unauthorized response from the API.