API

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

REST-API Endpoints und HTMX-Integration für das Content Studio.

Controller	ContentController.php
Backend	web_generate.py
Base-URL	/content

Web-UI Endpoints (RESTful)

Methode	Route	Controller	Beschreibung
GET	/content	index()	Auftrags-Liste
GET	/content/new	contentNew()	Erstellungs-Formular
POST	/content	store()	Auftrag speichern
GET	/content/{id}	show()	Auftrags-Details
GET	/content/{id}/edit	edit()	Bearbeitungs-Formular

HTMX-Endpoints

Diese Endpoints liefern HTML-Fragmente für dynamische Updates.

Methode	Route	Controller	Response
POST	/content/{id}/generate	generate()	Polling-Partial
GET	/content/{id}/generation-status	generationStatus()	Status/Version-Partial
POST	/content/{id}/critique	critique()	Polling-Partial
GET	/content/{id}/critique-status	critiqueStatus()	Status/Critique-Partial
POST	/content/{id}/revise	revise()	Version-Partial
POST	/content/{id}/approve	approve()	Success-Alert + Reload
POST	/content/{id}/decline	decline()	Warning-Alert + Reload

Asynchroner Workflow (Polling)

Die Generierung und Kritik laufen asynchron. Der Ablauf ist:

POST /content/{id}/generate startet die Generierung und liefert ein Polling-Partial
Das Partial pollt via HTMX automatisch GET /content/{id}/generation-status
Bei Status generating: Polling-Partial mit Log wird zurückgegeben
Bei Status completed: Fertiges Version-Partial wird zurückgegeben
Bei Status failed: Fehler-Alert wird zurückgegeben

Gleiches Prinzip für Kritik:

POST /content/{id}/critique startet die Kritik
Polling via GET /content/{id}/critique-status

Status-Werte

Status	Bedeutung	Response
idle	Keine Operation aktiv	Leerer Response
generating / critiquing	Operation läuft	Polling-Partial mit Log
completed	Erfolgreich abgeschlossen	Ergebnis-Partial
failed	Fehlgeschlagen	Fehler-Alert

REST-API Endpoint

Methode	Route	Beschreibung
PUT	/api/v1/content/{id}	Auftrag aktualisieren

Generate-Endpoint

Request

POST /content/{id}/generate
Content-Type: application/x-www-form-urlencoded

model=anthropic&collection=documents&context_limit=5

Parameter

Parameter	Typ	Default	Beschreibung
model	string	anthropic	LLM-Backend (anthropic, ollama)
collection	string	documents	Qdrant-Collection
context_limit	int	5	Anzahl RAG-Chunks

Response (Polling-Partial)

<div hx-get="/content/{id}/generation-status"
     hx-trigger="every 2s"
     hx-swap="outerHTML">
  <div class="spinner">Generiere...</div>
  <pre class="log">...</pre>
</div>

Generation-Status Endpoint

Request

GET /content/{id}/generation-status

Response bei completed (Version-Partial)

<div class="version-content">
  <div class="version-header">
    <span class="version-number">Version 1</span>
    <span class="badge success">Generiert</span>
  </div>
  <div class="content-text">...</div>
  <div class="sources">...</div>
</div>

Critique-Endpoint

Request

POST /content/{id}/critique
Content-Type: application/x-www-form-urlencoded

model=anthropic

Response (Polling-Partial)

<div hx-get="/content/{id}/critique-status"
     hx-trigger="every 2s"
     hx-swap="outerHTML">
  <div class="spinner">Analysiere...</div>
</div>

Critique-Status Endpoint

Request

GET /content/{id}/critique-status

Response bei completed (Critique-Partial)

<div class="critique-results">
  <div class="critique-header">
    <span>Kritik-Runde 1</span>
    <span class="badge warning">Revision nötig</span>
  </div>
  <div class="critique-item failed">...</div>
</div>

Python-Backend

Die Controller-Methoden rufen web_generate.py via Shell auf:

python web_generate.py generate <order_id> [model] [collection] [limit]
python web_generate.py critique <version_id> [model] [order_id]
python web_generate.py revise <version_id> [model]

Hinweis: Der optionale [order_id] Parameter bei critique aktiviert Live-Logging in der Datenbank (critique_log, critique_step). Ohne order_id läuft die Kritik im synchronen Modus ohne Live-Updates.

API-Update (curl)

curl -X PUT https://dev.campus.systemische-tools.de/api/v1/content/1 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Blogpost über Teamcoaching",
    "briefing": "Schreibe einen informativen Artikel..."
  }'

Fehlerbehandlung

Bei Fehlern wird ein HTML-Alert zurückgegeben:

<div class="alert error">Fehler: [Fehlermeldung]</div>