Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.questra.ai/llms.txt

Use this file to discover all available pages before exploring further.

Survey Q&A is an optional pre-flight step before programming. Use it when you want researchers to clarify ambiguous questionnaire instructions before Questra generates the survey IR. Q&A is stateless on the server until programming starts. Your app streams questions from a file, stores answers locally, and sends the final Q&A snapshot to POST /surveys/{id}/start-programming.

​
How the flow works

1

Create the survey

Upload the questionnaire with POST /surveys. The response includes both surveyId and fileId.The survey starts in status: "pending" and stays pending during Q&A.
2

Stream questions

Call POST /files/{fileId}/qa with any answered prior questions in priorQa.The response is a server-sent event stream. Each discrepancy event is a question to show the user. The final done event includes the number of questions emitted in that stream.
event: discrepancy
data: {"kind":"reference-missing","severity":"blocker","summary":"Q3 routes to an undefined end page."}

event: done
data: {"count":1}
3

Store answers client-side

Store each streamed question and its answer in client storage, such as localStorage.Do not create backend Q&A records. The server uses priorQa only as request context until you start programming.
4

Run follow-up rounds

Once the user answers the current questions, call POST /files/{fileId}/qa again with the answered snapshot in priorQa.This prevents Questra from re-asking resolved questions and lets it detect any follow-up ambiguity.
5

Start programming

When the stream returns done with count: 0, or when your UI decides to stop asking questions, call POST /surveys/{surveyId}/start-programming with the full Q&A snapshot in qa.Questra persists that qa array on the survey and uses it as clarification context while programming.

​
Request shapes

Call POST /files/{fileId}/qa with answered prior questions: 
{
  "priorQa": [
    {
      "id": "q1",
      "kind": "reference-missing",
      "severity": "blocker",
      "summary": "Q3 routes to an undefined end page.",
      "userClarification": "Route respondents to the termination screen."
    }
  ]
}
Call POST /surveys/{surveyId}/start-programming with the final snapshot: 
{
  "qa": [
    {
      "id": "q1",
      "kind": "reference-missing",
      "severity": "blocker",
      "summary": "Q3 routes to an undefined end page.",
      "excerpt": "If No, skip to end.",
      "userClarification": "Route respondents to the termination screen."
    }
  ]
}

​
TypeScript example

const qa: Array<{
  id: string;
  kind: string;
  severity: string;
  summary: string;
  excerpt?: string;
  suggestions?: string[];
  detail?: Record<string, unknown>;
  userClarification: string;
}> = [];

for await (const event of client.qa.stream(fileId, { priorQa: qa })) {
  if (event.type === 'discrepancy') {
    const answer = await askUser(event.discrepancy);
    qa.push({
      id: crypto.randomUUID(),
      ...event.discrepancy,
      userClarification: answer,
    });
  }

  if (event.type === 'done' && event.count === 0) {
    break;
  }
}

await client.surveys.startProgramming(surveyId, { qa });

​
Endpoint reference

  • POST /files/{id}/qa streams Q&A questions for a questionnaire file.
  • POST /surveys/{id}/start-programming persists the final Q&A snapshot and starts programming.
Q&A is optional. To skip it, call POST /surveys/{id}/start-programming with no qa body or with {"qa":[]}.