Assessments
Create shoulder, low-back, and knee musculoskeletal assessments and consume their results.
The MSK API creates a client-scoped musculoskeletal assessment record and
returns the three user-facing step URLs. The supported assessment codes are
shoulder, low-back, and knee.
For the existing webview credential handoff, see MSK authentication. General integrations can also use
User authentication or
Client tokens, subject to the
client's enabled mskAssessment module.
POST /api/msk/assessments/{code}
Replace {code} with shoulder, low-back, or knee. The JSON body may
include userId, email, and photoURL. When the authenticated token
contains those claims, the deployed route uses the token values in preference
to request-body values. A supplied user must already exist for the client.
const response = await fetch(
"https://your-client.gofa.app/api/msk/assessments/shoulder",
{
method: "POST",
headers: {
Authorization: `Bearer ${firebaseIdToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
userId: "client-user-id",
email: "person@example.com",
}),
},
);
if (!response.ok) throw new Error(`Create failed (${response.status})`);
const flow = await response.json();The successful response has status 200:
{
"assessmentResultId": "result-id",
"assessmentSurveyUrl": "/msk/assessment/result-id/assessment-survey",
"asessmentUrl": "/msk/assessment/result-id/assessment-results",
"painReviewUrl": "/msk/assessment/result-id/pain-review",
"createdAt": "2026-01-01T00:00:00.000Z"
}The response key is spelled asessmentUrl in the deployed implementation.
Preserve that spelling when consuming the response; it is part of the currently
observed contract. The route rejects an unknown assessment code with 400.
| Method | Route | Purpose |
|---|---|---|
GET | /api/msk/assessment-results | List results for the authenticated client or user. Supports limit; an explicit clientId is reserved for an authorized GOFA super-admin context. |
GET | /api/msk/assessment-result/{id} | Retrieve one result after access and client checks. |
PATCH | /api/msk/assessment-result/{id} | Save an allowed partial assessment update. |
List responses use { "data": [...], "count": number }. Detail responses use
{ "data": result }. Both routes are private and client-scoped.
The result is discriminated by assessmentCode and stores data beneath
assessmentData:
| Code | Stored result version and measures |
|---|---|
shoulder | SHOULDER_ASSESSMENT_RESULTS_V1, including abduction, flexion, extension, external rotation, internal rotation, and compression. |
low-back | LOW_BACK_ASSESSMENT_RESULTS_V1, including seated forward flexion. |
knee | KNEE_ASSESSMENT_RESULTS_V1, including squat. |
Each record can also contain assessmentSurvey, painReview, and assessment
risk output. The risk keys used by the deployed model are FS/SIS for shoulder,
LB/LDC/LDH for low-back, and OA/PFPS for knee. Use the version fields in the
response to handle future schema changes.
The update route selects the schema for the record's assessment code, rejects
unknown fields, and protects identity fields such as id, clientId,
userId, and createdAt. A successful update returns { "success": true }.
The MSK webview sends callbacks to its parent with a type and a data object
that can include assessmentResultId, assessmentCode, mskAssessResult, and
mskAssessResultFlattened. Current callback types include:
START_MSK_ASSESSMENT, FINISH_ASSESSMENT_SURVEY,
FINISH_PHYSICAL_ASSESSMENT, FINISH_PAIN_REVIEW, GENERATED_REPORT,
EARLY_QUIT_ASSESSMENT, QUIT_MSK_MODULE, and the compatibility event
QUIT_MODULE.
GENERATED_REPORT may include a base64 data:application/pdf value. Validate
the sender origin and iframe window, and never log the full result or report
string.
External flow boundary
This page documents the user-facing assessment flow and its result contract. Internal authoring, B2B management, linked-client administration, and operator controls are outside the public integration reference.