- Graphwise Platform Documentation
- Graphwise API Endpoints
- GraphRAG
- Conversations Service API
- The Conversations Service API -
POST /chat
The Conversations Service API - POST /chat
05/06/2026
This sections covers all details related to the POST /chat endpoint.
POST /chatInitiates a new conversation or asks a follow-up question in an existing conversation. Returns a Server-Sent Events (SSE) stream with real-time responses.
Based on whether the conversationId parameter in the request is a blank string or an actual conversation ID, it will either create a new conversation or use an existing one. It opens an SSE connection for each question (one connection per question). After the client has received all data each connection is closed.
POST /conversations/chat
Header | Required | Details |
|---|---|---|
Authorization | Yes | Bearer token |
Content-Type | Yes | application/json |
{
"conversationId": "",
"question": "What is GraphRAG?"
}Field | Type | Required | Details |
|---|---|---|---|
| string | Yes | Empty string for new conversation, UUID for a follow-up. |
| string | No | User's question. |
| string | No | Any custom information in the form of a JSON object. It is forwarded to n8n and also persisted in the START message of the conversation. This allows clients to attach arbitrary metadata (such as session context, tracking IDs, or application-specific flags) to individual questions without requiring changes to the core API contract. Custom data is stored with the conversation, supporting downstream analytics, auditability, and client-specific processing logic. |
curl -X POST "https://api.example.com/conversations/chat" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"conversationId": "",
"question": "What is GraphRAG?"
}'Each SSE event (message) follows the same basic structure;
Field | Type | Details |
|---|---|---|
| string | An UUID generated for the message |
| string | Identifies which information the payload is holding (see below) |
| string | The UUID of the conversation |
| string | The UUID of the question |
| string | ISO 8601 timestamp when the message was persisted and sent |
| object | The message payload based on its type |
The response is a Server-Sent Events stream. Each event contains a JSON message:
data: {"messageType":"START","conversationId":"abc-123","questionId":"xyz-789"}
data:
{"messageType":"ANSWER","payload":"GraphRAG is a technology that combines knowledge graphs with Retrieval-Augmented Generation..."}
data:
{"messageType":"SOURCES","payload":[{"uri":"docs/graphrag-overview.pdf","title":"GraphRAG Overview"}]}
data:
{"messageType":"CONCEPTS","payload":[{"id":"concept:123","label":"Knowledge Graph"}]}
data:
{"messageType":"FOLLOWUPS","payload":["How does GraphRAG improve accuracy?","What are the benefits of using knowledge graphs?"]}
data: {"messageType":"END"}Type | Details |
|---|---|
START | Stream initialization |
END | Stream completion |
EXPLAINABILITY | Workflow step notifications |
ANSWER | Complete answer |
ANSWERTOKENS | Streaming answer tokens |
SOURCES | Source documents |
CONCEPTS | Extracted concepts |
FOLLOWUPS | Suggested questions |
GUARDRAILS | Safety check triggered |
CUSTOM | Custom message type for workflow extensions |
TOKEN_USAGE_DETAILS | Provides token consumption details for each step and the total usage per question. |
INTROSPECTION | Contains debug and trace data, such as the main workflow execution ID. |
Sent immediately after the initialization of the SSE channel. Contains only the message header.
Payload
Field | Type | Details |
|---|---|---|
| string | The question asked by the user/client |
Indicates the end of the answering process resulting in the SSE channel being closed immediately after.
Payload;
Field | Type | Details |
|---|---|---|
| string | How did the question answering process end |
Value | Details |
|---|---|
| Process ended successfully |
| Process terminated by the client disconnecting from the SSE connection |
| The SSE connection timed out (see Timeouts) |
| Any other error; examine the logs for details |
Informs the client about a certain step in the question answering workflow (status, success notification, error details, etc.). A single question can contain multiple explainability messages.
Payload
Field | Type | Required | Details |
|---|---|---|---|
| string | Yes | Identifier of the step resulting in the explainability message |
| string | Yes | Message text for the client |
| string | No | Suggested notification type: SUCCESS, WARNING, ERROR, or INFO |
Contains the answer to the client's question generated by the LLM.
Payload
Field | Type | Details |
|---|---|---|
| string | The question asked by the user/client |
| string | The answer generated by the LLM |
Details on extracted concepts from either the client's question or the answer created by the LLM.
Payload
Field | Type | Details |
|---|---|---|
| string | Text source: question or answer |
| Concept[] | Array of concept objects with metadata, extraction score, and string position details |
Contains all sources (text snippets in documents) used to come to the LLM's conclusion.
Payload
Field | Type | Details |
|---|---|---|
| Source[] | Array of source documents with links and relevant text snippets |
Contains suggestions for follow-up questions.
Payload
Field | Type | Details |
|---|---|---|
| FollowUp[] | Array of FollowUp objects containing the question string, reasoning, and topic context |
Generated when guardrails are triggered. This message is not sent when guardrails checks succeed — only the EXPLAINABILITY message informs about the success.
Payload
Field | Type | Details |
|---|---|---|
| string | Whether triggered by input or output: |
| string | Explanation why the guardrails were triggered |
Used for streaming answer tokens to the client in real-time as they are generated by the LLM.
Payload
Field | Type | Details |
|---|---|---|
| string | A single token or chunk of the answer being streamed |
A custom message type that can be used by workflow extensions to send application-specific data to the client.
Payload
Field | Type | Details |
|---|---|---|
| object | Custom payload structure defined by the workflow |
Used for providing details about the token usage of each step of the question answering process.
Payload
Field | Type | Details |
|---|---|---|
| string | Represents the identifier of the step that generated the message. Currently, only a single step identifier is supported/returned. |
| object | A map of tokens used keyed by the name of the step using them. Example: "payload": {
"stepName": "Token usage details",
"details": {
"Input Guardrails": 305,
"Knowledge Graph": 17355,
"Main Answer": 5584,
"Output Guardrails": 922,
"FollowUps": 832
}
}, |
Contains debug and trace data, such as the main workflow execution ID.
Note
This field is marked for internal use. Currently, it only returns the main workflow execution ID, but it is designed to support additional internal information.
Payload
Field | Type | Details |
|---|---|---|
| string | Identifier of what is stored in the value, e.g. |
| any | The value matching the |
The SSE connection has a timeout with default set to 5 minutes. The client application must properly handle these timeouts.
When a timeout occurs, an END message with status ERROR_TIMEOUT is sent before the connection closes.
Use the conversationId from the previous response to ask a follow-up question:
curl -X POST "https://api.example.com/conversations/chat" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "conversationId": "550e8400-e29b-41d4-a716-446655440000",
"question": "Can you give me more details?"
}'