AISSIST Dokumentation

🛠️ API & Entwicklung ​

Dieser Bereich richtet sich an Entwickler:innen, die AISSIST über die API integrieren.

🔗 Swagger / API Dokumentation ​

Die vollständige interaktive API-Referenz ist über Swagger UI erreichbar:

#

Die Swagger-Dokumentation deckt alle REST-Endpunkte ab und enthält Beispiele für Request/Response-Strukturen, Authentifizierung sowie Fehler-Codes.

🤖 Agents API Dokumentation ​

Die Dokumentation der Agent-API (General Purpose Agent) ist separat verfügbar:

https://aissist-backend.bv.burda.com/agents/docs

Diese Dokumentation beschreibt die Endpunkte für die Nutzung von Agenten.

🔐 Zugriff erhalten ​

Der Zugriff auf die AISSIST API erfolgt über JWT Tokens, die im Authorization-Header als Bearer-Token gesendet werden müssen.

Beispiel für den HTTP-Header:

Authorization: Bearer <JWT_TOKEN>.

  • Der JWT Token enthält die Berechtigungen (Scopes/Rollen), die deine Anwendung für den Aufruf der jeweiligen Endpunkte benötigt.
  • Einen JWT Token mit den entsprechenden Rechten kannst du bei deinem jeweiligen AISSIST-Ansprechpartner im Unternehmen beantragen.
  • Bewahre den Token sicher auf und gib ihn nicht in Client-seitigem Code oder öffentlich zugänglichen Repositories weiter.

🔑 AISSIST API – Temporären JWT-Token für Swagger-Tests extrahieren ​

Ziel: Mit einem temporären Access Token können API-Endpunkte direkt über die Swagger-Dokumentation auf dem Produktiv-System getestet werden. Für die Erweiterung der Rechte der dauerhaften produktiven Token der jeweiligen Appliationen ist immer eine separate Freischaltung erforderlich.

1. Relevante Systeme ​

2. Grundsätzlicher Ablauf ​

  1. Testing und Entwicklung erfolgen mit einem temporären Token auf dem Produktiv-System.
  2. Der temporäre Token wird aus dem angemeldeten Frontend extrahiert und in Swagger verwendet.
  3. Sollen einzelne Endpunkte in produktiven Applikationen genutzt werden, müssen diese gezielt freigeschaltet und berechtigt werden.

Freischaltung für produktive Nutzung ​

Wichtig

Für produktive Endpunkte ist eine Anfrage über die zentralen Burda Forward Ansprechpartner erforderlich.

In der Anfrage sollten mindestens enthalten sein:

  • Name des produktiven Tokens
  • Gewünschter Endpunkt bzw. gewünschte Endpunkte
  • Gewünschter Termin für die Freischaltung (empfohlen: mindestens zwei Wochen Vorlauf)

3. Temporären JWT-Token extrahieren ​

  1. Am Frontend anmelden.
  2. Entwicklerwerkzeuge öffnen: Per Rechtsklick und „Untersuchen“. Je nach Browser kann die Bezeichnung leicht abweichen.
  3. Token kopieren: Im Tab „Application“ (Anwendung) im Bereich „Cookies“ die jeweilige Applikation auswählen und den Wert des accessToken kopieren.
  4. In Swagger nutzen: Den kopierten Token in der Swagger-Dokumentation oben über Authorize einfügen.

Damit werden ca. 95 % der bestehenden API-Endpunkte temporär freigeschaltet und können direkt getestet werden.

Gültigkeit

Der extrahierte Access Token ist maximal zwei Stunden gültig.

temporary_api_access_token.png

📊 Technische Limits ​

Die AISSIST API ist durch verschiedene technische Limits geschützt, um Stabilität und faire Nutzung sicherzustellen.

Request Limits (Rate Limiting) ​

Aktuell gelten folgende Standardlimits pro Nutzer:

  • maximal 120 Anfragen pro Minute
  • maximal 4.800 Anfragen pro Stunde

Diese Rate-Limiting-Policy ist aktiv und wird automatisch enforced.

  • Pro Client / API-Key / Benutzerkonto gelten diese Request-Limits pro Zeitfenster.
  • Bei Überschreitung der Limits kann es zu folgenden Antworten kommen:
    • HTTP 429 – Too Many Requests

Payload-Größen ​

  • Für Requests (insbesondere bei Datei-Uploads oder umfangreichen JSON-Bodies) gibt es ein maximales Payload-Limit von 1 GB.
  • Überschreitet ein Request dieses Limit, kann die API mit HTTP 413 – Payload Too Large antworten

Timeouts & Antwortzeiten ​

  • Requests, die länger als der aktuell definierte Timeout von 300s benötigen, können abgebrochen werden.
  • Plane in deinem Client:
    • Robuste Fehlerbehandlung (Timeouts, Retries mit Backoff).
    • Geeignete eigene Client-Timeouts, die zur API passen.

Best Practices im Umgang mit Limits ​

  • Implementiere Client-seitiges Caching, wo sinnvoll.
  • Logge 429- und 5xx-Fehler, um mögliche Limit-Überschreitungen früh zu erkennen.
  • Sprich bei dauerhaft hohen Lasten deinen AISSIST-Ansprechpartner an, um geeignete Kontingente oder Anpassungen zu klären.

📋 API-Änderungen je Version ​

Versionsbegleitende API-Änderungen sind jeweils in einer eigenen Seite dokumentiert