> ## 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 Cognitive Roadmap Details

> Fetch a full cognitive roadmap instance including required participant roles, nested test records, and product metadata to prepare for administration.

Use this endpoint to retrieve the complete details of a single cognitive roadmap instance. The response includes the roadmap product definition, required participant roles, and every test record that belongs to the package. Inspect this payload before authenticating profiles or administering tests.

## Endpoint

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

## Path Parameters

<ParamField path="token" type="string" required>
  The unique cognitive roadmap instance UUID.
</ParamField>

## Response

<ResponseField name="data.token" type="string">
  The roadmap instance UUID.
</ResponseField>

<ResponseField name="data.roadmap" type="object">
  Product metadata including `id`, `title`, `current_version`, `roles`, `groups`, and `categories`.
</ResponseField>

<ResponseField name="data.roles" type="array">
  Required participant roles for this roadmap. Each role has:

  * `id`: the role identifier you must reference during authentication
  * `title`: human-readable role name (for example, "Participant")
  * `min_age`: minimum age requirement (or `null` if none)
  * `max_age`: maximum age requirement (or `null` if none)
  * `gender`: `0` = both genders allowed, `1` = male only, `2` = female only
</ResponseField>

<ResponseField name="data.test_records" type="array">
  The test records included in this roadmap. Each item contains:

  * `token`: the test record UUID (use this to fetch questions and submit answers)
  * `test_id`: the test identifier (for example, DASS21, PHQ9)
  * `test_title`: the human-readable test name
  * `status`: `0` = VIP wait, `1` = finished, `2` = ready
  * `auth_required`: whether the profile must be authenticated before starting
  * `is_finished`: whether the test is already completed
  * `role`: the role ID this test is assigned to
</ResponseField>

<ResponseField name="data.status" type="integer">
  Roadmap status: `0` = VIP wait, `1` = finished with AI, `2` = ready, `3` = in progress, `4` = AI processing.
</ResponseField>

<ResponseField name="data.auth_required" type="boolean">
  Whether participant profiles must be authenticated before any tests can proceed.
</ResponseField>

<ResponseField name="data.tests_auth_required" type="boolean">
  Organizer policy for the authentication flow. `true` (default) means `POST /roadmap/{token}/auth/` sends an SMS code and returns a `draft_token` that you complete with `PUT /roadmap/{token}/auth/verify/`. `false` means all role profiles are authenticated instantly. Nested `test_records[]` items include the same flag.
</ResponseField>

<ResponseField name="data.is_finished" type="boolean">
  Whether the roadmap is fully completed and the AI analysis is available.
</ResponseField>

## Example Request

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

## Example Response

```json theme={"dark"}
{
  "data": {
    "token": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "roadmap": {
      "id": "ClinicalWellbeingTriage",
      "title": "Clinical Wellbeing Triage",
      "current_version": 1,
      "roles": [
        {
          "id": 1,
          "title": "Participant",
          "min_age": 18,
          "max_age": null,
          "gender": 0
        }
      ],
      "groups": [],
      "categories": []
    },
    "display_title": "Clinical Wellbeing Triage",
    "group_id": "default",
    "status": 2,
    "auth_required": true,
    "tests_auth_required": true,
    "is_finished": false,
    "submit_on": null,
    "roles": [
      {
        "id": 1,
        "title": "Participant",
        "min_age": 18,
        "max_age": null,
        "gender": 0
      }
    ],
    "test_records": [
      {
        "token": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "test_id": "DASS21",
        "test_title": "DASS-21",
        "status": 2,
        "auth_required": true,
        "tests_auth_required": true,
        "is_finished": false,
        "submit_on": null,
        "role": 1
      },
      {
        "token": "d4e5f6a7-b8c9-0123-def0-234567890123",
        "test_id": "PHQ9",
        "test_title": "PHQ-9",
        "status": 2,
        "auth_required": true,
        "tests_auth_required": true,
        "is_finished": false,
        "submit_on": null,
        "role": 1
      }
    ],
    "create": "2026-08-22T09:00:00Z"
  },
  "successful": true,
  "messages": []
}
```

## Error Responses

| HTTP | Cause                                          |
| ---- | ---------------------------------------------- |
| 404  | Roadmap not found or not owned by your account |