> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.questra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Questionnaire clarifications

> survey.questionnaire_clarifications — probe the tip questionnaire and subscribe to identified questions on the run stream.

Probe the tip questionnaire for clarifying questions before programming. Each probe pass is a `survey.questionnaire_clarifications` run (newest-wins per survey).

The durable step analyzes **UTF-8 questionnaire prose** (tip file bytes) with a single streaming LLM call, grounded by a Questra HCL authoring-knowledge preamble. Questions stream onto the run as they are identified. PDF / binary questionnaires are not text-extracted yet — upload plain text (or extractable UTF-8) for probing. Requires AI Gateway credentials (`AI_GATEWAY_API_KEY`).

## Start a probe

```http theme={null}
POST /v1/surveys/{surveyId}/questionnaire/clarifications
Content-Type: application/json

{}
```

**202** response includes:

| Field         | Use                                                |
| ------------- | -------------------------------------------------- |
| `workflow_id` | Run id (`wrun_...`)                                |
| `session`     | Tip Clarifications session snapshot at accept time |
| `stream_url`  | NDJSON subscribe URL for this pass                 |

<Tip>
  Open `stream_url` immediately after **202**. Questions are appended to the tip session as they are identified; the stream is how first-party UIs learn about them without polling.
</Tip>

## Subscribe to identified questions

```http theme={null}
GET /v1/surveys/{surveyId}/questionnaire/clarifications/runs/{workflow_id}/stream
```

(or the absolute path returned as `stream_url`)

* Response: `application/x-ndjson` — one `QuestionnaireClarificationsStreamChunk` JSON object per line
* From the start: omit `startIndex` or pass `0`
* Reconnect / tail: `?startIndex=N` (positive or negative) while the World retains the run

### Chunk kinds

| `kind`                 | Client action                                                            |
| ---------------------- | ------------------------------------------------------------------------ |
| `started`              | Show probing state                                                       |
| `clarification`        | Append `chunk.clarification` to the open-clarification list (unanswered) |
| `completed`            | Stop streaming; reconcile with tip `GET`                                 |
| `cancelled` / `failed` | Surface `error`; reconcile                                               |

See [Live updates](/workflows/live-updates#surveyquestionnaire_clarifications) for the full chunk schema and an example payload.

## Answer and follow-up

While or after the pass:

1. `GET .../questionnaire/clarifications` — tip session (side-effect free)
2. `PATCH .../questionnaire/clarifications/{clarificationId}` — `{ "kind": "answer", ... }` or `{ "kind": "skip" }`
3. When open clarifications are cleared and `probe_exhausted` is true, `POST .../clarifications` again for another pass, or proceed to programming when `status` is `complete`

Historical revisions under `.../questionnaire/revisions/{revision}/clarifications` are **read-only**.

## Concurrency

Newest-wins: a new probe cancels the prior `survey.questionnaire_clarifications` run for that survey. Drop the old stream and subscribe to the new `stream_url`.

## Tip reconciliation

| Channel                                        | When                                  |
| ---------------------------------------------- | ------------------------------------- |
| Run NDJSON stream                              | Live UI during `probing`              |
| `GET .../clarifications`                       | After stream end, reload, or gap fill |
| Webhook `questionnaire.clarifications.updated` | Backend fanout (full session payload) |

Answers and skips are **not** published on the run stream — only identification during the probe pass.