- Graphwise Platform Documentation
- Graphwise API Endpoints
- GraphRAG
- Conversations Service API
Conversations Service API
30/09/2026
GraphRAG version 1.2.0
The Conversations Service serves as the backend for the GraphRAG application, managing chat conversations and questions while integrating with the GraphRAG Workflows engine. It exposes an API for retrieving conversation history and provides real-time access to all GraphRAG functionality through Server-Sent Events (SSE).
Keycloak: The conversation service validates OAuth 2.0 tokens for all API requests through the Keycloak realm, ensuring users can only access their authorized content.
GraphRAG UI: The conversation service exposes APIs that provide conversation history and establish real-time chat connections via Server-Sent Events (SSE) for both the UI and other integrated applications.
DuckDB: The service persists all conversation data in a DuckDB database, including chat history and real-time messages exchanged through the SSE connection. Each message contains the complete user question-answer pair.
GraphRAG Workflows: During system deployment, the conversation service's initialization API configures GraphRAG Workflows by creating a dedicated service user, provisioning all required workflows, and securely storing the necessary credentials.
When a client initiates a chat, a webhook triggers a workflow. The webhook payload is sent to the conversation service's streaming endpoint, which forwards real-time updates to the client via an open Server-Sent Events (SSE) connection.
GraphRAG Workflows queries the conversation service to access the current conversation's question history, leveraging it as short-term memory for context-aware responses.
Base URL | https://{your-domain}/conversations |
|---|---|
Version | 1.2.0 |
Protocol | HTTP/HTTPS |
Resources are available at these locations:
Interactive Swagger UI |
|
OpenAPI Specification |
|
Note
Throughout this documentation, we use https://api.example.com as the base URL. Replace this with your actual deployment URL.
curl "https://api.example.com/conversations/__health"
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?"}'curl "https://api.example.com/conversations" \ -H "Authorization: Bearer <access_token>"
The client APIs provide the primary interface for user interactions with the GraphRAG system. These APIs manage the full lifecycle of conversation history. Users can submit initial questions and follow-up queries through any custom client application or user interface, with the APIs handling the routing of requests to the appropriate GraphRAG components and returning structured responses that preserve conversational context.
Endpoint | Purpose |
|---|---|
| Retrieves all conversations for the authenticated user enabling client applications to display complete conversation history. |
| Retrieves all questions of a specific conversation including all messages received via SSE for every question. |
| Permanently deletes a specific conversation from the conversation history. |
Endpoint | Purpose |
|---|---|
| Only retrieves a single conversation. Its structure matches that of its multi-API counterpart. |
| Only retrieves a single question including all messages received via SSE. Its structure matches that of its multi-API counterpart. |
| Retrieves concept details for a list of concepts |
Internally, the GraphRAG system leverages the conversation service API. Currently this is only the case when generating SSE event messages within the workflows orchestration.
Method | Endpoint | Details |
|---|---|---|
|
| Generates a message when a question is received over an open SSE connection (question asked). It persists the messages and forwards them to the client. |
Tip
Refer to the SSE section for more details on the structure and available message types.
Method | Endpoint | Details | Authentication |
|---|---|---|---|
|
| Start conversation or ask question | Default: Yes |
|
| List user's conversations | Default: Yes |
|
| Get conversation by ID | Default: Yes |
|
| Delete conversation | Default: Yes |
|
| Update title of conversation | Default: Yes |
|
| List questions in conversation | Default: Yes |
|
| Get specific question | Default: Yes |
|
| Get concept details for a list of concepts | Default: Yes |
|
| Internal: Generate SSE message | Internal |
|
| Troubleshooting | No |
|
| Health status | No |
|
| Readiness check | No |
|
| Service info | No |
| Bad request: returns string (error message) |
| Unauthorized |
| Forbidden; the server understood the request but refused to process it indicating an authorization issue |
| Not found; resource is either not available at all or not available for the currently logged in user |
| Too many requests; user tried to create too many concurrent SSE connections |
| Internal server error; no response content, examine the logs |