Public API

A free, read-only JSON API for building community tools on top of live HarvestSeason data. No authentication or API key required for public endpoints.

Fair use

The API is shared infrastructure. Please cache responses for at least 30 seconds and stay well under 10 requests/second. Abusive traffic is rate-limited at the server.

Endpoints

GET /api/status

Live server status — online state, player count, current season, featured crop, and active events.

Response shape 
{
  "online": true,
  "players": 12,
  "maxPlayers": 100,
  "season": 3,
  "seasonState": "active",
  "featuredCrop": "Carrot",
  "seasonEndsAt": 1751760000000,   // ms epoch, optional
  "tps": 19.8,                     // optional
  "activity": "Harvest Rush",      // optional active event name
  "maintenance": {
    "active": false,
    "message": ""
  },
  "announcement": {                // optional
    "active": true,
    "message": "Playtest weekend!",
    "href": "/news/playtest",
    "since": 1751000000
  }
}
GET /api/leaderboard?board=season&limit=25

Live leaderboard standings. board can be season, sales, featured, farming, or mastery. limit is 1–100.

Response shape 
{
  "board": "season",
  "entries": [
    {
      "rank": 1,
      "name": "PlayerName",
      "value": 142530,
      "division": "Grandmaster",
      "supporterRankId": null     // "patron"|"benefactor"|"luminary"|null
    }
  ]
}
GET /api/leaderboard?hof=1

Hall of Fame — past season champions.

Response shape 
{
  "champions": [
    { "season": 2, "name": "PlayerName", "score": 987654 }
  ]
}
GET /api/account?ign=PlayerName

Public player profile — current season score, rank, division, and rank metadata. Does not expose IPs, balances, alt accounts, or staff notes.

Response shape 
{
  "name": "PlayerName",
  "uuid": "uuid-string",
  "rankId": "cultivator",
  "supporterRankId": null,
  "score": 42000,
  "rank": 7,
  "division": "Diamond"
}
GET /api/season-stats

Aggregate season statistics — total players, field size, top/average score, crop totals.

GET /api/staff

Staff team members — name, rank, and online status. Does not expose private staff notes or alts.

GET /api/punishments?user=PlayerName

Active punishments for a player (ban/mute metadata only — no IP or moderator notes).

GET /api/badge.svg

Shields-style SVG status badge for use in READMEs, forum signatures, or server-list listings. Returns live player count.

Example:

HarvestSeason status badge [![HarvestSeason](https://playharvestseason.com/api/badge.svg)](https://playharvestseason.com)

Rate limits & caching

The API enforces a per-IP token bucket: up to 30 requests in a burst, refilling at 10 per second. Exceeding this returns 429 Too Many Requests with a retry-after: 1 header.

All responses can be cached freely by downstream consumers. The status endpoint updates on the server's heartbeat interval (~30s). Leaderboard data refreshes in near-real time as players score.

What is never exposed

  • IP addresses (raw or hashed)
  • Staff notes, watchlist, or internal moderation data
  • Player balances or inventory
  • Account links (Discord ↔ Minecraft)
  • Alt account groupings

See the Privacy Policy for the full data-handling overview.