MCCompanion API

The MCCompanion REST API powers the app and is partially available for public integrations. All endpoints live under:

https://api.mccompanion.net

Authentication

Most endpoints require a Firebase ID token passed as a Bearer token in the Authorization header:

Authorization: Bearer <firebase_id_token>

To get a token, sign in with Firebase Authentication using your MCCompanion email and password, then call getIdToken(). Tokens expire after 1 hour. Refresh them automatically using the Firebase SDK.

Unauthenticated requests to protected endpoints return 401 Unauthorized.

Public endpoints

These endpoints do not require authentication:

Method	Path	Description
GET	/api/version	Current app version string
GET	/api/health	API health check
GET	/api/metrics	Global stats (top servers, total connections)
GET	/api/lookup/java/:identifier	Look up a Java player by username or UUID
GET	/api/lookup/bedrock/:identifier	Look up a Bedrock player by gamertag or XUID
GET	/api/lookup/bedrock-java/:identifier	Auto-detect and cross-link Java and Bedrock profiles
GET	/api/featured-servers	List all featured servers
GET	/api/featured-packs	List all featured resource packs
GET	/api/packs/lookup?url=	Look up a resource pack by download URL
GET	/api/bots	Xbox relay bot status and friend counts
GET	/api/users/:username	Get a user's public profile
GET	/notification	Current in-app notification banner

User endpoints

Require a valid Firebase token for any registered MCCompanion user.

Method	Path	Description
GET	/api/auth/me	Get your roles and registration status
POST	/api/users/register	Register a new MCCompanion account
GET	/api/users/me	Get your full profile
PATCH	/api/users/me	Update display name, bio, avatar URL, appear offline
GET	/api/users/me/subscription	Check subscription status and tracker slots
GET	/api/users/me/friends	List friends
GET	/api/users/me/friend-requests	List pending friend requests
POST	/api/users/me/friends/:username	Send a friend request
PATCH	/api/users/me/friends/:username/accept	Accept a friend request
DELETE	/api/users/me/friends/:username	Remove a friend
POST	/api/users/me/block/:username	Block a user
GET	/api/users/search?q=	Search users by username (min 2 chars)
GET	/api/tracker/servers	List your tracked servers
POST	/api/tracker/servers	Add a server to track
PATCH	/api/tracker/servers/:id	Update a tracked server
DELETE	/api/tracker/servers/:id	Remove a tracked server
GET	/api/messages/conversations	List your conversations
GET	/api/messages/:username	Get message history with a user
POST	/api/messages/:username	Send a message
PATCH	/api/messages/:username/read	Mark messages as read
POST	/api/feedback	Submit a bug report or feature request
POST	/api/reports	Report a user

Xbox and Java account linking

Method	Path	Description
POST	/api/users/me/xbox/start	Start Xbox account linking (device code flow)
GET	/api/users/me/xbox/status	Poll Xbox linking status
DELETE	/api/users/me/xbox/:xuid	Unlink a specific Xbox account
POST	/api/users/me/java/start	Start Java account linking (device code flow)
GET	/api/users/me/java/status	Poll Java linking status
DELETE	/api/users/me/java/:uuid	Unlink a specific Java account

Rate limiting

The API applies rate limits per IP. Hitting a limit returns 429 Too Many Requests.

Endpoint group	Limit
General public endpoints	60 req / min per IP
Fast read endpoints (e.g. /api/users/me)	120 req / min per IP
Feedback submission	5 req / 10 min per IP

After 3 violations within 10 minutes, the IP is banned. To appeal, join our Discord.

Error format

All errors follow a consistent JSON format:

{
  "error": "error_code",
  "message": "Human-readable description"
}

Code	HTTP status	Meaning
unauthorized	401	Missing or invalid token
not_registered	403	Firebase user exists but no MCCompanion account yet
forbidden	403	Valid token but insufficient role
not_found	404	Resource does not exist
conflict	409	Resource already exists (e.g. duplicate username)
internal_error	500	Unexpected server error

info

The API is primarily designed to serve the MCCompanion app. Third-party usage is allowed for non-commercial integrations, but there is no formal SLA. Breaking changes may occur with prior notice in the Discord server.