Zum Hauptinhalt springen

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{'}'} bei nachfolgenden Endpunkten. Der optionale Text konfiguriert die anfĂ€ngliche Steuerung der Konversation (Persönlichkeit, Markensprache, Zielgruppe, LLM).

Pfadparameter​

ParameterTypErforderlichBeschreibung
workspaceIdstringJaDer Arbeitsbereich, auf den die Anfrage operiert. Muss mit dem Workspace-Anspruch im Gateway-Token ĂŒbereinstimmen.

Anfrage-Body​

FeldTypErforderlichBeschreibung
personalitystringNeinBeschreibung der Persönlichkeit im Freitext, die in die Systemaufforderung fĂŒr diese Konversation eingewoben ist. Wenn sowohl personality als auch eine Markensprache-Auflösung von brandVoiceId vorhanden sind, gewinnt die explizite personality-Zeichenkette.
personalityIdintegerNeinBezeichner einer gespeicherten Persönlichkeitsvorgabe, die dieser Konversation zugeordnet ist. Nur zur RĂŒckreferenz gespeichert — der tatsĂ€chliche zur Generierungszeit verwendete Persönlichkeitstext stammt immer noch von personality.
brandVoiceIdstringNeinBezeichner der Markensprache, die Assistentenantworten steuern soll. Der Dienst löst die Markensprache serverseitig von dieser ID auf.
targetAudienceIdstringNeinBezeichner der Zielgruppe, die Assistentenantworten steuern soll. Der Dienst löst die Zielgruppenbeschreibung serverseitig von dieser ID auf.
modelNamestringNeinEine Enumeration.

Antwort​

FeldTypBeschreibung
idstringStabiler Bezeichner der Konversation. Serverseitig bei POST /conversations generiert; erforderlich fĂŒr alle nachfolgenden Operationen auf der Konversation.
createdAtstringZeitpunkt der ersten Erstellung der Konversation.
modelNamestringLLM fĂŒr Assistentenantworten. null fĂ€llt auf die dienstweite Standardeinstellung zurĂŒck. Als freie Zeichenkette statt als Enumeration zurĂŒckgegeben, damit historische Konversationen, die mit Modellen erstellt wurden, die sich nicht mehr in der fĂŒr die Erstellung akzeptierten Menge befinden (siehe :class:ConversationCreateCmd.modelName), immer noch bei LesevorgĂ€ngen konsistent sind.
legacyCustomerIdintegerAutor der Konversation, erfasst vom Gateway-Token bei der Erstellung. null fĂŒr Konversationen, die erstellt wurden, bevor dieses Feld existierte — der Besitz fĂŒr diese fĂ€llt auf die api_master.ai_writer_projects.author_id-VerknĂŒpfung zurĂŒck.

Beispiel​

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"
}'

Antwort:

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

Eine Nachricht senden und eine synchrone Antwort erhalten​

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

FĂŒgen Sie eine Benutzernachricht zur Unterhaltung hinzu und geben Sie die Assistentenantwort zurĂŒck, sobald die Generierung abgeschlossen ist. Das erneute Abspielen derselben Nachricht id ist idempotent: die zuvor generierte Antwort wird ohne einen neuen LLM-Aufruf zurĂŒckgegeben.

Verwenden Sie fĂŒr Streaming-Antworten stattdessen POST .../message-streams.

Pfadparameter​

ParameterTypErforderlichBeschreibung
conversationIdstringJaKennung der Unterhaltung, zu der die Nachricht hinzugefĂŒgt wird.
workspaceIdstringJaDer Arbeitsbereich, auf den die Anfrage operiert. Muss mit dem Workspace-Anspruch im Gateway-Token ĂŒbereinstimmen.

Anfrage-Body​

FeldTypErforderlichBeschreibung
idstringJaVon dem Client bereitgestellte ID fĂŒr die Benutzernachricht. Idempotent: Das erneute Abspielen derselben ID gibt die zuvor generierte Assistentenantwort ohne erneute LLM-AusfĂŒhrung zurĂŒck.
textstringJaDer Text der Benutzernachricht.
createdAtstringJaClientseitiger Zeitstempel fĂŒr den Zeitpunkt, zu dem der Benutzer die Nachricht gesendet hat.
additionalContextarray<object>NeinZusĂ€tzliche Kontextausschnitte, die fĂŒr diesen Durchgang in die Eingabeaufforderung eingefĂŒgt werden (z. B. Produktfakten, Referenzausschnitte). Jeder Eintrag hat content und optionales source.
idintegerJa
contentstringJa
category_namestringNein
contextSizeintegerNeinMaximale Anzahl von Eingabe-Token der Unterhaltungsverlauf, die in das LLM eingespeist werden sollen. Ä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 -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
}'

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"
}

Ein Streaming-Antwort fĂŒr einen Unterhaltungsdurchgang öffnen​

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

FĂŒgen Sie eine Benutzernachricht hinzu und streamen Sie die Assistentenantwort als Server-Sent Events (Content-Type: text/event-stream). Jedes Ereignis trĂ€gt entweder ein partielles delta, die vollstĂ€ndige message-Nutzlast oder einen error.

Nur ein Stream pro Unterhaltung darf gleichzeitig aktiv sein — ein zweiter Aufruf gibt 409 conversationLocked zurĂŒck, bis der aktive Stream beendet wird oder ĂŒber DELETE .../message-streams abgebrochen wird. Streams sind nicht persistent: es gibt kein GET, um sie abzurufen.

Pfadparameter​

ParameterTypErforderlichBeschreibung
conversationIdstringJaKennung der Unterhaltung, in der eine Antwort gestreamt werden soll.
workspaceIdstringJaDer Arbeitsbereich, auf den die Anfrage operiert. Muss mit dem Workspace-Anspruch im Gateway-Token ĂŒbereinstimmen.

Anfrage-Body​

FeldTypErforderlichBeschreibung
idstringJaVon dem Client bereitgestellte ID fĂŒr die Benutzernachricht, die den Stream startet. Idempotent: Das erneute Abspielen derselben ID gibt die bestehende Assistentenantwort erneut ab, ohne das LLM erneut auszufĂŒhren (seien Sie also vorsichtig mit Wiederholungen — sie lösen KEINE neue Generierung aus).
textstringJaDer Text der Benutzernachricht.
createdAtstringJaClientseitiger Zeitstempel fĂŒr den Zeitpunkt, zu dem der Benutzer die Nachricht gesendet hat.
additionalContextarray<object>NeinZusĂ€tzliche Kontextausschnitte, die fĂŒr diesen Durchgang in die Eingabeaufforderung eingefĂŒgt werden (z. B. Produktfakten, Referenzausschnitte). Jeder Eintrag hat content und optionales source.
idintegerJa
contentstringJa
category_namestringNein
contextSizeintegerNeinMaximale Anzahl von Eingabe-Token der Unterhaltungsverlauf, die in das LLM eingespeist werden sollen. Ältere Nachrichten werden gekĂŒrzt, um zu passen. Standard ist 16000.

Beispiel​

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
}'

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, in der Standard-PaginierungshĂŒlle.

Pfadparameter​

ParameterTypErforderlichBeschreibung
workspaceIdstringJaDer Arbeitsbereich, auf den die Anfrage operiert. Muss mit dem Workspace-Anspruch im Gateway-Token ĂŒbereinstimmen.

Abfrageparameter​

ParameterTypStandardBeschreibung
pageinteger1Seitennummer zum Abrufen. Die erste Seite ist 1 (nicht 0).
sizeinteger20Anzahl der Elemente pro Seite. Maximum 100.

Antwort​

FeldTypBeschreibung
pageobject
sizeintegerAngeforderte SeitengrĂ¶ĂŸe. Wird zurĂŒckgesendet, auch wenn data weniger Elemente enthĂ€lt (z. B. auf der letzten Seite).
totalElementsintegerGesamtzahl der Elemente ĂŒber alle Seiten.
totalPagesintegerGesamtzahl der Seiten fĂŒr die angeforderte size.
currentPageintegerZurĂŒckgegebene Seitennummer. Die erste Seite ist 1 (nicht 0).
dataarray<object>Elemente auf der aktuellen Seite. Kann auf der letzten Seite weniger als page.size enthalten.
idstringStabiler Bezeichner der Konversation. Serverseitig bei POST /conversations generiert; erforderlich fĂŒr alle nachfolgenden Operationen auf der Konversation.
createdAtstringZeitpunkt der ersten Erstellung der Konversation.
modelNamestringLLM fĂŒr Assistentenantworten. null fĂ€llt auf die dienstweite Standardeinstellung zurĂŒck. Als freie Zeichenkette statt als Enumeration zurĂŒckgegeben, damit historische Konversationen, die mit Modellen erstellt wurden, die sich nicht mehr in der fĂŒr die Erstellung akzeptierten Menge befinden (siehe :class:ConversationCreateCmd.modelName), immer noch bei LesevorgĂ€ngen konsistent sind.
legacyCustomerIdintegerAutor der Konversation, erfasst vom Gateway-Token bei der Erstellung. null fĂŒr Konversationen, die erstellt wurden, bevor dieses Feld existierte — der Besitz fĂŒr diese fĂ€llt auf die api_master.ai_writer_projects.author_id-VerknĂŒpfung zurĂŒck.

Beispiel​

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

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-PaginierungshĂŒlle zurĂŒck. Offset / Limit werden aus den Abfrageparametern page und size abgeleitet.

Pfadparameter​

ParameterTypErforderlichBeschreibung
conversationIdstringJaKennung der Unterhaltung.
workspaceIdstringJaDer Arbeitsbereich, auf den die Anfrage operiert. Muss mit dem Workspace-Anspruch im Gateway-Token ĂŒbereinstimmen.

Abfrageparameter​

ParameterTypStandardBeschreibung
pageinteger1Seitennummer zum Abrufen. Die erste Seite ist 1 (nicht 0).
sizeinteger20Anzahl der Elemente pro Seite. Maximum 100.

Antwort​

FeldTypBeschreibung
pageobject
sizeintegerAngeforderte SeitengrĂ¶ĂŸe. Wird zurĂŒckgesendet, auch wenn data weniger Elemente enthĂ€lt (z. B. auf der letzten Seite).
totalElementsintegerGesamtzahl der Elemente ĂŒber alle Seiten.
totalPagesintegerGesamtzahl der Seiten fĂŒr die angeforderte size.
currentPageintegerZurĂŒckgegebene Seitennummer. Die erste Seite ist 1 (nicht 0).
dataarray<object>Elemente auf der aktuellen Seite. Kann auf der letzten Seite weniger als page.size enthalten.
idstringStabile Kennung der Nachricht.
textstringDer Nachrichtentext.
sourcestringEine Enumeration.
createdAtstringZeitpunkt, zu dem die Nachricht gespeichert wurde.

Beispiel​

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

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"
}
]
}

Eine Konversation aktualisieren​

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

Patchen Sie die Steuerungskonfiguration einer Konversation. Ausgelassene Felder bleiben unverÀndert; das Senden eines expliziten null löscht ein Feld. Der Text muss mindestens eines der Felder personality, brandVoiceId oder targetAudienceId enthalten.

Pfadparameter​

ParameterTypErforderlichBeschreibung
conversationIdstringJaBezeichner der zu aktualisierenden Konversation.
workspaceIdstringJaDer Arbeitsbereich, auf den die Anfrage operiert. Muss mit dem Workspace-Anspruch im Gateway-Token ĂŒbereinstimmen.

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 weg, um es unverÀndert zu lassen.
personalityIdintegerNeinKennung einer gespeicherten Persönlichkeitsvorgabe, die der Unterhaltung zugeordnet ist. Nur zur RĂŒckreferenz gespeichert — der eigentliche Persönlichkeitstext, der zum Zeitpunkt der Generierung verwendet wird, 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 weg, 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 weg, um es unverÀndert zu lassen.

Beispiel​

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": {}
}'

Antwort:

{}

Das aktive Streaming-Antwort abbrechen​

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

Signalisieren Sie dem Dienst, den aktiven SSE-Stream fĂŒr die angegebene Unterhaltung zu stoppen. Der SSE-Kanal des Streams wird bald danach geschlossen (alle bereits erstellten Teilergebnisse werden beibehalten). Das Aufrufen dieses Befehls, wenn kein Stream aktiv ist, ist ein No-Op und gibt immer noch 200 zurĂŒck.

Pfadparameter​

ParameterTypErforderlichBeschreibung
conversationIdstringJaKennung der Unterhaltung, deren Stream abgebrochen werden soll.
workspaceIdstringJaDer Arbeitsbereich, auf den die Anfrage operiert. Muss mit dem Workspace-Anspruch im Gateway-Token ĂŒbereinstimmen.

Beispiel​

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

Antwort:

{}