Get Cognitive Roadmap Details

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

GET https://braintest.ir/api/v2/roadmap/{token}

Path Parameters

string

required

The unique cognitive roadmap instance UUID.

Response

string

The roadmap instance UUID.

object

Product metadata including id, title, current_version, roles, groups, and categories.

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

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

integer

Roadmap status: 0 = VIP wait, 1 = finished with AI, 2 = ready, 3 = in progress, 4 = AI processing.

boolean

Whether participant profiles must be authenticated before any tests can proceed.

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.

boolean

Whether the roadmap is fully completed and the AI analysis is available.

Example Request

curl -X GET "https://braintest.ir/api/v2/roadmap/b2c3d4e5-f6a7-8901-bcde-f12345678901" \
  -H "API-KEY: YOUR_API_KEY"

Example Response

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

Overview

Connection

Records

Roadmaps

Get Cognitive Roadmap Details

Endpoint

Path Parameters

Response

Example Request

Example Response

Error Responses

​Endpoint

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

Endpoint

Path Parameters

Response

Example Request

Example Response

Error Responses