WebsitePlatform

Jumping

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. 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 (string, required): The name of the exercise. Choose one of the following: 'Countermovement Jump' or 'Drop Jump'.

  • 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 (Firebase auth):

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 'exercise=Countermovement Jump' \
     -F 'body_joint_angles=knee, ankle' \
     https://<backend-link>/jumping/management/sessions/

Example cURL (API KEY):

curl -X POST \
     -H 'Content-Type: multipart/form-data' \
     -H 'API-KEY: <YOUR_API_KEY>' \
     -F 'user_id=someUserId123' \
     -F 'video=@/path/to/video.mp4' \
     -F 'session_name=Morning Run' \
     -F 'exercise=Countermovement Jump' \
     -F 'body_joint_angles=knee, ankle' \
     https://<backend-link>/jumping/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: 'Countermovement Jump' or 'Drop Jump'.

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 /jumping/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"
}

Get Jumping Session Data

get

Retrieve detailed information about a specific processed jumping session using its unique session_id.

Optionally, set ?demo=true to retrieve the predefined demo session for the Jump activity.

Usage Example: Send a GET request with the session_id as a path parameter to obtain session details.

Parameters:

  • session_id (string, required): The unique identifier of the session whose data is being requested.

  • demo (boolean, optional): Set to true to return the predefined demo session for Jump.

Response Data Type:

  • 200 OK: A JSON object with the following structure:

    • angles (object): Contains arrays of various angle measurements:

      • hip_intersection_angle (array of numbers): Array of hip intersection angles.

      • ank_angle (array of numbers): Array of ankle angles.

      • rkne_angle (array of numbers): Array of right knee angles.

      • lkne_angle (array of numbers): Array of left knee angles.

      • kne_angle (array of numbers): Array of knee angles.

      • rank_angle (array of numbers): Array of right ankle angles.

      • lank_angle (array of numbers): Array of left ankle angles.

    • whole_report_metrics (object): Contains arrays of various metrics:

      • hipy (array of numbers): Array of hip height values.

      • grf (array of numbers): Array of ground reaction forces.

      • vhipy (array of numbers): Array of hip speed values.

      • toey (array of numbers): Array of toe Y-axis positions.

      • ahipy (array of numbers): Array of average hip Y-axis positions.

      • vtoey (array of numbers): Array of vertical toe velocities.

    • all_timestamps (array of numbers): Array of timestamps for each frame.

    • analyzed_video_url (string, URI): URL of the analyzed video.

    • video_url (string, URI): URL of the original video.

    • created_at (object): Contains the date and time of session creation:

      • date (string, format: YYYY-MM-DD): Creation date.

      • time (string, format: HH:MM AM/PM): Creation time.

    • exercise (string): Type of exercise being analyzed in the session.

    • user_name (string): Name of the user associated with the session.

    • activity (string): Type of activity being analyzed in the session.

    • title (string): Title of the session.

    • end_frames (array of integers): Array of frame numbers where each segment ends.

    • metrics (object): Contains various performance metrics as arrays of numbers.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

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

Responses
200

Successfully retrieved session data.

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

{
  "angles": {
    "hip_intersection_angle": [
      1
    ],
    "ank_angle": [
      1
    ],
    "rkne_angle": [
      1
    ],
    "lkne_angle": [
      1
    ],
    "kne_angle": [
      1
    ],
    "rank_angle": [
      1
    ],
    "lank_angle": [
      1
    ]
  },
  "whole_report_metrics": {
    "hipy": [
      1
    ],
    "grf": [
      1
    ],
    "vhipy": [
      1
    ],
    "toey": [
      1
    ],
    "ahipy": [
      1
    ],
    "vtoey": [
      1
    ]
  },
  "all_timestamps": [
    1
  ],
  "analyzed_video_url": "https://example.com",
  "video_url": "https://example.com",
  "created_at": {
    "date": "2025-08-24",
    "time": "10:40:19"
  },
  "exercise": "text",
  "user_name": "text",
  "activity": "text",
  "title": "text",
  "end_frames": [
    1
  ],
  "all_end_frames": [
    1
  ],
  "metrics": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  },
  "all_metrics": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  }
}

Export Jumping Session Data

get

Retrieve detailed information about a specific jumping session using its unique session_id.

Optionally, set ?demo=true to retrieve the predefined demo session for the Jump activity.

Usage Example: Send a GET request with the session_id as a path parameter to obtain session details.

Parameters:

  • session_id (string, required): The unique identifier of the session whose data is being requested.

  • demo (boolean, optional): Set to true to retrieve the predefined demo session for Jump. Note: This endpoint includes landmark points in the response.

Response Data Type:

  • 200 OK: A JSON object with the following structure:

    • keypoints (object): Contains arrays of landmark points.

      • 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.

    • angles (object): Contains arrays of various angle measurements.

      • hip_intersection_angle (array of numbers): Hip intersection angles.

      • ank_angle (array of numbers): Ankle angles.

      • rkne_angle (array of numbers): Right knee angles.

      • lkne_angle (array of numbers): Left knee angles.

      • kne_angle (array of numbers): Knee angles.

      • rank_angle (array of numbers): Right ankle angles.

      • lank_angle (array of numbers): Left ankle angles.

    • all_timestamps (array of numbers): Timestamps for each frame.

    • analyzed_video_url (string, URI): URL of the analyzed video.

    • video_url (string, URI): URL of the original video.

    • created_at (object): Contains the date and time of session creation.

      • date (string, format: YYYY-MM-DD): Creation date.

      • time (string, format: HH:MM AM/PM): Creation time.

    • user_name (string): Name of the user associated with the session.

    • activity (string): Type of activity being analyzed.

    • title (string): Title of the session.

    • end_frames (array of integers): Frame numbers where each segment ends.

    • metrics (object): Contains various performance metrics as arrays of numbers.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

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

Responses
200

Successfully retrieved session data.

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

{
  "keypoints": {
    "lknev": [
      1
    ],
    "ltoev": [
      1
    ],
    "relbv": [
      1
    ],
    "rtoey": [
      1
    ],
    "headv": [
      1
    ],
    "rearv": [
      1
    ],
    "rshox": [
      1
    ],
    "etc": [
      1
    ]
  },
  "angles": {
    "hip_intersection_angle": [
      1
    ],
    "ank_angle": [
      1
    ],
    "rkne_angle": [
      1
    ],
    "lkne_angle": [
      1
    ],
    "kne_angle": [
      1
    ],
    "rank_angle": [
      1
    ],
    "lank_angle": [
      1
    ]
  },
  "all_timestamps": [
    1
  ],
  "analyzed_video_url": "https://example.com",
  "video_url": "https://example.com",
  "created_at": {
    "date": "2025-08-24",
    "time": "10:40:19"
  },
  "user_name": "text",
  "activity": "text",
  "title": "text",
  "end_frames": [
    1
  ],
  "metrics": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  }
}

Get Jump Analysis Report

post

Retrieve Vertical Jump Analysis Report

This endpoint allows users to retrieve a comprehensive analysis report for a specific vertical jump session. The report includes graphical data, phase details, user information, and additional comments to provide an in-depth understanding of the user's performance during the session.

Usage Example: Send a POST request to /jumping/{session_id}/jump-analysis/ where {session_id} is the unique identifier of the session.

Parameters:

  • session_id (string, required): The unique identifier of the session for which the report is being requested.

  • demo (boolean, optional): Set to true to retrieve the predefined demo report instead of the real session.

Response Structure: Upon a successful request, the endpoint returns a JSON object containing the following sections:

  1. Exercise: The name of the exercise performed during the session.

  2. Graph Data: Visual representations of various metrics collected during the session.

  3. Frame Information: Details about the video frames involved in the session.

  4. Phase Data: Information about different phases of the vertical jump activity.

  5. User Information: Personal details of the user.

  6. Session Date: The date when the session took place.

  7. Comments: Feedback and comments based on the session performance.

Detailed Description of Response Fields:

  • exercise: The name of the exercise performed.

  • graph_data: Contains nested objects for each metric (e.g., hip_height, hip_speed) with data points over time.

  • min_frame & max_frame: Indicate the range of frames analyzed in the session video.

  • phase_data: Provides detailed information about each phase of the jump, including video frames, graph phases, and associated images.

  • user_information: Includes the user's name, age, weight, height, and gender.

  • session_date: The date of the session in DD/MM/YYYY format.

  • comments: Contains feedback related to specific metrics like power and ground reaction force (grf).

Note: Ensure that the session_id provided is valid and corresponds to an existing session in the system.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve the demo report.

Responses
200

Successfully retrieved jump analysis report.

application/json
post
POST /jumping/sessions/{session_id}/jump-analysis/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "exercise": "Countermovement Jump",
  "graph_data": {
    "hip_height": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "hip_speed": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "hip_trajectory": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "hip_velocity": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "toe_trajectory": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "grf": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "power": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "kne_angle": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "ank_angle": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    },
    "hip_angle": {
      "ANY_ADDITIONAL_PROPERTY": {
        "times": [
          1
        ],
        "data": [
          1
        ]
      }
    }
  },
  "min_frame": 1,
  "max_frame": 1,
  "phase_data": {
    "start_of_preparation": {
      "video_frame": 1,
      "graph_phase": 1,
      "image_url": "https://example.com"
    },
    "braking": {
      "video_frame": 1,
      "graph_phase": 1,
      "image_url": "https://example.com"
    },
    "zero_velocity": {
      "video_frame": 1,
      "graph_phase": 1,
      "image_url": "https://example.com"
    },
    "takeoff": {
      "video_frame": 1,
      "graph_phase": 1,
      "image_url": "https://example.com"
    },
    "peak": {
      "video_frame": 1,
      "graph_phase": 1,
      "image_url": "https://example.com"
    },
    "landing": {
      "video_frame": 1,
      "graph_phase": 1,
      "image_url": "https://example.com"
    },
    "damping": {
      "video_frame": 1,
      "graph_phase": 1,
      "image_url": "https://example.com"
    },
    "recuperation": {
      "video_frame": 1,
      "graph_phase": 1,
      "image_url": "https://example.com"
    }
  },
  "user_information": {
    "name": "text",
    "age": 1,
    "weight": 1,
    "height": 1,
    "gender": "text"
  },
  "session_date": "2025-08-24",
  "comments": {
    "power": "text",
    "grf": "text"
  }
}

Create Recommendations Threads

post

Create Recommendations Threads

This endpoint generates personalized recommendation threads based on the user's vertical jump analysis 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 /jumping/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.

Example Response for Countermovement Jump:

{
    "hip_height": "thread_ybIdbAtHLSnHM4BnH551X4fT",
    "hip_speed": "thread_MLGE8nAmLYyW3adwIViKiVpL",
    "grf": "thread_rBIUL25oD3VLtBaPRDLunFsu",
    "power": "thread_UGCg6dZzsRI1YCpSgCf0dgT4",
    "kne_angle": "thread_rEiSblZuq3bzPHRBNXd2etJ6",
    "ank_angle": "thread_QLrCfbBuBBKpmPFFnBkJfcln",
    "hip_angle": "thread_CMWV9HCt85XlpVSORSk4MmCG"
}

Example Response for Drop Jump:

{
    "hip_trajectory": "thread_ABC123",
    "hip_velocity": "thread_DEF456",
    "toe_trajectory": "thread_GHI789"
    "grf": "thread_JKL012",
    "power": "thread_MNO345",
    "kne_angle": "thread_PQR678",
    "ank_angle": "thread_STU901",
    "hip_angle": "thread_VWX234"
}

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 /jumping/sessions/{session_id}/recommendation/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "hip_height": "text",
  "hip_speed": "text",
  "hip_trajectory": "text",
  "hip_velocity": "text",
  "toe_trajectory": "text",
  "grf": "text",
  "power": "text",
  "kne_angle": "text",
  "ank_angle": "text",
  "hip_angle": "text"
}

Get Summary of a Session

get

Retrieve Session Summary

This endpoint provides a summary of a specific session, including key performance metrics, user data, and session creation details.

Usage Example: Send a GET request to /jumping/{session_id}/summary/ where {session_id} is the unique session ID.

Query Parameters:

  • demo (boolean, optional): Set to true to retrieve a pre-generated demo summary instead of a real session.

Response Structure:

  • exercise: Type of exercise being summarized.

  • metrics: Contains various measurements from the session.

  • summary: Descriptive overview of performance.

  • user_info: Basic info about the user.

  • session_date: Date when the session was recorded.

Note: Ensure the session_id exists. If demo=true is used, the system returns the pre-seeded demo session summary.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

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

Responses
200

Successfully retrieved session summary.

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

{
  "exercise": "text",
  "metrics": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  },
  "summary": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "user_info": {
    "name": "text",
    "age": 1,
    "weight": 1,
    "height": 1,
    "gender": "text"
  },
  "created_at": {
    "date": "2025-08-24",
    "time": "10:40:19"
  }
}

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 /jumping/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 block name to its corresponding thread ID.

Example Response for Countermovement Jump:

{
    "jump_flight": "thread_thread_id",
    "jump_forces": "thread_thread_id",
    "control_and_stability": "thread_thread_id",
    "efficiency": "thread_thread_id",
    "final_summary": "thread_thread_id",
}

Example Response for Drop Jump:

{
    "contact_and_jump_structure": "thread_thread_id",
    "performance_and_efficiency": "thread_thread_id",
    "force_metrics": "thread_thread_id",
    "final_summary": "thread_thread_id",
}

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 /jumping/sessions/{session_id}/summary/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}
PreviousRunningNextWeightlifting

Last updated

Was this helpful?