Mobility Assessment
Retrieve details of a specific Mobility Assessment session identified by its session_id. This endpoint returns information such as the number of segments, video URLs, angle data, timestamps, and other session metadata.
Path Parameter
session_id (string, required): Unique identifier of the Mobility Assessment session to retrieve.
Query Parameter
demo (boolean, optional): Set to
trueto retrieve the pre-generated demo session instead of a real session.
Successful Response (HTTP 200)
A JSON object containing:
segments (integer): The total number of segments in this mobility assessment.
video_url (string, URI): URL of the original uploaded video.
analyzed_video_url (string, URI, optional): URL of the analyzed (processed) video.
activity (string): The type of activity, e.g.,
Mobility Assessment.title (string): Title or name of the session.
user_name (string): Name of the user associated with the session.
created_at (object): An object with
dateandtimefor the session's creation.date (string): Format
DD/MM/YYYY.time (string): Format
HH:MM AM/PM.
exercise (string): The exercise name or type (e.g.,
Overhead Squad).angles (object): An object containing any angle data relevant to the mobility assessment.
hip_angle (array of numbers): Example array of hip angles.
ankle_angle (array of numbers): Example array of ankle angles.
... (additional angle fields as needed)
all_timestamps (array of numbers): Array of timestamps corresponding to the angle data.
Error Responses
400 Bad Request: Invalid or missing parameters.
401 Unauthorized: Missing or invalid authentication token.
403 Forbidden: User lacks permission to retrieve this session.
404 Not Found: Session not found.
500 Internal Server Error: Unexpected error occurred on the server.
A valid API-KEY token must be provided in the Authorization header.
Enter your bearer token (Firebase auth) in the format: Bearer
Set to true to retrieve the pre-generated demo session instead of a real session.
Successfully retrieved Mobility Assessment session data.
Bad Request - Invalid or missing parameters.
Unauthorized - Missing or invalid authentication token.
Forbidden - The user does not have permission to retrieve this session.
Not Found - The session was not found or does not exist.
Internal Server Error - An unexpected error occurred on the server.
This endpoint allows an admin (or sub-admin) to upload a video file for processing and create a new "session" resource on behalf of another user (Mobility Assessment). The server will return a session_id that can be used to poll or retrieve the session details/results.
Request Body (Multipart/Form-Data)
You must supply the following fields:
user_id (string, required): The ID of the user on whose behalf this session is created.
video (file, required): The raw video file to be processed.
session_name (string, optional): A human-readable name/title for the session.
exercise_name (string, required): The name of the exercise to be performed. Choose one of the following:
body_joint_angles (array[string], optional): A comma-separated list of joint names (e.g. 'elbow, knee, ankle'). Defaults to ['all'] if not provided.
Response Structure
On success (HTTP 200), the response is a JSON object with:
session_id (string): A unique identifier for the created session.
title (string): The session title (defaults to a fallback if
session_namewas not provided).
Workflow
POST a multipart/form-data request containing the required fields
user_idandvideo, plus any optional fields.Provide A valid API-KEY token in the
Authorizationheader.The caller must have admin privileges to successfully create a session for another user.
If successful, the server responds with
session_idandtitle.If an error occurs (e.g., missing fields, lack of permissions), a JSON object with an
errorkey is returned.
Example cURL:
Enter your bearer token (Firebase auth) in the format: Bearer
Required. The ID of the user for whom this session is created (form field: text).
Required. The raw video file to be processed (form field type: file).
Optional. A descriptive name for the session (form field: text).
Required. The name of the exercise. Choose one of the following: 'Overhead Squat', 'Joint Angle Mobility'
Optional. A comma-separated list of joint names. Available values: 'ankle', 'knee', 'elbow', 'hip', 'shoulder'. Example: ankle,knee,hip
Video processing session created successfully (HTTP 200).
Bad Request - Possibly due to missing user_id, missing video, or invalid form data.
Unauthorized - Missing or invalid access token.
Forbidden - The user does not have admin permission to create sessions for others.
Not Found - Indicates business logic issues or resource limitations (e.g., session limit).
Internal Server Error - Unexpected error occurred on the server.
Exports landmark data and angle data for a specific mobility-related session. This endpoint returns minimal metadata, including only activity, angles, all_timestamps, and keypoints with various arrays of landmark points.
Path Parameter
session_id (string, required): The unique identifier of the session whose data is being exported.
Query Parameter
demo (boolean, optional): Set to
trueto retrieve the demo session data instead of a real one.
Successful Response (HTTP 200)
A JSON object containing:
activity (string): The type of activity (e.g. 'Mobility Assessment').
angles (object): An object containing any angle data relevant to the mobility assessment.
hip_angle (array of numbers): Example array of hip angles.
ankle_angle (array of numbers): Example array of ankle angles.
... (additional angle fields as needed)
all_timestamps (array of numbers): Array of timestamps corresponding to each data point.
keypoints (object): Contains arrays of landmark points. Examples include:
lknev (array of numbers): Array of left knee landmark points.
ltoev (array of numbers): Array of left toe landmark points.
relbv (array of numbers): Array of right elbow landmark points.
rtoey (array of numbers): Array of right toe landmark points.
headv (array of numbers): Array of head landmark points.
rearv (array of numbers): Array of right ear landmark points.
rshox (array of numbers): Array of right shoulder landmark points.
etc (array of numbers): Array of all other landmark points.
Error Responses
400 Bad Request: Invalid or missing parameters.
401 Unauthorized: Missing or invalid authentication token.
403 Forbidden: Insufficient privileges to retrieve this data.
404 Not Found: The session does not exist.
500 Internal Server Error: An unexpected error occurred.
A valid API-KEY token must be provided in the Authorization header.
Enter your bearer token (Firebase auth) in the format: Bearer
Set to true to retrieve the demo session data instead of a real one.
Session data exported successfully.
Bad Request - Possibly due to invalid or missing session_id.
Unauthorized - Missing or invalid authentication token.
Forbidden - Insufficient privileges to retrieve session data.
Not Found - The session does not exist.
Internal Server Error - Unexpected error on the server.
Create Recommendations Threads
This endpoint generates personalized recommendation threads based on the user's Overhead Squat report for a specific session. These threads can be used to provide tailored advice, training suggestions, or performance insights to the user.
Usage Example: Send a POST request to /mobility-assessment/sessions/{session_id}/recommendation/ where {session_id} is the unique identifier of the session.
Parameters:
session_id(string, required): The unique identifier of the session for which recommendation threads are to be created.
Response Structure: Upon a successful request, the endpoint returns a JSON object containing thread IDs mapped to their respective metrics from the Overhead Squat report.
Example Response:
{
"ankle_dorsiflexion": "thread_boQ0PSivWvPHIx4MQ02HqSEX",
"hip_abduction": "thread_eoTqfX3qWuT2IrEhZpGcem7L",
"hip_flexion": "thread_0pJjWIs5ybuo5gzRJd1ykgaB",
"knee_flexion": "thread_8gp2spSn8XasAOafDwwzw5QT",
"knee_movement": "thread_8gp2spSn8XasAOafDwwzw5QT",
"final_summary": "thread_P3MqG76m9s6qlYwINJrlNomB"
}Note:
Ensure that the
session_idprovided is valid and corresponds to an existing session in the system.The user must have an active payment plan to access this feature.
Enter your bearer token (Firebase auth) in the format: Bearer
Threads created successfully.
Unauthorized - Missing or invalid token.
Forbidden - Invalid payment plan or insufficient privileges to create recommendation threads.
Not Found - Session not found or missing metrics.
Internal Server Error - An unexpected error occurred.
Generates or retrieves a detailed Overhead Squat report for a given session_id. This endpoint consolidates session metrics, organizes them into groups, and embeds user and session metadata.
Path Parameter
session_id (string, required): The unique identifier of the Overhead Squat session.
Query Parameter
demo (boolean, optional): Set to
trueto retrieve the demo Overhead Squat report instead of a real one.
Successful Response (HTTP 200)
Returns a JSON object containing:
grouped_data (object): Organized by metric groups (e.g.,
hip_flexion,knee_flexion). Each group has:metrics (object): Key-value pairs of aggregated metric results.
graph_data (object): Arrays of numeric data for graph plotting.
graph_timestamps (array[number]): List of timestamps (in milliseconds) corresponding to each graph data.
knee_movement_phases (object): URLs of visualization images showing different views of knee movement phases.
left (string): URL for the left view image.
right (string): URL for the right view image.
front (string): URL for the front view image.
user_info (object, optional): Basic user details associated with the session.
exercise (string): The exercise name/type (e.g.,
Overhead Squat).report_comments (object, optional): Detailed feedback on different movement aspects.
output_quality (object, optional): Any additional quality or scoring info.
date (string, format=DD/MM/YYYY): The creation or processing date of the session.
Example Successful Response
Error Handling
403 Forbidden: Returned if the user's payment plan is not Standard, Pro, or Enterprise.
404 Not Found: Returned if the session data cannot be found or no metrics are returned.
500 Internal Server Error: Returned if an unexpected error occurs on the server.
A valid API-KEY token must be provided in the Authorization header.
Enter your bearer token (Firebase auth) in the format: Bearer
Set to true to retrieve the demo Overhead Squat report instead of a real one.
Overhead Squat report generated/retrieved successfully.
Unauthorized - Missing or invalid access token.
Forbidden - The user does not have permission to create sessions (admin-only).
Not Found - Session data cannot be found or no metrics returned.
Internal Server Error - Unexpected error occurred.
Retrieves a high-level summary of Overhead Squat session data identified by its session_id. This endpoint returns grouped metrics (e.g., hip_flexion, knee_flexion) without detailed graph data, as well as optional user and session metadata.
Path Parameter
session_id (string, required): The unique identifier of the Overhead Squat session.
Query Parameter
demo (boolean, optional): Set to
trueto retrieve the pre-generated demo Overhead Squat summary instead of a real one.
Successful Response (HTTP 200)
Returns a JSON object containing:
grouped_data (object): High-level metrics grouped by category (e.g., hip_flexion, knee_flexion). Each group contains metric keys, each mapping to numeric values.
{ "hip_flexion": { "left_hip_flexion": 84.0, "right_hip_flexion": 80.0, "hip_flexion_asymmetry": 4.0 } }knee_movement_phases (object): URLs of visualization images showing different views of knee movement phases.
left (string): URL for the left view image.
right (string): URL for the right view image.
front (string): URL for the front view image.
user_info (object, optional): Contains user-related fields, e.g., weight, display_name, email.
exercise (string): The exercise name (e.g.,
Overhead Squat).output_quality (object, optional): Contains numeric values or indices (e.g., mobility_index).
summary (object, optional): Contains detailed feedback on different movement aspects.
date (string, format=DD/MM/YYYY): The creation/processing date of this session.
Example Successful Response
Error Handling
401 Unauthorized: Missing or invalid token.
403 Forbidden: Payment plan is not valid (Basic, Standard, Pro, or Enterprise required) or user lacks privileges.
404 Not Found: Session data is not found or metrics are missing.
500 Internal Server Error: Unexpected server error.
A valid API-KEY token must be provided in the Authorization header.
Enter your bearer token (Firebase auth) in the format: Bearer
Set to true to retrieve the pre-generated demo Overhead Squat summary instead of a real one.
Overhead Squat summary retrieved successfully.
Unauthorized - Missing or invalid token.
Forbidden - Invalid payment plan or insufficient privileges to retrieve the summary.
Not Found - Session not found or missing metrics.
Internal Server Error - An unexpected error occurred.
Generate Summary Threads
This endpoint generates summary threads for a given session based on predefined summary blocks and metrics.
Usage Example: Send a POST request to /mobility-assessment/sessions/{session_id}/summary/ where {session_id} is the unique identifier of the session.
Parameters:
session_id(string, required): The unique identifier of the session for which summary threads are to be generated.
Response Structure: Upon a successful request, the endpoint returns a JSON object mapping each metric to its corresponding thread ID.
Example Response:
{
"hip_flexion": "thread_x7C4p5ancmeluBmEJgmFwXra",
"hip_abduction": "thread_lth8oxKfnktwne9ryGZefd6V",
"knee_flexion": "thread_cM4jY2RLfVNeFIImJXaIinMK",
"knee_movement": "thread_8gp2spSn8XasAOafDwwzw5QT",
"ankle_dorsiflexion": "thread_EIwgj822ZHtGCTMucHZDtatH",
"final_summary": "thread_2XwSNDNrclHgakiBFm4o9K65"
}Notes:
Ensure that the
session_idprovided is valid and corresponds to an existing session in the system.The user must have the necessary permissions to generate summary threads.
Enter your bearer token (Firebase auth) in the format: Bearer
Measurement system: 'metric' or 'imperial'
Successfully generated summary threads.
Unauthorized - Missing or invalid token.
Forbidden - Invalid payment plan or insufficient privileges to create recommendation threads.
Not Found - Session not found or missing metrics.
Internal Server Error - An unexpected error occurred.
Generates a summarized Joint Angle Mobility report for a given session_id.
Path Parameter
session_id (string, required): The unique identifier of the mobility session.
Successful Response (HTTP 200)
Returns a JSON object containing:
title (string): The sessionβs title.
angles (object): Keys are joint names, values are:
max (number|null)
min (number|null)
values (array[number])
exercise (string): Always
Joint Angle Mobility.user_info (object): User details.
date (string): Formatted date (DD/MM/YYYY).
uploaded_date (string, date-time): Raw ISO timestamp.
shown_angles (array[string]): Which angles to show.
comments (object[string β string]): Per-angle comments.
Error Responses
400 Bad Request: Invalid session type or parameters.
404 Not Found: Session not found.
500 Internal Server Error: Unexpected server error.
Requires A valid API-KEY token in the Authorization header.
Enter your bearer token (Firebase auth) in the format: Bearer
Joint Angle Mobility report retrieved successfully.
Bad Request - Invalid exercise type or parameters.
Forbidden - Insufficient privileges to retrieve session data.
Not Found - Session data not found.
Internal Server Error - Unexpected error occurred.
Returns the current display settings for the specified Joint Angle mobility session.
Path Parameter
session_id(string, required): Identifier of the session to query.
Responses
200 OK: Configuration was found and returned.
shown_angles: Array of joint-angle keys the user has selected.comments: Map of any free-form notes keyed by angle.
401 Unauthorized: No valid authentication credentials provided.
403 Forbidden: Youβre not allowed to view this sessionβs settings.
404 Not Found: The session ID does not correspond to a stored configuration.
500 Internal Server Error: An unexpected error occurred on the server.
Enter your bearer token (Firebase auth) in the format: Bearer
Configuration retrieved successfully.
Unauthorized β Authentication credentials were missing or invalid.
Forbidden β You do not have permission to view this configuration.
Not Found β No report configuration exists for that session.
Internal Server Error β Something went wrong on our end.
Saves your chosen display settings for the specified Joint Angle mobility session.
Path Parameter
session_id(string, required): Session identifier.
Request Body
shown_angles(array[string], optional): Joint-angle keys you want to display.comments(object[stringβstring], optional): Any notes per angle.
Responses
200 OK: Configuration saved successfully (returns the stored settings).
400 Bad Request: One or more fields were invalid β see
errorsfor details.401 Unauthorized: No valid authentication credentials provided.
403 Forbidden: Youβre not allowed to modify this sessionβs settings.
500 Internal Server Error: An unexpected error occurred while saving.
Enter your bearer token (Firebase auth) in the format: Bearer
Angles to show
["shoulder_angle","ankle_angle"]Configuration saved and returned.
Bad Request β Validation failed for one or more fields.
Unauthorized β Authentication credentials were missing or invalid.
Forbidden β You do not have permission to modify this configuration.
Internal Server Error β Something went wrong saving your data.
Last updated
Was this helpful?