Cognitive Assessment API

Overview

API endpoints for managing cognitive assessment results, specifically for HK-MoCA (Hong Kong Montreal Cognitive Assessment) screening tool results.

Endpoints

Method	Endpoint	Description
GET	/api/cognitive-assessment-results	Get all cognitive assessment results for a client/user
GET	/api/cognitive-assessment-results/[cognitiveAssessmentResultId]	Get a specific cognitive assessment result by ID
GET	/api/client/[clientId]/analytics/player/[uid]/cognitive-assessment-history	Get cognitive assessment history for a specific player

---

GET /api/cognitive-assessment-results

Get all cognitive assessment results for a specific user or client.

Query Parameters

Parameter	Type	Required	Description
clientId	string	Optional	Filter by client ID
userId	string	Optional	Filter by user ID

Headers

• Authorization: Bearer <JWT>

Response

• 200 OK:

{
  "data": [
    {
      "id": "string",
      "clientId": "string",
      "userId": "string",
      "createdAt": "2025-01-15T10:30:00Z",
      "assessmentType": "HK-MoCA",
      "rawScore": 28,
      "educationAdjustment": 0,
      "totalScore": 28,
      "percentile": 75,
      "interpretation": "Normal",
      "riskLevel": "LOW",
      "domainScores": [
        {
          "domain": "Immediate Memory",
          "score": 5,
          "maxScore": 5,
          "percentage": 100
        },
        {
          "domain": "Language Fluency",
          "score": 8,
          "maxScore": 9,
          "percentage": 89
        },
        {
          "domain": "Orientation",
          "score": 6,
          "maxScore": 6,
          "percentage": 100
        },
        {
          "domain": "Delayed Recall",
          "score": 9,
          "maxScore": 10,
          "percentage": 90
        }
      ],
      "patientInfo": {
        "age": 38,
        "gender": "FEMALE",
        "educationYears": 12
      },
      "notes": "Patient performed well across all domains"
    }
  ],
  "count": 1
}

• 401 Unauthorized: { error: string }
• 500 Internal Server Error: { error: string }

---

GET /api/cognitive-assessment-results/[cognitiveAssessmentResultId]

Get a specific cognitive assessment result by ID.

Path Parameters

Parameter	Type	Required	Description
cognitiveAssessmentResultId	string	Yes	The unique assessment result ID

Headers

• Authorization: Bearer <JWT>

Response

• 200 OK:

{
  "data": {
    "id": "string",
    "clientId": "string",
    "userId": "string",
    "createdAt": "2025-01-15T10:30:00Z",
    "assessmentType": "HK-MoCA",
    "rawScore": 28,
    "educationAdjustment": 0,
    "totalScore": 28,
    "percentile": 75,
    "interpretation": "Normal",
    "riskLevel": "LOW",
    "domainScores": [
      {
        "domain": "Immediate Memory",
        "score": 5,
        "maxScore": 5,
        "percentage": 100
      }
    ],
    "patientInfo": {
      "age": 38,
      "gender": "FEMALE",
      "educationYears": 12
    }
  }
}

• 401 Unauthorized: { error: string }
• 404 Not Found: { error: string }
• 500 Internal Server Error: { error: string }

---

GET /api/client/[clientId]/analytics/player/[uid]/cognitive-assessment-history

Get cognitive assessment history for a specific player.

Path Parameters

Parameter	Type	Required	Description
clientId	string	Yes	The client ID
uid	string	Yes	The player's UID

Headers

• ClientToken: <client_token> OR
• Authorization: Bearer <firebase_id_token>

Response

• 200 OK:

{
  "success": true,
  "assessmentHistory": [
    {
      "id": "string",
      "createdAt": "2025-01-15T10:30:00Z",
      "assessmentType": "HK-MoCA",
      "rawScore": 28,
      "educationAdjustment": 0,
      "totalScore": 28,
      "percentile": 75,
      "interpretation": "Normal",
      "interpretationText": "正常",
      "riskLevel": "LOW",
      "riskLevelText": "低風險",
      "domainScores": [
        {
          "domain": "Immediate Memory",
          "score": 5,
          "maxScore": 5,
          "percentage": 100
        }
      ],
      "fullAssessmentDetails": {}
    }
  ],
  "total": 1
}

• 401 Unauthorized: { error: string }
• 404 Not Found: { error: string }
• 500 Internal Server Error: { error: string }

---

Data Models

CognitiveAssessmentResult

Field	Type	Description
id	string	Unique identifier
clientId	string	Client ID
userId	string	User ID
createdAt	string (ISO date)	Assessment date
assessmentType	string	Type of assessment (default: "HK-MoCA")
rawScore	number	Raw score (0-30)
educationAdjustment	number	Education adjustment points
totalScore	number	Total score after adjustment
percentile	number (optional)	Percentile ranking
interpretation	string	"Normal" | "Mild" | "Moderate" | "Severe"
riskLevel	string (optional)	"LOW" | "INTERMEDIATE" | "HIGH"
domainScores	DomainScore[]	Array of domain-specific scores
patientInfo	PatientInfo (optional)	Patient information
notes	string (optional)	Additional notes
metadata	object (optional)	Assessment metadata

CognitiveAssessmentDomainScore

Field	Type	Description
domain	string	Domain name (e.g., "Immediate Memory")
score	number	Score achieved
maxScore	number	Maximum possible score
percentage	number	Percentage score (0-100)

PatientInfo

Field	Type	Description
age	number	Patient's age
gender	string	"MALE" | "FEMALE" | "OTHER" | "UNSPECIFIED"
educationYears	number	Years of education

---

Risk Level Interpretation

Risk Level	Description
LOW	Normal cognitive function
INTERMEDIATE	Mild cognitive impairment, monitoring recommended
HIGH	Significant cognitive impairment, further evaluation needed

---

Authentication

All endpoints require Firebase authentication via Bearer token in the Authorization header or ClientToken for admin operations.

---

Error Responses

Status Code	Description
401	Unauthorized
404	Not found
500	Internal server error