Developer API

Getting started

All endpoints live under a single versioned base URL and respond with JSON. Requests are anonymous and read only: the API never exposes emails, internal ids, private messages, or anything else that is not already public on the site.

Base URL

https://minecraftlfg.com/api/v1

Example request

curl https://minecraftlfg.com/api/v1/stats

Response contract

Every response is one of two shapes. Successful calls wrap their payload in a top level data key, with an optional meta key for pagination. Failures return an error object and a matching HTTP status code.

Success

{ "data": { ... }, "meta": { ... } }

Failure

{ "error": { "code": "not_found", "message": "No active player profile with that username." } }

Error codes

• invalid_query400. A query parameter failed validation.
• not_found404. The requested resource does not exist.
• rate_limited429. Too many requests from your IP. Check the Retry-After header.
• internal_error500. Something went wrong on our side.

Rate limits

Each endpoint allows 60 requests per minute per IP address. When you go over, the API responds with HTTP 429 and a Retry-After header that tells you how many seconds to wait. The health endpoint is not rate limited, so uptime monitors can poll it freely.

Liveness probe for the service and its database. Always answers HTTP 200 so monitors can read the body. When the database check fails, status flips to degraded and database goes false.

Sample response

{
  "data": {
    "status": "ok",
    "database": true,
    "timestamp": "2026-01-01T00:00:00.000Z"
  }
}

Site-wide matchmaking numbers: active players in the pool, total matches made, and match requests sent in the last seven days. The values below are placeholders, not live figures.

Sample response

{
  "data": {
    "playersInPool": 123,
    "matchesMade": 456,
    "requestsThisWeek": 78
  }
}

Paginated list of players with active match profiles, ordered by most recent profile activity. Only public profile fields are included.

Query parameters

• pageInteger, minimum 1. Defaults to 1.
• perPageInteger, 1 to 50. Defaults to 20.
• editionOptional filter: JAVA, BEDROCK, or CROSSPLAY.
• languageOptional filter by language code, for example en, pt, or es.

Sample response

{
  "data": [
    {
      "username": "example_player",
      "displayName": "Example Player",
      "headline": "Laid back SMP builder looking for a weekend duo",
      "edition": "JAVA",
      "language": "en",
      "modes": ["SMP", "SURVIVAL"],
      "availability": ["WEEKEND_EVENINGS", "WEEKEND_NIGHTS"],
      "groupSize": "DUO",
      "voice": "VOICE_OK",
      "memberSince": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "perPage": 20, "total": 1, "pages": 1 }
}

Full public profile for a single player: the list fields plus about, playstyles, and preferred game version. Responds 404 when the user does not exist or has no active match profile.

Sample response

{
  "data": {
    "username": "example_player",
    "displayName": "Example Player",
    "headline": "Laid back SMP builder looking for a weekend duo",
    "about": "I like long survival worlds, big base projects, and low drama.",
    "edition": "JAVA",
    "language": "en",
    "modes": ["SMP", "SURVIVAL"],
    "playstyles": ["builder", "explorer"],
    "availability": ["WEEKEND_EVENINGS", "WEEKEND_NIGHTS"],
    "groupSize": "DUO",
    "voice": "VOICE_OK",
    "version": "1.21",
    "memberSince": "2026-01-01T00:00:00.000Z"
  }
}

Fair use

The API exists so you can build bots, overlays, and community tools. Cache responses where you can, identify your project with a descriptive User-Agent, and do not use the data to spam or scrape players. Endpoints may gain fields over time, so parse defensively and ignore keys you do not recognize.