MineGeo/docs/developer-api.md

MineGeo developer API

The developer key panel is at /dev/api; /api/dev redirects there. The API reference is part of the existing documentation at /docs?page=developer-api, alongside the player guides. Any visitor can read the reference. Any signed-in player can create API keys independently of the account dashboard and without a Moderator or Admin role.

Keys and permissions

Create a named key in the developer panel. A key is shown in full once, remains only in browser memory while the panel is open, and can be copied or hidden. Only a prefix and metadata appear in the key list. The server stores a SHA-256 hash, not the raw key. Keep keys out of source code, public repositories, browser JavaScript and URLs. Store them in a server-side environment variable such as MINEGEO_API_KEY.

An account can hold 5 active keys. Expiration is 1–365 days, default 90. Revoke keys in the panel at any time. Revocation is immediate; an expired or revoked key cannot be recovered. To change permissions, revoke and replace the key.

Scope	Access
maps:read	Published catalog and published map metadata. Selected by default.
account:read	Key owner's profile and username appearance.
account:maps:read	Key owner's map metadata, including private maps.
account:games:read	Key owner's game history.

Version 1 is read-only. No key grants uploads, edits, publication, moderation or access to other accounts' private data. Contributor upload tokens and Prometheus metrics tokens cannot be used as developer keys.

Requests

Base URL: https://minegeo.vercel.app/api/dev/v1

Every request requires Authorization: Bearer <developer-key>. Developer keys start with mg_dev_. Browser session cookies do not authenticate these endpoints. No MineGeo SDK is provided.

Install the Python HTTP library with python -m pip install requests, set MINEGEO_API_KEY in your environment, and make a request:

import os
import requests

response = requests.get(
    "https://minegeo.vercel.app/api/dev/v1/maps",
    headers={"Authorization": f"Bearer {os.environ['MINEGEO_API_KEY']}"},
    params={"limit": 20, "offset": 0},
    timeout=20,
)
response.raise_for_status()
print(response.json())

GET path	Required scope	Response
/maps	maps:read	{maps: [...], pagination: {...}}
/maps/{id}	maps:read	{map: {...}}
/me	account:read	{account: {...}}
/me/maps	account:maps:read	{maps: [...], pagination: {...}}
/me/games	account:games:read	{games: [...], pagination: {...}}

Lists accept limit (default 20, maximum 50) and offset (default 0, maximum 10000). /maps also accepts a map-name search in q (up to 80 characters). Unknown or duplicate query parameters return HTTP 400. Pagination contains limit, offset, total and nextOffset; nextOffset: null marks the end of the supported result window. Narrow the search if you reach the offset cap.

Map metadata contains id, name, description, source, state, bounds, panoramaCount, createdAt, updatedAt and url. The URL is relative to the site origin. It excludes raw storage paths, panorama coordinates and moderation notes.

/me contains id, displayName, createdAt and appearance (nameGlow, glowColor, bugFinder, customPrefix, customPrefixIcon). Email and account roles are excluded. Game records contain id, difficulty, createdAt, currentRound, complete and score. Score is null until completion; answer locations are never returned.

The machine-readable contract is /api/dev/openapi.json.

Rate limits and errors

Requests with a valid developer key are limited to 60 per minute per key and 180 per minute shared by all keys belonging to its account. Permission and validation failures consume the authenticated quota. Creating multiple keys does not bypass the account limit.

• RateLimit-Limit: per-key limit.
• RateLimit-Remaining: remaining per-key quota.
• RateLimit-Reset: seconds until the current minute window resets.
• X-RateLimit-Reset: reset time as a Unix timestamp.
• X-RateLimit-Owner-Limit and X-RateLimit-Owner-Remaining: shared account quota.
• On HTTP 429, Retry-After gives the minimum delay in seconds before retrying.

Errors use {"error":{"code":"...","message":"..."}}. Treat the HTTP status and code as machine-readable; messages may change. Expected statuses include 400 for invalid inputs, 401 for missing or invalid credentials (including expiry or revocation), 403 for a missing scope, 404 for unavailable maps or endpoints, 429 for quota exhaustion, and 500/503 for service failures. Honor retry delays and avoid rapid retry loops.