Web API

Base

• Service address: http://<server-ip>:<port>
• Port is from checkStorageConfig.json field port.

Auth

• Header: Authorization: Bearer <token>
• /api/login does not use token auth.
• If noPassword: true:
  • /api/storage/getData can be called without token.
  • /api/storage/getItem can be called without token.
  • /api/storage/sendGetItemResult still requires a valid token.
• If a token is sent to /api/storage/getData or /api/storage/getItem, backend validates it first.
• When noPassword: true and token validation fails, /api/storage/getData and /api/storage/getItem fall back to anonymous access.
• /api/storage/sendGetItemResult does not support anonymous fallback.

POST /api/login

• Request body:

{
  "username": "admin",
  "password": "your-password"
}

• Success response:

{
  "username": "admin",
  "token": "jwt-or-token-string"
}

GET /api/storage/getData

• Method: GET
• Response uses compact keys.
• Dimension key mapping:
• "0": overworld
• "-1": nether
• "1": end

Example response:

[
  {
    "n": "main",
    "d": {
      "i": {
        "barrel": {
          "c": 1152,
          "0": [
            [1, 100, 0, 576],
            [-1, 100, 0, 576]
          ]
        }
      },
      "e": {
        "0": [[0, 100, 0]]
      }
    }
  }
]

Field notes:

• n: storage name.
• d: storage data.
• d.i: item map keyed by itemId.
• For minecraft:* items, the minecraft: prefix is omitted in keys (example: barrel).
• d.i[itemId].c: total item count.
• d.i[itemId]["0" | "-1" | "1"]: position list in one dimension, each entry is [x, y, z, n].
• Empty dimension keys are omitted to reduce payload size.
• d.e["0" | "-1" | "1"]: error position list in one dimension, each entry is [x, y, z].

POST /api/storage/getItem

• Method: POST
• Auth:
  • Required when noPassword: false
  • Optional when noPassword: true
• Request body:

{
  "i": "minecraft:stone",
  "c": 64
}

Field notes:

• i: item id.
• c: requested count, must be integer >= 1.

Success response:

[
  {
    "n": "bot_getitem_1",
    "i": "stone",
    "c": 64
  }
]

Field notes:

• n: bot name.
• i: item id.
• For minecraft:* items, i omits minecraft: prefix (example: stone).
• c: count fetched by this bot.
• Commands and log lines are generated by frontend from n/i/c.
• If token validation succeeds, backend uses the token username as the getItem player name for rate limit tracking.
• If noPassword: true and token validation fails or no token is sent, backend handles this request as anonymous.

POST /api/storage/sendGetItemResult

• Method: POST
• Auth: always requires Authorization: Bearer <token>
• Purpose: send one or more getItem result lines to the online player mapped by the token username.
• Request body:

[
  {
    "i": "minecraft:stone",
    "c": 64,
    "n": "bot_getitem_1"
  }
]

Field notes:

• Request body must be an array.
• i: item id.
• c: item count shown in that bot result line.
• n: bot name.
• Multiple array items are sent in request order.

Success response:

{
  "success": true,
  "message": "Sent to player"
}

Behavior notes:

• Token username is used as the target Minecraft player name.
• If that player is not online, backend returns an error and does not send anything.
• This API does not fall back to anonymous access, even when noPassword: true.

Error response

Common error shape:

{
  "status": "400",
  "message": "error message"
}