Unterhaltungen

Eine Konversation erstellen

POST/api/v1/workspaces/{workspaceId}/conversations

Erstellen Sie eine neue Chat-Konversation im Arbeitsbereich. Die Konversations-ID wird serverseitig generiert und in der Antwort zurückgegeben — verwenden Sie sie als {'{'}conversationId{'}'} auf nachfolgenden Endpunkten. Der optionale Body konfiguriert die initiale Steuerung der Konversation (Persönlichkeit, Brand Voice, Zielgruppe, LLM).

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
workspaceId	string	Ja	Der Arbeitsbereich, auf den sich die Anfrage bezieht. Muss dem Workspace-Anspruch im Gateway-Token entsprechen.

Anfrage-Body

FeldTypErforderlichBeschreibung

personalitystringNeinFreiformige Persönlichkeitsbeschreibung, die in den System-Prompt für diese Konversation eingewoben wird. Falls sowohl personality als auch eine Brand-Voice-Auflösung von brandVoiceId vorhanden sind, gewinnt die explizite personality Zeichenfolge.

personalityIdintegerNeinKennung einer gespeicherten Persönlichkeits-Voreinstellung, die dieser Konversation zugeordnet ist. Nur für Rückreferenz gespeichert — die eigentliche Persönlichkeitstexte, die zum Zeitpunkt der Generierung verwendet werden, stammt immer noch von personality.

brandVoiceIdstringNeinKennung der Brand Voice, die Assistenzantworten steuern sollte. Der Service löst die Brand Voice serverseitig aus dieser ID auf.

targetAudienceIdstringNeinKennung der Zielgruppe, die Antworten des Assistenten steuern soll. Der Dienst löst die Zielgruppenbeschreibung serverseitig anhand dieser ID auf.

modelNamestringNeinEine Enumeration.

Antwort

FeldTypBeschreibung

idstringStabile Kennung der Konversation. Serverseitig bei POST /conversations generiert; erforderlich für alle nachfolgenden Operationen auf der Konversation.

createdAtstringZeitpunkt, zu dem die Konversation erstmals erstellt wurde.

modelNamestringLLM, das für Assistenzantworten verwendet wird. null fällt auf den serviceweit gültigen Standard zurück. Wird als freie Textzeichenfolge und nicht als Enumeration zurückgegeben, damit historische Konversationen, die mit Modellen erstellt wurden, die sich nicht mehr im akzeptierten Erstellungssatz befinden (siehe :class:ConversationCreateCmd.modelName), immer noch durch Lesevorgänge durchlaufen.

legacyCustomerIdintegerVerfasser der Konversation, erfasst vom Gateway-Token zum Zeitpunkt der Erstellung. null für Konversationen, die vor Existenz dieses Feldes erstellt wurden — der Besitz für diese fällt auf den api_master.ai_writer_projects.author_id Join zurück.

Beispiel

cURL

curl -X POST "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "personality": "string",
      "personalityId": 0,
      "brandVoiceId": "string",
      "targetAudienceId": "string",
      "modelName": "string"
  }'

Python

import requests

response = requests.post(
    f"https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "personality": "string",
        "personalityId": 0,
        "brandVoiceId": "string",
        "targetAudienceId": "string",
        "modelName": "string"
    },
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/v1/workspaces/${workspaceId}/conversations`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
          "personality": "string",
          "personalityId": 0,
          "brandVoiceId": "string",
          "targetAudienceId": "string",
          "modelName": "string"
    }),
  }
).then((r) => r.json());

Go

body, _ := json.Marshal(map[string]any{
		"personality": "string",
		"personalityId": 0,
		"brandVoiceId": "string",
		"targetAudienceId": "string",
		"modelName": "string",
	})

req, _ := http.NewRequest("POST", "https://app.neuroflash.com/api/v1/workspaces/"+workspaceID+"/conversations", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Antwort:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-01T09:00:00",
  "modelName": "gpt-4",
  "legacyCustomerId": 42
}

Nachricht senden und synchrone Antwort erhalten

POST/api/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages

Fügen Sie eine Benutzernachricht zur Unterhaltung hinzu und geben Sie die Antwort des Assistenten zurück, sobald die Generierung abgeschlossen ist. Das Wiederholen derselben Nachricht id ist idempotent: Die zuvor generierte Antwort wird zurückgegeben, ohne einen neuen LLM-Aufruf durchzuführen.

Für Streaming-Antworten verwenden Sie stattdessen POST .../message-streams.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
conversationId	string	Ja	Kennung der Unterhaltung, zu der die Nachricht hinzugefügt wird.
workspaceId	string	Ja	Der Arbeitsbereich, auf den sich die Anfrage bezieht. Muss dem Workspace-Anspruch im Gateway-Token entsprechen.

Anfrage-Body

FeldTypErforderlichBeschreibung

idstringJaVon Clients bereitgestellte ID für die Benutzernachricht. Idempotent: Das Wiederholen derselben ID gibt die zuvor generierte Assistenten-Antwort zurück, ohne das LLM erneut auszuführen.

textstringJaDer Text der Benutzernachricht.

createdAtstringJaClient-seitiger Zeitstempel, wann der Benutzer die Nachricht gesendet hat.

additionalContextarray<object>NeinZusätzliche Kontextausschnitte, die für diese Runde in den Prompt eingefügt werden (z. B. Produktfakten, Referenzauszüge). Jeder Eintrag hat content und optionales source.

idintegerJa

contentstringJa

category_namestringNein

contextSizeintegerNeinMaximale Anzahl von Input-Token der Unterhaltungshistorie, die an das LLM zugeführt werden. Ältere Nachrichten werden gekürzt, um zu passen. Standard ist 16000.

Antwort

FeldTypBeschreibung

idstringStabile Kennung der Nachricht.

textstringDer Nachrichtentext.

sourcestringEine Enumeration.

createdAtstringZeitpunkt, zu dem die Nachricht gespeichert wurde.

Beispiel

cURL

curl -X POST "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "id": "string",
      "text": "string",
      "createdAt": "string",
      "additionalContext": [],
      "contextSize": 16000
  }'

Python

import requests

response = requests.post(
    f"https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/messages",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "id": "string",
        "text": "string",
        "createdAt": "string",
        "additionalContext": [],
        "contextSize": 16000
    },
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/v1/workspaces/${workspaceId}/conversations/${conversationId}/messages`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
          "id": "string",
          "text": "string",
          "createdAt": "string",
          "additionalContext": [],
          "contextSize": 16000
    }),
  }
).then((r) => r.json());

Go

body, _ := json.Marshal(map[string]any{
		"id": "string",
		"text": "string",
		"createdAt": "string",
		"additionalContext": []any{},
		"contextSize": 16000,
	})

req, _ := http.NewRequest("POST", "https://app.neuroflash.com/api/v1/workspaces/"+workspaceID+"/conversations/"+conversationID+"/messages", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Antwort:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "text": "What's a catchy headline for a sustainable shoe brand?",
  "source": "user",
  "createdAt": "2026-05-01T09:01:30"
}

Streaming-Antwort für eine Unterhaltungsrunde öffnen

POST/api/v1/workspaces/{workspaceId}/conversations/{conversationId}/message-streams

Fügen Sie eine Benutzernachricht hinzu und streamen Sie die Assistenten-Antwort als Server-Sent Events (Content-Type: text/event-stream). Jedes Event enthält entweder ein partielles delta, die endgültige message-Nutzlast oder einen error.

Es darf sich jeweils nur ein aktiver Stream pro Unterhaltung befinden — ein zweiter Aufruf gibt 409 conversationLocked zurück, bis der aktive Stream beendet wird oder über DELETE .../message-streams abgebrochen wird. Streams werden nicht persistiert: Es gibt kein GET, um sie abzurufen.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
conversationId	string	Ja	Kennung der Unterhaltung, in der eine Antwort gestreamt werden soll.
workspaceId	string	Ja	Der Arbeitsbereich, auf den sich die Anfrage bezieht. Muss dem Workspace-Anspruch im Gateway-Token entsprechen.

Anfrage-Body

FeldTypErforderlichBeschreibung

idstringJaVon der Nachricht des Benutzers bereitgestellte ID, die den Stream startet. Idempotent: Das Wiederholen derselben ID gibt die vorhandene Assistenzantwort zurück, ohne die LLM erneut auszuführen (seien Sie also vorsichtig bei Wiederholungen – diese triggern KEINE neue Generierung).

textstringJaDer Text der Benutzernachricht.

createdAtstringJaClient-seitiger Zeitstempel, wann der Benutzer die Nachricht gesendet hat.

additionalContextarray<object>NeinZusätzliche Kontextausschnitte, die für diese Runde in den Prompt eingefügt werden (z. B. Produktfakten, Referenzauszüge). Jeder Eintrag hat content und optionales source.

idintegerJa

contentstringJa

category_namestringNein

contextSizeintegerNeinMaximale Anzahl von Input-Token der Unterhaltungshistorie, die an das LLM zugeführt werden. Ältere Nachrichten werden gekürzt, um zu passen. Standard ist 16000.

Beispiel

cURL

curl -X POST "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/message-streams" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "id": "string",
      "text": "string",
      "createdAt": "string",
      "additionalContext": [],
      "contextSize": 16000
  }'

Python

import requests

response = requests.post(
    f"https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/message-streams",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "id": "string",
        "text": "string",
        "createdAt": "string",
        "additionalContext": [],
        "contextSize": 16000
    },
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/v1/workspaces/${workspaceId}/conversations/${conversationId}/message-streams`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
          "id": "string",
          "text": "string",
          "createdAt": "string",
          "additionalContext": [],
          "contextSize": 16000
    }),
  }
).then((r) => r.json());

Go

body, _ := json.Marshal(map[string]any{
		"id": "string",
		"text": "string",
		"createdAt": "string",
		"additionalContext": []any{},
		"contextSize": 16000,
	})

req, _ := http.NewRequest("POST", "https://app.neuroflash.com/api/v1/workspaces/"+workspaceID+"/conversations/"+conversationID+"/message-streams", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Antwort:

{}

Konversationen im Arbeitsbereich auflisten

GET/api/v1/workspaces/{workspaceId}/conversations

Geben Sie die Konversationen im Arbeitsbereich zurück, die der aktuelle Aufrufer verfasst hat, neueste zuerst, im Standard-Paginierungs-Envelope.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
workspaceId	string	Ja	Der Arbeitsbereich, auf den sich die Anfrage bezieht. Muss dem Workspace-Anspruch im Gateway-Token entsprechen.

Abfrageparameter

Parameter	Typ	Standard	Beschreibung
page	integer	1	Page number to retrieve. The first page is 1 (not 0).
size	integer	20	Number of elements per page. Maximum 100.

Antwort

FeldTypBeschreibung

pageobject

sizeintegerRequested page size. Echoed back even when data contains fewer elements (e.g. on the last page).

totalElementsintegerTotal number of elements across all pages.

totalPagesintegerTotal number of pages given the requested size.

currentPageintegerPage number returned. The first page is 1 (not 0).

dataarray<object>Elements on the current page. May contain fewer than page.size on the last page.

idstringStabile Kennung der Konversation. Serverseitig bei POST /conversations generiert; erforderlich für alle nachfolgenden Operationen auf der Konversation.

createdAtstringZeitpunkt, zu dem die Konversation erstmals erstellt wurde.

modelNamestringLLM, das für Assistenzantworten verwendet wird. null fällt auf den serviceweit gültigen Standard zurück. Wird als freie Textzeichenfolge und nicht als Enumeration zurückgegeben, damit historische Konversationen, die mit Modellen erstellt wurden, die sich nicht mehr im akzeptierten Erstellungssatz befinden (siehe :class:ConversationCreateCmd.modelName), immer noch durch Lesevorgänge durchlaufen.

legacyCustomerIdintegerVerfasser der Konversation, erfasst vom Gateway-Token zum Zeitpunkt der Erstellung. null für Konversationen, die vor Existenz dieses Feldes erstellt wurden — der Besitz für diese fällt auf den api_master.ai_writer_projects.author_id Join zurück.

Beispiel

cURL

curl "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

response = requests.get(
    f"https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations",
    headers={"Authorization": f"Bearer {token}"},
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/v1/workspaces/${workspaceId}/conversations`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

Go

req, _ := http.NewRequest("GET", "https://app.neuroflash.com/api/v1/workspaces/"+workspaceID+"/conversations", nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Antwort:

{
  "page": {
    "size": 20,
    "totalElements": 137,
    "totalPages": 7,
    "currentPage": 1
  },
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-01T09:00:00",
      "modelName": "gpt-4",
      "legacyCustomerId": 42
    }
  ]
}

Nachrichten in einer Unterhaltung auflisten

GET/api/v1/workspaces/{workspaceId}/conversations/{conversationId}/messages

Geben Sie die Nachrichten der Unterhaltung in chronologischer Reihenfolge (älteste zuerst) in der Standard-Pagination-Hülle zurück. Offset / Limit werden aus den Abfrageparametern page und size abgeleitet.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
conversationId	string	Ja	Kennung der Unterhaltung.
workspaceId	string	Ja	Der Arbeitsbereich, auf den sich die Anfrage bezieht. Muss dem Workspace-Anspruch im Gateway-Token entsprechen.

Abfrageparameter

Parameter	Typ	Standard	Beschreibung
page	integer	1	Page number to retrieve. The first page is 1 (not 0).
size	integer	20	Number of elements per page. Maximum 100.

Antwort

FeldTypBeschreibung

pageobject

sizeintegerRequested page size. Echoed back even when data contains fewer elements (e.g. on the last page).

totalElementsintegerTotal number of elements across all pages.

totalPagesintegerTotal number of pages given the requested size.

currentPageintegerPage number returned. The first page is 1 (not 0).

dataarray<object>Elements on the current page. May contain fewer than page.size on the last page.

idstringStabile Kennung der Nachricht.

textstringDer Nachrichtentext.

sourcestringEine Enumeration.

createdAtstringZeitpunkt, zu dem die Nachricht gespeichert wurde.

Beispiel

cURL

curl "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

response = requests.get(
    f"https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/messages",
    headers={"Authorization": f"Bearer {token}"},
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/v1/workspaces/${workspaceId}/conversations/${conversationId}/messages`,
  { headers: { Authorization: `Bearer ${token}` } }
).then((r) => r.json());

Go

req, _ := http.NewRequest("GET", "https://app.neuroflash.com/api/v1/workspaces/"+workspaceID+"/conversations/"+conversationID+"/messages", nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Antwort:

{
  "page": {
    "size": 20,
    "totalElements": 137,
    "totalPages": 7,
    "currentPage": 1
  },
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "text": "What's a catchy headline for a sustainable shoe brand?",
      "source": "user",
      "createdAt": "2026-05-01T09:01:30"
    }
  ]
}

Unterhaltung aktualisieren

PATCH/api/v1/workspaces/{workspaceId}/conversations/{conversationId}

Patchet die Steuerkonfiguration einer Unterhaltung. Ausgelassene Felder bleiben unverändert; das Senden eines expliziten null löscht ein Feld. Der Body muss mindestens eines der folgenden Felder enthalten: personality, brandVoiceId oder targetAudienceId.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
conversationId	string	Ja	Kennung der zu aktualisierenden Unterhaltung.
workspaceId	string	Ja	Der Arbeitsbereich, auf den sich die Anfrage bezieht. Muss dem Workspace-Anspruch im Gateway-Token entsprechen.

Anfrage-Body

FeldTypErforderlichBeschreibung

personalityobjectNeinErsetzen Sie die Persönlichkeit der Unterhaltung durch diese Zeichenkette. Senden Sie null, um sie zu löschen. Lassen Sie das Feld aus, um es unverändert zu lassen.

personalityIdintegerNeinKennung einer gespeicherten Persönlichkeitsvorgabe, die der Unterhaltung zugeordnet ist. Wird nur zu Referenzzwecken gespeichert — der tatsächliche Persönlichkeitstext zur Generierungszeit stammt aus personality.

brandVoiceIdobjectNeinErsetzen Sie die Brand-Voice-Steuerung der Unterhaltung durch die Brand Voice mit dieser ID. Der Dienst löst die Brand-Voice-Nutzlast serverseitig auf. Senden Sie null, um sie zu löschen; lassen Sie das Feld aus, um es unverändert zu lassen.

targetAudienceIdobjectNeinErsetzen Sie die Zielgruppen-Steuerung der Unterhaltung durch die Zielgruppe mit dieser ID. Der Dienst löst die Zielgruppenbeschreibung serverseitig auf. Senden Sie null, um sie zu löschen; lassen Sie das Feld aus, um es unverändert zu lassen.

Beispiel

cURL

curl -X PATCH "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "personality": {},
      "personalityId": 0,
      "brandVoiceId": {},
      "targetAudienceId": {}
  }'

Python

import requests

response = requests.patch(
    f"https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
    json={
        "personality": {},
        "personalityId": 0,
        "brandVoiceId": {},
        "targetAudienceId": {}
    },
).json()

Node.js

const response = await fetch(
  `https://app.neuroflash.com/api/v1/workspaces/${workspaceId}/conversations/${conversationId}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
          "personality": {},
          "personalityId": 0,
          "brandVoiceId": {},
          "targetAudienceId": {}
    }),
  }
).then((r) => r.json());

Go

body, _ := json.Marshal(map[string]any{
		"personality": map[string]any{},
		"personalityId": 0,
		"brandVoiceId": map[string]any{},
		"targetAudienceId": map[string]any{},
	})

req, _ := http.NewRequest("PATCH", "https://app.neuroflash.com/api/v1/workspaces/"+workspaceID+"/conversations/"+conversationID+"", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Antwort:

{}

Aktive Streaming-Antwort abbrechen

DELETE/api/v1/workspaces/{workspaceId}/conversations/{conversationId}/message-streams

Signal an den Service, um den aktiven SSE-Stream für die angegebene Konversation zu stoppen. Der SSE-Kanal des Streams wird sich kurz darauf schließen (bereits erzeugte Teilausgabe bleibt erhalten). Dies aufzurufen, wenn kein Stream aktiv ist, ist ein No-Op und gibt trotzdem 200 zurück.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
conversationId	string	Ja	Kennung der Konversation, deren Stream abgebrochen werden soll.
workspaceId	string	Ja	Der Arbeitsbereich, auf den sich die Anfrage bezieht. Muss dem Workspace-Anspruch im Gateway-Token entsprechen.

Beispiel

cURL

curl -X DELETE "https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/message-streams" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

requests.delete(
    f"https://app.neuroflash.com/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}/message-streams",
    headers={"Authorization": f"Bearer {token}"},
)

Node.js

await fetch(
  `https://app.neuroflash.com/api/v1/workspaces/${workspaceId}/conversations/${conversationId}/message-streams`,
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${token}` },
  }
);

Go

req, _ := http.NewRequest("DELETE", "https://app.neuroflash.com/api/v1/workspaces/"+workspaceID+"/conversations/"+conversationID+"/message-streams", nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

Antwort:

{}