Dokumentacja

API dla bota Cordly.

Bot odpytuje panel o uprawnienia serwera i pobiera zlecenia budowy wygenerowane przez AI. Wszystkie odpowiedzi są w formacie JSON, a każdy request wymaga klucza BOT_API_KEY.

Autoryzacja

Do każdego żądania dodaj nagłówek Authorization: Bearer <BOT_API_KEY>. Klucz jest porównywany w czasie stałym, a jego wartość ustawiasz wyłącznie po stronie serwera w pliku .env.

curl https://cordly.176.223.138.51.nip.io/api/entitlements/123456789012345678 \
  -H "Authorization: Bearer $BOT_API_KEY"

Bezpieczeństwo: nie umieszczaj klucza w kodzie klienta, repozytorium ani w prompcie. Panel i API powinny działać za HTTPS, zanim zaczniesz obsługiwać prawdziwe płatności.

Uprawnienia gildii

Zwraca plan właściciela serwera, limity generacji i tokenów oraz aktualne zużycie AI.

GET /api/entitlements/{guild_id}

Parametry: guild_id — identyfikator serwera Discord (snowflake).

{
  "plan": "pro",
  "plan_name": "Pro",
  "status": "active",
  "current_period_end": "2026-11-24T12:00:00+00:00",
  "max_guilds": 1,
  "max_channels": null,
  "generations": 20,
  "generation_period": "month",
  "token_limit": 1000000,
  "token_period": "month",
  "max_output_tokens": 6000,
  "ai_model": "DeepSeek V4.1 Flash 1017",
  "ai_model_id": "deepseek/deepseek-v4.1-flash-1017",
  "max_prompt_chars": 2000,
  "backups": true,
  "priority_support": true,
  "onboarding": false,
  "features": ["20 generacji AI miesięcznie", "..."],
  "generation_usage": 3,
  "generation_remaining": 17,
  "token_usage": 184320,
  "token_remaining": 815680,
  "guild": {"id": "123456789012345678", "name": "Kraków RP"}
}

Kolejka budowy

Pobiera najstarsze oczekujące zlecenie i oznacza je jako running. Wywołuj cyklicznie, np. co 10 sekund. Gdy kolejka jest pusta, odpowiedź zawiera {"build": null}.

GET /api/builds/next

Pole spec zawiera pełną, zwalidowaną specyfikację wygenerowaną przez AI — dokładnie w formacie przyjmowanym przez builder bota.

{
  "build": {
    "id": 42,
    "guild_id": "123456789012345678",
    "guild_name": "Kraków RP",
    "user_id": "987654321098765432",
    "status": "running",
    "plan": "pro",
    "max_channels": null,
    "max_guilds": 1,
    "allowed": true,
    "prompt": "Serwer RP w GTA...",
    "entitlement": {"plan": "pro", "generations": 20, "...": "..."},
    "spec": {
      "template": "custom-ai",
      "name": "Miasto Roleplay",
      "roles": [{"name": "Zarząd", "color": "#F59E0B", "staff": true, "permissions": ["manage_guild"]}],
      "categories": [{"name": "INFORMACJE", "read_only": true, "channels": [{"name": "zasady", "type": "text"}]}],
      "welcome": {"channel": "powitanie", "title": "Witaj", "fields": []},
      "rules": {"channel": "zasady", "rules": []},
      "messages": []
    }
  }
}

Idempotencja: zlecenie jest blokowane w transakcji, więc dwa równoległe procesy bota nie otrzymają tego samego build.id.

Zakończenie budowy

Po zakończeniu (lub błędzie) budowy zgłoś wynik. Panel oznaczy projekt jako built albo build_failed, dzięki czemu użytkownik widzi prawdziwy status w panelu.

POST /api/builds/{build_id}/complete

{
  "ok": true,
  "result": {
    "roles_created": 8,
    "categories_created": 5,
    "channels_created": 19,
    "embeds_sent": 3,
    "warnings": []
  }
}

Odpowiedź: {"ok": true}. Jeśli zlecenie nie istnieje lub nie jest w stanie running, API zwraca 404.

Kody błędów

Kod	Znaczenie	Co zrobić
401	Brak lub nieprawidłowy klucz API	Sprawdź nagłówek Authorization i wartość BOT_API_KEY.
404	Nie znaleziono zlecenia lub nie jest w toku	Nie ponawiaj tego samego build_id — pobierz kolejne zlecenie.
422	Niepoprawne ciało żądania	Upewnij się, że pole `ok` jest typu boolean.
503	Funkcja nieaktywna	Sprawdź konfigurację serwera i logi usługi.

Format specyfikacji

Specyfikacja jest walidowana po stronie panelu i ponownie przez builder bota. Bezpieczeństwo jest nadrzędne wobec treści wygenerowanych przez model:

Uprawnienie administrator nigdy nie jest przyznawane automatycznie.
Kanały staffu są prywatne, a kanały informacyjne tylko do czytania.
Nazwy kanałów tekstowych są slugowane, tematy i embedy pozostają po polsku.
Modele: Start — Nemotron 3 Super, Pro — DeepSeek V4.1 Flash 1017, Studio — Kimi K3.1 Pro.
Nieudane generowanie nie zużywa limitu generacji; zużyte tokeny AI nadal obciążają budżet planu, jeśli wywołanie dotarło do modelu.

Tryb demo: bez klucza OpenRouter panel generuje deterministyczną specyfikację lokalnie. Służy do testów interfejsu i nie jest wysyłana do modelu.