API

Die API der Web-App ist mit API Platform gebaut und spricht JSON-LD unter /api. Die interaktive Dokumentation liegt unter agent-tools.elkuku.dev/api/docs; Admins finden einen Token für deren Schaltfläche Authorize auf ihrer Profilseite.

Authentifizierung

Jede Anfrage außer GET /api/links braucht einen Google-ID-Token, der für den Web-OAuth-Client ausgestellt ist:

Authorization: Bearer <Google ID token>

Unbekannte Google-Konten werden bei ihrer ersten Anfrage als Benutzer registriert. Fehler kommen als application/problem+json mit einem detail, auch der 401 bei fehlendem oder ungültigem Token.

Endpunkte

Methode	Pfad	Was
GET	/api/me	Der angemeldete Benutzer: ID, Kennung, Rolle, Agentenname, Avatar, Sondermedaillen, sichtbare Teile, Bannergress-Synchronisierung.
PATCH	/api/me	JSON Merge Patch (application/merge-patch+json) von Agentenname, Sondermedaillen, sichtbaren Teilen und Bannergress-Synchronisierung.
GET	/api/agent-stats	Die eigenen Statistiken des Benutzers, alle, die neuesten zuerst.
GET	/api/agent-stats/{id}	Eine der Statistiken des Benutzers.
POST	/api/agent-stats	Statistiken speichern (201; 409 für dasselbe Datum mit derselben Uhrzeit; 422 für Statistiken eines anderen Agenten).
GET, POST	/api/timeline-events	Die eigenen Zeitleisten-Ereignisse des Benutzers; eines hinzufügen.
PATCH, DELETE	/api/timeline-events/{id}	Ein eigenes Ereignis ändern oder löschen (422 für sich überschneidende Reisen).
GET	/api/done-banners	Die erledigten Banner des Benutzers.
PATCH	/api/done-banners/{id}	Den Tag setzen, an dem ein eigenes Banner erledigt wurde.
GET	/api/agents	Die Agenten, die ihr Profil zeigen.
GET	/api/agents/{agentName}	Ein Agent mit den Teilen, die er zeigt (404, wenn privat).
GET	/api/users	Admins: alle Benutzer und was sie zeigen.
GET	/api/links	Die Linkliste: Abschnitte mit ihren Links (title, url, description). Ohne Token; eine Stunde gecacht.

Statistiken speichern

Der Body hat die Spaltennamen von agent_stat der 4e-website:

{
  "datetime": "2026-10-19 15:35:56",
  "nickname": "TestAgent",
  "faction": "Enlightened",
  "level": 16,
  "ap": 243517130,
  "explorer": 27659,
  "…": "…"
}

curl -X POST https://agent-tools.elkuku.dev/api/agent-stats \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/ld+json" \
  -d @stats.json

Sondermedaillen

GET und PATCH /api/me enthalten die Sondermedaillen im Format der 4e-website:

{ "anomaly": { "orion": "platinum" }, "annual": { "voyager": 5 }, "event": { "…": "…" } }

Ein PATCH ersetzt die Gruppen, die er sendet, und behält die anderen.