================================================================================
ScottGPT - Externe Chat-API
================================================================================

Basis-URL:     https://scottgpt.eu/api/
Dokumentation: https://scottgpt.eu/API-EXTERN.txt
Admin-Keys:    https://scottgpt.eu/admin.html  -> Tab "Externe API"

WICHTIG - 404 vermeiden:
  - Nur POST verwenden (GET im Browser liefert 404 oder 405)
  - Vollstaendige URL inkl. Endpunkt:
      POST https://scottgpt.eu/api/v1/chat/anonymous
      POST https://scottgpt.eu/api/v1/chat/steam
  - Header: Content-Type: application/json
  - Body: gueltiges JSON mit Feld "message"
  - API-Uebersicht per GET: https://scottgpt.eu/api/v1/chat

================================================================================
1. UEBERSICHT
================================================================================

Die externe API erlaubt Chat-Anfragen an ScottGPT von anderen Websites, Bots
oder Diensten. Gleiche Verarbeitung wie der Web-Chat:

  - RAG-Suche (indexierte Wiki-/Quellen-Eintraege)
  - optional Web-Recherche
  - Antwort via Ollama-Sprachmodell
  - Quellenangaben in der Antwort

Zwei Endpunkte:

  A) Mit Steam-ID  -> API-Key PFLICHT + steam_id im Body
  B) Anonym        -> KEIN API-Key (oeffentlich)

Beide werden im Admin unter "Externe API" -> "API-Anfragen" geloggt.

================================================================================
2. API-KEY (nur Endpunkt A - Steam)
================================================================================

Format:     sgpt_<48 hexadezimale Zeichen>
Beispiel:   sgpt_a1b2c3d4e5f6789012345678abcdef01234567890abcdef01

Erstellung: Admin -> Externe API -> "API-Key anlegen"
            Der vollstaendige Key wird NUR EINMAL beim Erstellen angezeigt.

Uebermittlung (eine Variante):

  Header:  X-API-Key: sgpt_...
  oder
  Header:  Authorization: Bearer sgpt_...

Deaktivierung: Admin -> API-Key -> "Deaktivieren"

Der anonyme Endpunkt (B) benoetigt KEINEN API-Key.

================================================================================
3. ENDPUNKT A - CHAT MIT STEAM-ID (API-Key erforderlich)
================================================================================

URL:          POST https://scottgpt.eu/api/v1/chat/steam
Auth:         API-Key PFLICHT
Content-Type: application/json

Request-Body (JSON):
{
  "message": "Wie viel Geld darf ich bei einer Geiselnahme fordern?",
  "steam_id": "76561198012345678"
}

Felder:
  message   (string, Pflicht)  Frage an ScottGPT (max. ca. 8000 Zeichen)
  steam_id  (string, Pflicht)  17-stellige SteamID64 (beginnt mit 7656...)

Response 200 (JSON):
{
  "ok": true,
  "request_id": 42,
  "request_type": "steam",
  "steam_id": "76561198012345678",
  "display_name": "Michael Scott",
  "answer": "Bei einer Geiselnahme darf maximal 250.000,00 EUR je Geisel ..."
}

Hinweis: Die API-Antwort enthaelt absichtlich keine Quellenangaben (sources).
Quellen werden intern nur fuer das Admin-Protokoll gespeichert.

Ohne gueltigen API-Key: HTTP 401

================================================================================
4. ENDPUNKT B - ANONYMER CHAT (ohne Authentifizierung)
================================================================================

URL:          POST https://scottgpt.eu/api/v1/chat/anonymous
Auth:         KEINE - oeffentlich
Content-Type: application/json

Request-Body (JSON):
{
  "message": "Was ist das AGLP auf LostParadise?"
}

Felder:
  message  (string, Pflicht)  Die Frage an ScottGPT

Response 200 (JSON):
{
  "ok": true,
  "request_id": 43,
  "request_type": "anonymous",
  "answer": "Das AGLP ist das Allgemeine Gesetzbuch ..."
}

Hinweis: Keine Quellenangaben (sources) in der API-Antwort.

================================================================================
5. FEHLERANTWORTEN
================================================================================

HTTP 404 - Falsche URL oder GET statt POST:
  Falsch: https://scottgpt.eu/api/v1/chat
  Falsch: GET https://scottgpt.eu/api/v1/chat/anonymous
  Richtig: POST https://scottgpt.eu/api/v1/chat/anonymous

HTTP 405 - GET auf Endpunkt (Hinweis statt 404):
  { "detail": "Nur POST erlaubt. ..." }

HTTP 401 - API-Key fehlt/ungueltig (nur Steam-Endpunkt):
  { "detail": "Ungueltiger oder fehlender API-Key" }

HTTP 400 - Validierung:
  { "detail": "Nachricht fehlt" }
  { "detail": "Ungueltige steam_id (17-stellige SteamID64, z. B. 76561198...)" }

HTTP 500 - Serverfehler (z. B. Ollama nicht erreichbar)

================================================================================
6. BEISPIELE (copy & paste)
================================================================================

--- cURL: Anonym (ohne API-Key) ---
curl -X POST "https://scottgpt.eu/api/v1/chat/anonymous" \
  -H "Content-Type: application/json" \
  -d "{\"message\":\"Was ist LostParadise?\"}"

--- cURL: Steam (mit API-Key) ---
curl -X POST "https://scottgpt.eu/api/v1/chat/steam" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sgpt_DEIN_API_KEY_HIER" \
  -d "{\"message\":\"Was ist LostParadise?\",\"steam_id\":\"76561198012345678\"}"

--- JavaScript (fetch) - Anonym ---
const response = await fetch("https://scottgpt.eu/api/v1/chat/anonymous", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Was ist LostParadise?" }),
});
const data = await response.json();
console.log(data.answer);

--- JavaScript (fetch) - Steam ---
const response = await fetch("https://scottgpt.eu/api/v1/chat/steam", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "sgpt_DEIN_API_KEY_HIER",
  },
  body: JSON.stringify({
    message: "Erklaere die Serverregeln zu Geiselnahmen.",
    steam_id: "76561198012345678",
  }),
});
const data = await response.json();

--- Python (requests) - Anonym ---
import requests

resp = requests.post(
    "https://scottgpt.eu/api/v1/chat/anonymous",
    headers={"Content-Type": "application/json"},
    json={"message": "Was ist das AGLP?"},
    timeout=180,
)
print(resp.json()["answer"])

--- Python (requests) - Steam ---
import requests

resp = requests.post(
    "https://scottgpt.eu/api/v1/chat/steam",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "sgpt_DEIN_API_KEY_HIER",
    },
    json={
        "message": "Wie funktioniert das Paycheck-System?",
        "steam_id": "76561198012345678",
    },
    timeout=180,
)
print(resp.json()["answer"])

--- PHP - Anonym ---
<?php
$ch = curl_init("https://scottgpt.eu/api/v1/chat/anonymous");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 180,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["message" => "Was ist LostParadise?"]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
echo $data["answer"] ?? "Fehler";

--- PHP - Steam ---
<?php
$ch = curl_init("https://scottgpt.eu/api/v1/chat/steam");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 180,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-Key: sgpt_DEIN_API_KEY_HIER",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "message" => "Was ist LostParadise?",
        "steam_id" => "76561198012345678",
    ]),
]);
$raw = curl_exec($ch);
curl_close($ch);
$data = json_decode($raw, true);
echo $data["answer"] ?? "Fehler";

================================================================================
7. CORS
================================================================================

/api/v1/* erlaubt CORS: Access-Control-Allow-Origin: *
Fuer Server-zu-Server-Aufrufe ist CORS irrelevant.

================================================================================
8. TIMEOUT
================================================================================

Chat-Anfragen koennen 30-180 Sekunden dauern (RAG + LLM).
Clients: Timeout mindestens 180 Sekunden setzen.

================================================================================
9. ADMIN-LOGGING
================================================================================

Alle API-Anfragen: Admin -> Externe API -> API-Anfragen
  - Typ Steam / Anonym
  - Steam-ID und Name (bei Steam)
  - API-Key oder "Oeffentlich" (bei anonym)

================================================================================
10. SICHERHEIT
================================================================================

  - API-Keys nur fuer Steam-Endpunkt
  - Keys nie im oeffentlichen Frontend-JavaScript
  - Keys nur serverseitig verwenden
  - Deaktivierte Keys werden sofort abgelehnt
  - Anonym oeffentlich - Missbrauch im Admin-Log nachverfolgbar

================================================================================
Stand: Juli 2026 | ScottGPT | https://scottgpt.eu/
================================================================================