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

# Get Test Questions

> Fetch questionnaire content for an authenticated test record as a flat JSON questions array or a pre-rendered HTML form.

Use this endpoint to retrieve the questionnaire for a test record from the Braintest analyst engine. The response is either a flat JSON `questions[]` array (when the test has a JSON definition) or a rendered HTML form (when the test uses an HTML template).

## Endpoint

```http theme={"dark"}
GET https://braintest.ir/api/v2/record/{token}/questions/
```

## Headers

| Header    | Value                                 |
| --------- | ------------------------------------- |
| `API-KEY` | Your API key from the organizer panel |

## Path parameters

<ParamField path="token" type="string" required>
  The UUID token of the test record.
</ParamField>

## Prerequisites

* Profile authenticated (`auth_required` is `false` on the record).
* If the organizer has `tests_auth_required: true`, complete `POST /record/{token}/auth/` followed by `PUT /record/{token}/auth/verify/` first.
* Record must not be finished; billing/VIP checks must pass. Otherwise the endpoint returns **403** or **409**.

## Response formats

The analyst chooses the delivery format per test. There is **no** `sections` wrapper: questions are a flat array in display order.

| Format             | When                                  | `data` shape                                 |
| ------------------ | ------------------------------------- | -------------------------------------------- |
| JSON questionnaire | Test has a JSON definition in analyst | `test_id`, optional `preface`, `questions[]` |
| HTML questionnaire | Test uses an HTML template in analyst | `{ "html": "<...>" }` only                   |

## JSON response fields

<ResponseField name="test_id" type="string">
  Test identifier. Matches the `test_id` on the record (for example, `MCMI`, `NEO`, `DASS21`).
</ResponseField>

<ResponseField name="preface" type="string | null">
  Optional instruction text shown before the questions.
</ResponseField>

<ResponseField name="questions" type="array">
  Flat array of questions in display order. Each item contains:

  <Expandable title="question item">
    <ResponseField name="num" type="string">
      Question number as defined in analyst data.
    </ResponseField>

    <ResponseField name="question" type="object">
      Question stem with optional media.

      * `text` (string): Question text.
      * `audio` (string | null): Optional audio path (may be relative to the analyst media base URL).
      * `image` (string | null): Optional image path (may be relative to the analyst media base URL).
    </ResponseField>

    <ResponseField name="answer" type="object">
      Answer specification.

      * `text` (boolean): `true` means free-text answer (no options); `false` means the participant selects one option from `options`.
      * `options` (array, present when `text` is `false`): Available choices.
    </ResponseField>
  </Expandable>
</ResponseField>

Each option object contains:

<ResponseField name="id" type="integer">
  Value to submit in the `record` array for this question when the participant selects this option.
</ResponseField>

<ResponseField name="num" type="string">
  Display order label.
</ResponseField>

<ResponseField name="text" type="string">
  Option label shown to the participant. Do not send this string as the answer.
</ResponseField>

<ResponseField name="audio" type="string | null">
  Optional audio path.
</ResponseField>

<ResponseField name="image" type="string | null">
  Optional image path.
</ResponseField>

## Example request

```bash theme={"dark"}
curl -X GET "https://braintest.ir/api/v2/record/3fa85f64-5717-4562-b3fc-2c963f66afa6/questions/" \
  -H "API-KEY: YOUR_API_KEY"
```

## Example response (JSON questionnaire)

```json theme={"dark"}
{
  "data": {
    "test_id": "MCMI",
    "preface": "Read each statement and select the closest answer.",
    "questions": [
      {
        "num": "1",
        "question": {
          "text": "Lately, I feel I have not had much energy even in the morning.",
          "audio": null,
          "image": null
        },
        "answer": {
          "text": false,
          "options": [
            { "num": "1", "id": 0, "text": "True", "audio": null, "image": null },
            { "num": "2", "id": 1, "text": "False", "audio": null, "image": null }
          ]
        }
      },
      {
        "num": "2",
        "question": {
          "text": "I must be sure my work is well planned and organized.",
          "audio": null,
          "image": null
        },
        "answer": {
          "text": false,
          "options": [
            { "num": "1", "id": 0, "text": "True", "audio": null, "image": null },
            { "num": "2", "id": 1, "text": "False", "audio": null, "image": null }
          ]
        }
      }
    ]
  },
  "successful": true,
  "messages": []
}
```

## Submitting answers

Call `POST /record/{token}/` with `record` as an array with one entry per question, in the same order as `questions[]`:

* Option questions → the selected option's **`id`** (integer).
* Free-text questions (`answer.text: true`) → the participant's string answer.

Example for a 3-item test: `[1, 0, "my written answer"]`.

Allowed values and array length are validated by the analyst for each test (for example, MCMI expects 195 integers of `0` or `1`).

## Example response (HTML questionnaire)

When the analyst uses an HTML template, `data` contains only an `html` string:

```json theme={"dark"}
{
  "data": {
    "html": "<div class=\"test-form\">...</div>"
  },
  "successful": true,
  "messages": []
}
```

Embed the `html` string in an iframe or WebView. HTML forms are designed for the Braintest panel flow; for deep external integration, prefer tests that return JSON so you control the UI and submit via `POST /record/{token}/`.

## Errors

| Status | Meaning                                             |
| ------ | --------------------------------------------------- |
| 403    | Profile auth, payment, or VIP prerequisite not met. |
| 404    | Test record not found.                              |
| 409    | Record already completed.                           |