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"
}

Behavior notes:

• websiteLoginCooldownSeconds limits repeated login attempts by request username.
• Successful and failed login attempts both count toward the cooldown.
• Requests limited by this rule return 429.

Login error messages:

• 401 may return these message values:
  • Invalid username or password
  • Username cannot be empty
  • Password cannot be empty
  • User data error
• 500 may return:
  • Unknown error

GET /api/storage/getData

• Method: GET
• Data is generated from the current checkStorageConfig.json and checkStorageList files when the request is handled.
• getStorageDataCooldownSeconds limits repeated queries by token username.
• If noPassword: true and no valid token is used, all anonymous queries share the empty-string cooldown key.
• Requests limited by this rule return 429.
• Response uses compact keys and only includes total counts for each item.
• Error positions still use dimension keys:
• "0": overworld
• "-1": nether
• "1": end

Example response:

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

Field notes:

• n: storage name.
• d: item list.
• d[].i: item ID.
• For minecraft:* items, the minecraft: prefix is omitted in keys (example: barrel).
• d[].c: total item count.
• 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.
• Backend chooses slots by minimizing the fetched total that is at least the requested count, then minimizing the number of slots for that total.
• 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"
}

Known message values returned by backend:

• Auth:
  • Invalid username or password
  • Username cannot be empty
  • Password cannot be empty
  • User data error
  • Invalid token
  • Token expired
• Rate limit:
  • Rate limited, wait <seconds> seconds
• Storage website:
  • Website getItem is disabled
  • Target player is not online
  • Minecraft server is not initialized
• Generic:
  • Unknown error