Skip to main content

API Documentation

The Cookie SMP API addon is an optional purchase for the standalone Cookie SMP setup. It provides a REST API for server statistics and leaderboards.

Players can generate their own API keys using /api to retrieve player statistics (including money, kills, deaths, playtime, and more), get player information including username, rank, and current location, and access top players for various statistics.

Dependencies​

All the following dependencies are present on the setup when downloaded.

Required​

  • PlaceholderAPI: Core dependency for retrieving player data

Optional (for full functionality)​

  • Vault: For economy balance
  • LuckPerms: For rank information
  • CoinsEngine: For shards balance
  • Statz: For blocks placed/broken and mobs killed
  • AJLeaderboards: For leaderboard functionality

Installation​

  1. Download the plugin JAR file
  2. Place it in your server's plugins folder
  3. Restart your server
  4. Configure the API addon in its config.yml, especially the port the API runs on.

Configuration​

# Port for the API server
port: 8080

# Documentation link shown when players use /api command
documentation-link: "https://atomatrix.gg/docs/server-setups/cookie-smp/api-documentation"

# Players excluded from lookup queries
# These players cannot be queried via the /v1/lookup endpoint
excluded-players:
  - "ExamplePlayer1"
  - "ExamplePlayer2"

API Endpoints​

All endpoints require an API key parameter: ?key=YOUR_API_KEY

Player Stats​

GET /v1/stats?username=PLAYER&key=API_KEY

Returns player statistics including:

  • money
  • shards
  • kills
  • deaths
  • playtime
  • placed_blocks
  • broken_blocks
  • mobs_killed
  • money_spent_on_shop
  • money_made_from_sell

Response​

200​
{
  "status": 200,
  "result": {
    "money": "17714",
    "shards": "104",
    "kills": "4",
    "deaths": "18",
    "playtime": "25111986",
    "placed_blocks": "28",
    "broken_blocks": "151",
    "mobs_killed": "30",
    "money_spent_on_shop": "2100",
    "money_made_from_sell": "14815"
  }
}

Player Lookup​

GET /v1/lookup?username=PLAYER&key=API_KEY

Returns player information including username, rank, and location. Note: Player must be online.

Response​

200​
{
  "status": 200,
  "result": {
    "username": "Atomatrix",
    "rank": "default",
    "location": "overworld"
  }
}
503​
{
  "status": 503,
  "reason": "This user is not currently online."
}
404​
{
  "status": 403,
  "error": "This player is excluded from lookup queries"
}
​

Leaderboard​

GET /v1/leaderboards/{type}/{page}?key=API_KEY

Returns the leaderboards for the whole server

Available types:

  • money - Top players by balance
  • shards - Top players by shards
  • kills - Top players by kills
  • deaths - Most deaths
  • playtime - Most playtime
  • placedblocks - Most blocks placed
  • brokenblocks - Most blocks broken
  • mobskilled - Most mobs killed
  • shop - Most money spent in shop
  • sell - Most money made from selling

Pages show 10 entries each (page 1 = ranks 1-10, page 2 = ranks 11-20, etc.)

Response​

200​
{
  "status": 200,
  "result": [
    {
      "username": "Player1",
      "uuid": "7acdc84f-6e89-474e-9b87-71f375270cc9",
      "value": "21230"
    },
    {
      "username": "Player2",
      "uuid": "5ef684ca-2a4c-4b15-b0a1-88f2c83ece61",
      "value": "19870"
    }
  ]
}
​