Web / REST Integration

Authentication

Base URL: https://pikstats.com/api/

Every request must include your game's SDK key as an HTTP header:

X-SDK-Key: your-sdk-key

All responses share the same envelope:

{
  "ok": true,
  "data": { ... }
}

POST /api/player/identify

Registers a player if they don't exist, or confirms they exist. Call this when your game session starts. Free — no PIKE consumed.

Request

POST /api/player/identify
X-SDK-Key: your-sdk-key
Content-Type: application/json

{
  "username": "PlayerOne"
}

Response

{
  "ok": true,
  "data": {
    "username": "PlayerOne",
    "created": true
  }
}

created is true on first registration, false on subsequent calls.

POST /api/player/set

Writes a value to a variable for a specific player. If the player doesn't exist yet, they are created automatically. Costs 1 PIKE per call.

Request

POST /api/player/set
X-SDK-Key: your-sdk-key
Content-Type: application/json

{
  "username": "PlayerOne",
  "variable_token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "value": 4200
}

Response

{
  "ok": true,
  "data": {
    "username": "PlayerOne",
    "variable": "score",
    "value": "4200",
    "pike_remaining": 19999
  }
}

GET /api/player/get

Returns all live variable values for a player. Free — no PIKE consumed.

Request

GET /api/player/get?username=PlayerOne
X-SDK-Key: your-sdk-key

Response

{
  "ok": true,
  "data": {
    "username": "PlayerOne",
    "values": {
      "score": "4200",
      "level": "3",
      "skin": "knight"
    }
  }
}

Keys are variable names. Values are always strings — cast on your side as needed. If the player doesn't exist, values is an empty object {}.

GET /api/leaderboard

Returns the top players for a variable, sorted from best to worst. Optionally includes the calling player's rank if they fall outside the top N. Costs 1 PIKE per call.

Request

GET /api/leaderboard?variable_token=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4&limit=10&player=PlayerOne
X-SDK-Key: your-sdk-key

Response (player outside top 10)

{
  "ok": true,
  "data": {
    "variable": "score",
    "entries": [
      { "rank": 1, "username": "ace", "value": "99000" },
      { "rank": 2, "username": "nova", "value": "87200" },
      ...
    ],
    "player": {
      "rank": 47,
      "username": "PlayerOne",
      "value": "4200"
    },
    "pike_remaining": 19998
  }
}

If player is in the top N, the player field is omitted. If no player param is sent, player is also omitted.

GET /api/variables

Returns all live variables for the game including their scope. Useful for fetching variable tokens at runtime without hardcoding them. Free — no PIKE consumed.

Request

GET /api/variables
X-SDK-Key: your-sdk-key

Response

{
  "ok": true,
  "data": [
    {
      "name": "score",
      "type": "int",
      "default_value": "0",
      "token": "a1b2c3d4e5f6a1b2",
      "scope": "player"
    },
    {
      "name": "launch_count",
      "type": "int",
      "default_value": "0",
      "token": "b2c3d4e5f6a1b2c3",
      "scope": "system"
    }
  ]
}

Only Live variables are returned. The scope field is either "player" or "system" — use it to determine which endpoints to call.

POST /api/game/set

Writes a value to a Game System Variable — a single game-wide value not tied to any player (e.g. launch counter, active event name, difficulty multiplier). Costs 1 PIKE per call.

Request

POST /api/game/set
X-SDK-Key: your-sdk-key
Content-Type: application/json

{
  "variable": "b2c3d4e5f6a1b2c3",
  "value": 42
}

Response

{
  "ok": true,
  "data": {
    "pike_remaining": 19999
  }
}

GET /api/game/get

Returns all live Game System Variables and their current values. If a variable has never been set, its default_value is returned. Free — no PIKE consumed.

Request

GET /api/game/get
X-SDK-Key: your-sdk-key

Response

{
  "ok": true,
  "data": {
    "launch_count": 142,
    "active_event": "double_xp",
    "difficulty_multiplier": 1.5
  }
}

Keys are variable names. Values are typed — integers, floats, and booleans are returned as their native JSON types, not strings.

GET /api/rank

Returns a player's world rank for a variable as a single integer. Free — no SDK key required. Safe to call from a public frontend or web widget.

Request

GET /api/rank?game=GAME_TOKEN&variable=VAR_TOKEN&username=PlayerOne

Response

{
  "ok": true,
  "data": 423
}

Rank is 1-based — rank 1 is the top player. Higher variable values rank better. Only works on Player Variables of type int, float, or date.