Migrate from Single-Shot Questions to Conversations

Deprecated

The single-shot question flow is deprecated and will be removed in a future release. Migrate to the conversation endpoints as soon as possible to avoid breakage.

This guide explains how to replace the asynchronous single-shot question flow with the synchronous conversation flow. You can preserve one-question-per-request behavior by starting a new conversation for every question. You only need to continue a conversation if you want multi-turn context.

Why migrate?

No polling: starting a conversation returns the question and answer in one synchronous response.
One API surface: submission, retrieval, feedback, and history use conversation and message resources.
Multi-turn ready: the same API supports follow-up questions when your application needs them.

Quick mapping (old → new)

Base URL note: the legacy submit endpoint uses Agent API ({{baseUrl}}/agent/...). Conversation endpoints use QnA API ({{baseUrl}}/qna/...).

Workflow step	Single-shot flow (legacy)	Conversation flow	Notes
Submit a question	`POST /agent/agents/{agentId}/questions`	`POST /qna/agents/{agentId}/conversations`	Returns `200 OK` with the answer instead of `202 Accepted`.
Retrieve an answer	`GET /qna/questions/{questionId}/answer`	Response from `POST /conversations`, or `GET /qna/agents/{agentId}/conversations/{conversationId}/messages/{messageId}`	Polling is removed.
Submit feedback	`POST /qna/questions/{questionId}/answer/feedback`	`POST /qna/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback`	Store both IDs returned when the conversation starts.
Retrieve history	`GET /qna/agents/{agentId}/questions/history`	`GET /qna/agents/{agentId}/conversations`, then `GET /qna/agents/{agentId}/conversations/{conversationId}/messages`	Conversation history is hierarchical and cursor-paginated.

The agentId and Hxp-Environment value do not change. The application key and token scope do:

Flow	`Hxp-App`	Required token scope
Single-shot (legacy)	`hxai-discovery`	`hxp iam.jti-capture`
Conversation	`cin-ece-kd`	`hxp`

The ECE-powered Conversation API does not require iam.jti-capture. If your application also calls Agent management or Agent discovery endpoints, use the key that matches the Knowledge Discovery implementation: hxai-discovery for legacy or cin-ece-kd for ECE-powered Knowledge Discovery. Those /agent endpoint paths are shared by both implementations.

warning

If your HTTP client doesn't add the User-Agent header by default, include it in every request (for example, User-Agent: MyApp/1.0) to avoid a 403 Forbidden response.

Step-by-step migration

Step 1 — Replace question submission and polling

The legacy flow submits a question to Agent API and then polls QnA API until processing completes.

Before: submit and poll

HTTP
curl

POST {{baseUrl}}/agent/agents/{{agentId}}/questions
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: hxai-discovery
Content-Type: application/json

{
  "question": "What is the vacation policy for new employees?",
  "contextObjectIds": null,
  "dynamicFilter": null
}

After the endpoint returns 202 Accepted, retrieve the questionId from the Location header or response body and poll:

GET {{baseUrl}}/qna/questions/{{questionId}}/answer
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: hxai-discovery

AGENT_ID="hr-agent-id"

curl -X POST "${DISCOVERY_API_BASE_URL}/agent/agents/${AGENT_ID}/questions" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: hxai-discovery" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the vacation policy for new employees?",
    "contextObjectIds": null,
    "dynamicFilter": null
  }'

curl -X GET "${DISCOVERY_API_BASE_URL}/qna/questions/${QUESTION_ID}/answer" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: hxai-discovery"

After: start a conversation

Send the same question fields to the QnA conversation endpoint:

HTTP
curl

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: cin-ece-kd
Content-Type: application/json

{
  "question": "What is the vacation policy for new employees?",
  "contextObjectIds": null,
  "dynamicFilter": null
}

AGENT_ID="hr-agent-id"

curl -X POST "${DISCOVERY_API_BASE_URL}/qna/agents/${AGENT_ID}/conversations" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: cin-ece-kd" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the vacation policy for new employees?",
    "contextObjectIds": null,
    "dynamicFilter": null
  }'

The endpoint returns 200 OK after the first answer has been generated:

{
  "conversation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": null,
    "description": null,
    "lastModified": "2026-09-14T10:30:05Z"
  },
  "message": {
    "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "question": "What is the vacation policy for new employees?",
    "answer": "New employees are eligible for 15 days of paid vacation per year.",
    "documentReferences": [],
    "graphDocumentReferences": [],
    "feedback": null,
    "staticFilter": null,
    "dynamicFilter": null,
    "dateCreated": "2026-09-14T10:30:00Z",
    "dateAnswered": "2026-09-14T10:30:05Z",
    "agentVersion": 1,
    "status": "Answered"
  }
}

Persist conversation.id and message.id. Conversation operations, message retrieval, and feedback require these identifiers.

Configure synchronous timeouts

Conversation requests can take up to 480 seconds for complex Graph RAG queries. Configure the HTTP client and every intermediary timeout to allow at least 480 seconds; otherwise the client can disconnect before the API returns the answer.

Request field mapping

Single-shot request field	Conversation request field	Notes
`question`	`question`	No change.
`contextObjectIds`	`contextObjectIds`	No change.
`dynamicFilter`	`dynamicFilter`	No change; it must still match the agent's dynamic filter template.
—	`enableCitations`	Optional. Set to `true` to include inline citation markers in the answer.

Response field mapping

Single-shot answer field	Conversation response field	Notes
`questionId`	`message.id`	A conversation also has its own `conversation.id`.
`answer`	`message.answer`	Returned synchronously.
`question`	`message.question`	Nested under `message`.
`responseCompleteness: "Complete"`	`message.status: "Answered"`	Other message statuses are `Unspecified`, `Submitted`, `Error`, and `Blocked`.
`objectReferences[].objectId`	`message.documentReferences[].documentId`	Nested reference entries keep `referenceId`, `rankScore`, and `rank`.
`feedback`	`message.feedback`	Feedback remains message-specific.
`staticFilter`	`message.staticFilter`	Nested under `message`.
`dynamicFilter`	`message.dynamicFilter`	Nested under `message`.

Step 2 — Update feedback submission

Replace the question-based path with the conversation message path.

HTTP
curl

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}/messages/{{messageId}}/feedback
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: cin-ece-kd
Content-Type: application/json

{
  "feedback": "Good"
}

CONVERSATION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
MESSAGE_ID="f1e2d3c4-b5a6-7890-1234-567890abcdef"

curl -X POST "${DISCOVERY_API_BASE_URL}/qna/agents/${AGENT_ID}/conversations/${CONVERSATION_ID}/messages/${MESSAGE_ID}/feedback" \
  -H "Authorization: Bearer ${DISCOVERY_ACCESS_TOKEN}" \
  -H "Hxp-Environment: ${ENVIRONMENT_KEY}" \
  -H "Hxp-App: cin-ece-kd" \
  -H "Content-Type: application/json" \
  -d '{"feedback": "Good"}'

The supported feedback values remain Good, Bad, and Retry.

Step 3 — Replace question history

The legacy endpoint returns a flat, page-number-paginated list of questions. The conversation API first lists conversations, then lists the messages within a selected conversation.

List conversations for an agent

GET {{baseUrl}}/qna/agents/{{agentId}}/conversations?pageSize=20
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: cin-ece-kd

List messages in a conversation

GET {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}/messages?pageSize=50&maxContentLength=500
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: cin-ece-kd

Both endpoints use cursor pagination. Read pagination.nextCursor from the response and pass it as the cursor query parameter while pagination.hasMore is true.

Legacy history behavior	Conversation history behavior
One flat list of questions and answers	A list of conversations, each containing messages
`pageNumber` and `pageSize`	`cursor` and `pageSize`
Question ID identifies each item	Conversation ID identifies the container; message ID identifies each question and answer
`maxContentLength` on the history request	`maxContentLength` on the message-list request

There is no single conversation endpoint that reproduces the legacy flat history response. For history screens, list conversations first and fetch messages when a conversation is selected instead of expanding every conversation eagerly.

Optional Step 4 — Continue a conversation

Applications that only need one-off answers can start a new conversation for each question and stop after Step 1. To retain context for a follow-up question, add a message to the existing conversation:

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}/messages
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: cin-ece-kd
Content-Type: application/json

{
  "question": "How does the policy change after five years?",
  "contextObjectIds": null,
  "dynamicFilter": null
}

The response is a single message object. Store its id for later retrieval or feedback.

Code change checklist (consumer-side)

Replace POST /agent/agents/{agentId}/questions with POST /qna/agents/{agentId}/conversations.
Change Hxp-App from hxai-discovery to cin-ece-kd and request only the hxp token scope.
Remove polling of GET /qna/questions/{questionId}/answer.
Configure the client and intermediary timeouts for synchronous requests of up to 480 seconds.
Parse the answer from message.answer and status from message.status.
Store both conversation.id and message.id; do not treat them as interchangeable.
Replace objectReferences handling with documentReferences handling.
Update feedback requests to include the agent, conversation, and message IDs.
Replace flat, page-number-based history handling with conversation and message lists using cursor pagination.
Keep question, contextObjectIds, and dynamicFilter request values unchanged.

For the complete conversation API, including conversation metadata and message retrieval, see the Conversations Tutorial.

Why migrate?​

Quick mapping (old → new)​

Step-by-step migration​

Step 1 — Replace question submission and polling​

Before: submit and poll​

After: start a conversation​

Request field mapping​

Response field mapping​

Step 2 — Update feedback submission​

Step 3 — Replace question history​

List conversations for an agent​

List messages in a conversation​

Optional Step 4 — Continue a conversation​

Code change checklist (consumer-side)​