API documentation

All routes are rate-limited per IP unless noted. Base URL: https://mcprofiles.me. Privacy.

GET/api/player/[query]

Returns a Java player profile (Mojang session + aggregated capes + Geyser verified Bedrock enrichment when available).

Response kind is one of profile, archiveFallback, historicalMatches, or notFound. Historical matches are returned when a searched username is not currently claimed but exists in MCProfiles' observed archive.

Query params: type=java|bedrock|all (default all) — metadata only; same lookup pipeline. Use bedrock to set meta.bedrockFocus for clients.

Response: { data, meta } with cacheState, requestedType, etc.

GET/api/server/[address]

Java and Bedrock server status via mcstatus.io (see README for provider stack).

POST/api/refresh/[uuid]

Force-refresh a cached player profile (stricter rate limit).

GET/api/discover

Recent players and aggregate stats for the home page. playersTracked comes from Turso archive metrics, while userSearches counts user-initiated player/server/compare searches and excludes refresh jobs.

GET/api/username/check

Username availability heuristic (Mojang 404-based).

GET/api/capes/explore

Cape explorer over stored snapshots. Without params returns the full cape catalog with observed-owner counts (unique players from MCProfiles' archive owner table). With capeSlugs (comma-separated cape slugs) returns players who own all specified capes (intersection match, capped at 200 results).

GET/api/search/universal?q=…

Combined player + server search. Returns up to 8 players and 5 servers matching the query string (case-insensitive substring match).

GET/api/servers/search?q=…

Server-only search with synthetic TLD suggestions when the query has no dot.

GET/api/username/dropping

Returns scheduled NameMC seed data merged with MCProfiles' own observed username changes. This is a heuristic feed, not an official availability API. Response metadata includes freshness and failure fields such as stale, lastSuccessfulSeedAt, lastFailedSeedAt, and lastFailureReason.

GET/api/watchlist?sessionId=…

List watches and optional alert email settings for a browser session.

POST/api/watchlist

Body: { sessionId, playerUuid }. Free tier max 8 entries per session; Plus max 60 when subscription is active.

DELETE/api/watchlist

Remove a watch (same body shape as POST).

PATCH/api/watchlist/alert

Configure email digest / notification preferences.

GET/api/cron/watchlist

Daily Vercel Cron watchlist refresh — requires Authorization: Bearer CRON_SECRET.

GET/api/cron/cape-recheck

Daily Vercel Cron refresh for recently viewed players so current profiles and official cape ownership stay fresh.

GET/api/cron/username-drops

Daily Vercel Cron seed refresh for the username drop feed. On upstream failure, the previous stale snapshot is preserved and failure metadata is updated.

POST/api/privacy-request

Privacy / suppression requests (see privacy page).

GET/api/subscription?sessionId=…

Returns { plus, watchlistMax } for MCProfiles Plus status on this browser session.

GET/api/stripe/status

{ configured: boolean } — whether Stripe keys and price id are set server-side.

POST/api/stripe/checkout

Body: { sessionId }. Returns { url } to Stripe Checkout when configured.

POST/api/stripe/webhook

Stripe webhook — server-only; verifies signature with STRIPE_WEBHOOK_SECRET.