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

POST a multipart/form-data request containing the required fields user_id and video, plus any optional fields.
Provide A valid API-KEY token in the Authorization header.
The caller must have admin privileges to successfully create a session for another user.
If successful, the server responds with session_id and title.
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

AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

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

400

Bad Request - Possibly due to missing user_id, missing video, or invalid form data.

application/json

401

Unauthorized - Missing or invalid access token.

application/json

403

Forbidden - The user does not have admin permission to create sessions for others.

application/json

404

Not Found - Indicates business logic issues or resource limitations (e.g., session limit).

application/json

500

Internal Server Error - Unexpected error occurred on the server.

application/json

post

/jumping/sessions/

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

AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

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

400

Bad Request - Invalid session_id provided.

application/json

401

Unauthorized - Access token is missing or invalid.

application/json

403

Forbidden - User lacks necessary permissions.

application/json

404

Not Found - No session data found for the provided session_id.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

get

/jumping/sessions/{session_id}/

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-12-12",
    "time": "19:14:17"
  },
  "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

AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

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

400

Bad Request - Invalid session_id provided.

application/json

401

Unauthorized - Access token is missing or invalid.

application/json

403

Forbidden - User lacks necessary permissions.

application/json

404

Not Found - No session data found for the provided session_id.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

get

/jumping/sessions/{session_id}/export/

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-12-12",
    "time": "19:14:17"
  },
  "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:

Exercise: The name of the exercise performed during the session.
Graph Data: Visual representations of various metrics collected during the session.
Frame Information: Details about the video frames involved in the session.
Phase Data: Information about different phases of the vertical jump activity.
User Information: Personal details of the user.
Session Date: The date when the session took place.
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

AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters

session_idanyRequired

Query parameters

demobooleanOptional

Set to true to retrieve the demo report.

Responses

200

Successfully retrieved jump analysis report.

application/json

400

Bad Request - Invalid session_id provided.

application/json

401

Unauthorized - Access token is missing or invalid.

application/json

403

Forbidden - User lacks necessary permissions.

application/json

404

Not Found - No session data found for the provided session_id.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

post

/jumping/sessions/{session_id}/jump-analysis/

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-12-12",
  "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

AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters

session_idanyRequired

Responses

200

Threads created successfully.

application/json

400

Bad Request - Invalid session_id provided.

application/json

401

Unauthorized - Access token is missing or invalid.

application/json

403

Forbidden - User lacks necessary permissions.

application/json

404

Not Found - No session data found for the provided session_id.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

post

/jumping/sessions/{session_id}/recommendation/

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

AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

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

400

Bad Request - Invalid session_id provided.

application/json

401

Unauthorized - Access token is missing or invalid.

application/json

403

Forbidden - User lacks necessary permissions.

application/json

404

Not Found - No session data found for the provided session_id.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

get

/jumping/sessions/{session_id}/summary/

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-12-12",
    "time": "19:14:17"
  }
}

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

AuthorizationstringRequired

Enter your bearer token (Firebase auth) in the format: Bearer

Path parameters

session_idanyRequired

Query parameters

measurement_systemstring · enumOptional

Measurement system: 'metric' or 'imperial'

Possible values:

Responses

201

Successfully generated summary threads.

application/json

400

Bad Request - Invalid session_id provided.

application/json

401

Unauthorized - Access token is missing or invalid.

application/json

403

Forbidden - User lacks necessary permissions.

application/json

404

Not Found - No session data found for the provided session_id.

application/json

500

Internal Server Error - An unexpected error occurred.

application/json

post

/jumping/sessions/{session_id}/summary/

POST /jumping/sessions/{session_id}/summary/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}

PreviousRunning NextWeightlifting

Last updated 4 months ago

Was this helpful?