azaAPI

Uwierzytelnianie

Domyślnie wszystkie endpointy /api/v1/* wymagają aktywnego klucza. Zalecany jest standardowy nagłówek:

Authorization: Bearer KLUCZ_API

Alternatywnie można użyć:

X-API-Key: KLUCZ_API

Jeżeli żądanie zawiera oba nagłówki, zawsze pierwszeństwo ma Authorization. Brak klucza, niepoprawny format Bearer albo nieaktywny klucz daje HTTP 401.

Klucz tworzy operator będący w grze poleceniem /azaapi key create <nazwa>. Sekret jest widoczny tylko raz i tylko temu graczowi. Konsola nie otrzymuje pełnego klucza.

Endpointy

GET /api/v1

{
  "name": "azaAPI",
  "version": "1.0.0",
  "endpoints": {
    "status": "GET /api/v1/status",
    "command": "POST /api/v1/command",
    "commands": "POST /api/v1/commands"
  }
}

POST /api/v1/command

Wyślij JSON z niepustym polem command. Początkowy ukośnik jest usuwany; pozostała treść nie jest zmieniana ani filtrowana.

{
  "command": "/minecraft:give Steve minecraft:diamond 1"
}

Odpowiedź:

{
  "success": true,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "command": "minecraft:give Steve minecraft:diamond 1",
  "output": [
    "Gave 1 [Diamond] to Steve"
  ],
  "durationMs": 14,
  "timestamp": "2026-08-10T12:00:00Z"
}

output zawsze jest tablicą. Dla komendy bez odpowiedzi ma wartość [].

POST /api/v1/commands

Komendy są wykonywane kolejno, w podanej kolejności. stopOnError określa, czy zatrzymać paczkę po pierwszym błędzie. Liczbę komend ogranicza wyłącznie skonfigurowany rozmiar całego requestu.

{
  "commands": [
    "say Restart serwera",
    "save-all",
    "stop"
  ],
  "stopOnError": false
}

{
  "success": true,
  "requestId": "699d5c47-f516-4fde-83e7-c6282a431fda",
  "results": [
    {"command":"say Restart serwera","success":true,"output":[],"durationMs":3},
    {"command":"save-all","success":true,"output":["Saved the game"],"durationMs":18},
    {"command":"stop","success":true,"output":[],"durationMs":2}
  ],
  "durationMs": 23,
  "timestamp": "2026-08-10T12:00:00Z"
}

GET /api/v1/status

{
  "success": true,
  "server": {
    "online": true,
    "minecraftVersion": "1.21.11",
    "paperVersion": "wersja Paper",
    "pluginVersion": "1.0.0",
    "playersOnline": 2,
    "maxPlayers": 100,
    "playerNames": ["Steve", "Alex"],
    "tps": [20.0, 19.99, 19.98],
    "mspt": 12.4,
    "uptimeMs": 12345678
  },
  "timestamp": "2026-08-10T12:00:00Z"
}

Błędy

{
  "success": false,
  "requestId": "a564657c-a12d-4687-8eaf-4ca0e8fde2cc",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Pole command jest wymagane."
  },
  "timestamp": "2026-08-10T12:00:00Z"
}

Najprostszy request curl

curl -X POST \
  -H "Authorization: Bearer KLUCZ_API" \
  -H "Content-Type: application/json" \
  -d '{"command":"list"}' \
  https://api.347aza.pl/api/v1/command

Krótki przykład Python / aiohttp

To jedynie przykład połączenia, nie osobne SDK ani bot Discord.

import aiohttp


async def execute_command(command: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.347aza.pl/api/v1/command",
            headers={
                "Authorization": "Bearer KLUCZ_API",
            },
            json={
                "command": command,
            },
        ) as response:
            return await response.json()

Przechwytywanie odpowiedzi i ograniczenia

azaAPI przechwytuje tekst i komponenty Adventure wysłane przez komendę do jej obiektu CommandSender. Dotyczy to również wielu kolejnych wiadomości i błędów zwracanych nadawcy.

API wykonuje komendy Minecraft/Paper/pluginów, a nie polecenia systemu Windows ani Linux. Kod nie rejestruje listenerów kliknięć ekwipunku i nie ingeruje w GUI innych pluginów.