List Cognitive Roadmaps

Use this endpoint to list all cognitive roadmaps associated with your organizer account. Roadmaps are multi-test packages with AI-powered combined analysis, created from the Braintest user panel. You can search by title or filter by completion status, roadmap product type, and participant profile attributes.

Endpoint

GET https://braintest.ir/api/v2/roadmap/

Query Parameters

string

Free-text search across roadmap titles, profile names, mobile numbers, and external IDs.

integer

default:"1"

Page number for pagination. Results are paginated at 30 items per page by default.

boolean

Filter by completion state. Use false to find roadmaps that still need to be started or completed.

string

Filter by roadmap product identifier, for example ClinicalWellbeingTriage.

boolean

Filter by the gender of an assigned participant profile.

string

Filter by the UUID of an assigned participant profile.

integer

Filter by the partner-assigned external profile ID.

Response

integer

Total number of roadmaps matching the query.

string | null

URL for the next page, or null if there are no more pages.

string | null

URL for the previous page, or null on the first page.

array

Array of roadmap list items. Each item includes token, roadmap_id, roadmap_title, display_title, group_id, status, auth_required, tests_auth_required, is_finished, submit_on, and create.

array

Available roadmap product types for filtering, each with id and title.

Example Request

curl -X GET "https://braintest.ir/api/v2/roadmap/?filter__is_finished=false&page=1" \
  -H "API-KEY: YOUR_API_KEY"

Example Response

{
  "data": {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "token": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "roadmap_id": "ClinicalWellbeingTriage",
        "roadmap_title": "Clinical Wellbeing Triage",
        "display_title": "Clinical Wellbeing Triage",
        "group_id": "default",
        "status": 2,
        "auth_required": true,
        "tests_auth_required": true,
        "is_finished": false,
        "submit_on": null,
        "create": "2026-08-22T09:00:00Z"
      }
    ],
    "roadmaps_filter": [
      {
        "id": "ClinicalWellbeingTriage",
        "title": "Clinical Wellbeing Triage"
      }
    ]
  },
  "successful": true,
  "messages": []
}

Status Codes in Results

Code	Meaning
0	Waiting for organizer VIP or billing action
1	Finished with AI analysis
2	Ready to start (no tests submitted)
3	In progress (some tests submitted or profiles assigned)
4	AI generation queued or processing

Error Responses

HTTP	Cause
400	Invalid filter parameter or query
401	Missing or invalid API key
403	Key blocked, API disabled, or prerequisite not met

Overview

Connection

Records

Roadmaps

Endpoint

Query Parameters

Response

Example Request

Example Response

Status Codes in Results

Error Responses

​Endpoint

​Query Parameters

​Response

​Example Request

​Example Response

​Status Codes in Results

​Error Responses

Endpoint

Query Parameters

Response

Example Request

Example Response

Status Codes in Results

Error Responses