Weightlifting
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_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: 'snatch', 'clean', or 'clean_and_jerk'.
Optional. The mass of the barbell used (numeric string). Defaults to 100 kg (or 220 lb) if not provided.
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.
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
trueto 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/YYYYformat.time (string): Creation time in
HH:MM AM/PMformat.
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.
Enter your bearer token (Firebase auth) in the format: Bearer
Set to true to retrieve a pre-generated demo session instead of a real one.
Weightlifting session details retrieved successfully.
Bad Request - Invalid parameters or admin UID.
Unauthorized - Missing or invalid access token.
Forbidden - Insufficient privileges.
Not Found - Session not found or invalid activity.
Internal Server Error - An unexpected error occurred.
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
trueto 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.
Enter your bearer token (Firebase auth) in the format: Bearer
Set to true to retrieve a pre-generated demo session instead of a real one.
Weightlifting session data retrieved successfully.
Bad Request - Invalid parameters or admin UID error.
Unauthorized - Missing or invalid access token.
Forbidden - User does not have sufficient privileges.
Not Found - The session was not found or its activity is not 'Weightlifting'.
Internal Server Error - An unexpected error occurred on the server.
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
trueto return a pre-generated demo lift analysis session.
Response structure (HTTP 200)
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.
Enter your bearer token (Firebase auth) in the format: Bearer
Set to true to retrieve the pre-generated demo lift analysis instead of a real one.
Lift analysis report generated successfully.
Bad Request - Invalid token or parameters.
Unauthorized - Token is invalid or expired.
Forbidden - Admin access is required.
Not Found - Session not found or user does not have a valid payment plan.
Internal Server Error - An unexpected error occurred.
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:
Send a GET request with the
session_idin the path.The endpoint replies with a structured JSON object (see below).
Query Parameter
demo (boolean, optional) β Set to
trueto 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.
Enter your bearer token (Firebase auth) in the format: Bearer
Set to true to retrieve a pre-generated demo summary for this weightlifting session.
Successfully retrieved weightlifting session summary
Bad Request - Invalid parameters.
Unauthorized - Token missing or expired.
Forbidden - User lacks a valid payment plan.
Not Found - Session not located.
Internal Server Error.
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_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'
Summary threads generated successfully.
Bad Request - Invalid token or parameters.
Unauthorized - Token is invalid or expired.
Forbidden - Admin access is required.
Not Found - Session not found or user does not have a valid payment plan.
Internal Server Error - An unexpected error occurred.
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_idmust 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.
Enter your bearer token (Firebase auth) in the format: Bearer
Measurement system used inside the prompts
Threads created successfully.
Bad Request - Invalid token or parameters.
Unauthorized - Token is invalid or expired.
Forbidden - Admin access is required.
Not Found - Session not found or user does not have a valid payment plan.
Internal Server Error - An unexpected error occurred.
Last updated
Was this helpful?