The POST /v2/stream/interactive_ask/respond endpoint answers a clarification checkpoint raised during a /v2/stream/interactive_ask conversation. When the conversation pauses and emits a pendingQuestion frame, you send the user's choice here — and the original, still-open /v2/stream/interactive_ask SSE stream resumes from where it paused.

This is the clarification side-channel for the v2 interactive conversation. Like stream/ask/respond, it is a short, non-streaming request: it returns immediately with { "status": "accepted" }, while every further event (more AI content_block_* frames — with ECharts charts arriving inline — another pendingQuestion, or the terminal { "done": true }) continues on the SSE connection you already have open — you do not reopen /v2/stream/interactive_ask. See the stream/interactive_ask reference for the full conversation stream.

What It Does

1. Correlates your answer to the paused conversation using the queryId from the leading init frame and the questionId from the pendingQuestion frame.
2. Applies the chosen action — SUBMIT, SKIP, RETRY, or CLOSE.
3. Returns immediately with { "status": "accepted" }. This call never streams.
4. The original /v2/stream/interactive_ask stream resumes — it keeps forwarding AI content blocks (charts arrive inline), emits another pendingQuestion if more input is needed, and finally the terminal { "done": true }.

The answer is routed only by queryId + questionId, and the paused conversation is held in memory by the server instance that owns the open stream. Answer promptly, on the same connection you opened.

How It Works

graph TD
  ask["POST /v2/stream/interactive_ask (SSE stays open)"]
  init["init frame (carries queryId)"]
  pending["pendingQuestion (carries questionId)"]
  respond["POST /v2/stream/interactive_ask/respond (side-channel)"]
  accepted["Returns status: accepted"]
  resume["Original conversation resumes"]
  done["done: true"]

  ask --> init
  init -->|"AI needs clarification"| pending
  pending -->|"Reply with action + answers/freeText"| respond
  respond --> accepted
  respond -.->|"Unblocks the paused conversation"| resume
  resume --> done

Basic Usage

The leading init frame of /v2/stream/interactive_ask carries the queryId you use to answer clarifications:

data: { "type": "init", "threadId": "0625991d-1bba-407d-8ad4-dd0210172484", "queryId": "1f0a3c7d-4e5f-6a7b-8c9d-0e1f2a3b4c5d" }

Later, the conversation may pause and emit a pendingQuestion frame carrying the questionId:

data: {
  "type": "pendingQuestion",
  "data": {
    "questionId": "b8f0c1e2-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "checkpoint": "intent",
    "question": "Which \"customers\" did you mean?",
    "options": [
      { "value": "all", "label": "All registered customers" },
      { "value": "active", "label": "Only active customers" }
    ],
    "selectionType": "single"
  }
}

Answer it with the queryId from the init frame and the questionId from the pendingQuestion frame:

{
  "projectId": 1,
  "queryId": "1f0a3c7d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "questionId": "b8f0c1e2-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
  "action": "SUBMIT",
  "answers": ["active"],
  "threadId": "0625991d-1bba-407d-8ad4-dd0210172484"
}

{
  "status": "accepted"
}

The conversation then continues on the same /v2/stream/interactive_ask connection — for example:

data: { "type": "content_block_start", "content_block": { "type": "text", "name": "summary_generation" }}
data: { "type": "content_block_delta", "delta": { "text": "Here are the active customers ..." }}
data: { "type": "content_block_stop" }
data: { "done": true }

Request fields

Actions

action is case-insensitive. A SUBMIT must include at least one of answers or freeText.

Error Handling

This endpoint is a plain JSON request/response — errors come back as a normal error body ({ id?, error, code? }), not as an SSE error frame.