WebsitePlatform

Mobility Assessment

Retrieve Mobility Assessment Session

get

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 true to 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 date and time for 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.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve the pre-generated demo session instead of a real session.

Responses
200

Successfully retrieved Mobility Assessment session data.

application/json
get
GET /mobility-assessment/sessions/{session_id}/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "segments": 1,
  "video_url": "https://example.com",
  "analyzed_video_url": "https://example.com",
  "activity": "text",
  "title": "text",
  "user_name": "text",
  "created_at": {
    "date": "text",
    "time": "text"
  },
  "exercise": "text",
  "angles": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  },
  "all_timestamps": [
    1
  ]
}

Create a New Video Processing Session

post

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_name was not provided).

Workflow

  1. POST a multipart/form-data request containing the required fields user_id and video, plus any optional fields.

  2. Provide A valid API-KEY token in the Authorization header.

  3. The caller must have admin privileges to successfully create a session for another user.

  4. If successful, the server responds with session_id and title.

  5. If an error occurs (e.g., missing fields, lack of permissions), a JSON object with an error key is returned.

Example cURL:

curl -X POST \
     -H 'Content-Type: multipart/form-data' \
     -H 'Authorization: API-KEY <YOUR_ADMIN_TOKEN>' \
     -F 'user_id=someUserId123' \
     -F 'video=@/path/to/video.mp4' \
     -F 'session_name=Custom Session' \
     -F 'body_joint_angles=ankle, knee' \
     https://<backend-link>/mobility-assessment/management/sessions/
Authorizations
Body
user_idstringRequired

Required. The ID of the user for whom this session is created (form field: text).

videostringRequired

Required. The raw video file to be processed (form field type: file).

session_namestringOptional

Optional. A descriptive name for the session (form field: text).

exercisestringRequired

Required. The name of the exercise. Choose one of the following: 'Overhead Squat', 'Joint Angle Mobility'

body_joint_anglesarrayOptional

Optional. A comma-separated list of joint names. Available values: 'ankle', 'knee', 'elbow', 'hip', 'shoulder'. Example: ankle,knee,hip

Responses
200

Video processing session created successfully (HTTP 200).

application/json
post
POST /mobility-assessment/sessions/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 96

"user_id='text'&video='text'&session_name='text'&exercise='text'&body_joint_angles=[]"
{
  "session_id": "text",
  "title": "text"
}

Export Session Data (Mobility Assessment)

get

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 true to 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.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve the demo session data instead of a real one.

Responses
200

Session data exported successfully.

application/json
get
GET /mobility-assessment/sessions/{session_id}/export/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "activity": "text",
  "angles": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  },
  "all_timestamps": [
    1
  ],
  "keypoints": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  }
}

Create Recommendations Threads

post

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_id provided is valid and corresponds to an existing session in the system.

  • The user must have an active payment plan to access this feature.

Authorizations
Path parameters
session_idanyRequired
Responses
200

Threads created successfully.

application/json
post
POST /mobility-assessment/sessions/{session_id}/recommendation/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "ankle_dorsiflexion": "text",
  "hip_abduction": "text",
  "hip_flexion": "text",
  "knee_flexion": "text",
  "knee_movement": "text",
  "final_summary": "text"
}

Generate Overhead Squat Report

post

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 true to 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

{
  "grouped_data": {
    "hip_flexion": {
      "metrics": {
        "left_hip_flexion": 12.5,
        "right_hip_flexion": 15.3,
        "hip_flexion_asymmetry": 2.8
      },
      "graph_data": {
        "lhip_flexion": [10, 20, 30],
        "rhip_flexion": [15, 25, 35]
      }
    },
    "ankle_dorsiflexion": {
      "metrics": {
        "left_ankle_flexion": 9.8,
        "right_ankle_flexion": 10.5,
        "ankle_flexion_asymmetry": 0.7
      },
      "graph_data": {
        "lank_flexion": [6, 12, 18],
        "rank_flexion": [7, 14, 21]
      }
    }
  },
  "graph_timestamps": [0, 5000, 10000],
  "knee_movement_phases": {
    "left": "https://storage.googleapis.com/aikonweb001.appspot.com/report-images/.../left.png",
    "right": "https://storage.googleapis.com/aikonweb001.appspot.com/report-images/.../right.png",
    "front": "https://storage.googleapis.com/aikonweb001.appspot.com/report-images/.../front.png"
  },
  "user_info": {
    "weight": 70,
    "email": "[email protected]",
    ...
  },
  "exercise": "Overhead Squat",
  "report_comments": {
    "hip_flexion": "For optimal hip flexion improvement, focus on dynamic stretching and mobility exercises.",
    "ankle_dorsiflexion": "Natalia, your left ankle dorsiflexion is at 9.0 degrees...",
    "final_summary": "Natalia, your knee and hip flexion metrics are strong...",
    "hip_abduction": "For optimal hip abduction performance, focus on improving..."
  },
  "output_quality": {
    "mobility_index": 46,
    "quality_index": 67
  },
  "date": "11/03/2025"
}

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.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve the demo Overhead Squat report instead of a real one.

Responses
200

Overhead Squat report generated/retrieved successfully.

application/json
post
POST /mobility-assessment/sessions/{session_id}/report/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "grouped_data": {
    "ANY_ADDITIONAL_PROPERTY": {
      "metrics": {
        "ANY_ADDITIONAL_PROPERTY": 1
      },
      "graph_data": {
        "ANY_ADDITIONAL_PROPERTY": [
          1
        ]
      }
    }
  },
  "graph_timestamps": [
    1
  ],
  "knee_movement_phases": {
    "left": "text",
    "right": "text",
    "front": "text"
  },
  "user_info": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "exercise": "text",
  "output_quality": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "report_comments": {
    "hip_flexion": "text",
    "ankle_dorsiflexion": "text",
    "final_summary": "text",
    "hip_abduction": "text"
  },
  "date": "text"
}

Retrieve Overhead Squat Summary

get

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 true to 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

{
  "grouped_data": {
    "hip_flexion": {
      "left_hip_flexion": 84.0,
      "right_hip_flexion": 80.0,
      "hip_flexion_asymmetry": 4.0
    },
    "hip_adduction": {
      "left_hip_abduction": 9.0,
      "right_hip_abduction": 16.0,
      "hip_abduction_asymmetry": 7.0
    },
    "knee_flexion": {
      "left_knee_flexion": 79.0,
      "right_knee_flexion": 82.0,
      "knee_flexion_asymmetry": 3.0
    },
    "ankle_dorsiflexion": {
      "left_ankle_flexion": 9.0,
      "right_ankle_flexion": 15.0,
      "ankle_flexion_asymmetry": 6.0
    }
  },
  "knee_movement_phases": {
    "left": "https://storage.googleapis.com/aikonweb001.appspot.com/report-images/.../left.png",
    "right": "https://storage.googleapis.com/aikonweb001.appspot.com/report-images/.../right.png",
    "front": "https://storage.googleapis.com/aikonweb001.appspot.com/report-images/.../front.png"
  },
  "user_info": {
    "display_name": "Natalia Alioth",
    "weight": 70.0,
    "email": "[email protected]",
    ...
  },
  "exercise": "Overhead Squat",
  "output_quality": {
    "mobility_index": 46.0,
    "quality_index": 67.0
  },
  "summary": {
    "hip_flexion": "For optimal hip flexion improvement, focus on dynamic stretching and mobility exercises.",
    "ankle_dorsiflexion": "Natalia, your left ankle dorsiflexion is at 9.0 degrees...",
    "final_summary": "Natalia, your knee and hip flexion metrics are strong...",
    "hip_abduction": "For optimal hip abduction performance, focus on improving..."
  },
  "date": "11/03/2025"
}

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.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve the pre-generated demo Overhead Squat summary instead of a real one.

Responses
200

Overhead Squat summary retrieved successfully.

application/json
get
GET /mobility-assessment/sessions/{session_id}/summary/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "grouped_data": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": 1
    }
  },
  "knee_movement_phases": {
    "left": "text",
    "right": "text",
    "front": "text"
  },
  "user_info": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "exercise": "text",
  "output_quality": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "summary": {
    "hip_flexion": "text",
    "ankle_dorsiflexion": "text",
    "final_summary": "text",
    "hip_abduction": "text"
  },
  "date": "text"
}

Generate Summary Threads for a Session

post

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_id provided is valid and corresponds to an existing session in the system.

  • The user must have the necessary permissions to generate summary threads.

Authorizations
Path parameters
session_idanyRequired
Query parameters
measurement_systemstring · enumOptional

Measurement system: 'metric' or 'imperial'

Possible values:
Responses
201

Successfully generated summary threads.

application/json
post
POST /mobility-assessment/sessions/{session_id}/summary/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "hip_flexion": "text",
  "hip_abduction": "text",
  "knee_flexion": "text",
  "knee_movement": "text",
  "ankle_dorsiflexion": "text",
  "final_summary": "text"
}

Generate Joint Angle Mobility Report

post

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.

Authorizations
Path parameters
session_idanyRequired
Responses
200

Joint Angle Mobility report retrieved successfully.

application/json
post
POST /mobility-assessment/sessions/{session_id}/joint-mobility/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "title": "text",
  "angles": {
    "ANY_ADDITIONAL_PROPERTY": {
      "max": 1,
      "min": 1,
      "values": [
        1
      ]
    }
  },
  "exercise": "text",
  "user_info": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "date": "text",
  "uploaded_date": "2025-08-24T10:48:04.010Z",
  "shown_angles": [
    "text"
  ],
  "comments": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Retrieve the saved report configuration for a session

get

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.

Authorizations
Path parameters
session_idanyRequired
Responses
200

Configuration retrieved successfully.

application/json
get
GET /mobility-assessment/sessions/{session_id}/joint-mobility-config/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "shown_angles": [
    "knee_angle",
    "hip_angle"
  ],
  "comments": {
    "knee_angle": "Check alignment on flexion."
  }
}

Create or update the report configuration for a session

post

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 errors for 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.

Authorizations
Path parameters
session_idanyRequired
Body
shown_anglesstring[]Optional

Angles to show

Example: ["shoulder_angle","ankle_angle"]
Responses
200

Configuration saved and returned.

application/json
post
POST /mobility-assessment/sessions/{session_id}/joint-mobility-config/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "shown_angles": [
    "hip_angle",
    "knee_angle"
  ],
  "comments": {
    "hip_angle": "Monitor range of motion."
  }
}
{
  "shown_angles": [
    "hip_angle",
    "knee_angle"
  ],
  "comments": {
    "hip_angle": "Range improved."
  }
}
PreviousWeightliftingNextHTML Files

Last updated

Was this helpful?