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

This is the clarification side-channel for the v2 (adhoc) streaming ask. It is a short, non-streaming request: it returns immediately with { "status": "accepted" }, while every further event (more state frames, the streamed summary, or another pendingQuestion) continues on the SSE connection you already have open — you do not reopen /v2/stream/ask. See the stream/ask reference for the full stream lifecycle and event types.

What It Does

1. Correlates your answer to the paused turn using the queryId and questionId carried by 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/ask stream resumes — it continues SQL generation and execution, streams the summary, emits another pendingQuestion if more input is needed, and finally message_stop.

The answer is routed only by queryId + questionId, and the paused turn 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/ask (SSE stays open)"]
  pending["pendingQuestion (carries queryId + questionId)"]
  respond["POST /v2/stream/ask/respond (side-channel)"]
  accepted["Returns status: accepted"]
  resume["Original stream resumes"]
  stop["message_stop"]

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

Basic Usage

The /v2/stream/ask stream pauses and emits a pendingQuestion frame carrying the queryId and questionId you must echo back:

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",
    "queryId": "1f0a3c7d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "threadId": "0625991d-1bba-407d-8ad4-dd0210172484"
  }
}

Answer it with a SUBMIT, passing the selected option value(s) in answers:

{
  "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 turn then continues on the same /v2/stream/ask connection — for example:

data: { "type": "state", "data": { "state": "sql_generation_generating" }}
data: { "type": "state", "data": { "state": "sql_generation_success", "sql": "SELECT ... WHERE \"status\" = 'active' LIMIT 5" }}
data: { "type": "state", "data": { "state": "sql_execution_start" }}
data: { "type": "state", "data": { "state": "sql_execution_end" }}
data: { "type": "content_block_start", "content_block": { "type": "text", "name": "summary_generation" }}
data: { "type": "content_block_delta", "delta": { "text": "Here are the top active customers ..." }}
data: { "type": "content_block_stop" }
data: { "type": "message_stop" }

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.