{"openapi":"3.1.0","info":{"title":"MineGeo Developer API","version":"1.0.0","description":"Read-only HTTPS API. Bearer keys are managed at /dev/api. 60 requests per key per fixed minute; 180 requests per account per minute shared across keys. All authenticated requests, including validation/permission errors, consume quota. A 429 response includes Retry-After; successful authorized responses include RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until reset). X-RateLimit-Reset is a Unix timestamp. Requests with invalid keys cannot access account data. No upload, publication, gameplay writes or moderator access is granted."},"servers":[{"url":"/api/dev/v1"}],"paths":{"/maps":{"get":{"summary":"List published maps","description":"Requires the maps:read key permission.","x-required-scope":"maps:read","security":[{"DeveloperKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"q","in":"query","schema":{"type":"string","maxLength":80},"description":"Case-insensitive map-name search"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["maps","pagination"],"properties":{"maps":{"type":"array","items":{"$ref":"#/components/schemas/Map"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid query or map ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Quota exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/maps/{id}":{"get":{"summary":"Get a published map","description":"Requires the maps:read key permission.","x-required-scope":"maps:read","security":[{"DeveloperKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["map"],"properties":{"map":{"$ref":"#/components/schemas/Map"}}}}}},"400":{"description":"Invalid query or map ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Quota exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"summary":"Get the key owner's profile","description":"Requires the account:read key permission.","x-required-scope":"account:read","security":[{"DeveloperKey":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["account"],"properties":{"account":{"$ref":"#/components/schemas/Account"}}}}}},"400":{"description":"Invalid query or map ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Quota exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/maps":{"get":{"summary":"List the owner's maps, including private maps","description":"Requires the account:maps:read key permission.","x-required-scope":"account:maps:read","security":[{"DeveloperKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"q","in":"query","schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["maps","pagination"],"properties":{"maps":{"type":"array","items":{"$ref":"#/components/schemas/Map"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid query or map ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Quota exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/games":{"get":{"summary":"List the owner's solo-game history","description":"Requires the account:games:read key permission.","x-required-scope":"account:games:read","security":[{"DeveloperKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["games","pagination"],"properties":{"games":{"type":"array","items":{"$ref":"#/components/schemas/Game"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Invalid query or map ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Required permission missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource or endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Quota exceeded; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"DeveloperKey":{"type":"http","scheme":"bearer","bearerFormat":"mg_dev_<64 hex characters>"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"nextOffset":{"type":["integer","null"]}}},"Map":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"source":{"type":"string"},"state":{"type":"string"},"bounds":{"type":"object","properties":{"minX":{"type":"number"},"minZ":{"type":"number"},"maxX":{"type":"number"},"maxZ":{"type":"number"}}},"panoramaCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"url":{"type":"string","description":"Relative MineGeo map page path; private maps still require their owner's browser login."}}},"Account":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"appearance":{"type":"object","properties":{"nameGlow":{"type":"boolean"},"glowColor":{"type":"string"},"bugFinder":{"type":"boolean"},"customPrefix":{"type":["string","null"]},"customPrefixIcon":{"type":"string"}}}}},"Game":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"difficulty":{"type":"string","enum":["easy","normal","hard"]},"createdAt":{"type":"string","format":"date-time"},"currentRound":{"type":"integer","minimum":0,"maximum":5},"complete":{"type":"boolean"},"score":{"type":["integer","null"],"minimum":0,"maximum":25000,"description":"Final score only; null until a complete five-round result is available."}}}}}}