Run a Cognitive Roadmap with AI Analysis

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.

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

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.

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.

List your roadmaps

Fetch your available roadmaps and filter for unfinished packages.

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.

Inspect the roadmap

Retrieve the full roadmap details to understand its structure, roles, and test records.

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

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

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)

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)

{
  "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)

{
  "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.

Verify the SMS code (SMS path only)

Ask for the code sent to the shared mobile and submit it with the draft_token.

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

{
  "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.

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

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

# 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
  }'

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

Request AI generation

Once every test record in the roadmap is finished, queue the AI analysis.

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.

Poll for generation status

Check the generation status periodically until it completes or fails.

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

Polling logic example

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

Retrieve the results

After the AI analysis completes, fetch the combined report.

curl -X GET "https://braintest.ir/api/v2/roadmap/{token}/result/json/" \
  -H "API-KEY: YOUR_API_KEY"

curl -X GET "https://braintest.ir/api/v2/roadmap/{token}/result/html/" \
  -H "API-KEY: YOUR_API_KEY"

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

Flow summary

SMS enabled (tests_auth_required: true, default)

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)

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 for single-test workflows
Check the status code reference to understand roadmap lifecycle states
See the error reference for handling common issues like incomplete roadmaps or duplicate profiles

Get Started

Core Concepts

Guides

Reference

Run a Cognitive Roadmap with AI Analysis

Two authentication paths

Flow summary

What to do next

​Two authentication paths

​Flow summary

​What to do next

Two authentication paths

Flow summary

What to do next