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

# Cognitive Roadmaps: Multi-Test AI Analysis Packages

> Discover cognitive roadmaps: multi-test packages with AI-powered combined analysis, roles, and async generation for deeper insights.

A cognitive roadmap is a curated package of multiple psychological tests bundled together and analyzed as a whole. Unlike standalone records, which return a single test score, roadmaps feed all participant answers into an AI model that produces a combined, narrative analysis across tests.

## What a roadmap contains

Each roadmap defines:

* A set of test records (e.g., MCMI + NEO + DASS-21)
* Required participant roles (who takes which tests)
* An AI analysis module that runs after all tests are complete

Roadmaps are ideal for use cases that need holistic insight, such as pre-marital counseling, comprehensive clinical intake, or executive coaching assessments.

## Participant roles

Every roadmap declares the roles it requires. Common examples include:

| Role        | Typical use case                      |
| ----------- | ------------------------------------- |
| Participant | Single-person assessments             |
| Partner 1   | First person in a couples assessment  |
| Partner 2   | Second person in a couples assessment |

When you authenticate a roadmap, you provide one profile per required role. The API then links each profile to the correct subset of records automatically.

## Roadmap status codes

| Code | Name             | Meaning                                                                          |
| ---- | ---------------- | -------------------------------------------------------------------------------- |
| 0    | VIP wait         | Roadmap exists but is not yet active.                                            |
| 1    | Finished with AI | All tests are complete and AI analysis is ready.                                 |
| 2    | Ready            | Roadmap is active and awaiting authentication.                                   |
| 3    | In progress      | At least one test has been authenticated or submitted, but not all are finished. |
| 4    | AI processing    | All tests are finished. AI analysis is running.                                  |

## Authentication difference

Roadmap records must be authenticated through the roadmap endpoint, not the record endpoint.

* Correct: `POST /roadmap/{token}/auth/`
* Incorrect: `POST /record/{token}/auth/` (will fail for roadmap records)

A single call to `/roadmap/{token}/auth/` starts the authentication flow for all required profiles and links them to every record in the package. You do not need to call auth for each record individually.

The organizer setting `tests_auth_required` (echoed in every roadmap and nested test record) determines the flow:

* `true` (default): the auth call sends an SMS code to the shared mobile and returns a `draft_token`. Finish the flow by calling `PUT /roadmap/{token}/auth/verify/` with the code.
* `false`: the auth call authenticates all role profiles immediately and returns them in the response.

## AI generation

After all tests in a roadmap are finished, you must explicitly queue the AI analysis:

1. Call `POST /roadmap/{token}/generate/` to start the analysis job.
2. Poll `GET /roadmap/{token}/generate/status/` until the status is `completed` or `failed`.
3. The generation typically takes 5 to 10 minutes.

<Note>
  Do not skip the generation step. Roadmap results are not available until the AI analysis job finishes successfully.
</Note>

## Result formats

Once generation is complete, retrieve the combined result:

* `GET /roadmap/{token}/result/json/` for structured data
* `GET /roadmap/{token}/result/html/` for a rendered report