MSK Assessment API

Overview

API endpoints for managing MSK (Musculoskeletal) assessment results, including shoulder, low-back, and knee assessments.

Endpoints

Method	Endpoint	Description
GET	/api/msk/assessments	List all MSK assessments
POST	/api/msk/assessments/[code]	Create a new MSK assessment result
GET	/api/msk/assessment-result/[assessmentResultId]	Get a specific MSK assessment result
PATCH	/api/msk/assessment-result/[assessmentResultId]	Update an MSK assessment result
GET	/api/msk/export-pdf	Export MSK assessment results as PDF

---

GET /api/msk/assessments

List all MSK assessments available for the client.

Headers:

• Authorization: Bearer <JWT>

Response:

• 200 OK: Array of available MSK assessments

---

POST /api/msk/assessments/[code]

Creates a new MSK assessment result for the specified assessment code.

Path Parameters:

Parameter	Type	Required	Description
code	string	Yes	Assessment code: shoulder, low-back, or knee

Headers:

• Authorization: Bearer <JWT>
• Content-Type: application/json

Request Body:

{
  "userId": "string (optional)",
  "email": "string (optional)",
  "photoURL": "string (optional)"
}

Field	Type	Required	Description
userId	string	Optional	User ID to associate with the assessment result
email	string	Optional	User's email (must be valid if provided)
photoURL	string	Optional	User's photo URL (must be a valid URL if provided)

Response:

• 200 OK:

{
  "assessmentResultId": "string",
  "assessmentSurveyUrl": "/msk/assessment/{assessmentResultId}/assessment-survey",
  "asessmentUrl": "/msk/assessment/{assessmentResultId}/assessment-results",
  "painReviewUrl": "/msk/assessment/{assessmentResultId}/pain-review",
  "createdAt": "string (ISO date)"
}

Field	Type	Description
assessmentResultId	string	Unique ID for the created assessment
assessmentSurveyUrl	string	URL for the assessment survey step
asessmentUrl	string	URL for the assessment results step
painReviewUrl	string	URL for the pain review step
createdAt	string	ISO date string of creation

Error Responses:

Status	Description
400	Invalid assessment code, email, photoURL, or user missing
401	Unauthorized
500	Internal server error or client ID not found

---

GET /api/msk/assessment-result/[assessmentResultId]

Returns the result for a specific MSK assessment result ID.

Path Parameters:

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

Headers:

• Authorization: Bearer <JWT>

Response:

• 200 OK:

{
  "id": "string",
  "clientId": "string",
  "userId": "string (optional)",
  "email": "string (optional)",
  "photoURL": "string (optional)",
  "assessmentCode": "string",
  "assessmentData": {
    "assessmentSurvey": {},
    "assessmentResults": {},
    "painReview": {}
  },
  "createdAt": "string (ISO date)"
}

Field	Type	Description
id	string	Unique result ID
clientId	string	Client ID
userId	string	User ID (optional)
email	string	User email (optional)
photoURL	string	User photo URL (optional)
assessmentCode	string	Assessment type (shoulder/low-back/knee)
assessmentData	object	Contains survey, results, and pain review
createdAt	string	ISO date string

Error Responses:

Status	Description
401	Unauthorized
404	Assessment not found
500	Internal server error

---

PATCH /api/msk/assessment-result/[assessmentResultId]

Update an existing MSK assessment result. Only schema-defined fields are accepted.

Path Parameters:

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

Headers:

• Authorization: Bearer <JWT>
• Content-Type: application/json

Request Body:

Must match the MSKAssessmentResultUpdateSchema. Only documented fields are accepted.

Response:

• 200 OK: { success: true }
• 400 Bad Request: { error: "Invalid or unknown fields in request body", details: [...] }
• 404 Not Found: { error: "MSK assessment result not found" }
• 500 Internal Server Error: { error: string }

warning

Unknown fields or invalid data will be rejected with a 400 error and validation details.

---

Assessment Types

Code	Description
shoulder	Shoulder MSK assessment
low-back	Low back MSK assessment
knee	Knee MSK assessment

---

Assessment Flow

The MSK assessment follows a multi-step workflow:

1. Create Assessment - Call POST /api/msk/assessments/[code] to create a new assessment session
2. Assessment Survey - User completes the survey at assessmentSurveyUrl
3. Physical Assessment - User performs the physical test (e.g., shoulder arm raise)
4. Pain Review - User completes pain review at painReviewUrl
5. Results - Final results available at asessmentUrl

---

Shoulder Assessment Details

For specific details about the Shoulder Arm Raise assessment flow, see Shoulder Arm Raise.