WebsitePlatform

Weightlifting

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_name (string, required): The name of the exercise. Choose one of the following: 'snatch', 'clean', or 'clean_and_jerk'.

  • barbell_mass (string, optional): The mass of the barbell used (numeric string). Defaults to 100 kg (or 220 lb) if not provided.

  • 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 'exercise_name=clean' \
     -F 'barbell_mass=30' \
     -F 'body_joint_angles=elbow, knee, ankle' \
     https://<backend-link>/weightlifting/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).

exercise_namestringRequired

Required. The name of the exercise. Choose one of the following: 'snatch', 'clean', or 'clean_and_jerk'.

barbell_massstringOptional

Optional. The mass of the barbell used (numeric string). Defaults to 100 kg (or 220 lb) if not provided.

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 /weightlifting/sessions/ HTTP/1.1
Host: api.aikynetix.app
Authorization: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 123

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

Retrieve Weightlifting Session Details

get

Retrieves the details of a weightlifting session specified by its session_id. The returned data includes URLs to the original and analyzed videos, session creation timestamp, exercise type, user information, metrics, angles, report metrics, and timestamps.

Path Parameter

  • session_id (string, required): The unique identifier of the session to retrieve.

Query Parameter

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

Response Structure (HTTP 200)

On success, the response is a JSON object with the following properties:

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

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

  • created_at (object): A dictionary with:

    • date (string): Creation date in DD/MM/YYYY format.

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

  • exercise (string): The exercise performed (e.g., 'snatch').

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

  • activity (string): The activity type (should be 'Weightlifting').

  • title (string): The title of the session.

  • metrics (object): A dictionary of numeric metric values (e.g., speed, power). Each key maps to a number.

  • angles (object): A dictionary where each key maps to an array of numeric values representing angles.

  • report_metrics (object): A dictionary where each key maps to an array of numeric values representing report-specific metrics.

  • all_timestamps (array[number]): An array of timestamps (e.g., in seconds) for the session data.

Error Handling

  • 400 Bad Request: Invalid parameters (e.g., invalid admin UID).

  • 401 Unauthorized: Missing or invalid access token.

  • 403 Forbidden: Insufficient privileges.

  • 404 Not Found: Session not found or the activity is not Weightlifting.

  • 500 Internal Server Error: An unexpected error occurred on the server.

Security

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 a pre-generated demo session instead of a real one.

Responses
200

Weightlifting session details retrieved successfully.

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

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

Export Weightlifting Session Data

get

Retrieves a user's weightlifting session data from Firestore, including keypoints, angles, and timestamps. The session's activity must be 'Weightlifting'.

Path Parameter

  • session_id (string, required): The unique identifier of the session to export data for.

Query Parameter

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

Response Structure (HTTP 200)

On success, the response is a JSON object containing:

  • keypoints (object): A dictionary where each key (e.g., 'lknev', 'lknex', etc.) maps to an array of numbers representing keypoint data.

  • angles (object): A dictionary where each key (e.g., 'lank_angle', 'lkne_angle', etc.) maps to an array of numbers representing angle measurements.

  • all_timestamps (array[number]): An array of timestamps corresponding to the session data.

  • metrics (object): A dictionary of numeric metric values (e.g., max_GRF, max_bar_speed). Each key maps to a number.

  • activity (string): The session activity, expected to be 'Weightlifting'.

Error Handling

  • 400 Bad Request: Invalid parameters (e.g., admin UID error).

  • 401 Unauthorized: Missing or invalid access token.

  • 403 Forbidden: Insufficient privileges.

  • 404 Not Found: Session not found or invalid activity.

  • 500 Internal Server Error: An unexpected server-side error occurred.

Security

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 a pre-generated demo session instead of a real one.

Responses
200

Weightlifting session data retrieved successfully.

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

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

Analyze Weightlifting Lift

post

Runs a full biomechanical analysis of a weight-lifting session (snatch, clean, etc.).

Path parameter

  • session_id (string, required) – Unique ID of the weight-lifting session.

Query Parameter (Optional)

  • demo (boolean) – Set to true to return a pre-generated demo lift analysis session.

Response structure (HTTP 200)

Returns a JSON report containing sectioned, frame-by-frame metrics, phase timing and user info.

{
  "exercise": "snatch",
  "key_metrics": {
    "power_output":           [ 2350, 2425, 2510, 2600, 2705 ],
    "ground_reaction_force":  [ 1120, 1180, 1215, 1260, 1300 ],
    "barbell_velocity":       [ 0.90, 1.05, 1.28, 1.55, 2.02 ]
  },
  "body_positioning": {
    "hip_velocity": [ 0.45, 0.52, 0.60 ],
    "shin_angle":   [ 75.0, 72.5, 70.2 ],
    "hip_height":   [ 450, 455, 468 ],
    "torso_angle":  [ 40.0, 38.5, 36.8 ]
  },
  "joint_angles": {
    "hip_angle":  [ 165, 159, 152 ],
    "knee_angle": [ 155, 147, 138 ]
  },
  "barbell_positioning": {
    "bar_height":              [ 120, 385, 610 ],
    "barbell_trajectory":      [ 0, -8, -2 ],
    "vertical_shoulder_height":[ 1380, 1400, 1440 ]
  },
  "phase_data": {
    "start_of_lifting":        { "image_url": "https://storage.googleapis.com..." },
    "first_pull_end":   { "image_url": "https://storage.googleapis.com..." }
  },
  "chart_data": {
    "setup":       { "start": 0,    "end": 536 },
    "first_pull":  { "start": 536,  "end": 952 }
  },
  "user_information": {
    "display_name": "Ahror Jabborov",
    "age": 28,
    "weight": 75,
    "height": 178
  },
  "session_date": "18/05/2025",
  "comments": {}
}

Error codes

  • 400 Bad Request – Invalid parameters.

  • 401 Unauthorized – Missing/invalid token.

  • 403 Forbidden – User lacks valid payment plan.

  • 404 Not Found – Session does not exist.

  • 500 Internal Server Error – Unexpected failure.

Security

Requires A valid API-KEY token in the Authorization header.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve the pre-generated demo lift analysis instead of a real one.

Responses
200

Lift analysis report generated successfully.

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

{
  "exercise": "text",
  "key_metrics": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  },
  "body_positioning": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  },
  "joint_angles": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  },
  "barbell_positioning": {
    "ANY_ADDITIONAL_PROPERTY": [
      1
    ]
  },
  "phase_data": {
    "ANY_ADDITIONAL_PROPERTY": {
      "average_time_ms": 1
    }
  },
  "chart_data": {
    "ANY_ADDITIONAL_PROPERTY": {
      "start": 1,
      "end": 1
    }
  },
  "user_information": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "session_date": "2025-08-24",
  "comments": {}
}

Get Summary of a Weightlifting Session

get

Retrieve a detailed summary of a weightlifting session using its unique session_id. The summary combines quantitative lift metrics with optional GenAI commentary.

Usage Instructions:

  1. Send a GET request with the session_id in the path.

  2. The endpoint replies with a structured JSON object (see below).

Query Parameter

  • demo (boolean, optional) – Set to true to retrieve a pre-generated demo summary.

Response Structure:

  • summary_text (object, optional) - GenAI commentary. Keys may include:

    • velocity - Insights on bar velocity.

    • power - Observations on force & power output.

    • stability - Notes on bar path / control.

    • final_summary - Overall coaching summary.

  • exercise_type (string) - The lift performed (e.g. Snatch).

  • velocity (object):

    • bar_velocity - { min, max, values[] } (m/s).

  • power (object):

    • ground_reaction_force - { min, max, values[] } (N).

    • power - { min, max, values[] } (W).

  • stability (object):

    • total_time (number) - Lift duration (s).

    • bar_height - { max, values[] } (m).

    • bar_trajectory (object) - { xAxis[], yAxis[] } (m).

  • user_information (object) - Same keys as running summaries (weight, height, etc.).

  • session_date (string) - Formatted date (e.g. 07/04/2025).

Note: summary_text appears only after GenAI feedback has been generated.

Authorizations
Path parameters
session_idanyRequired
Query parameters
demobooleanOptional

Set to true to retrieve a pre-generated demo summary for this weightlifting session.

Responses
200

Successfully retrieved weightlifting session summary

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

{
  "summary_text": {
    "velocity": "text",
    "power": "text",
    "stability": "text",
    "final_summary": "text"
  },
  "exercise_type": "text",
  "velocity": {
    "bar_velocity": {
      "min": 1,
      "max": 1,
      "values": [
        1
      ]
    }
  },
  "power": {
    "ground_reaction_force": {
      "min": 1,
      "max": 1,
      "values": [
        1
      ]
    },
    "power": {
      "min": 1,
      "max": 1,
      "values": [
        1
      ]
    }
  },
  "stability": {
    "total_time": 1,
    "bar_height": {
      "max": 1,
      "values": [
        1
      ]
    },
    "bar_trajectory": {
      "xAxis": [
        1
      ],
      "yAxis": [
        1
      ]
    }
  },
  "user_information": {
    "weight": 1,
    "height": 1,
    "age": "text",
    "gender": "text",
    "email": "text",
    "display_name": "text"
  },
  "session_date": "text"
}

Generate Summary for a WeightLifting 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 /weightlifting/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:

{
    "velocity": "thread_thread_id",
    "power": "thread_thread_id",
    "stability": "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

Summary threads generated successfully.

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

{
  "velocity": "thread_id_1",
  "power": "thread_id_2",
  "stability": "thread_id_3",
  "final_summary": "thread_id_4"
}

Generate lift-analysis comment threads for a Weightlifting Session

post

Generate Lift-analysis Comment Threads

Creates one GenAI thread per lift-analysis metric (power, force, bar velocity, joint angles, etc.) so that the assistant can return concise coaching comments for each.

Usage Example: POST /weightlifting/sessions/{session_id}/recommendation/

Parameters:

  • session_id (string, required) – Identifier of the weightlifting session to analyse.

  • measurement_system (query, optional) – 'metric' (default) or 'imperial'; determines the units embedded in each prompt.

Response Structure: A JSON object that maps every requested metric to the ID of the GenAI thread created for it.

Example Response:

{
  "power_output":           "thread_a12b34",
  "ground_reaction_force":  "thread_c56d78",
  "barbell_velocity":       "thread_e90f12",
  "hip_velocity":           "thread_g34h56",
  "shin_angle":             "thread_i78j90",
  "hip_height":             "thread_k12l34",
  "torso_angle":            "thread_m56n78",
  "hip_angle":              "thread_o90p12",
  "knee_angle":             "thread_q34r56",
  "bar_height":             "thread_s78t90",
  "barbell_trajectory":     "thread_u12v34",
  "vertical_shoulder_height":"thread_w56x78"
}

Notes:

  • session_id must reference an existing weight-lifting session.

  • The caller needs appropriate permissions (valid token & payment plan).

  • Use the returned thread IDs to poll / retrieve the generated comments later.

Authorizations
Path parameters
session_idanyRequired
Query parameters
measurement_systemstring · enumOptional

Measurement system used inside the prompts

Possible values:
Responses
201

Threads created successfully.

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

{
  "power_output": "text",
  "ground_reaction_force": "text",
  "barbell_velocity": "text",
  "hip_velocity": "text",
  "shin_angle": "text",
  "hip_height": "text",
  "torso_angle": "text",
  "hip_angle": "text",
  "knee_angle": "text",
  "bar_height": "text",
  "barbell_trajectory": "text",
  "vertical_shoulder_height": "text"
}
PreviousJumpingNextMobility Assessment

Last updated

Was this helpful?