API-Referenz

voiceagent REST-API

47 oeffentliche Endpoints aus app/api/*. Jede Route mit Request- und Response-Beispiel sowie einem Try-it-Button, der einen kopierbaren cURL-Snippet generiert. Source-of-Truth bleibt die jeweilige route.ts.

Strukturierte Quelle: lib/api/endpoints.ts - Ergaenze dort einen Eintrag, wenn eine neue Route dazukommt.

Voice (6)

Voice-Pipeline: Call eroeffnen, Audio-Chunks streamen, Call beenden, Persona-Greeting, NPS.

POST/api/voice/start#

Oeffnet einen neuen VoiceCall-Eintrag und gibt dessen ID zurueck.

Request

{
  "branch": "shop",
  "flowId": "optional flow id"
}

Response

{
  "callId": "ck0123abc...",
  "startedAt": "2026-05-18T09:32:11.123Z"
}

POST/api/voice/audio#

Ein Audio-Chunk durch die volle Pipeline (Whisper -> Claude+Tools -> ElevenLabs).

Multipart-Upload. maxDuration=60s.

Request

multipart/form-data
  audio:  File (webm/opus)
  callId: string
  branch: "shop" | "b2b" | "dienstleister"

Response

{
  "transcript": { "user": "...", "agent": "..." },
  "audioBase64": "...",
  "toolCalls": [
    { "name": "shop_get_order", "input": { "orderNumber": "1042" }, "result": { ... } }
  ],
  "latencyMs": 1820
}

POST/api/voice/end#

Schliesst den Call ab. Schreibt durationMs / latencyMs / WER (wenn Reference-Transcript dabei).

Request

{
  "callId": "ck0123abc...",
  "taskCompleted": true,
  "referenceTranscript": "optional reference"
}

Response

{ "ok": true, "durationMs": 32100, "wer": 0.07 }

POST/api/voice/nps#

Speichert NPS-Score (0-10) + optionalen Kommentar nach Call-Ende.

Request

{ "callId": "ck0123abc...", "score": 9, "comment": "klappt" }

Response

{ "ok": true }

POST/api/voice/greeting#

Synthetisiert die Persona-Greeting-Zeile via ElevenLabs (mp3, base64).

Budget-Check absichtlich skipped (~0.001 EUR/Call).

Request

{ "branch": "shop" }

Response

{
  "persona": { "id": "lara", "name": "Lara", "tone": "freundlich", "greetingText": "..." },
  "audioBase64": "...",
  "mimeType": "audio/mpeg"
}

GET/api/voice/calls?branch=shop&limit=50#

Liste der letzten VoiceCalls fuer /admin und /eval.

limit max 500. Beide Query-Params optional.

Kein Body — Parameter via URL / Cookies.

Response

[
  {
    "id": "ck0123abc",
    "branch": "ECOMMERCE",
    "durationMs": 32100,
    "latencyMs": 1820,
    "startedAt": "2026-05-18T09:32:11.123Z"
  }
]

Connectors (8)

Tool-Dispatch fuer Mock-Shop, Demo-ERP, Calendar, Gmail und Mailbox. Wird von der Voice-Pipeline und vom Flow-Builder genutzt.

POST/api/connectors/mockshop#

Fuehrt eines der shop_*-Tools aus. Read by default, Write nur mit Permissions.

Request

{
  "toolName": "shop_get_order",
  "args": { "orderNumber": "1042" },
  "permissions": { "canRead": true, "canWrite": false }
}

Response

{
  "ok": true,
  "result": { "orderNumber": "1042", "status": "SHIPPED", "totalEur": 49.9 }
}

POST/api/connectors/mockshop/admin#

Vier Shop-Admin-Tools (Search / Invoice / Overdue / UpdateNote).

Request

{ "toolName": "shop_admin_list_overdue_invoices", "args": {} }

Response

{ "ok": true, "result": [ { "orderNumber": "1042", "overdueDays": 14 } ] }

POST/api/connectors/erp#

Demo-ERP / B2B-Tools (Customer, Order, Tickets).

Request

{
  "toolName": "erp_create_ticket",
  "args": { "customerId": "c1", "subject": "Lieferung verspaetet", "priority": "HIGH" },
  "permissions": { "canRead": true, "canWrite": true }
}

Response

{ "ok": true, "result": { "ticketId": "t-123", "status": "OPEN" } }

POST/api/connectors/erp/lager#

Fuenf Inventory-fokussierte ERP-Tools (Check / LowStock / Reserve / Release / Adjust).

Request

{ "toolName": "erp_inventory_check", "args": { "sku": "SKU-1" } }

Response

{ "ok": true, "result": { "sku": "SKU-1", "available": 42, "reserved": 3 } }

POST/api/connectors/calendar#

Calendar-Tools (Available / Book / Reschedule / Upcoming).

Request

{ "action": "book", "input": { "slotId": "2026-05-20T10:00" } }

Response

{ "ok": true, "result": { "meetingId": "m-7", "startsAt": "2026-05-20T10:00:00Z" } }

POST/api/connectors/gmailSession#

Gmail-Tools (Send / ListRecent / Search). Echter OAuth-Connector.

Request

{ "action": "search", "input": { "query": "from:alice@example.com newer_than:7d" } }

Response

{
  "ok": true,
  "result": [
    { "id": "msg_123", "subject": "Re: Angebot", "from": "alice@example.com" }
  ]
}

POST/api/connectors/mailbox#

Demo-Mailbox-Tools (List / Get / Search / Reply / Mark / Archive / Star).

Request

{
  "toolName": "mailbox_send_reply",
  "args": { "threadId": "thread_1", "body": "Danke fuer Ihre Nachricht..." }
}

Response

{ "ok": true, "result": { "messageId": "msg_456" } }

POST/api/connectors/[type]/activateSession#

Setzt einen Mock-Connector (mockshop / erp / calendar) im Onboarding auf CONNECTED.

Kein Body. type kommt aus der URL. Gmail laeuft separat via OAuth.

Kein Body — Parameter via URL / Cookies.

Response

{ "ok": true, "type": "MOCK_SHOP", "status": "CONNECTED" }

Shop (6)

Cookie-basierter Warenkorb + Demo-Checkout. Schreibt in dieselbe Tabelle, aus der die Shop-Tools lesen.

GET/api/shop/cart#

Aktuelle CartView (read-only, Cookie-basiert).

Kein Body — Parameter via URL / Cookies.

Response

{
  "items": [
    { "sku": "SKU-1", "title": "Espresso 1kg", "quantity": 2, "priceEur": 12.5 }
  ],
  "totalEur": 25
}

POST/api/shop/cart/add#

Item zum Cart hinzufuegen.

Request

{ "sku": "SKU-1", "quantity": 2 }

Response

{ "items": [ { "sku": "SKU-1", "quantity": 2 } ], "totalEur": 25 }

POST/api/shop/cart/update#

Menge fuer eine SKU setzen. quantity=0 entfernt das Item.

Request

{ "sku": "SKU-1", "quantity": 3 }

Response

{ "items": [ { "sku": "SKU-1", "quantity": 3 } ], "totalEur": 37.5 }

POST/api/shop/cart/remove#

SKU komplett aus dem Cart entfernen.

Request

{ "sku": "SKU-1" }

Response

{ "items": [], "totalEur": 0 }

POST/api/shop/cart/clear#

Cart komplett leeren.

Kein Body — Parameter via URL / Cookies.

Response

{ "items": [], "totalEur": 0 }

POST/api/shop/checkout#

Demo-Checkout. Schreibt Order + OrderItems und leert den Cart.

Request

{
  "customerName": "Anna Beispiel",
  "email": "anna@example.com",
  "address": "Musterstrasse 1, 80331 Muenchen"
}

Response

{ "orderNumber": "1042" }

Mailbox (5)

Demo-Webmail-UI Endpoints. Gleicher Datentopf wie die mailbox_* MCP-Tools.

GET/api/demo/mailbox/list#

Mailbox-Snapshot (Threads + Stats). Vom UI alle 15s gepollt.

Kein Body — Parameter via URL / Cookies.

Response

{
  "threads": [ { "id": "thread_1", "subject": "Angebot", "unread": true } ],
  "stats": { "unread": 3, "total": 27 }
}

GET/api/demo/mailbox/thread?id=thread_1#

Einzelnen Thread inklusive aller Messages laden.

Kein Body — Parameter via URL / Cookies.

Response

{
  "id": "thread_1",
  "subject": "Angebot",
  "messages": [ { "id": "msg_1", "from": "alice@example.com", "body": "..." } ]
}

POST/api/demo/mailbox/reply#

Antwort an einen Thread senden.

Request

{ "threadId": "thread_1", "body": "Vielen Dank fuer Ihre Anfrage..." }

Response

{ "ok": true, "messageId": "msg_789" }

POST/api/demo/mailbox/archive#

Thread archivieren.

Request

{ "threadId": "thread_1" }

Response

{ "ok": true }

POST/api/demo/mailbox/star#

Stern fuer einen Thread setzen / entfernen.

Request

{ "threadId": "thread_1", "starred": true }

Response

{ "ok": true }

Eval & Cost (6)

Auswertung der Bachelor-Studie (Stats, WER, NPS) + Cost-Tracking gegen das Monatsbudget.

GET/api/eval/stats?branch=shop&dateFrom=2026-05-01&dateTo=2026-05-31#

Aggregierte Stats (mean latency, WER, NPS, Task-Completion).

Kein Body — Parameter via URL / Cookies.

Response

{
  "count": 42,
  "meanLatencyMs": 1820,
  "meanWer": 0.08,
  "npsScore": 8.4,
  "taskCompletionRate": 0.93
}

GET/api/eval/calls?branch=shop&page=1&pageSize=20#

Paginierte Liste der Calls fuer /eval.

Kein Body — Parameter via URL / Cookies.

Response

{
  "data": [
    { "id": "ck01", "startedAt": "2026-05-18T09:32:11Z", "latencyMs": 1820, "nps": 9 }
  ],
  "total": 42
}

GET/api/eval/calls/[id]#

Vollstaendige Call-Details (Transcript + Tool-Calls).

Kein Body — Parameter via URL / Cookies.

Response

{
  "id": "ck01",
  "transcript": [ { "speaker": "user", "text": "..." } ],
  "toolCalls": [ { "name": "shop_get_order", "result": {} } ],
  "nps": { "score": 9, "comment": "klappt" }
}

GET/api/eval/export?branch=shop#

CSV-Export fuer den BA-Appendix.

Kein Body — Parameter via URL / Cookies.

Response

text/csv

id,startedAt,branch,durationMs,latencyMs,wer,taskCompleted,npsScore,npsComment,toolCallsCount
ck01,2026-05-18T09:32:11Z,ECOMMERCE,32100,1820,0.07,true,9,klappt,3

GET/api/eval/tool-counts?branch=shop&days=30#

Aggregierte Tool-Call-Haeufigkeiten (fuer Eval-Bar-Charts).

Kein Body — Parameter via URL / Cookies.

Response

{
  "counts": [
    { "toolName": "shop_get_order", "count": 18 },
    { "toolName": "shop_request_return", "count": 4 }
  ]
}

GET/api/cost#

Monatsverbrauch (EUR) und verbleibendes Budget, per Provider.

Kein Body — Parameter via URL / Cookies.

Response

{
  "monthlyEur": 7.42,
  "budgetEur": 40,
  "remainingEur": 32.58,
  "percentage": 18.55,
  "byProvider": { "anthropic": 5.2, "elevenlabs": 1.8, "openai_whisper": 0.42 }
}

Flows (5)

CRUD fuer Flow-Definitionen (Reactflow-Graphen) und ihre Tool-Permissions.

GET/api/flowsSession#

Liste aller Flows (Presets + Custom).

Kein Body — Parameter via URL / Cookies.

Response

[
  {
    "id": "flow_1",
    "name": "Shop Standard",
    "branch": "ECOMMERCE",
    "isPreset": false,
    "updatedAt": "2026-05-18T09:32:11Z"
  }
]

POST/api/flowsSession#

Neuen Flow anlegen.

Request

{
  "name": "Mein Flow",
  "branch": "shop",
  "graph": { "nodes": [], "edges": [] },
  "permissions": []
}

Response

{ "id": "flow_42", "name": "Mein Flow" }

GET/api/flows/[id]Session#

Einzelnen Flow inkl. Permissions laden.

Kein Body — Parameter via URL / Cookies.

Response

{
  "id": "flow_42",
  "name": "Mein Flow",
  "graph": { "nodes": [], "edges": [] },
  "permissions": []
}

PUT/api/flows/[id]Session#

Flow ueberschreiben (Graph + Permissions).

Request

{
  "name": "Mein Flow v2",
  "graph": { "nodes": [], "edges": [] },
  "permissions": []
}

Response

{ "ok": true }

DELETE/api/flows/[id]Session#

Flow inkl. Permissions loeschen.

Kein Body — Parameter via URL / Cookies.

Response

{ "ok": true }

Auth & Account (6)

Magic-Link Callback, Test-Login, Sign-out und Account-Operationen (Profil, Avatar, Soft-Delete).

GET/api/auth/callback?code=...&next=/onboarding#

Magic-Link / OAuth-Callback. Tauscht code gegen Session-Cookies.

Kein Body — Parameter via URL / Cookies.

Response

302 -> next

POST/api/auth/signout?next=/Session#

Aktuelle Supabase-Session beenden.

Kein Body — Parameter via URL / Cookies.

Response

302 -> next

POST/api/account/profileSession#

Display-Name + Avatar des eigenen Profils aktualisieren.

Request

{ "displayName": "Philipp", "avatarUrl": "https://..." }

Response

{ "ok": true, "profile": { "displayName": "Philipp", "avatarUrl": "..." } }

POST/api/account/avatarSession#

Avatar-Bild als data: URI im Profil speichern (max 1 MB).

Request

multipart/form-data
  file: File (image/jpeg|image/png|image/webp)

Response

{ "ok": true, "avatarUrl": "data:image/png;base64,..." }

POST/api/account/deleteSession#

Soft-Delete des Profils + Hard-Delete in auth.users (wenn Service-Role-Key gesetzt).

Kein Body — Parameter via URL / Cookies.

Response

{ "ok": true }

System (5)

Health-Snapshot, SSE-Realtime-Bus, Onboarding-Flag, Client-Error-Logging, Demo-Reset.

GET/api/health#

Health-Snapshot (200 ok / 503 degraded).

Kein Body — Parameter via URL / Cookies.

Response

{
  "ok": true,
  "checks": [
    { "name": "postgres", "status": "ok", "latencyMs": 4 },
    { "name": "anthropic", "status": "ok" }
  ]
}

GET/api/realtime?channel=shop&channel=erp#

Server-Sent-Events Stream. Channel-Param wiederholbar (oder '*').

Kein Body — Parameter via URL / Cookies.

Response

text/event-stream

event: tool.executed
data: { "toolName": "shop_request_return", "branch": "shop", "result": { ... } }

POST/api/onboarding/completeSession#

Onboarding-Flag setzen + preferredBranch persistieren.

Request

{ "preferredBranch": "shop" }

Response

{ "ok": true }

POST/api/log/error#

Client-seitige Errors aus den Route-Error-Boundaries entgegennehmen.

Antwortet immer 200 (logging soll nie failen).

Request

{
  "message": "...",
  "stack": "...",
  "url": "...",
  "userAgent": "..."
}

Response

{ "ok": true }

POST/api/demo/reset?scope=shop#

Demo-Daten zuruecksetzen (Shop, ERP, Mailbox, Calendar).

scope = shop | erp | mailbox | calendar | all.

Kein Body — Parameter via URL / Cookies.

Response

{
  "ok": true,
  "scope": "shop",
  "durationMs": 245,
  "cleared": { "orders": 12, "items": 31 }
}

voiceagent REST-API

Strukturierte Quelle: lib/api/endpoints.ts - Ergaenze dort einen Eintrag, wenn eine neue Route dazukommt.

{ "transcript": { "user": "...", "agent": "..." }, "audioBase64": "...", "toolCalls": [ { "name": "shop_get_order", "input": { "orderNumber": "1042" }, "result": { ... } } ], "latencyMs": 1820 }