> ## 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.

# Run a Cognitive Roadmap with AI Analysis

> Run a multi-test cognitive roadmap on Braintest: authenticate roles (SMS or instant), complete each test, generate the AI report, and retrieve results.

This guide walks you through administering a cognitive roadmap: a multi-test package that collects answers from several psychological tests and produces a single AI-powered combined analysis. You will list roadmaps, authenticate all role profiles (using either SMS verification or the instant path), complete each test, trigger AI generation, and retrieve the final report.

<Note>
  **Prerequisites**

  * A valid API key from the organizer panel, sent in the `API-KEY` header
  * At least one roadmap with `status: 2` (ready) available in your account
</Note>

<Warning>
  Do **not** use `/record/{token}/auth/` for test records that belong to a roadmap. Roadmap profiles must be authenticated through `/roadmap/{token}/auth/` instead, which registers all participants across every test in the package.
</Warning>

## Two authentication paths

Every roadmap payload (and each nested item in `test_records`) includes an organizer-level flag named `tests_auth_required` that controls how authentication works:

| `tests_auth_required` | Behavior                                                                                                                                                    |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true` (default)      | `POST /roadmap/{token}/auth/` sends an SMS code to the shared mobile and returns a `draft_token`. Finish the flow with `PUT /roadmap/{token}/auth/verify/`. |
| `false`               | `POST /roadmap/{token}/auth/` authenticates every role immediately and returns them. Skip the verify step.                                                  |

Read `tests_auth_required` from the roadmap before choosing the next step.

<Steps>
  <Step title="List your roadmaps">
    Fetch your available roadmaps and filter for unfinished packages.

    ```bash theme={"dark"}
    curl -X GET "https://braintest.ir/api/v2/roadmap/?filter__is_finished=false" \
      -H "API-KEY: YOUR_API_KEY"
    ```

    Look for a roadmap with `status: 2` (ready). The response includes the `token` you need and `tests_auth_required` which tells you whether SMS verification is on.
  </Step>

  <Step title="Inspect the roadmap">
    Retrieve the full roadmap details to understand its structure, roles, and test records.

    ```bash theme={"dark"}
    curl -X GET "https://braintest.ir/api/v2/roadmap/{token}/" \
      -H "API-KEY: YOUR_API_KEY"
    ```

    Key fields to review:

    * `roles`: array of role definitions, each with an `id`, `title`, `min_age`, `max_age`, and `gender`
    * `test_records`: array of individual test records included in the package (each also carries `tests_auth_required`)
    * `status`: must be `2` (ready)
    * `auth_required`: indicates whether profiles still need to be linked
    * `tests_auth_required`: selects the auth path
  </Step>

  <Step title="Start authentication for all roles">
    Post every role profile in a single call. This registers all participants across every test in the package.

    **Single-role roadmap example**

    ```bash theme={"dark"}
    curl -X POST "https://braintest.ir/api/v2/roadmap/{token}/auth/" \
      -H "API-KEY: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "mobile": "09123456789",
        "roles": [
          {
            "id": 1,
            "profile": {
              "name": "علی احمدی",
              "birth": "1990-05-15",
              "is_male": true,
              "external_id": 12345
            }
          }
        ]
      }'
    ```

    **Two-role roadmap example (couple)**

    ```bash theme={"dark"}
    curl -X POST "https://braintest.ir/api/v2/roadmap/{token}/auth/" \
      -H "API-KEY: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "mobile": "09129876543",
        "roles": [
          {
            "id": 1,
            "profile": {
              "name": "علی احمدی",
              "birth": "1990-05-15",
              "is_male": true,
              "external_id": 12345
            }
          },
          {
            "id": 2,
            "profile": {
              "name": "مریم رضایی",
              "birth": "1992-08-20",
              "is_male": false,
              "external_id": 12346
            }
          }
        ]
      }'
    ```

    * `mobile`: shared contact number for the roadmap. When SMS verification is on, the code is sent here.
    * `roles`: array where each object contains the role `id` and a `profile` object with the same fields used in standalone tests.

    The response echoes `tests_auth_required`. Branch on it to decide the next step.

    **SMS path (`tests_auth_required: true`)**

    ```json theme={"dark"}
    {
      "data": {
        "tests_auth_required": true,
        "draft_token": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "successful": true,
      "messages": []
    }
    ```

    An SMS code is sent to the shared mobile. Keep the `draft_token` for the verify step. It expires after 5 minutes.

    **Instant path (`tests_auth_required: false`)**

    ```json theme={"dark"}
    {
      "data": {
        "tests_auth_required": false,
        "roles": [
          {
            "role_id": 1,
            "profile": {
              "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
              "external_id": 12345,
              "case_number": "ORG-00001",
              "mobile": "09129876543",
              "name": "علی احمدی",
              "age": 34,
              "birth": "1990-05-15",
              "is_male": true
            }
          }
        ]
      },
      "successful": true,
      "messages": []
    }
    ```

    All profiles are created and linked to every record in the package. Skip the next step.
  </Step>

  <Step title="Verify the SMS code (SMS path only)">
    Ask for the code sent to the shared mobile and submit it with the `draft_token`.

    ```bash theme={"dark"}
    curl -X PUT "https://braintest.ir/api/v2/roadmap/{token}/auth/verify/" \
      -H "API-KEY: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "draft_token": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "vcode": "58291"
      }'
    ```

    **Success response**

    ```json theme={"dark"}
    {
      "data": {
        "tests_auth_required": true,
        "roles": [
          { "role_id": 1, "profile": { "token": "...", "name": "علی احمدی", "age": 34, "is_male": true } },
          { "role_id": 2, "profile": { "token": "...", "name": "مریم رضایی", "age": 32, "is_male": false } }
        ]
      },
      "successful": true,
      "messages": []
    }
    ```

    **Common errors**

    | Message                                                        | Fix                                                                                             |
    | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
    | `Verification draft token is invalid or expired.`              | The draft token is unknown or older than 5 minutes. Restart from `POST /roadmap/{token}/auth/`. |
    | `Verification code is invalid.`                                | Ask for the code again.                                                                         |
    | `SMS verification is not required for this organizer account.` | The setting is disabled. Use the roles returned by the auth call instead.                       |

    Skip this step entirely when `tests_auth_required` is `false`.
  </Step>

  <Step title="Complete each test record">
    For every test record inside the roadmap, fetch its questions and submit answers. The order does not matter, but all records must be finished before you can generate the AI analysis.

    **Pseudocode for looping through records**

    ```python theme={"dark"}
    for record in roadmap.test_records:
        if not record.is_finished:
            # 1. Fetch questions
            questions = get(f"/record/{record.token}/questions/")

            # 2. Collect answers from the participant
            answers = []
            for q in questions:
                selected = show_question_and_wait_for_answer(q)
                answers.append({
                    "question_id": q.id,
                    "answer_id": selected
                })

            # 3. Submit answers
            post(f"/record/{record.token}/", {
                "record": answers,
                "doing_duration_in_minutes": duration
            })
    ```

    **Example curl for one record**

    ```bash theme={"dark"}
    # Fetch questions
    curl -X GET "https://braintest.ir/api/v2/record/{record_token}/questions/" \
      -H "API-KEY: YOUR_API_KEY"

    # Submit answers
    curl -X POST "https://braintest.ir/api/v2/record/{record_token}/" \
      -H "API-KEY: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "record": [
          { "question_id": 1, "answer_id": 2 },
          { "question_id": 2, "answer_id": 3 }
        ],
        "doing_duration_in_minutes": 15
      }'
    ```

    <Warning>
      Never call `POST /record/{token}/auth/` or `PUT /record/{token}/auth/verify/` for roadmap records. Authentication was already completed at the roadmap level.
    </Warning>
  </Step>

  <Step title="Request AI generation">
    Once every test record in the roadmap is finished, queue the AI analysis.

    ```bash theme={"dark"}
    curl -X POST "https://braintest.ir/api/v2/roadmap/{token}/generate/" \
      -H "API-KEY: YOUR_API_KEY"
    ```

    The roadmap status changes to `4` (AI processing). Generation typically takes **5 to 10 minutes**.
  </Step>

  <Step title="Poll for generation status">
    Check the generation status periodically until it completes or fails.

    ```bash theme={"dark"}
    curl -X GET "https://braintest.ir/api/v2/roadmap/{token}/generate/status/" \
      -H "API-KEY: YOUR_API_KEY"
    ```

    **Polling logic example**

    ```python theme={"dark"}
    import time

    while True:
        status = get(f"/roadmap/{token}/generate/status/")
        if status.data.state == "completed":
            break
        elif status.data.state == "failed":
            raise Exception("AI generation failed")
        time.sleep(30)  # wait 30 seconds between checks
    ```

    Stop polling when the response returns `state: "completed"` or `state: "failed"`.
  </Step>

  <Step title="Retrieve the results">
    After the AI analysis completes, fetch the combined report.

    <CodeGroup>
      ```bash JSON result theme={"dark"}
      curl -X GET "https://braintest.ir/api/v2/roadmap/{token}/result/json/" \
        -H "API-KEY: YOUR_API_KEY"
      ```

      ```bash HTML result theme={"dark"}
      curl -X GET "https://braintest.ir/api/v2/roadmap/{token}/result/html/" \
        -H "API-KEY: YOUR_API_KEY"
      ```
    </CodeGroup>

    The JSON response contains structured AI analysis, scores from all tests, and combined interpretations. The HTML response is a ready-to-render report page.
  </Step>
</Steps>

## Flow summary

**SMS enabled (`tests_auth_required: true`, default)**

```text theme={"dark"}
GET  /roadmap/                         → read tests_auth_required
POST /roadmap/{token}/auth/            → draft_token (SMS sent)
PUT  /roadmap/{token}/auth/verify/     → roles[]
→ per record: questions → submit
POST /roadmap/{token}/generate/
GET  /roadmap/{token}/generate/status/
GET  /roadmap/{token}/result/json|html/
```

**SMS disabled (`tests_auth_required: false`)**

```text theme={"dark"}
POST /roadmap/{token}/auth/            → roles[] (instant)
→ per record: questions → submit
POST /roadmap/{token}/generate/
GET  /roadmap/{token}/generate/status/
GET  /roadmap/{token}/result/json|html/
```

## What to do next

* Review the [standalone test guide](/guides/run-standalone-test) for single-test workflows
* Check the [status code reference](/reference/status-codes) to understand roadmap lifecycle states
* See the [error reference](/reference/errors) for handling common issues like incomplete roadmaps or duplicate profiles