Skip to main content
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

202 response includes:
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.

​
Subscribe to identified questions

(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

See Live updates 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

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