API-Referenz¶

Diese Seite dokumentiert ausgewählte REST-API-Endpunkte des LLARS-Backends. Die vollständige Liste findest du in app/routes/ sowie app/routes/registry.py.

Base URL

Alle Endpunkte sind relativ zur Base URL: http://localhost:55080/api

Authentifizierung¶

Alle API-Endpunkte (außer /auth/*) erfordern einen gültigen JWT-Token im Authorization-Header:

Authorization: Bearer <access_token>

Token erhalten¶

POST /auth/login

Wird über Authentik OAuth2/OIDC Flow gehandhabt. Siehe Authentik Setup.

Chatbot API¶

Chatbots¶

Liste aller Chatbots¶

GET /api/chatbots

Response:

{
  "success": true,
  "chatbots": [
    {
      "id": 1,
      "name": "Support Bot",
      "description": "Kundensupport Assistent",
      "is_published": true,
      "owner_id": 1,
      "created_at": "2025-12-01T10:00:00Z"
    }
  ]
}

Chatbot erstellen¶

POST /api/chatbots
Content-Type: application/json

{
  "name": "Neuer Bot",
  "description": "Beschreibung",
  "llm_model_id": 1,
  "system_prompt": "Du bist ein hilfreicher Assistent."
}

Response: 201 Created

Chatbot Details¶

GET /api/chatbots/{id}

Chatbot aktualisieren¶

PATCH /api/chatbots/{id}
Content-Type: application/json

{
  "name": "Aktualisierter Name",
  "description": "Neue Beschreibung"
}

Chatbot löschen¶

DELETE /api/chatbots/{id}

Chat-Nachrichten¶

Nachricht senden¶

POST /api/chatbots/{id}/chat
Content-Type: application/json

{
  "message": "Hallo, wie kann ich dir helfen?",
  "session_id": "unique-session-id",
  "conversation_id": null,
  "include_sources": true
}

Response (Streaming):

data: {"delta": "Hallo"}
data: {"delta": "! Ich"}
data: {"delta": " kann"}
data: {"done": true, "sources": [...], "conversation_id": 1}

Konversation abrufen¶

GET /api/chatbots/{id}/conversations/{conversation_id}

Response:

{
  "success": true,
  "conversation": {
    "id": 1,
    "title": "Erste Unterhaltung",
    "messages": [
      {"role": "user", "content": "Hallo"},
      {"role": "assistant", "content": "Hallo! Wie kann ich helfen?"}
    ]
  }
}

RAG API¶

Collections¶

Alle Collections¶

GET /api/rag/collections

Query-Parameter: - include_stats (bool): Chunk-Statistiken einschließen

Collection erstellen¶

POST /api/rag/collections
Content-Type: application/json

{
  "name": "Wissensbasis",
  "description": "Dokumente für Kundensupport"
}

Collection Details¶

GET /api/rag/collections/{id}

Collection löschen¶

DELETE /api/rag/collections/{id}

Dokumente¶

Dokument hochladen¶

POST /api/rag/documents
Content-Type: multipart/form-data

file: <binary>
collection_id: 1

Response:

{
  "success": true,
  "document": {
    "id": 1,
    "filename": "handbuch.pdf",
    "status": "pending",
    "mime_type": "application/pdf"
  }
}

Dokument-Status¶

GET /api/rag/documents/{id}

Response:

{
  "success": true,
  "document": {
    "id": 1,
    "filename": "handbuch.pdf",
    "status": "indexed",
    "chunk_count": 45,
    "processed_at": "2025-12-01T10:05:00Z"
  }
}

Dokument löschen¶

DELETE /api/rag/documents/{id}

Suche¶

Semantische Suche¶

POST /api/rag/search
Content-Type: application/json

{
  "query": "Wie setze ich mein Passwort zurück?",
  "collection_ids": [1, 2],
  "top_k": 5,
  "include_content": true
}

Response:

{
  "success": true,
  "results": [
    {
      "document_id": 1,
      "chunk_index": 12,
      "content": "Um Ihr Passwort zurückzusetzen...",
      "score": 0.89,
      "metadata": {
        "filename": "handbuch.pdf",
        "page_number": 5
      }
    }
  ]
}

Judge API¶

Sessions¶

Alle Sessions¶

GET /api/judge/sessions

Session erstellen¶

POST /api/judge/sessions
Content-Type: application/json

{
  "name": "GPT-4 vs Claude Vergleich",
  "pillar_ids": [1, 2, 3],
  "sampling_strategy": "random",
  "sample_size": 50
}

Session starten¶

POST /api/judge/sessions/{id}/start

Session pausieren¶

POST /api/judge/sessions/{id}/pause

Session-Statistiken¶

GET /api/judge/sessions/{id}/stats

Pillars (Bewertungskriterien)¶

Alle Pillars¶

GET /api/judge/pillars

Response:

{
  "success": true,
  "pillars": [
    {
      "id": 1,
      "name": "Relevanz",
      "description": "Wie relevant ist die Antwort für die Frage?",
      "weight": 1.0
    }
  ]
}

Admin API¶

System-Einstellungen¶

Alle Einstellungen¶

GET /api/admin/settings

Permission: admin:settings:view

Einstellung aktualisieren¶

PATCH /api/admin/settings/{key}
Content-Type: application/json

{
  "value": "new_value"
}

Permission: admin:settings:edit

Analytics¶

Analytics-Einstellungen¶

GET /api/admin/analytics/settings
PATCH /api/admin/analytics/settings

Benutzer¶

Alle Benutzer¶

GET /api/admin/users

Query-Parameter: - page (int): Seitennummer - per_page (int): Einträge pro Seite - search (string): Suchbegriff

Benutzer-Permissions¶

GET /api/admin/users/{id}/permissions
PATCH /api/admin/users/{id}/permissions

User API¶

Profil¶

Eigenes Profil¶

GET /api/users/me

Profil aktualisieren¶

PATCH /api/users/me/settings
Content-Type: application/json

{
  "collab_color": "#b0ca97",
  "avatar_seed": "random-seed"
}

Avatar hochladen¶

POST /api/users/me/avatar
Content-Type: multipart/form-data

file: <image>

Error Responses¶

Standard-Fehlerformat¶

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": {}
  }
}

HTTP-Status-Codes¶

Code	Bedeutung
200	OK
201	Created
400	Bad Request (Validierungsfehler)
401	Unauthorized (Kein Token)
403	Forbidden (Keine Berechtigung)
404	Not Found
409	Conflict
500	Internal Server Error

Rate Limiting¶

Rate Limiting ist via flask-limiter implementiert.

Modus	Standard-Limit
Development	1000 Requests/Stunde
Production	500 Requests/Stunde

Endpunkt-spezifische Limits können in app/main.py konfiguriert werden. Bei Überschreitung wird HTTP 429 (Too Many Requests) zurückgegeben.

WebSocket-Endpunkte¶

Für Echtzeit-Updates siehe WebSocket API.