{ "openapi": "3.1.0", "info": { "title": "FlowAI Routing API", "version": "v1", "description": "Modelle ohne FlowSuite-Abonnement integrieren: eigene Routing-Schlüssel, EUR-Guthaben, synchrone und asynchrone Antworten sowie optionaler Brain-Kontext." }, "servers": [ { "url": "https://creativeskyline.de/api/flowai/v1", "description": "FlowAI API v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "models", "description": "Modelle" }, { "name": "embeddings", "description": "Embeddings" }, { "name": "audio-transcription", "description": "Audio transkribieren" }, { "name": "chat-completions", "description": "Chat-Completions" }, { "name": "responses", "description": "Responses" }, { "name": "end-users", "description": "Endnutzerverwaltung" }, { "name": "files", "description": "Dateien als Endnutzerkontext" }, { "name": "workspace-files", "description": "Dateien des Workspace" }, { "name": "memories", "description": "Erinnerungen" }, { "name": "webhooks", "description": "Webhooks" }, { "name": "billing", "description": "Abrechnung und API-Schlüssel" } ], "paths": { "/models": { "get": { "operationId": "models-list", "summary": "Modelle auflisten", "description": "Listet die verfügbaren Modell-Aliase des abonnementgebundenen Schlüssels auf. Der Cursor ist jeweils der öffentliche Modell-Alias.", "tags": [ "models" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Einträge von 1 bis 100, Standard 100", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "Alias aus last_id der vorherigen Seite", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "groq/openai/gpt-oss-120b", "object": "model", "created": 1735000000, "owned_by": "creativeskyline", "pricing": { "prompt": "1", "completion": "2", "currency": "EUR", "unit": "per_million_tokens" }, "kind": "chat", "context_length": 131072, "max_output_tokens": 32768, "capabilities": { "reasoning": true, "reasoning_levels": [ "low", "medium", "high" ], "web_search": false, "web_search_forced": false, "tools": true, "tool_choice": true, "parallel_tool_calls": true, "vision": false, "json_object": true, "json_schema": true, "sampling": true, "streaming": true }, "supported_parameters": [ "temperature", "top_p", "max_tokens", "tools", "tool_choice", "parallel_tool_calls", "response_format", "reasoning_effort", "stream" ], "flowai_limits": { "input_tokens": 131072, "max_output_tokens": 32768, "max_messages": 50, "max_payload_bytes": 131072, "max_chars_per_message": 32000 }, "provider_metadata": { "architecture": null, "supported_parameters_raw": null }, "deprecated_at": null } ], "has_more": false, "first_id": "groq/openai/gpt-oss-120b", "last_id": "groq/openai/gpt-oss-120b", "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/models/{model_id}": { "get": { "operationId": "models-show", "summary": "Ein Modell abrufen", "description": "Liefert einen einzelnen Modelleintrag mit Preisen, Fähigkeiten und den tatsächlich geltenden FlowAI-Grenzen.", "tags": [ "models" ], "parameters": [ { "name": "model_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "groq/openai/gpt-oss-120b", "object": "model", "created": 1735000000, "owned_by": "creativeskyline", "pricing": { "prompt": "1", "completion": "2", "currency": "EUR", "unit": "per_million_tokens" }, "kind": "chat", "context_length": 131072, "max_output_tokens": 32768, "capabilities": { "reasoning": true, "reasoning_levels": [ "low", "medium", "high" ], "web_search": false, "web_search_forced": false, "tools": true, "tool_choice": true, "parallel_tool_calls": true, "vision": false, "json_object": true, "json_schema": true, "sampling": true, "streaming": true }, "supported_parameters": [ "temperature", "top_p", "max_tokens", "tools", "tool_choice", "parallel_tool_calls", "response_format", "reasoning_effort", "stream" ], "flowai_limits": { "input_tokens": 131072, "max_output_tokens": 32768, "max_messages": 50, "max_payload_bytes": 131072, "max_chars_per_message": 32000 }, "provider_metadata": { "architecture": null, "supported_parameters_raw": null }, "deprecated_at": null, "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/embeddings": { "post": { "operationId": "embeddings-create", "summary": "Vektoren erzeugen", "description": "Erzeugt Einbettungsvektoren für eine Zeichenfolge oder einen Stapel von Zeichenfolgen.", "tags": [ "embeddings" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.0023, -0.0091 ], "index": 0 }, { "object": "embedding", "embedding": [ 0.0114, 0.0072 ], "index": 1 } ], "model": "openai/text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8, "cost": "0.000004", "currency": "EUR" }, "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Kennung eines freigegebenen Embedding-Modells im Format anbieter/modellkennung" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": [] } ], "description": "Eine Zeichenfolge oder bis zu 2.048 Zeichenfolgen mit je höchstens 8.192 Zeichen" }, "encoding_format": { "type": "string", "description": "float (Standard) oder base64 für Little-Endian-Float32" }, "dimensions": { "type": "integer", "description": "Gewünschte Vektorlänge, sofern das Modell sie unterstützt" }, "user": { "type": "string", "description": "Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung" } }, "required": [ "model", "input" ] }, "example": { "model": "openai/text-embedding-3-small", "input": [ "Erster Text", "Zweiter Text" ] } } } } } }, "/audio/transcriptions": { "post": { "operationId": "audio-post-transcriptions", "summary": "Datei transkribieren", "description": "Datei transkribieren. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "object": "audio.transcription", "model": "groq/whisper-large-v3-turbo", "status": "queued", "text": "", "flowai_request_id": "request-id", "usage": { "currency": "EUR", "cost": "0.000000", "cost_micro_eur": 0, "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "audio_seconds": 0 }, "error": null, "expires_at": null, "progress": 0 } } } }, "202": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "object": "audio.transcription", "model": "groq/whisper-large-v3-turbo", "status": "queued", "text": "", "flowai_request_id": "request-id", "usage": { "currency": "EUR", "cost": "0.000000", "cost_micro_eur": 0, "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "audio_seconds": 0 }, "error": null, "expires_at": null, "progress": 0 } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Freigegebene Kennung anbieter/modell aus GET /models" }, "language": { "type": "string", "description": "Modellabhängiger Sprachcode, beispielsweise de" }, "timestamps": { "type": "boolean", "description": "Zeitstempel ausdrücklich aktivieren; Standard false" }, "diarize": { "type": "boolean", "description": "Anonyme Sprecherzuordnung aktivieren; Standard false" }, "file": { "type": "string", "format": "binary", "description": "Audiodatei, maximal 200 MiB und acht Stunden, Modellgrenzen beachten" }, "background": { "type": "boolean", "description": "Über 24 MiB oder zehn Minuten erforderlich. Antwort 202 mit Auftrags-ID." } }, "required": [ "model", "file" ] }, "example": [] } } } } }, "/audio/transcriptions/{id}": { "get": { "operationId": "audio-get-transcriptions-id", "summary": "Auftrag abrufen", "description": "Auftrag abrufen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "object": "audio.transcription", "model": "groq/whisper-large-v3-turbo", "status": "completed", "text": "Guten Tag.", "flowai_request_id": "request-id", "usage": { "currency": "EUR", "cost": "0.000000", "cost_micro_eur": 0, "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "audio_seconds": 2 }, "error": null, "expires_at": "2026-09-23T12:00:00+00:00", "progress": 1 } } } } } }, "delete": { "operationId": "audio-delete-transcriptions-id", "summary": "Abgeschlossenen Auftrag löschen", "description": "Abgeschlossenen Auftrag löschen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "deleted": true } } } } } } }, "/audio/transcriptions/{id}/cancel": { "post": { "operationId": "audio-post-transcriptions-id-cancel", "summary": "Auftrag abbrechen", "description": "Auftrag abbrechen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "object": "audio.transcription", "model": "groq/whisper-large-v3-turbo", "status": "cancelled", "text": "Guten Tag.", "flowai_request_id": "request-id", "usage": { "currency": "EUR", "cost": "0.000000", "cost_micro_eur": 0, "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "audio_seconds": 2 }, "error": null, "expires_at": "2026-09-23T12:00:00+00:00", "progress": 1 } } } } } } }, "/audio/transcription-sessions": { "post": { "operationId": "audio-post-transcription-sessions", "summary": "Live-Sitzung erstellen", "description": "Live-Sitzung erstellen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "object": "audio.transcription_session", "model": "deepgram/nova-3", "status": "waiting", "text": "", "flowai_request_id": "request-id", "usage": { "currency": "EUR", "cost": "0.000000", "cost_micro_eur": 0, "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "audio_seconds": 0 }, "error": null, "expires_at": null, "segments": [], "next_after_sequence": 0, "last_sequence": 0, "ticket": "0000000000000000000000000000000000000000000000000000000000000000", "ticket_expires_at": "2026-09-22T12:01:00+00:00", "websocket_url": "wss://example.invalid/api/flowai/v1/audio/transcription-sessions/c7a58c7e-d155-4268-929f-9910c866f9d8/stream" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Freigegebene Kennung anbieter/modell aus GET /models" }, "language": { "type": "string", "description": "Modellabhängiger Sprachcode, beispielsweise de" }, "timestamps": { "type": "boolean", "description": "Zeitstempel ausdrücklich aktivieren; Standard false" }, "diarize": { "type": "boolean", "description": "Anonyme Sprecherzuordnung aktivieren; Standard false" }, "source": { "type": "string", "description": "push für Apps oder url für direkte HTTP(S)-Audiostreams" }, "url": { "type": "string", "description": "Bei source=url erforderlich. Keine privaten Ziele, Zugangsdaten oder HLS-Playlists." }, "max_seconds": { "type": "integer", "description": "Standard 7200, maximal 28800 Sekunden" } }, "required": [ "model", "source" ] }, "example": { "model": "deepgram/nova-3", "source": "push", "language": "de" } } } } } }, "/audio/transcription-sessions/{id}": { "get": { "operationId": "audio-get-transcription-sessions-id", "summary": "Sitzung und bestätigte Abschnitte abrufen", "description": "Sitzung und bestätigte Abschnitte abrufen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after_sequence", "in": "query", "required": false, "description": "Nur spätere bestätigte Abschnitte abrufen, maximal 1000 pro Seite", "schema": { "type": "integer" } } ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "object": "audio.transcription_session", "model": "deepgram/nova-3", "status": "completed", "text": "Guten Tag.", "flowai_request_id": "request-id", "usage": { "currency": "EUR", "cost": "0.000000", "cost_micro_eur": 0, "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "audio_seconds": 2 }, "error": null, "expires_at": "2026-09-23T12:00:00+00:00", "segments": [ { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "sequence": 1, "text": "Guten Tag." } ], "next_after_sequence": 1, "last_sequence": 1 } } } } } }, "delete": { "operationId": "audio-delete-transcription-sessions-id", "summary": "Abgeschlossene Sitzung löschen", "description": "Abgeschlossene Sitzung löschen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "deleted": true } } } } } } }, "/audio/transcription-sessions/{id}/connection-ticket": { "post": { "operationId": "audio-post-transcription-sessions-id-connection-ticket", "summary": "Neues Verbindungsticket anfordern", "description": "Neues Verbindungsticket anfordern. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "ticket": "0000000000000000000000000000000000000000000000000000000000000000", "ticket_expires_at": "2026-09-22T12:01:00+00:00", "websocket_url": "wss://example.invalid/api/flowai/v1/audio/transcription-sessions/c7a58c7e-d155-4268-929f-9910c866f9d8/stream" } } } } } } }, "/audio/transcription-sessions/{id}/stop": { "post": { "operationId": "audio-post-transcription-sessions-id-stop", "summary": "Aufnahme beenden und Ergebnisse abschließen", "description": "Aufnahme beenden und Ergebnisse abschließen. Routing-Schlüssel erforderlich. Fertige Ergebnisse bleiben 24 Stunden nach Abschluss verfügbar.", "tags": [ "audio-transcription" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "object": "audio.transcription_session", "model": "deepgram/nova-3", "status": "completed", "text": "Guten Tag.", "flowai_request_id": "request-id", "usage": { "currency": "EUR", "cost": "0.000000", "cost_micro_eur": 0, "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "audio_seconds": 2 }, "error": null, "expires_at": "2026-09-23T12:00:00+00:00", "segments": [ { "id": "c7a58c7e-d155-4268-929f-9910c866f9d8", "sequence": 1, "text": "Guten Tag." } ], "next_after_sequence": 1, "last_sequence": 1 } } } } } } }, "/chat/completions": { "post": { "operationId": "chat-non-stream", "summary": "Routing mit Chat-Completions", "description": "Sendet Nachrichten an ein freigegebenes Anbietermodell. Ohne Endnutzerkennung verwaltet der Client den Verlauf; mit Kennung ergänzt Brain den persönlichen Kontext.", "tags": [ "chat-completions" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "chatcmpl-01HXYZ", "object": "chat.completion", "created": 1735000000, "model": "groq/openai/gpt-oss-120b", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Eine klare Planung macht Ziele, Aufgaben und Termine nachvollziehbar." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 42, "completion_tokens": 24, "total_tokens": 66, "cost": "0.000090", "currency": "EUR" }, "flowai_request_id": "01HXYZ" } }, "text/event-stream": { "schema": { "type": "string" }, "example": "data: {\"id\":\"chatcmpl-018f1234-5678-7abc-9def-0123456789ab\",\"object\":\"chat.completion.chunk\",\"model\":\"groq/openai/gpt-oss-120b\",\"choices\":[{\"index\":0,\"delta\":{\"content\":\"Klare Ziele helfen.\"},\"finish_reason\":null}]}\n\ndata: [DONE]\n\n" } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Vollständige Kennung aus GET /models im Format anbieter/modellkennung" }, "external_identifier": { "type": "string", "description": "Aktiviert Brain-Kontext für deine stabile Endnutzerkennung mit 1 bis 255 Zeichen; im JSON-Body" }, "messages": { "type": "array", "items": [], "description": "Neue Nachrichten mit role und content; mindestens eine nicht leere Nutzernachricht" }, "conversation": { "type": "string", "format": "uuid", "description": "UUID aus der vorherigen Antwort desselben Endnutzers; für eine neue Unterhaltung weglassen" }, "max_tokens": { "type": "integer", "description": "Obergrenze der Ausgabe, 1 bis 128.000. Ohne Angabe gilt das Maximum des Modells; ist für das Modell keines hinterlegt, greifen 4.096 Tokens. null zählt wie ohne Angabe. OpenAI-Modelle nehmen mindestens 16 Tokens an, ein kleinerer Wert wird mit 400 abgelehnt" }, "stream": { "type": "boolean", "description": "true liefert Chat-Completions-Chunks als SSE; Standard false" }, "context_compression": { "type": "boolean", "description": "Erlaubt, einen zu langen selbst gesendeten Verlauf serverseitig zusammenzufassen; Standard false. Ohne diese Angabe wird ein zu langer Verlauf mit 400 context_length_exceeded abgelehnt statt gekürzt. Die Zusammenfassung ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression ausgewiesen" }, "reasoning_effort": { "type": "string", "description": "Denktiefe des Modells: none, minimal, low, medium, high, xhigh oder max. Ohne Angabe gilt der Standard des Anbieters, es entsteht also kein Denkbudget, das du nicht angefordert hast. Welche Stufen ein Modell annimmt, steht in capabilities.reasoning_levels aus GET /models; eine nicht unterstützte Stufe wird mit HTTP 400 und unsupported_for_model abgelehnt" }, "web_search": { "type": "boolean", "description": "Schaltet die native Websuche des Anbieters ein. Standard ist aus, weil jede Suche zusätzlich abgerechnet wird. Modelle ohne native Suche lehnen true ab, Modelle mit fest eingebauter Suche (Perplexity, Groq Compound) lehnen false ab, jeweils mit HTTP 400 und unsupported_for_model; maßgeblich sind web_search und web_search_forced aus GET /models" }, "response_format": { "type": "object", "description": "Ausgabeform: {\"type\":\"text\"}, {\"type\":\"json_object\"} oder {\"type\":\"json_schema\",\"json_schema\":{\"name\":…,\"schema\":…,\"strict\":…}}. Die Felder json_object und json_schema aus GET /models sagen, was das Modell nativ beherrscht; fehlt die Fähigkeit, antwortet die API mit HTTP 400 und unsupported_for_model, statt still Fließtext zu liefern. Bei json_object ergänzt FlowAI einen kurzen JSON-Hinweis, wenn das Wort json in keiner Nachricht vorkommt, weil manche Anbieter den JSON-Modus sonst ablehnen. Bei json_schema gilt ohne Angabe strict: false. Lehnt der Anbieter das Schema trotzdem ab, antwortet die API mit HTTP 400, invalid_field_value und param response_format" }, "tools": { "type": "array", "items": [], "description": "Deine eigenen Funktionen im Format [{\"type\":\"function\",\"function\":{\"name\":…,\"description\":…,\"parameters\":}}]. Höchstens 128 Einträge, jede Beschreibung höchstens 65.536 Zeichen, jedes Schema höchstens 65.536 Bytes als JSON. FlowAI führt diese Funktionen nicht aus: Das Modell antwortet mit tool_calls, du führst die Funktion in deinem eigenen System aus und sendest das Ergebnis als Nachricht mit role \"tool\" zurück. Ob ein Modell Funktionen annimmt, steht in tools aus GET /models; fehlt die Fähigkeit, antwortet die API mit HTTP 400 und unsupported_for_model. Zusammen mit flowai_tools ist das Feld nicht erlaubt und wird mit HTTP 400 und invalid_field_value abgelehnt" }, "tool_choice": { "oneOf": [ { "type": "string" }, { "type": "object" } ], "description": "Steuert die Werkzeugwahl: \"auto\", \"none\", \"required\" oder {\"type\":\"function\",\"function\":{\"name\":…}} für genau eine Funktion. Nur zusammen mit tools erlaubt, und der genannte Name muss in tools vorkommen. Ohne Angabe gilt der Standard des Anbieters" }, "parallel_tool_calls": { "type": "boolean", "description": "Erlaubt oder verbietet mehrere Funktionsaufrufe in einer Antwort. Nur zusammen mit tools erlaubt. Nicht jedes Modell kennt diesen Schalter; maßgeblich ist parallel_tool_calls aus GET /models, sonst antwortet die API mit HTTP 400 und unsupported_for_model" }, "max_completion_tokens": { "type": "integer", "description": "Dieselbe Angabe wie max_tokens, unter dem Namen der Responses-API. Beide zugleich mit unterschiedlichen Werten werden abgelehnt" }, "stream_options": { "type": "object", "description": "Nimmt ausschliesslich include_usage an und setzt stream: true voraus. Mit include_usage: true folgt ein abschliessender Chunk, der den Verbrauch der gestreamten Antwort nennt" }, "user": { "type": "string", "description": "Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung, bis 128 Zeichen. Diese Kennung ersetzt external_identifier nicht und aktiviert keinen Brain-Kontext" }, "search_domain_filter": { "type": "array", "items": [], "description": "Beschränkt die native Websuche auf bis zu 20 Domains, etwa [\"firma.de\"], oder schließt sie mit vorangestelltem Minus aus, etwa [\"-reddit.com\"]. Entweder nur Freigaben oder nur Ausschlüsse; Domains ohne https:// und ohne Pfad, Subdomains sind eingeschlossen. Das Feld schaltet die Websuche ein und wird zusätzlich abgerechnet. Wie viele Domains das Modell annimmt, steht in GET /models unter capabilities.web_search_domain_filter_max (xAI 5, sonst 20); Modelle ohne Domainfilter wie Gemini lehnen das Feld mit 400 unsupported_for_model ab" } }, "required": [ "model", "messages" ] }, "example": { "model": "groq/openai/gpt-oss-120b", "messages": [ { "role": "user", "content": "Fasse die Vorteile einer klaren Projektplanung zusammen." } ], "max_tokens": 512, "stream": false } } } } } }, "/responses": { "post": { "operationId": "responses-create", "summary": "Routing mit Responses", "description": "Alternative mit input statt messages, synchron, als SSE oder im Hintergrund. Eine Endnutzerkennung ergänzt optional Brain-Kontext.", "tags": [ "responses" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "resp_01HXYZ", "object": "response", "created_at": 1735000000, "status": "completed", "model": "groq/openai/gpt-oss-120b", "conversation": "018f1234-5678-7abc-9def-0123456789ab", "output": [ { "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "Eine klare Planung macht Ziele, Aufgaben und Termine nachvollziehbar." } ] } ], "usage": { "input_tokens": 42, "output_tokens": 24, "total_tokens": 66, "cost": "0.000090", "currency": "EUR" }, "flowai_request_id": "01HXYZ" } }, "text/event-stream": { "schema": { "type": "string" }, "example": "id: 5\nevent: response.output_text.delta\ndata: {\"type\":\"response.output_text.delta\",\"sequence_number\":5,\"item_id\":\"msg_example\",\"output_index\":0,\"content_index\":0,\"delta\":\"Klare Ziele helfen.\"}\n\n" } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Vollständige Kennung aus GET /models im Format anbieter/modellkennung" }, "external_identifier": { "type": "string", "description": "Aktiviert Brain-Kontext für deine stabile Endnutzerkennung mit 1 bis 255 Zeichen; im JSON-Body" }, "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": [] } ], "description": "Neue Nutzernachricht als Text oder unterstützte Nachrichtenstruktur" }, "conversation": { "type": "string", "format": "uuid", "description": "UUID aus der vorherigen Antwort desselben Endnutzers; für eine neue Unterhaltung weglassen" }, "stream": { "type": "boolean", "description": "Antwortereignisse als SSE empfangen; auch mit background kombinierbar" }, "background": { "type": "boolean", "description": "Im Hintergrund ausführen; ohne stream folgt HTTP 202 mit Response-ID" }, "store": { "type": "boolean", "description": "Response und Ereignisse für 24 Stunden nach Abschluss abrufbar halten; Standard bei background true, sonst false" }, "webhook_endpoint_id": { "type": "string", "format": "uuid", "description": "Registriertes Webhook-Ziel für einen Hintergrundauftrag" }, "max_output_tokens": { "type": "integer", "description": "Obergrenze der Ausgabe, 1 bis 128.000. Ohne Angabe gilt das Maximum des Modells; ist für das Modell keines hinterlegt, greifen 4.096 Tokens. null zählt wie ohne Angabe. OpenAI-Modelle nehmen mindestens 16 Tokens an, ein kleinerer Wert wird mit 400 abgelehnt" }, "context_compression": { "type": "boolean", "description": "Erlaubt, einen zu langen selbst gesendeten Verlauf serverseitig zusammenzufassen; Standard false. Ohne diese Angabe wird ein zu langer Verlauf mit 400 context_length_exceeded abgelehnt statt gekürzt. Die Zusammenfassung ist ein zusätzlicher kostenpflichtiger Modellaufruf und wird in usage.flowai.compression ausgewiesen" }, "reasoning": { "type": "object", "properties": { "effort": { "type": "string", "description": "Denktiefe des Modells: none, minimal, low, medium, high, xhigh oder max, auf diesem Endpunkt im Objekt reasoning statt als reasoning_effort. Welche Stufen ein Modell annimmt, steht in capabilities.reasoning_levels aus GET /models. Ohne Angabe gilt der Standard des Anbieters; eine für das Modell unbekannte Stufe wird mit HTTP 400 und unsupported_for_model abgelehnt" } } }, "web_search": { "type": "boolean", "description": "Schaltet die native Websuche des Anbieters ein. Standard ist aus, weil jede Suche zusätzlich abgerechnet wird. Modelle ohne native Suche lehnen true ab, Modelle mit fest eingebauter Suche (Perplexity, Groq Compound) lehnen false ab, jeweils mit HTTP 400 und unsupported_for_model; maßgeblich sind web_search und web_search_forced aus GET /models" }, "response_format": { "type": "object", "description": "Ausgabeform wie bei Chat-Completions: {\"type\":\"text\"}, {\"type\":\"json_object\"} oder {\"type\":\"json_schema\",\"json_schema\":{\"name\":…,\"schema\":…,\"strict\":…}}. Die Antwort spiegelt sie als text.format mit flach eingebettetem Schema zurück; ohne Angabe enthält die Antwort kein Feld text" }, "text": { "type": "object", "properties": { "format": { "type": "object", "description": "Alternative Schreibweise der OpenAI-Responses-API, wie sie die offiziellen SDKs senden: {\"type\":\"json_object\"} oder {\"type\":\"json_schema\",\"name\":…,\"schema\":…,\"strict\":…} mit flachem Schema. Wirkt genau wie response_format. Beide Felder zusammen werden mit HTTP 400 abgelehnt, ebenso weitere Schlüssel in text wie verbosity" } } }, "tools": { "type": "array", "items": [], "description": "Deine eigenen Funktionen, in derselben Schreibweise wie bei Chat-Completions: [{\"type\":\"function\",\"function\":{\"name\":…,\"parameters\":}}]. Die Antwort spiegelt sie in der Responses-Schreibweise mit flachem name zurück; gesendet wird jedoch immer die verschachtelte Form. FlowAI führt die Funktionen nicht aus" }, "tool_choice": { "oneOf": [ { "type": "string" }, { "type": "object" } ], "description": "Wie bei Chat-Completions: \"auto\", \"none\", \"required\" oder ein Objekt, das genau eine Funktion nennt. Beide Schreibweisen werden angenommen, {\"type\":\"function\",\"name\":…} ebenso wie {\"type\":\"function\",\"function\":{\"name\":…}}" }, "parallel_tool_calls": { "type": "boolean", "description": "Erlaubt oder verbietet mehrere Funktionsaufrufe in einer Antwort. Nur zusammen mit tools erlaubt. Nicht jedes Modell kennt diesen Schalter; maßgeblich ist parallel_tool_calls aus GET /models, sonst antwortet die API mit HTTP 400 und unsupported_for_model" }, "stream_options": { "type": "object", "description": "Nimmt ausschliesslich include_usage an und setzt stream: true voraus. Mit include_usage: true folgt ein abschliessender Chunk, der den Verbrauch der gestreamten Antwort nennt" }, "user": { "type": "string", "description": "Eigene Kennung des aufrufenden Endnutzers zur Missbrauchsnachverfolgung, bis 128 Zeichen. Diese Kennung ersetzt external_identifier nicht und aktiviert keinen Brain-Kontext" }, "metadata": { "type": "object", "description": "Bis zu 16 Zeichenkettenpaare, die mit der gespeicherten Antwort aufbewahrt und in ihr zurückgegeben werden. Auf Chat-Completions wird das Feld abgelehnt, weil dort nichts gespeichert wird" }, "search_domain_filter": { "type": "array", "items": [], "description": "Beschränkt die native Websuche auf bis zu 20 Domains, etwa [\"firma.de\"], oder schließt sie mit vorangestelltem Minus aus, etwa [\"-reddit.com\"]. Entweder nur Freigaben oder nur Ausschlüsse; Domains ohne https:// und ohne Pfad, Subdomains sind eingeschlossen. Das Feld schaltet die Websuche ein und wird zusätzlich abgerechnet. Wie viele Domains das Modell annimmt, steht in GET /models unter capabilities.web_search_domain_filter_max (xAI 5, sonst 20); Modelle ohne Domainfilter wie Gemini lehnen das Feld mit 400 unsupported_for_model ab" } }, "required": [ "model", "input" ] }, "example": { "model": "groq/openai/gpt-oss-120b", "external_identifier": "customer-42", "input": "Fasse die Vorteile einer klaren Projektplanung zusammen.", "max_output_tokens": 512 } } } } } }, "/responses/{response_uuid}": { "get": { "operationId": "responses-show", "summary": "Antwortstatus abrufen", "description": "Liefert eine gespeicherte Routing-Response desselben Teams innerhalb ihrer Aufbewahrungsfrist.", "tags": [ "responses" ], "parameters": [ { "name": "response_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "resp_01HXYZ", "object": "response", "created_at": 1735000000, "status": "completed", "model": "groq/openai/gpt-oss-120b", "conversation": "018f1234-5678-7abc-9def-0123456789ab", "output": [ { "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "Eine klare Planung macht Ziele, Aufgaben und Termine nachvollziehbar." } ] } ], "usage": { "input_tokens": 42, "output_tokens": 24, "total_tokens": 66, "cost": "0.000090", "currency": "EUR" }, "flowai_request_id": "01HXYZ" } }, "text/event-stream": { "schema": { "type": "string" }, "example": "id: 5\nevent: response.output_text.delta\ndata: {\"type\":\"response.output_text.delta\",\"sequence_number\":5,\"item_id\":\"msg_example\",\"output_index\":0,\"content_index\":0,\"delta\":\"Klare Ziele helfen.\"}\n\n" } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/responses/{response_uuid}/cancel": { "post": { "operationId": "responses-cancel", "summary": "Antwort abbrechen", "description": "Fordert idempotent den Abbruch eines Hintergrundauftrags an und liefert dessen aktuellen Zustand.", "tags": [ "responses" ], "parameters": [ { "name": "response_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "resp_018f1234-5678-7abc-9def-0123456789ab", "object": "response", "created_at": 1735000000, "status": "cancelled", "error": null, "incomplete_details": null, "model": "groq/openai/gpt-oss-120b", "output": [], "output_text": "", "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/end-users": { "get": { "operationId": "end-users-list", "summary": "Endnutzer auflisten", "description": "Listet die Endnutzer des authentifizierten Workspace mit UUID-Cursor auf.", "tags": [ "end-users" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Anzahl der Einträge von 1 bis 100, Standard 100", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "UUID aus last_id der vorherigen Seite", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user", "external_identifier": "customer-42", "metadata": { "plan": "pro" } } ], "has_more": false, "first_id": "018f1234-5678-7abc-9def-0123456789ab", "last_id": "018f1234-5678-7abc-9def-0123456789ab", "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "end-users-create", "summary": "Endnutzer anlegen oder auflösen", "description": "Legt einen Endnutzer anhand deiner stabilen externen Kennung an oder liefert den vorhandenen Datensatz.", "tags": [ "end-users" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user", "external_identifier": "customer-42", "metadata": { "plan": "pro" }, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_identifier": { "type": "string", "description": "Deine stabile, nicht sensible Kennung für diesen Endnutzer" }, "metadata": { "type": "object", "description": "Optionale eigene Metadaten" } }, "required": [ "external_identifier" ] }, "example": { "external_identifier": "customer-42", "metadata": { "plan": "pro" } } } } } } }, "/end-users/{end_user_uuid}": { "get": { "operationId": "end-users-show", "summary": "Endnutzer abrufen", "description": "Liefert einen Endnutzer über seine UUID.", "tags": [ "end-users" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user", "external_identifier": "customer-42", "metadata": { "plan": "pro" }, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "end-users-update", "summary": "Endnutzer ändern", "description": "Ergänzt Metadaten oder ändert die automatische Erinnerungsextraktion eines Endnutzers.", "tags": [ "end-users" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user", "external_identifier": "customer-42", "metadata": { "plan": "enterprise" }, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "object", "description": "Metadaten, die mit den vorhandenen Werten zusammengeführt werden" }, "memory_extraction_enabled": { "type": "boolean", "description": "Aktiviert oder deaktiviert die automatische Erinnerungsextraktion" } } }, "example": { "memory_extraction_enabled": false } } } } }, "delete": { "operationId": "end-users-delete", "summary": "Endnutzer löschen", "description": "Löscht die persönlichen Arbeitsdaten eines Endnutzers. Abrechnungs- und Verbrauchszeilen bleiben erhalten.", "tags": [ "end-users" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user", "deleted": true, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/end_users/{end_user_uuid}/erasures": { "get": { "operationId": "end-users-erasures-list", "summary": "Löschvorgänge auflisten", "description": "Listet die Löschbelege zu einer Endnutzerkennung, auch nach der Löschung.", "tags": [ "end-users" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, 1 bis 100, Standard 20", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "Cursor aus last_id der vorherigen Seite", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user.erasure", "status": "completed", "requested_at": "2026-09-11T08:15:00+00:00", "completed_at": "2026-09-11T08:15:04+00:00", "manifest_summary": { "resources": { "memories": { "before": 12, "after": 0 }, "end_user_files": { "before": 3, "after": 0 } }, "objects_remaining": 0 } } ], "has_more": false, "last_id": "aWQ6MTIz", "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/end_users/{end_user_uuid}/erasures/{run_uuid}": { "get": { "operationId": "end-users-erasures-show", "summary": "Löschbeleg abrufen", "description": "Liefert einen einzelnen Löschbeleg mit Zeitpunkten und Mengenangaben je Datenart.", "tags": [ "end-users" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "run_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user.erasure", "status": "completed", "requested_at": "2026-09-11T08:15:00+00:00", "completed_at": "2026-09-11T08:15:04+00:00", "manifest_summary": { "resources": { "memories": { "before": 12, "after": 0 }, "end_user_files": { "before": 3, "after": 0 } }, "objects_remaining": 0 }, "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/end_users/{end_user_uuid}/files": { "post": { "operationId": "end-users-file-create", "summary": "Endnutzerdatei hochladen", "description": "Speichert eine Textdatei für den Endnutzer und startet ihre Verarbeitung. Verwende multipart/form-data.", "tags": [ "files" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user.file", "filename": "profil.pdf", "bytes": 2048, "status": "pending", "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Unterstützte Text- oder Dokumentdatei mit Dateiname bis 255 Zeichen" }, "purpose": { "type": "string", "description": "Pflichtwert user_data; andere Zwecke werden abgelehnt" } }, "required": [ "file", "purpose" ] } } } } }, "get": { "operationId": "end-users-files-list", "summary": "Dateien auflisten", "description": "Listet die Dateien eines Endnutzers, neueste zuerst.", "tags": [ "files" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, 1 bis 100, Standard 20", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "Cursor aus last_id der vorherigen Seite", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user.file", "filename": "angebot.pdf", "bytes": 18432, "status": "completed", "created": 1735000000 } ], "has_more": false, "last_id": "aWQ6MTIz", "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/end_users/{end_user_uuid}/files/{file_uuid}": { "get": { "operationId": "end-users-files-show", "summary": "Datei abrufen", "description": "Liefert die Angaben zu einer einzelnen Datei, ohne deren Inhalt.", "tags": [ "files" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user.file", "filename": "angebot.pdf", "bytes": 18432, "status": "completed", "created": 1735000000, "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "end-users-files-delete", "summary": "Datei löschen", "description": "Entfernt eine einzelne Datei samt der daraus gewonnenen Textabschnitte.", "tags": [ "files" ], "parameters": [ { "name": "end_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "file_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "end_user.file", "deleted": true, "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files": { "post": { "operationId": "files-create", "summary": "Datei hochladen", "description": "Speichert eine Datei für spätere FlowAI-Anfragen. Verwende multipart/form-data.", "tags": [ "workspace-files" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "file-018f1234-5678-7abc-9def-0123456789ab", "object": "file", "bytes": 2048, "created_at": 1735000000, "expires_at": null, "filename": "analyse.pdf", "purpose": "user_data", "status": "processed", "status_details": null, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Hochzuladende Datei" }, "purpose": { "type": "string", "description": "user_data oder vision" } }, "required": [ "file", "purpose" ] } } } } }, "get": { "operationId": "files-list", "summary": "Dateien auflisten", "description": "Listet die Dateien des Workspace mit stabilem Cursor auf.", "tags": [ "workspace-files" ], "parameters": [ { "name": "purpose", "in": "query", "required": false, "description": "Filter: user_data oder vision", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "Sortierung: asc oder desc", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Anzahl von 1 bis 100", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "Öffentliche Datei-ID aus last_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "file-018f1234-5678-7abc-9def-0123456789ab", "object": "file", "bytes": 2048, "filename": "analyse.pdf", "purpose": "user_data", "status": "processed" } ], "has_more": false, "first_id": "file-018f1234-5678-7abc-9def-0123456789ab", "last_id": "file-018f1234-5678-7abc-9def-0123456789ab", "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_uuid}": { "get": { "operationId": "files-show", "summary": "Dateimetadaten abrufen", "description": "Liefert Metadaten, aber nicht den Dateiinhalt.", "tags": [ "workspace-files" ], "parameters": [ { "name": "file_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "file-018f1234-5678-7abc-9def-0123456789ab", "object": "file", "bytes": 2048, "created_at": 1735000000, "expires_at": null, "filename": "analyse.pdf", "purpose": "user_data", "status": "processed", "status_details": null, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "files-delete", "summary": "Datei löschen", "description": "Löscht die gespeicherten Bytes und ihre Metadaten.", "tags": [ "workspace-files" ], "parameters": [ { "name": "file_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "file-018f1234-5678-7abc-9def-0123456789ab", "object": "file", "deleted": true, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{file_uuid}/content": { "get": { "operationId": "files-content", "summary": "Dateiinhalt herunterladen", "description": "Liefert die gespeicherten Bytes als Download mit dem ursprünglichen Medientyp.", "tags": [ "workspace-files" ], "parameters": [ { "name": "file_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/memories": { "post": { "operationId": "memories-create", "summary": "Erinnerung anlegen", "description": "Speichert eine persönliche Erinnerung für einen Endnutzer.", "tags": [ "memories" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "memory", "created": 1735000000, "text": "Bevorzugt kurze Zusammenfassungen.", "kind": "preference", "revision": 1, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_identifier": { "type": "string", "description": "Stabile externe Endnutzerkennung" }, "text": { "type": "string", "description": "Nicht leerer Text mit höchstens 10.000 Zeichen" }, "kind": { "type": "string", "description": "Optionale Art der Erinnerung" } }, "required": [ "external_identifier", "text" ] }, "example": { "external_identifier": "customer-42", "text": "Bevorzugt kurze Zusammenfassungen.", "kind": "preference" } } } } }, "get": { "operationId": "memories-search", "summary": "Erinnerungen durchsuchen", "description": "Sucht semantisch in den Erinnerungen eines Endnutzers.", "tags": [ "memories" ], "parameters": [ { "name": "external_identifier", "in": "query", "required": true, "description": "Deine stabile Endnutzerkennung", "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "Suchtext; ohne Angabe werden die Erinnerungen chronologisch aufgelistet", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, 1 bis 100, Standard 20", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "Cursor aus last_id der vorherigen Seite; nur beim Auflisten", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "memory", "created": 1735000000, "text": "Bevorzugt kurze Zusammenfassungen.", "kind": "preference", "revision": 1 } ], "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/memories/{memory_uuid}": { "patch": { "operationId": "memories-update", "summary": "Erinnerung ändern", "description": "Ändert eine Erinnerung, wenn die angegebene Revision aktuell ist.", "tags": [ "memories" ], "parameters": [ { "name": "memory_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "memory", "created": 1735000000, "text": "Bevorzugt sehr kurze Zusammenfassungen.", "kind": "preference", "revision": 2, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_identifier": { "type": "string", "description": "Stabile externe Endnutzerkennung" }, "text": { "type": "string", "description": "Neuer Erinnerungstext" }, "revision": { "type": "integer", "description": "Aktuelle Revision, mindestens 1" } }, "required": [ "external_identifier", "text", "revision" ] }, "example": { "external_identifier": "customer-42", "text": "Bevorzugt kurze Zusammenfassungen mit drei Stichpunkten.", "revision": 1 } } } } }, "delete": { "operationId": "memories-delete", "summary": "Erinnerung löschen", "description": "Löscht eine Erinnerung des angegebenen Endnutzers.", "tags": [ "memories" ], "parameters": [ { "name": "memory_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "memory", "deleted": true, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_identifier": { "type": "string", "description": "Stabile externe Endnutzerkennung" } }, "required": [ "external_identifier" ] }, "example": { "external_identifier": "customer-42" } } } } } }, "/webhook_endpoints": { "post": { "operationId": "webhooks-create", "summary": "Webhook anlegen", "description": "Registriert ein HTTPS-Ziel und gibt das Signatur-Secret einmalig zurück.", "tags": [ "webhooks" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "webhook_endpoint", "url": "https://example.com/flowai", "events": [ "response.completed" ], "description": "Produktiv", "is_active": true, "deactivated_at": null, "deactivation_reason": null, "last_delivered_at": null, "created": 1735000000, "secret": "whsec_example", "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Öffentlich erreichbare HTTPS-Adresse, maximal 2.048 Zeichen" }, "events": { "type": "array", "items": [], "description": "Mindestens ein unterstützter Ereignistyp" }, "description": { "type": "string", "description": "Optionale Beschreibung, maximal 255 Zeichen" } }, "required": [ "url", "events" ] } } } } }, "get": { "operationId": "webhooks-list", "summary": "Webhooks auflisten", "description": "Listet die Webhook-Ziele des Workspace ohne Secrets auf.", "tags": [ "webhooks" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Anzahl von 1 bis 100", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "UUID aus last_id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "webhook_endpoint", "url": "https://example.com/flowai", "events": [ "response.completed" ], "is_active": true } ], "has_more": false, "first_id": "018f1234-5678-7abc-9def-0123456789ab", "last_id": "018f1234-5678-7abc-9def-0123456789ab", "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_endpoints/{webhook_uuid}": { "get": { "operationId": "webhooks-show", "summary": "Webhook abrufen", "description": "Liefert ein Webhook-Ziel ohne Signatur-Secret.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "webhook_endpoint", "url": "https://example.com/flowai", "events": [ "response.completed" ], "description": "Produktiv", "is_active": true, "deactivated_at": null, "deactivation_reason": null, "last_delivered_at": null, "created": 1735000000, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "webhooks-update", "summary": "Webhook ändern", "description": "Ändert Ziel, Ereignisse, Beschreibung oder Aktivierungsstatus.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "webhook_endpoint", "url": "https://example.com/flowai", "events": [ "response.completed" ], "description": "Aktualisiert", "is_active": true, "deactivated_at": null, "deactivation_reason": null, "last_delivered_at": null, "created": 1735000000, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Neue öffentlich erreichbare HTTPS-Adresse" }, "events": { "type": "array", "items": [], "description": "Neue Liste unterstützter Ereignistypen" }, "description": { "type": "string", "description": "Neue Beschreibung oder null" }, "is_active": { "type": "boolean", "description": "Deaktiviert oder reaktiviert das Ziel" } } } } } } }, "delete": { "operationId": "webhooks-delete", "summary": "Webhook löschen", "description": "Löscht das Ziel und seinen Zustellungsverlauf.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "webhook_endpoint", "deleted": true, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_endpoints/{webhook_uuid}/deliveries": { "get": { "operationId": "webhook-deliveries-list", "summary": "Zustellungen auflisten", "description": "Listet Zustellungsversuche mit Status und Fehlerdetails auf.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "pending, delivered, failed oder exhausted", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Anzahl von 1 bis 100", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "UUID aus last_id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "id": "018f1234-5678-7abc-9def-0123456789ab", "object": "webhook_delivery", "event_type": "response.completed", "status": "delivered", "attempts": 1, "http_status": 200, "failure_kind": null, "created": 1735000000, "delivered_at": 1735000001, "failed_at": null, "next_attempt_at": null, "response_id": "resp_01HXYZ…" } ], "has_more": false, "first_id": "018f1234-5678-7abc-9def-0123456789ab", "last_id": "018f1234-5678-7abc-9def-0123456789ab", "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_endpoints/{webhook_uuid}/test": { "post": { "operationId": "webhooks-test", "summary": "Testzustellung senden", "description": "Stellt eine synthetische Zustellung vom Typ webhook.test in die Warteschlange. Das Ergebnis erscheint im Zustellungsverlauf.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "webhook_delivery", "uuid": "018f1234-5678-7abc-9def-0123456789ab", "status": "pending", "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhook_endpoints/{webhook_uuid}/rotate_secret": { "post": { "operationId": "webhooks-rotate-secret", "summary": "Secret wechseln", "description": "Erzeugt ein neues Signatur-Secret und gibt es einmalig zurück. Das bisherige Secret bleibt bis zum genannten Zeitpunkt gültig.", "tags": [ "webhooks" ], "parameters": [ { "name": "webhook_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "webhook_endpoint", "uuid": "018f1234-5678-7abc-9def-0123456789ab", "secret": "whsec_example", "secondary_secret_expires_at": 1735086400, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credits": { "get": { "operationId": "billing-credits", "summary": "Guthaben abrufen", "description": "Liefert das unabhängige EUR-Konto des authentifizierten Routing-Teams, ohne Zahlung oder Modellaufruf.", "tags": [ "billing" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "credit_balance", "currency": "EUR", "billing_mode": "prepaid", "balance_micro_eur": 20000000, "reserved_micro_eur": 1000000, "available_micro_eur": 19000000, "outstanding_micro_eur": 0, "postpaid_limit_micro_eur": 0, "spendable_micro_eur": 19000000, "reserved_oldest_at": "2026-09-11T08:15:00+00:00", "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "operationId": "usage-summary", "summary": "Verbrauch zusammenfassen", "description": "Fasst Anfragen, Tokens und Kosten eines Zeitraums nach Tag, Modell, Schlüssel oder Endnutzer zusammen.", "tags": [ "billing" ], "parameters": [ { "name": "start", "in": "query", "required": false, "description": "Erster Tag im Format JJJJ-MM-TT, Standard 29 Tage vor end", "schema": { "type": "string" } }, { "name": "end", "in": "query", "required": false, "description": "Letzter Tag im Format JJJJ-MM-TT, Standard heute", "schema": { "type": "string" } }, { "name": "group_by", "in": "query", "required": false, "description": "day, model, api_key oder end_user; Standard day", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "bucket": "2026-09-10", "requests": 42, "prompt_tokens": 18450, "completion_tokens": 3120, "total_tokens": 21570, "cost_micro_eur": 1840000 } ], "start": "2026-08-13", "end": "2026-09-11", "group_by": "day", "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage/requests": { "get": { "operationId": "usage-requests", "summary": "Einzelne Anfragen auflisten", "description": "Listet einzelne Anfragen mit Modell, Anbieter, Status, Laufzeit, Tokenzahlen und Kosten, ohne Anfrage- oder Antworttext.", "tags": [ "billing" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Einträge je Seite, 1 bis 100, Standard 20", "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "description": "Cursor aus last_id der vorherigen Seite", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Nur Anfragen mit diesem Status", "schema": { "type": "string" } }, { "name": "api_key", "in": "query", "required": false, "description": "UUID eines Schlüssels desselben Workspace", "schema": { "type": "string" } }, { "name": "end_user", "in": "query", "required": false, "description": "Externe Endnutzerkennung", "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "description": "Modellkennung wie in der Anfrage gesendet", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "list", "data": [ { "request_id": "01HXYZ", "created_at": "2026-09-11T08:15:00+00:00", "api_key": "018f1234-5678-7abc-9def-0123456789ab", "end_user": "customer-42", "model": "groq/openai/gpt-oss-120b", "provider": "groq", "status": "success", "error_code": null, "latency_ms": 842, "prompt_tokens": 430, "completion_tokens": 112, "cost_micro_eur": 41000 } ], "has_more": false, "last_id": "aWQ6MTIz", "flowai_request_id": "01HXYZ" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/key": { "get": { "operationId": "api-key-status", "summary": "Verwendeten API-Schlüssel prüfen", "description": "Liefert Status, Schlüsselart und geltende Anfragegrenzen für den authentifizierenden API-Schlüssel.", "tags": [ "billing" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "object": "api_key", "uuid": "018f1234-5678-7abc-9def-0123456789ab", "name": "Produktiv", "status": "active", "kind": "inference", "created_at": "2026-09-07T12:00:00+00:00", "last_used_at": "2026-09-07T12:10:00+00:00", "expires_at": null, "limits": { "requests": { "per_minute": 60, "per_minute_per_model": 30, "per_second_burst": 5 }, "payload": { "max_payload_bytes": 131072, "max_messages_per_request": 50, "max_chars_per_message": 32000 }, "spending": { "currency": "EUR", "monthly_limit_micro_eur": 50000000 } }, "flowai_request_id": "01HXYZ…ULID" } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/user/api-keys": { "servers": [ { "url": "https://creativeskyline.de" } ], "get": { "operationId": "api-keys-list", "summary": "API-Schlüssel auflisten", "description": "Listet die aktiven Schlüssel des authentifizierten Benutzers im authentifizierten Workspace auf. Geheime Tokenwerte werden nie ausgegeben.", "tags": [ "billing" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": [ { "uuid": "018f1234-5678-7abc-9def-0123456789ab", "name": "Produktiv", "is_personal": false, "kind": "inference", "created_at": "2026-09-07T12:00:00+00:00", "last_used_at": null, "expires_at": null } ] } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "api-keys-create", "summary": "API-Schlüssel anlegen", "description": "Legt einen Schlüssel im authentifizierten Workspace an und gibt den neuen Tokenwert in dieser Antwort aus.", "tags": [ "billing" ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "API key created.", "data": { "token": "at_…", "uuid": "018f1234-5678-7abc-9def-0123456789ab", "name": "Produktiv", "kind": "inference", "created_at": "2026-09-07T12:00:00+00:00", "expires_at": null } } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Anzeigename, maximal 255 Zeichen" }, "kind": { "type": "string", "description": "inference oder management; Standard management. Für Modellanfragen inference ausdrücklich angeben" }, "expires_at": { "type": "string", "format": "date-time", "description": "Optionaler Ablaufzeitpunkt in der Zukunft" } }, "required": [ "name" ] }, "example": { "name": "Routing-Produktion", "kind": "inference" } } } } } }, "/api/user/api-keys/{key_uuid}": { "servers": [ { "url": "https://creativeskyline.de" } ], "delete": { "operationId": "api-keys-delete", "summary": "API-Schlüssel sperren", "description": "Sperrt einen zusätzlichen Schlüssel des authentifizierten Workspace sofort. Persönliche Schlüssel können nur erneuert werden.", "tags": [ "billing" ], "parameters": [ { "name": "key_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "API key deleted." } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/user/api-keys/{key_uuid}/regenerate": { "servers": [ { "url": "https://creativeskyline.de" } ], "put": { "operationId": "api-keys-regenerate", "summary": "API-Schlüssel erneuern", "description": "Ersetzt den Tokenwert eines Schlüssels im authentifizierten Workspace. Die konfigurierte Übergangsfrist bestimmt, wie lange der vorherige Wert noch gilt.", "tags": [ "billing" ], "parameters": [ { "name": "key_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Erfolgreiche Antwort", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "API key regenerated.", "data": { "token": "at_…", "uuid": "018f1234-5678-7abc-9def-0123456789ab", "name": "Produktiv" } } } } }, "default": { "description": "Fehlerantwort im gemeinsamen Fehlerformat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API-Schlüssel als Authorization: Bearer . Andere Übergabewege werden mit 401 invalid_token_source abgelehnt." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "type", "code" ], "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "string" }, "param": { "type": [ "string", "null" ] } } }, "flowai_request_id": { "type": "string" } } }, "Usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cost": { "type": "string" }, "currency": { "type": "string" } } }, "ChatCompletion": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "chat.completion" }, "created": { "type": "integer" }, "model": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object" } }, "usage": { "$ref": "#/components/schemas/Usage" }, "flowai_request_id": { "type": "string" } } }, "Response": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "status": { "type": "string" }, "model": { "type": "string" }, "output": { "type": "array", "items": { "type": "object" } }, "output_text": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" }, "flowai_request_id": { "type": "string" } } }, "Model": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "model" }, "created": { "type": "integer" }, "owned_by": { "type": "string" }, "pricing": { "type": "object" }, "context_length": { "type": [ "integer", "null" ] }, "capabilities": { "type": "object" }, "flowai_limits": { "type": "object" }, "deprecated_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }