swagger: '2.0'
info:
  title: AIKYNETIX WEB API
  description: API documentation
  termsOfService: https://aikynetix.app/terms
  contact:
    email: info@aikynetix.com
  license:
    name: BSD License
  version: v2
host: api.aikynetix.app
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
    description: 'Enter your bearer token (Firebase auth) in the format: Bearer <token>'
  ApiKeyAuth:
    type: apiKey
    name: API-KEY
    in: header
    description: 'Enter your API key in the header: API-KEY: <api_key>'
security:
  - ApiKeyAuth: []
  - Bearer: []
paths:
  /admin-management/admins-list/:
    get:
      operationId: admin-management_admins-list_list
      summary: Retrieve a List of Admins
      description: >-
        ### Retrieve a List of Admins


        This endpoint allows administrators to retrieve a list of all admins
        associated with their account. The response includes user details.


        **Usage Example:**

        Send a `GET` request to `admin-management/admins-list/`.


        **Response Structure:**

        Upon a successful request, the endpoint returns a JSON array, where each
        element is an admin object containing:


        - `uid` *(string)*: Unique identifier of the admin.

        - `email` *(string)*: Email address of the admin.

        - `display_name` *(string)*: Display name of the admin.

        - `status` *(string)*: Status of the admin account. Possible values:
        'Active'.


        **Notes:**

        - Proper authorization is required; only users with admin privileges can
        access this endpoint.
      parameters: []
      responses:
        '200':
          description: Successfully retrieved the list of admins.
          schema:
            required:
              - query_count
              - users
            type: object
            properties:
              users:
                description: List of admins retrieved.
                type: array
                items:
                  required:
                    - uid
                    - email
                    - display_name
                    - status
                  type: object
                  properties:
                    uid:
                      description: Unique identifier of the admin.
                      type: string
                    email:
                      description: Email address of the admin.
                      type: string
                      format: email
                    display_name:
                      description: Display name of the admin.
                      type: string
                    status:
                      description: >-
                        Status of the admin account. Possible values: 'Active',
                        'Invited'.
                      type: string
          examples:
            application/json:
              users:
                - uid: userUid1
                  email: user1@example.com
                  display_name: User One
                  status: active
                - uid: userUid2
                  email: user2@example.com
                  display_name: User Two
                  status: invited
        '400':
          description: Bad Request - Invalid query parameters provided.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid request
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User lacks super admin privileges.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be a super admin to access this data.
        '404':
          description: Not Found - No admins found.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: No admins exist.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred
      tags:
        - admin-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /admin-management/invitation/:
    get:
      operationId: admin-management_invitation_list
      summary: List User Invitations
      description: >-
        ### List User Invitations


        This endpoint allows a user to retrieve a list of their pending
        invitations to become a sub-admin. Each invitation includes details such
        as the inviter's information and the invitation status.


        **Usage Example:**

        Send a `GET` request to `admin-management/invitations/`.


        **Response Structure:**

        Upon a successful request, the endpoint returns a JSON object containing
        a list of invitations.


        **Notes:**

        - Proper authentication is required; only authenticated users can access
        their invitations.
      parameters: []
      responses:
        '200':
          description: Successfully retrieved a list of user invitations.
          schema:
            required:
              - invitations
            type: object
            properties:
              invitations:
                description: List of user invitations.
                type: array
                items:
                  required:
                    - invite_token
                    - admin_uid
                    - admin_email
                    - admin_display_name
                    - invitee_email
                    - status
                    - created_at
                  type: object
                  properties:
                    invite_token:
                      description: Unique token identifying the invitation.
                      type: string
                    admin_uid:
                      description: UID of the admin who sent the invitation.
                      type: string
                    admin_email:
                      description: Email address of the admin.
                      type: string
                      format: email
                    admin_display_name:
                      description: Display name of the admin.
                      type: string
                    invitee_email:
                      description: Email address of the invitee.
                      type: string
                      format: email
                    status:
                      description: >-
                        Current status of the invitation. Possible values:
                        'pending', 'accepted', 'declined'.
                      type: string
                    created_at:
                      description: Timestamp when the invitation was created.
                      type: string
                      format: date-time
            example:
              invitations:
                - invite_token: 123e4567-e89b-12d3-a456-426614174000
                  admin_uid: adminUid456
                  admin_email: admin@example.com
                  admin_display_name: Admin User
                  invitee_email: user@example.com
                  status: pending
                  created_at: '2025-01-30T12:34:56Z'
                - invite_token: 223e4567-e89b-12d3-a456-426614174001
                  admin_uid: adminUid789
                  admin_email: admin2@example.com
                  admin_display_name: Second Admin
                  invitee_email: anotheruser@example.com
                  status: accepted
                  created_at: '2025-01-29T11:22:33Z'
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: No token provided.
              error_code: NO_TOKEN_PROVIDED
        '404':
          description: Not Found - No invitations found for the user.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: No pending invitations found.
              error_code: NO_INVITATIONS_FOUND
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred while retrieving invitations.
              error_code: INVITATION_RETRIEVAL_FAILED
      tags:
        - admin-management
      security:
        - Bearer: []
    post:
      operationId: admin-management_invitation_create
      summary: Create a User Invitation
      description: >-
        ### Create a User Invitation


        This endpoint allows a super administrator to create an invitation for a
        user to become a sub-admin. Provide the `user_email` of the user you
        wish to invite. Optionally, you can include a `platform_link` to direct
        the user to your platform upon accepting the invitation.


        **Usage Example:**

        Send a `POST` request to `admin-management/invitation/` with a JSON body
        containing the `user_email` and optionally the `platform_link`.


        **Request Body:**

        - `user_email` *(string, required)*: The email address of the user to be
        invited as a sub-admin.

        - `platform_link` *(string, optional)*: A URL to direct the invited user
        to your platform.


        **Response Structure:**

        Upon a successful request, the endpoint returns a JSON object containing
        the invitation details.


        **Notes:**

        - The `user_email` must correspond to an existing user or a new user to
        be invited.

        - Only users with super admin privileges can access this endpoint.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            required:
              - user_email
            type: object
            properties:
              user_email:
                description: Email address of the user to be invited as a sub-admin.
                type: string
                format: email
              platform_link:
                description: >-
                  Optional URL to direct the invited user upon accepting the
                  invitation.
                type: string
                format: uri
            example:
              user_email: invitee@example.com
              platform_link: https://yourplatform.com/welcome
      responses:
        '201':
          description: Invitation successfully created.
          schema:
            required:
              - invite_token
              - admin_uid
              - invitee_email
              - status
              - created_at
            type: object
            properties:
              invite_token:
                description: Unique token identifying the invitation.
                type: string
              admin_uid:
                description: UID of the admin who created the invitation.
                type: string
              invitee_email:
                description: Email address of the invited user.
                type: string
                format: email
              status:
                description: 'Current status of the invitation. Possible values: ''pending''.'
                type: string
              created_at:
                description: Timestamp when the invitation was created.
                type: string
                format: date-time
              platform_link:
                description: URL to direct the invited user upon accepting the invitation.
                type: string
                format: uri
            example:
              invite_token: 123e4567-e89b-12d3-a456-426614174000
              admin_uid: adminUid456
              invitee_email: invitee@example.com
              status: pending
              created_at: '2025-01-30T12:34:56Z'
              platform_link: https://yourplatform.com/welcome
        '400':
          description: Bad Request - Missing or invalid parameters.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: User email is required.
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User lacks super admin privileges.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be a super admin to access this endpoint.
        '404':
          description: Not Found - Admin or user not found.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Admin does not exist.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred while creating the invitation.
      tags:
        - admin-management
      security:
        - Bearer: []
    delete:
      operationId: admin-management_invitation_delete
      summary: Remove a User Invitation
      description: >-
        ### Remove a User Invitation


        This endpoint allows a super administrator to remove an existing
        invitation identified by the `invite_token`. Providing a valid
        `invite_token` will delete the corresponding invitation.


        **Usage Example:**

        Send a `DELETE` request to `admin-management/invitations/` with a JSON
        body containing the `invite_token`.


        **Request Body:**

        - `invite_token` *(string, required)*: The unique token of the
        invitation to be removed.


        **Response Structure:**

        Upon a successful request, the endpoint returns a confirmation message.


        **Notes:**

        - The `invite_token` must correspond to an existing invitation.

        - Only users with super admin privileges can access this endpoint.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            required:
              - invite_token
            type: object
            properties:
              invite_token:
                description: Unique token identifying the invitation to be removed.
                type: string
            example:
              invite_token: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Invitation successfully removed.
          schema:
            type: object
            properties:
              message:
                description: Confirmation message.
                type: string
            example:
              message: >-
                Invitation with token 123e4567-e89b-12d3-a456-426614174000 has
                been removed successfully.
        '400':
          description: Bad Request - Missing or invalid parameters.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invite token is required.
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User lacks super admin privileges.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be a super admin to access this endpoint.
        '404':
          description: Not Found - Invitation not found.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invitation not found.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred while removing the invitation.
      tags:
        - admin-management
      security:
        - Bearer: []
    parameters: []
  /admin-management/invitation/respond/:
    post:
      operationId: admin-management_invitation_respond_create
      summary: Respond to an Invitation
      description: >-
        ### Respond to an Invitation


        This endpoint allows a user to respond to a specific invitation
        identified by the `invite_token`. Provide the `user_response` parameter
        with either 'accept' or 'decline' to respond to the invitation.


        **Usage Example:**

        Send a `POST` request to `admin-management/invitations/respond/` with a
        JSON body containing the `invite_token` and `user_response`.


        **Request Body:**

        - `invite_token` *(string, required)*: Unique token identifying the
        invitation to respond to.

        - `user_response` *(string, required)*: The user's response to the
        invitation. Must be either 'accept' or 'decline'.


        **Response Structure:**

        Upon a successful request, the endpoint returns a confirmation message.


        **Notes:**

        - The `invite_token` must correspond to an existing invitation.

        - Only authenticated users can access this endpoint.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            required:
              - user_response
              - invite_token
            type: object
            properties:
              invite_token:
                description: Unique token identifying the invitation to respond to.
                type: string
              user_response:
                description: >-
                  The user's response to the invitation. Must be either 'accept'
                  or 'decline'.
                type: string
                enum:
                  - accept
                  - decline
            example:
              invite_token: 123e4567-e89b-12d3-a456-426614174000
              user_response: accept
      responses:
        '200':
          description: Invitation successfully responded to.
          schema:
            type: object
            properties:
              message:
                description: Confirmation message.
                type: string
            example:
              message: Invitation accepted.
        '400':
          description: Bad Request - Missing or invalid parameters.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid response. Must be 'accept' or 'decline'.
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: No token provided.
              error_code: NO_TOKEN_PROVIDED
        '403':
          description: Forbidden - User lacks permissions to respond to this invitation.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You do not have permission to respond to this invitation.
        '404':
          description: Not Found - Invitation not found or already responded to.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invitation has already been responded to.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred while responding to the invitation.
      tags:
        - admin-management
      security:
        - Bearer: []
    parameters: []
  /admin-management/sub-admins/:
    get:
      operationId: admin-management_sub-admins_list
      summary: Retrieve a Paginated List of Sub-Admins
      description: >-
        ### Retrieve a List of Sub-Admins


        This endpoint allows administrators to retrieve a list of sub-admins
        associated with their account. The response includes key user details
        such as unique ID, email, display name, assigned role, and account
        status.


        **Usage Example:**

        Send a `GET` request to `admin-management/sub-admins/` to retrieve all
        sub-admins under the current super admin.


        **Response Structure:**

        Upon a successful request, the endpoint returns a JSON object containing
        the following fields:


        1. **query_count**: Total number of sub-admins available.

        2. **users**: An array of sub-admin objects.


        **Detailed Description of Response Fields:**

        - **query_count** *(integer)*: Represents the total number of sub-admins
        associated with the requesting super admin.

        - **users** *(array of objects)*: Each object within the array
        represents a sub-admin with the following properties:
          - `uid` *(string)*: Unique identifier of the sub-admin.
          - `email` *(string)*: Email address of the sub-admin.
          - `display_name` *(string)*: Display name of the sub-admin.
          - `role` *(string)*: Role of the sub-admin. Possible values: 'Admin' or 'Owner'.
          - `status` *(string)*: Status of the sub-admin account. Possible values: 'Active', 'Invited'.

        **Notes:**

        - Proper authorization is required; only users with admin privileges can
        access this endpoint.
      parameters: []
      responses:
        '200':
          description: Successfully retrieved a paginated list of sub-admins.
          schema:
            required:
              - query_count
              - users
            type: object
            properties:
              query_count:
                description: Total number of sub-admins available.
                type: integer
              users:
                description: List of sub-admins retrieved.
                type: array
                items:
                  required:
                    - uid
                    - email
                    - display_name
                    - role
                    - status
                  type: object
                  properties:
                    uid:
                      description: Unique identifier of the sub-admin.
                      type: string
                    email:
                      description: Email address of the sub-admin.
                      type: string
                      format: email
                    display_name:
                      description: Display name of the sub-admin.
                      type: string
                    role:
                      description: >-
                        Role of the sub-admin. Possible values: 'Admin' or
                        'Owner'.
                      type: string
                    status:
                      description: >-
                        Status of the sub-admin account. Possible values:
                        'active', 'invited'.
                      type: string
          examples:
            application/json:
              query_count: 10
              users:
                - uid: userUid1
                  email: user1@example.com
                  display_name: User One
                  role: Owner
                  status: active
                - uid: userUid2
                  email: user2@example.com
                  display_name: User Two
                  role: Admin
                  status: Invited
        '400':
          description: Bad Request - Invalid query parameters provided.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid limit parameter
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User lacks super admin privileges.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be a super admin to access this data.
        '404':
          description: Not Found - No sub-admins found or retrieval failed.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Failed to retrieve sub-admins or none exist
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred
      tags:
        - admin-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: admin-management_sub-admins_create
      summary: Add a Sub-Admin
      description: >-
        ### Add a Sub-Admin


        This endpoint allows a super administrator to add a new sub-admin to
        their account. Provide the `user_uid` of the user you wish to promote to
        sub-admin status.


        **Usage Example:**

        Send a `POST` request to `admin-management/sub-admins/` with a JSON body
        containing the `user_uid`.


        **Request Body:**

        - `user_uid` *(string, required)*: The UID of the user to be added as a
        sub-admin.


        **Response Structure:**

        Upon a successful request, the endpoint returns a confirmation message.


        **Notes:**

        - The `user_uid` must correspond to an existing user.

        - Only users with super admin privileges can access this endpoint.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            required:
              - user_uid
            type: object
            properties:
              user_uid:
                description: UID of the user to be set as sub-admin.
                type: string
            example:
              user_uid: userUid123
      responses:
        '201':
          description: Sub-admin successfully added.
          schema:
            type: object
            properties:
              message:
                description: Confirmation message.
                type: string
            example:
              message: User with UID userUid123 is now a sub-admin of adminUid456.
        '400':
          description: Bad Request - Missing or invalid parameters.
          schema:
            type: object
            properties:
              error:
                description: Error message detailing what went wrong.
                type: string
            example:
              error: User UID is required.
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating missing token.
                type: string
            example:
              error: No token provided.
        '403':
          description: Forbidden - User lacks super admin privileges.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
            example:
              error: You must be a super admin to access this endpoint.
        '404':
          description: Not Found - User not found or already a sub-admin.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating the user was not found or already a
                  sub-admin.
                type: string
            example:
              error: User with UID userUid123 does not exist.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred while adding sub-admin.
      tags:
        - admin-management
      security:
        - Bearer: []
    delete:
      operationId: admin-management_sub-admins_delete
      summary: Remove a Sub-Admin
      description: >-
        ### Remove a Sub-Admin


        This endpoint allows a super administrator to remove an existing
        sub-admin from their account. Provide the `user_uid` of the sub-admin
        you wish to remove.


        **Usage Example:**

        Send a `DELETE` request to `admin-management/sub-admins/` with a JSON
        body containing the `user_uid`.


        **Request Body:**

        - `user_uid` *(string, required)*: The UID of the sub-admin to be
        removed.


        **Response Structure:**

        Upon a successful request, the endpoint returns a confirmation message.


        **Notes:**

        - The `user_uid` must correspond to an existing sub-admin.

        - Only users with super admin privileges can access this endpoint.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            required:
              - user_uid
            type: object
            properties:
              user_uid:
                description: UID of the sub-admin to be removed.
                type: string
            example:
              user_uid: userUid123
      responses:
        '200':
          description: Sub-admin successfully removed.
          schema:
            type: object
            properties:
              message:
                description: Confirmation message.
                type: string
            example:
              message: User with UID userUid123 has been removed from sub-admins.
        '400':
          description: Bad Request - Missing or invalid parameters.
          schema:
            type: object
            properties:
              error:
                description: Error message detailing what went wrong.
                type: string
            example:
              error: User UID is required.
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating missing token.
                type: string
            example:
              error: No token provided.
        '403':
          description: Forbidden - User lacks super admin privileges.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
            example:
              error: You must be a super admin to access this endpoint.
        '404':
          description: Not Found - Sub-admin not found.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating the sub-admin was not found.
                type: string
            example:
              error: User with UID userUid123 is not a sub-admin.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred while removing sub-admin.
      tags:
        - admin-management
      security:
        - Bearer: []
    parameters: []
  
  /client-management/clients/:
    get:
      operationId: client-management_clients_list
      summary: Retrieve a Paginated List of Users
      description: >-
        ### Retrieve a Paginated List of Users


        This endpoint allows an administrator to retrieve a paginated list of
        users under their account. The response includes detailed information
        for each user such as personal attributes, contact details, and metadata
        related to their account.


        **Usage Example:**

        Send a `GET` request to `client-management/clients/` with the
        appropriate API-KEY token in the Authorization header.


        **Response Structure:**

        - **users** *(array)*: A list of user objects, where each object
        includes the following fields:
          - **created_at** *(string, date-time)*: Timestamp when the user was created.
          - **weight** *(number)*: The user’s weight.
          - **age** *(string)*: The user’s age.
          - **ycom** *(number)*: The user’s YCOM value.
          - **height** *(number)*: The user’s height.
          - **phone** *(string)*: The user’s phone number.
          - **leg_length** *(number)*: The user’s leg length.
          - **display_name** *(string)*: The user’s display name.
          - **shoeSize** *(string)*: The user’s shoe size.
          - **email** *(string)*: The user’s email address.
          - **gender** *(string)*: The user’s gender.
          - **brand** *(string)*: The brand associated with the user.
          - **shoeModel** *(string)*: The model of the user’s shoe.
          - **user_uid** *(string)*: The unique identifier for the user.

        **Notes:**

        - A valid API-KEY token is required to access this endpoint.

        - If there are no users or an error occurs, an appropriate error message
        is returned.
      parameters: []
      responses:
        '200':
          description: Successfully retrieved the list of users.
          schema:
            required:
              - users
            type: object
            properties:
              users:
                description: An array of user objects.
                type: array
                items:
                  required:
                    - created_at
                    - weight
                    - age
                    - ycom
                    - height
                    - phone
                    - leg_length
                    - display_name
                    - shoeSize
                    - email
                    - gender
                    - brand
                    - shoeModel
                    - user_uid
                  type: object
                  properties:
                    created_at:
                      description: Timestamp when the user was created.
                      type: string
                      format: date-time
                    weight:
                      description: The user’s weight.
                      type: number
                    age:
                      description: The user’s age.
                      type: string
                    ycom:
                      description: The user’s YCOM value.
                      type: number
                    height:
                      description: The user’s height.
                      type: number
                    phone:
                      description: The user’s phone number.
                      type: string
                    leg_length:
                      description: The user’s leg length.
                      type: number
                    display_name:
                      description: The user’s display name.
                      type: string
                    shoeSize:
                      description: The user’s shoe size.
                      type: string
                    email:
                      description: The user’s email address.
                      type: string
                      format: email
                    gender:
                      description: The user’s gender.
                      type: string
                    brand:
                      description: Brand associated with the user.
                      type: string
                    shoeModel:
                      description: Model of the user's shoe.
                      type: string
                    profile_photo:
                      description: Public URL of the user’s profile photo.
                      type: string
                      format: uri
                    user_uid:
                      description: Unique identifier for the user.
                      type: string
          examples:
            application/json:
              users:
                - created_at: '2024-12-02T19:17:30.371Z'
                  weight: 79.78699276972904
                  age: '30'
                  ycom: 1.0134599999999998
                  height: 177.79999999999998
                  phone: '92039023232'
                  leg_length: 0.9627869999999997
                  display_name: User2
                  shoeSize: '8'
                  email: User2@example.com
                  gender: Male
                  brand: Nike
                  shoeModel: Peak-smart
                  profile_photo: >-
                    https://storage.googleapis.com/bucket/admins/A123/U1/profile_photo.jpg
                  user_uid: hLT10sKbCumCUIsNAk3h
                - created_at: '2024-08-16T00:29:21.349Z'
                  weight: 70
                  age: '22'
                  ycom: 0.9570000000000001
                  height: 174
                  phone: '8328889011'
                  leg_length: 0.90915
                  display_name: User1
                  shoeSize: '6'
                  email: user1@example.com
                  gender: Female
                  brand: Fabletics
                  shoeModel: The Everyday Sneaker II
                  profile_photo: >-
                    https://storage.googleapis.com/bucket/admins/A123/U1/profile_photo.jpg
                  user_uid: CMQe1HuAg4uMXqHE6dVO
        '400':
          description: Bad Request - Invalid query parameters or missing required data.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: Invalid parameters provided.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Unauthorized error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User does not have the required permissions.
          schema:
            type: object
            properties:
              error:
                description: Forbidden error message.
                type: string
          examples:
            application/json:
              error: You do not have permission to access this data.
        '404':
          description: Not Found - Users not found or retrieval failed.
          schema:
            type: object
            properties:
              error:
                description: Error message when no users are found.
                type: string
          examples:
            application/json:
              error: Admin does not exist.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      consumes:
        - multipart/form-data
      tags:
        - client-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: client-management_clients_create
      summary: Create a New User
      description: >-
        ### Create a New User


        This endpoint allows an authenticated admin to create a new user under
        their account. The admin must provide the user's email and display name,
        and may optionally include other fields. 


        **Usage Example:**

        Send a `POST` request to `/clients/` with a JSON payload containing the
        required fields. A valid API-KEY token must be included in the
        Authorization header.


        ### Request parameters

        - **display_name** (string)

        - **email** (string, valid email)

        - **age** (integer)

        - **gender** (male | female)

        - **shoeSize** (float)

        - **weight** (float)

        - **height** (float)


        **Response Structure:**

        Upon success (HTTP 201), the endpoint returns a JSON object with a
        `userData` field containing the following keys and data types:

        - **user_uid** *(string)*: A unique identifier for the newly created
        user.

        - **display_name** (string)

        - **email** (string, valid email)

        - **age** (integer)

        - **gender** (male | female)

        - **shoeSize** (float)

        - **weight** (float)

        - **height** (float)


        - **profile_photo** *(file, JPEG/PNG)* - optional image; only available
        with `multipart/form-data`.


        In case of an error (e.g., missing parameters, unauthorized access, or
        an internal error), a JSON object with an `error` field (string) is
        returned.
      parameters:
        - name: display_name
          in: formData
          required: true
          type: string
        - name: email
          in: formData
          required: true
          type: string
          format: email
        - name: age
          in: formData
          required: true
          type: integer
        - name: gender
          in: formData
          required: true
          type: string
          enum:
            - male
            - female
        - name: shoeSize
          in: formData
          required: true
          type: number
          format: float
        - name: weight
          in: formData
          required: true
          type: number
          format: float
        - name: height
          in: formData
          required: true
          type: number
          format: float
        - name: preferable_activities
          in: formData
          description: >-
            Optional JSON-encoded list of preferred activity types. Allowed
            values: 'Running', 'Vertical Jump', 'Weightlifting', 'Mobility
            Assessment'.


            Example: `["Running", "Weightlifting"]`
          required: false
          type: string
        - name: profile_photo
          in: formData
          description: Optional JPEG/PNG image.
          required: false
          type: file
      responses:
        '201':
          description: User created successfully.
          schema:
            type: object
            properties:
              userData:
                required:
                  - user_uid
                  - email
                  - display_name
                type: object
                properties:
                  user_uid:
                    type: string
                  display_name:
                    type: string
                  email:
                    type: string
                  age:
                    type: integer
                  gender:
                    type: string
                  shoeSize:
                    type: number
                    format: float
                  weight:
                    type: number
                    format: float
                  height:
                    type: number
                    format: float
                  profile_photo:
                    description: Public URL of the user’s profile photo.
                    type: string
                    format: uri
                  preferable_activities:
                    description: List of preferred activities.
                    type: array
                    items:
                      type: string
          examples:
            application/json:
              userData:
                user_uid: AbCdEf123
                display_name: Alex
                email: alex@mail.com
                age: 28
                gender: Female
                shoeSize: 39
                weight: 66.4
                height: 170
                profile_photo: >-
                  https://storage.googleapis.com/bucket/admins/A123/AbCdEf123/profile_photo.jpg
                preferable_activities:
                  - Running
                  - Weightlifting
        '400':
          description: Bad Request - Missing or invalid parameters.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message describing the input issue.
                type: string
          examples:
            application/json:
              error: Email and display name are required.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User is not authorized to create users.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - User creation limit reached for Pro plan.
          schema:
            type: object
            properties:
              error:
                description: User creation limit reached for Pro plan
                type: string
          examples:
            application/json:
              error: User creation limit reached for Pro plan.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      consumes:
        - multipart/form-data
      tags:
        - client-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    put:
      operationId: client-management_clients_update
      summary: Update User Information
      description: >-
        ### Update User Information


        This endpoint lets an authenticated admin update **selected fields** of
        an existing user, using **query-string parameters**.


        **Required query parameter**

        - **user_uid** *(string)* - the UID of the user being updated.


        **Optional query parameters** - supply one or more of the following:

        - **display_name** *(string)* - new display name

        - **email** *(string, valid email)* - new email address

        - **age** *(integer)*

        - **gender** *(string, one of `male`, `female`)*

        - **shoeSize** *(float)*

        - **weight** *(float)*

        - **height** *(float)*


        **Response (HTTP 200)**

        ```json

        { "message": "User information updated successfully." }

        ```


        If validation fails or the user is not found, the response contains an
        **error** field with details.
      parameters:
        - name: user_uid
          in: formData
          required: true
          type: string
        - name: display_name
          in: formData
          required: false
          type: string
        - name: email
          in: formData
          required: false
          type: string
          format: email
        - name: age
          in: formData
          required: false
          type: integer
        - name: gender
          in: formData
          required: false
          type: string
          enum:
            - male
            - female
        - name: shoeSize
          in: formData
          required: false
          type: number
          format: float
        - name: weight
          in: formData
          required: false
          type: number
          format: float
        - name: height
          in: formData
          required: false
          type: number
          format: float
        - name: preferable_activities
          in: formData
          description: >-
            Optional JSON-encoded list of preferred activity types. Allowed
            values: 'Running', 'Vertical Jump', 'Weightlifting', 'Mobility
            Assessment'.


            Example: `["Running", "Weightlifting"]`
          required: false
          type: string
        - name: profile_photo
          in: formData
          description: Optional JPEG/PNG image.
          required: false
          type: file
      responses:
        '200':
          description: User information updated successfully.
          schema:
            type: object
            properties:
              message:
                description: Confirmation message indicating successful update.
                type: string
          examples:
            application/json:
              message: User information updated successfully.
        '400':
          description: Bad Request - Missing required fields or invalid data.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message describing what went wrong.
                type: string
          examples:
            application/json:
              error: User UID is required.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User is not authorized to update user information.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      consumes:
        - multipart/form-data
      tags:
        - client-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    delete:
      operationId: client-management_clients_delete
      summary: Delete a User
      description: >-
        ### Delete a User


        This endpoint allows an authenticated admin to delete a user from their
        account. The admin must supply the unique identifier of the user to be
        deleted in the request body.


        **Request Body:**

        - **user_uid** *(string, required)*: The unique identifier of the user
        to be deleted.


        **Response Structure:**

        Upon success (HTTP 200), the endpoint returns a JSON object with a
        **message** field of type string confirming the deletion. In case of an
        error (for example, if the user UID is missing, the user is not found,
        or an internal error occurs), a JSON object with an **error** field
        (string) is returned.
      parameters:
        - name: user_uid
          in: query
          description: UID of the user to delete
          required: true
          type: string
      responses:
        '200':
          description: User deleted successfully.
          schema:
            type: object
            properties:
              message:
                description: >-
                  Confirmation message indicating that the user has been
                  deleted.
                type: string
          examples:
            application/json:
              message: User with UID MYmC7MzsPBNU6uSQBnJ0 deleted from admin
        '400':
          description: Bad Request - Missing required user UID.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Detailed error message indicating that the user UID is
                  missing.
                type: string
          examples:
            application/json:
              error: User UID is required.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User is not authorized to delete users.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - User not found or not under admin.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the user is not found under the
                  admin's account.
                type: string
          examples:
            application/json:
              error: User is not under admin.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      consumes:
        - multipart/form-data
      tags:
        - client-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /client-management/clients/filter/:
    get:
      operationId: client-management_clients_filter_list
      summary: Filter and Paginate Users
      description: >-
        ### Filter and Paginate Users


        This endpoint allows an authenticated admin to filter and paginate
        through the users under their account. You can optionally specify query
        parameters to control pagination:


        - **start_after_id** *(string, optional)*: The UID after which to start
        retrieving users (for forward pagination).

        - **limit** *(integer, optional)*: The maximum number of users to
        retrieve. Defaults to 5 if not provided.


        You can also filter users based on various criteria such as:


        - **admin_uid** *(string, optional)*: The UID of the admin to filter
        users by.

        - **start_date** *(string, optional)*: Lower bound (inclusive) for the
        user's last session in `YYYY-MM-DD` format.

        - **end_date** *(string, optional)*: Upper bound (inclusive) for the
        user's last session in `YYYY-MM-DD` format.

        - **gender** *(string, optional)*: Filter by gender (`male` or
        `female`).

        - **preferable_activities** *(array, optional)*: Filter by user's
        preferable activities.

        **Response Structure (HTTP 200):**

        The response returns a JSON object with the following fields:


        - **query_count** *(integer)*: Total number of users under the admin.

        - **users** *(array)*: An array of user objects. Each user object
        contains:
          - **created_at** *(string, date-time)*: User creation timestamp.
          - **weight** *(number)*: The user's weight.
          - **age** *(string)*: The user's age.
          - **ycom** *(number)*: The user's YCOM value.
          - **height** *(number)*: The user's height.
          - **phone** *(string)*: The user's phone number.
          - **leg_length** *(number)*: The user's leg length.
          - **display_name** *(string)*: The user's display name.
          - **shoeSize** *(string)*: The user's shoe size.
          - **email** *(string)*: The user's email address.
          - **gender** *(string)*: The user's gender.
          - **brand** *(string)*: The brand associated with the user.
          - **shoeModel** *(string)*: The model of the user's shoe.
          - **user_uid** *(string)*: The unique identifier of the user.

        - **first_uid** *(string)*: The UID of the first user in the current
        page.

        - **last_uid** *(string)*: The UID of the last user in the current page.


        **Notes:**

        - A valid API-KEY token is required.

        - If no users are found, an error message is returned with status code
        404.
      parameters:
        - name: admin_uid
          in: query
          description: UID of the admin (who created the user) to filter users by.
          required: false
          type: string
        - name: start_date
          in: query
          description: Lower bound (inclusive) for *last_session* in `YYYY-MM-DD`.
          required: false
          type: string
        - name: end_date
          in: query
          description: Upper bound (inclusive) for *last_session* in `YYYY-MM-DD`.
          required: false
          type: string
        - name: gender
          in: query
          description: Filter by gender (`male` or `female`).
          required: false
          type: string
          enum:
            - male
            - female
        - name: preferable_activities
          in: query
          description: JSON array of preferred activities.
          required: false
          type: string
        - name: start_after_id
          in: query
          required: false
          type: string
        - name: limit
          in: query
          required: false
          type: integer
          default: 10
      responses:
        '200':
          description: Successfully retrieved the filtered list of users.
          schema:
            required:
              - query_count
              - users
              - first_uid
              - last_uid
            type: object
            properties:
              query_count:
                description: Total number of users under the admin.
                type: integer
              users:
                description: An array of user objects.
                type: array
                items:
                  required:
                    - created_at
                    - weight
                    - age
                    - ycom
                    - height
                    - phone
                    - leg_length
                    - display_name
                    - shoeSize
                    - email
                    - gender
                    - brand
                    - shoeModel
                    - user_uid
                  type: object
                  properties:
                    created_at:
                      description: User creation timestamp.
                      type: string
                      format: date-time
                    weight:
                      description: User's weight.
                      type: number
                    age:
                      description: User's age.
                      type: string
                    ycom:
                      description: User's YCOM value.
                      type: number
                    height:
                      description: User's height.
                      type: number
                    phone:
                      description: User's phone number.
                      type: string
                    leg_length:
                      description: User's leg length.
                      type: number
                    display_name:
                      description: User's display name.
                      type: string
                    shoeSize:
                      description: User's shoe size.
                      type: string
                    email:
                      description: User's email address.
                      type: string
                      format: email
                    gender:
                      description: User's gender.
                      type: string
                    brand:
                      description: The brand associated with the user.
                      type: string
                    shoeModel:
                      description: The model of the user's shoe.
                      type: string
                    profile_photo:
                      description: Public URL of the user’s profile photo.
                      type: string
                      format: uri
                    user_uid:
                      description: Unique identifier for the user.
                      type: string
              first_uid:
                description: UID of the first user in the current page.
                type: string
              last_uid:
                description: UID of the last user in the current page.
                type: string
          examples:
            application/json:
              query_count: 2
              users:
                - created_at: '2024-12-02T19:17:30.371Z'
                  weight: 79.79
                  age: '30'
                  ycom: 1.01
                  height: 177.8
                  phone: '92039023232'
                  leg_length: 0.96
                  display_name: User1
                  shoeSize: '8'
                  email: user1@gmail.com
                  gender: Male
                  brand: Nike
                  shoeModel: Peak-smart
                  profile_photo: >-
                    https://storage.googleapis.com/bucket/admins/A123/U1/profile_photo.jpg
                  user_uid: idsKbCumCUIsNAk3h
                - created_at: '2024-08-16T00:29:21.349Z'
                  weight: 70
                  age: '22'
                  ycom: 0.96
                  height: 174
                  phone: '8328889011'
                  leg_length: 0.91
                  display_name: User2
                  shoeSize: '6'
                  email: user2@gmail.com
                  gender: Female
                  brand: Fabletics
                  shoeModel: The Everyday Sneaker II
                  profile_photo: >-
                    https://storage.googleapis.com/bucket/admins/A123/U1/profile_photo.jpg
                  user_uid: slsKbCumCUIsNAk3h
              first_uid: idsKbCumCUIsNAk3h
              last_uid: slsKbCumCUIsNAk3h
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Authentication error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - The requester does not have admin privileges.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: >-
            Not Found - No users found under the admin or an error occurred
            during retrieval.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating the issue.
                type: string
          examples:
            application/json:
              error: No users found under admin
        '500':
          description: >-
            Internal Server Error - An unexpected error occurred during
            retrieval.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'Error fetching user records: <error details>'
      tags:
        - client-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /client-management/clients/save-notes/{user_uid}:
    post:
      operationId: client-management_clients_save-notes_create
      summary: Set / replace a note for a client
      description: >-
        Stores **one** note per client. If *note* is omitted or empty, the
        previous note is cleared (saved as `null`).


        Document structure:

        ```json

        "notes": {
          "text": "Hamstring strain - reduce speed work for 2 wks",  // or null
          "updated_at": "2025-07-14T09:32:11.123Z"
        }

        ```
      parameters:
        - name: data
          in: body
          required: true
          schema:
            required:
              - note
            type: object
            properties:
              note:
                description: >-
                  Free-form note text (≤ 100 kB). If omitted or empty, the note
                  is cleared.
                type: string
            example:
              note: Hamstring strain - reduce speed work for 2 weeks
        - name: user_uid
          in: path
          description: The unique identifier of the user.
          required: true
          type: string
      responses:
        '200':
          description: Note saved / replaced successfully.
          schema:
            required:
              - message
            type: object
            properties:
              message:
                type: string
          examples:
            application/json:
              message: Note saved.
        '400':
          description: Bad Request - The user UID is missing or invalid.
          schema:
            type: object
            properties:
              error:
                description: Error message describing the problem.
                type: string
          examples:
            application/json:
              error: User UID is required.
        '401':
          description: Unauthorized - Missing or invalid token.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that authentication failed.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - The requester does not have admin privileges.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - The user is not found or is not under the admin.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the user was not found.
                type: string
          examples:
            application/json:
              error: User is not under this admin
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'Error fetching user data: <error details>'
      tags:
        - client-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: user_uid
        in: path
        required: true
        type: string
  /client-management/clients/{user_uid}:
    get:
      operationId: client-management_clients_read
      summary: Retrieve Details for a Specific User
      description: >-
        ### Retrieve User Details


        This endpoint allows an authenticated admin to retrieve detailed
        information for a specific user under their account. The user is
        identified by the unique `user_uid` provided in the URL.


        **Path Parameter:**

        - **user_uid** *(string, required)*: The unique identifier of the user.


        **Response Structure (HTTP 200):**

        Returns a JSON object with the following fields and data types:


        - **created_at** *(string, date-time)*: Timestamp when the user was
        created.

        - **weight** *(number)*: The user's weight.

        - **age** *(string)*: The user's age.

        - **ycom** *(number)*: The user's YCOM value.

        - **height** *(number)*: The user's height.

        - **phone** *(string)*: The user's phone number.

        - **leg_length** *(number)*: The user's leg length.

        - **display_name** *(string)*: The user's display name.

        - **shoeSize** *(string)*: The user's shoe size.

        - **email** *(string)*: The user's email address.

        - **gender** *(string)*: The user's gender.

        - **brand** *(string)*: The brand associated with the user.

        - **shoeModel** *(string)*: The model of the user's shoe.

        - **user_uid** *(string)*: The unique identifier for the user.


        **Example Successful Response:**

        ```json

        {
          "created_at": "2024-12-02T19:17:30.371Z",
          "weight": 79,
          "age": "30",
          "ycom": 1.1,
          "height": 177,
          "phone": "92039023232",
          "leg_length": 0.9,
          "display_name": "User1",
          "shoeSize": "8",
          "email": "user1@gmail.com",
          "gender": "Male",
          "brand": "Nike",
          "shoeModel": "Peak-smart",
          "user_uid": "hoEwsdv2fsFs2fav"
        }

        ```


        **Notes:**

        - A valid API-KEY token with admin privileges is required.

        - If the specified user does not exist or is not under the admin, a 404
        error is returned.
      parameters:
        - name: user_uid
          in: path
          description: The unique identifier of the user.
          required: true
          type: string
      responses:
        '200':
          description: User details retrieved successfully.
          schema:
            required:
              - created_at
              - weight
              - age
              - ycom
              - height
              - phone
              - leg_length
              - display_name
              - shoeSize
              - email
              - gender
              - brand
              - shoeModel
              - user_uid
            type: object
            properties:
              created_at:
                description: Timestamp when the user was created.
                type: string
                format: date-time
              weight:
                description: The user's weight.
                type: number
              age:
                description: The user's age.
                type: string
              ycom:
                description: The user's YCOM value.
                type: number
              height:
                description: The user's height.
                type: number
              phone:
                description: The user's phone number.
                type: string
              leg_length:
                description: The user's leg length.
                type: number
              display_name:
                description: The user's display name.
                type: string
              shoeSize:
                description: The user's shoe size.
                type: string
              email:
                description: The user's email address.
                type: string
                format: email
              gender:
                description: The user's gender.
                type: string
              brand:
                description: The brand associated with the user.
                type: string
              shoeModel:
                description: The model of the user's shoe.
                type: string
              profile_photo:
                description: Public URL of the profile photo.
                type: string
                format: uri
              user_uid:
                description: The unique identifier for the user.
                type: string
          examples:
            application/json:
              created_at: '2024-12-02T19:17:30.371Z'
              weight: 80
              age: '30'
              ycom: 1.1
              height: 177
              phone: '92039023232'
              leg_length: 0.9
              display_name: User1
              shoeSize: '8.5'
              email: user1@example.com
              gender: Male
              brand: Nike
              shoeModel: Ps-1
              profile_photo: >-
                https://storage.googleapis.com/bucket/admins/A123/AbCdEf123/profile_photo.jpg
              user_uid: mKbCumCUIsNAk3h
        '400':
          description: Bad Request - The user UID is missing or invalid.
          schema:
            type: object
            properties:
              error:
                description: Error message describing the problem.
                type: string
          examples:
            application/json:
              error: User UID is required.
        '401':
          description: Unauthorized - Missing or invalid token.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that authentication failed.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - The requester does not have admin privileges.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - The user is not found or is not under the admin.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the user was not found.
                type: string
          examples:
            application/json:
              error: User is not under this admin
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'Error fetching user data: <error details>'
      tags:
        - client-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: user_uid
        in: path
        required: true
        type: string
  
  /company-profile/:
    get:
      operationId: company-profile_list
      summary: Retrieve Company Profile
      description: >
        ### Retrieve the authenticated user’s company profile


        **Usage Example**

        ```bash

        curl -H "Authorization: API-KEY <ID-Token>" \
             -X GET https://api.example.com/company-profile/
        ```


        **Response Structure**

        - **companyName** *(string, required)* – Official name of the company.

        - **ownerName** *(string)* – Full name of the company owner.

        - **role** *(string)* – Role/position of the current user within the
        company.

        - **measurement** *(string)* – Preferred measurement system (e.g.
        `metric`).

        - **companyLogo** *(string, URI)* – Public URL of the logo stored in
        Firebase.


        **Notes**

        - Requires a valid Firebase **ID token** in the `Authorization` header.

        - Returns **404** if no profile document exists for the user.
      parameters: []
      responses:
        '200':
          description: Company profile retrieved successfully.
          schema:
            required:
              - companyName
            type: object
            properties:
              companyName:
                description: Official name of the company.
                type: string
              ownerName:
                description: Full name of the company owner.
                type: string
              role:
                description: >-
                  Primary role/position of the authenticated user in the
                  company.
                type: string
              measurement:
                description: Preferred measurement system (e.g., `metric`, `imperial`).
                type: string
              companyLogo:
                description: Public URL of the company logo stored in Firebase Storage.
                type: string
                format: uri
          examples:
            application/json:
              companyName: Apple Inc.
              ownerName: Mario Rossi
              role: CTO
              measurement: metric
              companyLogo: >-
                https://storage.googleapis.com/bucket/companies/uid/company_logo.jpg
        '404':
          description: Profile not found.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: Profile not found.
        '500':
          description: Unexpected server error.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <details>'
      consumes:
        - multipart/form-data
      tags:
        - company-profile
      security:
        - Bearer: []
    post:
      operationId: company-profile_create
      summary: Create / Replace Company Profile
      description: >
        ### Create a new company profile or replace an existing one


        **Accepted Content-Types**

        - `application/json` – Supply profile fields directly as JSON.

        - `multipart/form-data` – Use when uploading a **companyLogo** file.


        **Usage Example (JSON)**

        ```bash

        curl -H "Authorization: API-KEY <ID-Token>" \
             -H "Content-Type: application/json" \
             -d '{"companyName":"Apple Inc.","ownerName":"Mario Rossi"}' \
             -X POST https://api.example.com/company-profile/
        ```


        **Usage Example (Multipart)**

        ```bash

        curl -H "Authorization: API-KEY <ID-Token>" \
             -F companyName="Apple Inc." \
             -F companyLogo=@logo.jpg \
             -X POST https://api.example.com/company-profile/
        ```


        **Response Structure (201)**

        - **companyName** *(string)* – Official name of the company.

        - **ownerName** *(string)* – Full name of the company owner.

        - **role** *(string)* – Role of the current user in the company.

        - **companyLogo** *(string, URI)* – Public URL of the uploaded logo.


        **Notes**

        - `companyName`, `ownerName`, and `role` are required.

        - If a profile already exists, fields are merged (not overwritten
        entirely).
      parameters:
        - name: companyLogo
          in: formData
          description: '**Optional.** Image file (`jpeg`/`png`).'
          type: file
        - name: companyName
          in: formData
          description: '**Required (POST)** – Company name (text field).'
          required: false
          type: string
        - name: ownerName
          in: formData
          description: Full name of the owner (text field).
          required: false
          type: string
        - name: role
          in: formData
          description: Role of the current user (text field).
          required: false
          type: string
        - name: measurement
          in: formData
          description: Preferred measurement system (`metric` / `imperial`).
          required: false
          type: string
      responses:
        '201':
          description: Profile created successfully.
          schema:
            required:
              - companyName
              - ownerName
              - role
            type: object
            properties:
              companyName:
                type: string
              ownerName:
                type: string
              role:
                type: string
              companyLogo:
                type: string
                format: uri
          examples:
            application/json:
              companyName: Apple Inc.
              ownerName: Mario Rossi
              role: CEO
              companyLogo: https://.../company_logo.jpg?v=1726243847
        '400':
          description: Validation error.
          schema:
            required:
              - errors
            type: object
            properties:
              errors:
                description: List of Pydantic validation errors.
                type: array
                items:
                  type: object
        '500':
          description: Unexpected server error.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
      consumes:
        - multipart/form-data
      tags:
        - company-profile
      security:
        - Bearer: []
    patch:
      operationId: company-profile_partial_update
      summary: Update Company Profile
      description: >
        ### Partially update one or more profile fields


        **Accepted Content-Types**

        - `application/json`

        - `multipart/form-data` (for logo replacement)


        **Usage Example (clear logo)**

        ```bash

        curl -H "Authorization: API-KEY <ID-Token>" \
             -H "Content-Type: application/json" \
             -d '{"companyLogo":""}' \
             -X PATCH https://api.example.com/company-profile/
        ```


        **Usage Example (replace logo)**

        ```bash

        curl -H "Authorization: API-KEY <ID-Token>" \
             -F companyLogo=@new_logo.png \
             -X PATCH https://api.example.com/company-profile/
        ```


        **Response Structure (200)**

        - **companyName** *(string)* – Official name of the company.

        - **ownerName** *(string)* – Full name of the company owner.

        - **role** *(string)* – Role of the current user in the company.

        - **companyLogo** *(string, URI)* – Public URL of the updated logo.


        **Notes**

        - Only the supplied fields are modified; unspecified fields remain
        unchanged.

        - Providing an empty string (`""`) for **companyLogo** removes the logo.
      parameters:
        - name: companyLogo
          in: formData
          description: '**Optional.** Image file (`jpeg`/`png`).'
          type: file
        - name: companyName
          in: formData
          description: '**Required (POST)** – Company name (text field).'
          required: false
          type: string
        - name: ownerName
          in: formData
          description: Full name of the owner (text field).
          required: false
          type: string
        - name: role
          in: formData
          description: Role of the current user (text field).
          required: false
          type: string
        - name: measurement
          in: formData
          description: Preferred measurement system (`metric` / `imperial`).
          required: false
          type: string
      responses:
        '200':
          description: Profile updated successfully.
          schema:
            type: object
            properties:
              companyName:
                type: string
              ownerName:
                type: string
              role:
                type: string
              companyLogo:
                type: string
                format: uri
          examples:
            application/json:
              companyName: Apple Inc.
              companyLogo: https://.../company_logo.jpg?v=1726249847
        '400':
          description: Validation error.
          schema:
            required:
              - errors
            type: object
            properties:
              errors:
                description: List of Pydantic validation errors.
                type: array
                items:
                  type: object
        '500':
          description: Unexpected server error.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
      consumes:
        - multipart/form-data
      tags:
        - company-profile
      security:
        - Bearer: []
    parameters: []
  /company-profile/organization-status/:
    get:
      operationId: company-profile_organization-status_list
      summary: Retrieve Organization Status
      description: >-
        ### Retrieve Organization Status


        This endpoint allows an authenticated user (admin or sub-admin) to
        retrieve organization status details. The response includes various
        details such as the session number, user UID, role, payment type, and
        associated activities. 


        **Response Structure (HTTP 200):**

        - **session_number** *(integer)*: The number of sessions associated with
        the organization.

        - **uid** *(string)*: The unique identifier of the authenticated user.

        - **role** *(string)*: The role of the user, which can be either `admin`
        or `sub_admin`.

        - **payment_type** *(string)*: The type of payment plan for the
        organization.

        - **activity** *(array of strings)*: A list of activities associated
        with the organization.

        - **companyName** *(string or null)*: The name of the company, if
        available.

        - **name** *(string or null)*: The name of the user.


        **Example Successful Response:**

        ```json

        {
          "session_number": 50,
          "uid": "aB3xYz1PqW8LmTnK4R9VfJ0gHsCd",
          "role": "admin",
          "payment_type": "Enterprise",
          "activity": ["Running", "Weightlifting", "VerticalJump", "MobilityAssessment"],
          "companyName": "Apple",
          "name": "Username"
        }

        ```


        **Notes:**

        - A valid API-KEY token is required to access this endpoint.

        - If the organization status is not found or the data is invalid (e.g.
        missing session_number), a 404 error is returned.
      parameters: []
      responses:
        '200':
          description: Organization status details retrieved successfully.
          schema:
            required:
              - session_number
              - uid
              - role
              - payment_type
              - activity
              - companyName
              - name
            type: object
            properties:
              session_number:
                description: The number of sessions associated with the organization.
                type: integer
              uid:
                description: The unique identifier of the authenticated user.
                type: string
              role:
                description: The user's role; either 'admin' or 'sub_admin'.
                type: string
              payment_type:
                description: The payment plan type for the organization.
                type: string
              activity:
                description: A list of activities associated with the organization.
                type: array
                items:
                  description: An activity associated with the organization.
                  type: string
              companyName:
                description: The name of the company, if available.
                type: string
              name:
                description: The name of the user, if available.
                type: string
          examples:
            application/json:
              session_number: 50
              uid: aB3xYz1PqW8LmTnK4R9VfJ0gHsCd
              role: admin
              payment_type: Enterprise
              activity:
                - Running
                - Weightlifting
                - VerticalJump
                - MobilityAssessment
              companyName: Apple
              name: Username
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating authentication failure.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - The requester does not have sufficient privileges.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: >-
            Not Found - The user was not found or the organization status data
            is invalid.
          schema:
            type: object
            properties:
              error:
                description: Error message describing the issue.
                type: string
          examples:
            application/json:
              error: User not found or invalid status data
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - company-profile
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  
  /dashboard-running/client-overview/compare-metrics/:
    get:
      operationId: dashboard-running_client-overview_compare-metrics_list
      summary: Compare Metrics (week-by-week)
      description: >-
        Return a single composite object that places several running metrics on
        the same ISO-week timeline.


        **chart_data**

        • **x_values** - first day of each ISO-week in the interval.

        • **y_values** - dictionary keyed by metric (snake-case); each entry is
        a list
          whose items line up with **x_values** (use *null* when a week has no data).
        • **max_values** - the interval-wide maximum for every requested metric
        (handy for axis scaling).


        **weeks**

        Helper structure for tables/tool-tips: every bucket is broken out with
        its start/end dates and per-metric value(s).
      parameters:
        - name: user_ids
          in: query
          description: One or more user ids (CSV list)
          required: false
          type: array
          items:
            type: string
          collectionFormat: csv
        - name: metrics
          in: query
          description: CSV list of metrics to compare or `All`
          required: true
          type: array
          items:
            type: string
            enum:
              - All
              - Speed
              - Distance
              - Pace
              - Stride Length
              - Contact Time
              - Flight Time
              - Cadence
              - Power
              - Normalized Power
              - Contact Angle
              - Footstrike
              - Incline
              - Balance
              - Training Frequency
          collectionFormat: csv
        - name: start_date
          in: query
          description: Interval start (YYYY-MM-DD)
          required: true
          type: string
          format: date
        - name: end_date
          in: query
          description: Interval end (YYYY-MM-DD)
          required: true
          type: string
          format: date
      responses:
        '200':
          description: Metrics compared successfully.
          schema:
            type: object
          examples:
            application/json:
              chart_data:
                max_values:
                  speed: 20.676
                  training_frequency: 2
                  footstrike: 100
                y_values:
                  speed:
                    - null
                    - null
                    - null
                    - null
                    - 9.47105
                    - null
                  training_frequency:
                    - null
                    - null
                    - null
                    - null
                    - 2
                    - null
                  footstrike:
                    - null
                    - null
                    - null
                    - null
                    - forefoot: 100
                    - null
                x_values:
                  - '2025-05-25'
                  - '2025-06-01'
                  - '2025-06-08'
                  - '2025-06-15'
                  - '2025-06-22'
                  - '2025-06-29'
              weeks:
                week_5:
                  start_date: '2025-06-22'
                  end_date: '2025-06-28'
                  values:
                    speed: 9.47105
                    training_frequency: 2
                    footstrike:
                      forefoot: 100
                week_1:
                  start_date: …
                  end_date: …
                  values: {}
                week_2:
                  start_date: …
                  end_date: …
                  values: {}
                week_3:
                  start_date: …
                  end_date: …
                  values: {}
                week_4:
                  start_date: …
                  end_date: …
                  values: {}
                week_6:
                  start_date: …
                  end_date: …
                  values: {}
        '400':
          description: Bad Request - invalid parameters
          examples:
            application/json:
              error: Invalid metric list.
        '401':
          description: Unauthorized - token missing or invalid
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - admin access required
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: Not Found - user or session data missing
          examples:
            application/json:
              error: User not found.
        '500':
          description: Internal Server Error
          examples:
            application/json:
              error: Internal server error.
      tags:
        - dashboard-running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /dashboard-running/client-overview/compare-sessions-individually/:
    get:
      operationId: dashboard-running_client-overview_compare-sessions-individually_list
      summary: Compare Sessions (flat series per metric)
      description: >-
        Return a **per-session** breakdown for one or more running metrics.


        *  **chart_data** - one entry per metric:  
           • **x_values** - ISO dates (`YYYY-MM-DD`) of every requested session in chronological order.  
           • **y_values** - the same length list of *session-detail objects* — each object carries the
             metric **value** plus the session / user identifiers needed for tool-tips or tables.
        *  **weeks** - unchanged: sessions grouped into ISO-week buckets (handy
        for tables/tool-tips).

        *  **sessions** - quick lookup list of `{ session_id, session_name }`
        used to populate filters.
      parameters:
        - name: session_ids
          in: query
          description: One or more session ids (CSV list)
          required: true
          type: array
          items:
            type: string
          collectionFormat: csv
        - name: metrics
          in: query
          description: One or more metrics (CSV) or `All`
          required: true
          type: array
          items:
            type: string
            enum:
              - All
              - Speed
              - Distance
              - Pace
              - Stride Length
              - Contact Time
              - Flight Time
              - Cadence
              - Power
              - Normalized Power
              - Contact Angle
              - Footstrike
              - Incline
              - Balance
              - Training Frequency
          collectionFormat: csv
        - name: start_date
          in: query
          description: Interval start (YYYY-MM-DD)
          required: true
          type: string
          format: date
        - name: end_date
          in: query
          description: Interval end (YYYY-MM-DD)
          required: true
          type: string
          format: date
      responses:
        '200':
          description: Per-session metrics returned successfully.
          schema:
            type: object
            properties:
              chart_data:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    x_values:
                      type: array
                      items:
                        type: string
                    y_values:
                      type: array
                      items:
                        type: object
              weeks:
                type: object
                additionalProperties:
                  type: object
              sessions:
                type: array
                items:
                  type: object
                  properties:
                    session_id:
                      type: string
                    session_name:
                      type: string
          examples:
            application/json:
              chart_data:
                speed:
                  x_values:
                    - '2025-07-13'
                    - '2025-07-13'
                  y_values:
                    - value: 2.2564
                      session_name: vhmvkm
                      session_id: c5157606…
                      user_id: Xk832Dgg…
                      user_name: fbhxdfhdxf
                    - value: 2.4758
                      session_name: gym,g,gbn,
                      session_id: 48c612dc…
                      user_id: Xk832Dgg…
                      user_name: fbhxdfhdxf
                footstrike:
                  x_values:
                    - '2025-07-13'
                    - '2025-07-13'
                  y_values:
                    - value: forefoot
                      session_name: vhmvkm
                      session_id: c5157606…
                      user_id: Xk832Dgg…
                      user_name: fbhxdfhdxf
                    - value: forefoot
                      session_name: gym,g,gbn,
                      session_id: 48c612dc…
                      user_id: Xk832Dgg…
                      user_name: fbhxdfhdxf
              weeks:
                week_4:
                  start_date: '2025-07-11'
                  end_date: '2025-07-17'
                  sessions:
                    - session_id: 48c612dc…
                      session_name: gym,g,gbn,
                      created_at: '2025-07-13T19:12:24Z'
                      user_id: Xk832Dgg…
                      user_name: fbhxdfhdxf
                      values:
                        speed: 2.4758
                        training_frequency: 1
                        ...: …
                ...other weeks…: {}
              sessions:
                - session_id: c5157606…
                  session_name: vhmvkm
                - session_id: 48c612dc…
                  session_name: gym,g,gbn,
        '400':
          description: Bad Request - invalid parameters
          examples:
            application/json:
              error: Invalid metric list.
        '401':
          description: Unauthorized - token missing or invalid
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - admin access required
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: Not Found - user or session data missing
          examples:
            application/json:
              error: User not found.
        '500':
          description: Internal Server Error
          examples:
            application/json:
              error: Internal server error.
      tags:
        - dashboard-running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /dashboard-running/client-overview/compare-sessions/:
    get:
      operationId: dashboard-running_client-overview_compare-sessions_list
      summary: Compare Sessions (per-session values in weekly buckets)
      description: >-
        Return a **per-session** breakdown for one or more running metrics.


        *   The requested interval is split into ISO-weeks (listed in
        `x_values`).

        *   **chart_data** → one entry per metric.  For each week the `y_values`
        array contains the **session objects** that fall into that bucket.

        *   **weeks** mirrors the same data for easy table / tooltip rendering.
      parameters:
        - name: session_ids
          in: query
          description: One or more session ids (CSV list)
          required: true
          type: array
          items:
            type: string
          collectionFormat: csv
        - name: metrics
          in: query
          description: One or more metrics (CSV) or `All`
          required: true
          type: array
          items:
            type: string
            enum:
              - All
              - Speed
              - Distance
              - Pace
              - Stride Length
              - Contact Time
              - Flight Time
              - Cadence
              - Power
              - Normalized Power
              - Contact Angle
              - Footstrike
              - Incline
              - Balance
              - Training Frequency
          collectionFormat: csv
        - name: start_date
          in: query
          description: Interval start (YYYY-MM-DD)
          required: true
          type: string
          format: date
        - name: end_date
          in: query
          description: Interval end (YYYY-MM-DD)
          required: true
          type: string
          format: date
      responses:
        '200':
          description: Per-session metrics returned successfully.
          schema:
            type: object
          examples:
            application/json:
              chart_data:
                speed:
                  min: 2.3
                  max: 6
                  avg: 4.15
                  x_values:
                    - '2025-04-07'
                    - '2025-04-14'
                  y_values:
                    - - session_id: s1
                        session_name: Morning run
                        created_at: '2025-04-09T09:17:00Z'
                        user_id: u1
                        user_name: Alice
                        value: 4.8
                      - session_id: s2
                        session_name: Evening jog
                        created_at: '2025-04-10T18:02:00Z'
                        user_id: u2
                        user_name: Bob
                        value: 3.9
                    - []
                footstrike:
                  x_values:
                    - '2025-04-07'
                    - '2025-04-14'
                  y_values:
                    - - session_id: s1
                        session_name: Morning run
                        created_at: '2025-04-09T09:17:00Z'
                        user_id: u1
                        user_name: Alice
                        value: forefoot
                    - []
              weeks:
                week_1:
                  start_date: '2025-04-07'
                  end_date: '2025-04-13'
                  sessions:
                    - session_id: s1
                      session_name: Morning run
                      created_at: '2025-04-09T09:17:00Z'
                      user_id: u1
                      user_name: Alice
                      values:
                        speed: 4.8
                        footstrike: forefoot
                        training_frequency: 1
                    - session_id: s2
                      session_name: Evening jog
                      created_at: '2025-04-10T18:02:00Z'
                      user_id: u2
                      user_name: Bob
                      values:
                        speed: 3.9
                        training_frequency: 1
                week_2:
                  start_date: '2025-04-14'
                  end_date: '2025-04-20'
                  sessions: []
        '400':
          description: Bad Request - invalid parameters
          examples:
            application/json:
              error: Invalid metric list.
        '401':
          description: Unauthorized - token missing or invalid
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - admin access required
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: Not Found - user or session data missing
          examples:
            application/json:
              error: User not found.
        '500':
          description: Internal Server Error
          examples:
            application/json:
              error: Internal server error.
      tags:
        - dashboard-running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /dashboard-running/client-overview/compare-users/:
    get:
      operationId: dashboard-running_client-overview_compare-users_list
      summary: Compare Users (interval-wide totals)
      description: >-
        Compare selected running metrics **per user** across the requested date
        range.  

        The interval is split into calendar-week buckets.  


        * **chart_data** - for every metric, supplies the overall *min / max /
        avg* and a **y_values** matrix *(user x week)* aligned to **x_values**
        (ISO week start dates).  

        * **weeks** - lists, for every bucket, the users that contributed
        sessions and the underlying session details.  

        * **users** - an ordered roster mapping user IDs to display names.  


        *   For numeric metrics each cell in *y_values* is the user's weekly
        average.  

        *   **Training Frequency** cells are raw counts.  

        *   **Footstrike** cells are percentage breakdowns of strike patterns
        for that user & week.
      parameters:
        - name: user_ids
          in: query
          description: One or more user ids (CSV list)
          required: false
          type: array
          items:
            type: string
          collectionFormat: csv
        - name: metrics
          in: query
          description: CSV list of metrics to compare or `All`
          required: true
          type: array
          items:
            type: string
            enum:
              - All
              - Speed
              - Distance
              - Pace
              - Stride Length
              - Contact Time
              - Flight Time
              - Cadence
              - Power
              - Normalized Power
              - Contact Angle
              - Footstrike
              - Incline
              - Balance
              - Training Frequency
          collectionFormat: csv
        - name: start_date
          in: query
          description: Interval start (YYYY-MM-DD)
          required: true
          type: string
          format: date
        - name: end_date
          in: query
          description: Interval end (YYYY-MM-DD)
          required: true
          type: string
          format: date
      responses:
        '200':
          description: Per-user weekly metric values returned successfully.
          schema:
            type: object
            properties:
              chart_data:
                type: object
              weeks:
                type: object
              users:
                type: array
                items:
                  type: object
          examples:
            application/json:
              chart_data:
                speed:
                  min: 2.2564
                  max: 16.6857
                  avg: 9.47105
                  x_values:
                    - '2025-05-30'
                    - '2025-06-06'
                    - '2025-06-13'
                    - '2025-06-20'
                    - '2025-06-27'
                  y_values:
                    - - null
                      - null
                      - null
                      - 16.6857
                      - null
                    - - null
                      - null
                      - null
                      - 2.2564
                      - null
                training_frequency:
                  min: 1
                  max: 1
                  avg: 1
                  x_values:
                    - '2025-05-30'
                    - '2025-06-06'
                    - '2025-06-13'
                    - '2025-06-20'
                    - '2025-06-27'
                  y_values:
                    - - null
                      - null
                      - null
                      - 1
                      - null
                    - - null
                      - null
                      - null
                      - 1
                      - null
                footstrike:
                  x_values:
                    - '2025-05-30'
                    - '2025-06-06'
                    - '2025-06-13'
                    - '2025-06-20'
                    - '2025-06-27'
                  y_values:
                    - - null
                      - null
                      - null
                      - forefoot: 100
                      - null
                    - - null
                      - null
                      - null
                      - forefoot: 100
                      - null
              weeks:
                week_4:
                  start_date: '2025-06-20'
                  end_date: '2025-06-26'
                  users:
                    - user_id: UID_A
                      user_name: User-A
                      sessions:
                        - session_id: sess-1
                          session_name: Morning run
                          created_at: '2025-06-26T11:30:39.334Z'
                          values:
                            training_frequency: 1
                            footstrike: forefoot
                            speed: 16.6857
              users:
                - user_id: UID_A
                  user_name: User-A
                - user_id: UID_B
                  user_name: User-B
        '400':
          description: Bad Request - invalid parameters
          examples:
            application/json:
              error: Unknown metric Speedy.
        '401':
          description: Unauthorized - token missing or invalid
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - admin access required
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: Not Found - user or data missing
          examples:
            application/json:
              error: User not found.
        '500':
          description: Internal Server Error
          examples:
            application/json:
              error: Internal server error.
      tags:
        - dashboard-running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /dashboard-running/client-overview/metric-extended/:
    get:
      operationId: dashboard-running_client-overview_metric-extended_list
      summary: Retrieve Extended Metric Data (weekly buckets)
      description: >-
        Return a detailed, week-by-week breakdown for **one** running metric.


        *   The interval is split into ISO-weeks (see `x_values`).

        *   **chart_data** contains the global min / max / avg and an array of
        bucket averages in `y_values`.

        *   **weeks** enumerates the sessions that form each bucket and exposes
        their raw metric values.


        Special cases:

        • **Training Frequency** - raw weekly counts.

        • **Foot-strike** - weekly percentage splits (categorical).

        • All other metrics - numeric *min / avg / max* per session.
      parameters:
        - name: user_ids
          in: query
          description: One or more user ids (CSV list)
          required: false
          type: array
          items:
            type: string
          collectionFormat: csv
        - name: metric
          in: query
          description: The metric to drill into
          required: true
          type: string
          enum:
            - Speed
            - Distance
            - Pace
            - Stride Length
            - Contact Time
            - Flight Time
            - Cadence
            - Power
            - Normalized Power
            - Contact Angle
            - Footstrike
            - Incline
            - Balance
            - Training Frequency
        - name: start_date
          in: query
          description: Interval start (YYYY-MM-DD)
          required: true
          type: string
          format: date
        - name: end_date
          in: query
          description: Interval end (YYYY-MM-DD)
          required: true
          type: string
          format: date
      responses:
        '200':
          description: Extended metric data returned successfully.
          schema:
            type: object
          examples:
            application/json:
              chart_data:
                speed:
                  min: 2.072
                  max: 20.676
                  avg: 9.47105
                  y_values:
                    - null
                    - null
                    - null
                    - 9.47105
                    - null
                  x_values:
                    - '2025-05-30'
                    - '2025-06-06'
                    - '2025-06-13'
                    - '2025-06-20'
                    - '2025-06-27'
              weeks:
                week_1:
                  start_date: '2025-05-30'
                  end_date: '2025-06-05'
                  sessions: []
                week_2:
                  start_date: '2025-06-06'
                  end_date: '2025-06-12'
                  sessions: []
                week_3:
                  start_date: '2025-06-13'
                  end_date: '2025-06-19'
                  sessions: []
                week_4:
                  start_date: '2025-06-20'
                  end_date: '2025-06-26'
                  sessions:
                    - session_id: a24b6a6fe370491eb19d0e13cb741ae8
                      session_name: Track Intervals
                      created_at: '2025-06-26T11:30:39Z'
                      user_id: WND2pCENAEsOyUNLuY0x
                      user_name: UserT
                      values:
                        min: 15.32
                        avg: 16.6857
                        max: 20.676
                    - session_id: 295e6a4e08144908a09d672d1073766c
                      session_name: Recovery Jog
                      created_at: '2025-06-26T11:30:54Z'
                      user_id: Xk832DggPOyAs1BhVC0d
                      user_name: UserB
                      values:
                        min: 2.072
                        avg: 2.2564
                        max: 2.796
                week_5:
                  start_date: '2025-06-27'
                  end_date: '2025-07-03'
                  sessions: []
        '400':
          description: Bad Request - invalid parameters.
          schema:
            type: object
            properties:
              error:
                description: Details of the invalid request.
                type: string
          examples:
            application/json:
              error: Unknown metric 'Foo'.
        '401':
          description: Unauthorized - token missing or invalid.
          schema:
            type: object
            properties:
              error:
                description: Auth error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - admin access required.
          schema:
            type: object
            properties:
              error:
                description: Admin privileges required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: Not Found - user or session missing / invalid plan.
          schema:
            type: object
            properties:
              error:
                description: Resource not found.
                type: string
          examples:
            application/json:
              error: Session not found.
        '500':
          description: Internal Server Error.
          schema:
            type: object
            properties:
              error:
                description: Server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - dashboard-running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /dashboard-running/client-overview/overview:
    get:
      operationId: dashboard-running_client-overview_overview_list
      summary: Retrieve Dashboard Metrics (weekly buckets)
      description: |-
        Return aggregated running metrics for dashboard charts.  
        The requested interval is split into **calendar-week buckets**.  

        The response has two top-level blocks:  
        * **chart_data** - global stats and weekly values for every metric.  
        * **weeks**- per-week session lists (and their metric values).  

        * **Training Frequency** is a simple count per week.  
        * **Footstrike** is a percentage breakdown for the whole interval.
      parameters:
        - name: user_ids
          in: query
          description: One or more user ids (CSV list)
          required: false
          type: array
          items:
            type: string
          collectionFormat: csv
        - name: metrics
          in: query
          description: One or more metrics (CSV) or `All`
          required: true
          type: array
          items:
            type: string
            enum:
              - All
              - Speed
              - Distance
              - Pace
              - Stride Length
              - Contact Time
              - Flight Time
              - Cadence
              - Power
              - Normalized Power
              - Contact Angle
              - Footstrike
              - Incline
              - Balance
              - Training Frequency
          collectionFormat: csv
        - name: start_date
          in: query
          description: Interval start (YYYY-MM-DD)
          required: true
          type: string
          format: date
        - name: end_date
          in: query
          description: Interval end (YYYY-MM-DD)
          required: true
          type: string
          format: date
      responses:
        '200':
          description: Aggregated metrics returned successfully.
          schema:
            type: object
            properties:
              chart_data:
                type: object
                additionalProperties:
                  type: object
              weeks:
                type: object
                additionalProperties:
                  type: object
          examples:
            application/json:
              chart_data:
                speed:
                  min: 2.072
                  max: 20.676
                  avg: 9.47105
                  y_values:
                    - null
                    - null
                    - null
                    - 9.47105
                    - null
                  x_values:
                    - '2025-05-30'
                    - '2025-06-06'
                    - '2025-06-13'
                    - '2025-06-20'
                    - '2025-06-27'
                footstrike:
                  start_date: '2025-05-30'
                  end_date: '2025-06-28'
                  values:
                    forefoot: 100
                training_frequency:
                  min: 2
                  max: 2
                  avg: 2
                  y_values:
                    - null
                    - null
                    - null
                    - 2
                    - null
                  x_values:
                    - '2025-05-30'
                    - '2025-06-06'
                    - '2025-06-13'
                    - '2025-06-20'
                    - '2025-06-27'
                ...other metrics…: {}
              weeks:
                week_1:
                  start_date: '2025-05-30'
                  end_date: '2025-06-05'
                  sessions: []
                week_4:
                  start_date: '2025-06-20'
                  end_date: '2025-06-26'
                  sessions:
                    - session_id: a24b6a6fe370491eb19d0e13cb741ae8
                      session_name: dfghdghdfg
                      created_at: '2025-06-26T11:30:39.334Z'
                      user_id: WND2pCENAEsOyUNLuY0x
                      user_name: UserT
                      values:
                        speed:
                          min: 15.32
                          avg: 16.6857
                          max: 20.676
                        distance: 499.73800000000006
                        footstrike: forefoot
                        training_frequency: 1
                ...other weeks…: {}
        '400':
          description: Bad Request - invalid parameters.
          schema:
            type: object
            properties:
              error:
                description: Details of the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid metric list.
        '401':
          description: Unauthorized - token missing or invalid.
          schema:
            type: object
            properties:
              error:
                description: Auth error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - admin access required.
          schema:
            type: object
            properties:
              error:
                description: Admin privileges required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: Not Found - user or session missing / invalid plan.
          schema:
            type: object
            properties:
              error:
                description: Resource not found.
                type: string
          examples:
            application/json:
              error: Session not found.
        '500':
          description: Internal Server Error.
          schema:
            type: object
            properties:
              error:
                description: Server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - dashboard-running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  
  /helper/html-files/:
    get:
      operationId: helper_html-files_list
      summary: Retrieve HTML File
      description: >-
        Retrieves an HTML file stored in Firebase using an encrypted token
        passed as a query parameter. 


        ### Query Parameter

        - **token** *(string, required)*: Encrypted token representing the user,
        session, and file name. This token is used to locate and decrypt the
        corresponding HTML file.


        ### Response (HTTP 200)


        On success, returns the content of the HTML file with a `Content-Type`
        of `text/html`.


        ```html

        <html><body><h1>Example HTML</h1></body></html>

        ```


        ### Error Handling


        - **400 Bad Request**: Returned if the `token` query parameter is
        missing or empty.

        - **404 Not Found**: Returned if the HTML file cannot be retrieved
        (e.g., invalid token or file not found).

        - **500 Internal Server Error**: Returned if an unexpected error occurs
        on the server.


        ### Security


        No authentication is required for this endpoint.
      parameters:
        - name: token
          in: query
          description: Encrypted token used to retrieve the HTML file.
          required: true
          type: string
      responses:
        '200':
          description: HTML file retrieved successfully.
          schema:
            description: The HTML file content.
            type: string
            example: <html><body><h1>Example HTML</h1></body></html>
        '400':
          description: >-
            Bad Request - Returned if the `token` parameter is missing or empty.
            Ensure that the token is provided in the query string.
          schema:
            type: object
            properties:
              error:
                description: Error message explaining that the token is required.
                type: string
          examples:
            application/json:
              error: Token is required
        '404':
          description: >-
            Not Found - Returned if the HTML file cannot be retrieved. This may
            be due to an invalid token or if the file does not exist.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the HTML file could not be
                  found.
                type: string
          examples:
            application/json:
              error: 'Error retrieving file: <error>'
        '500':
          description: >-
            Internal Server Error - Returned if an unexpected error occurred on
            the server. Check the error details for further information.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      consumes:
        - multipart/form-data
        - application/x-www-form-urlencoded
      tags:
        - helper
      security: []
    post:
      operationId: helper_html-files_create
      summary: Upload HTML File
      description: >-
        Uploads an HTML file to Firebase for a specific session. The file must
        be provided as form-data with a key `html_file` and have a content type
        of 'text/html'. Additionally, the `session_id` must be included in the
        form-data to associate the file with a session.


        ### Form Data

        - **html_file** *(file, required)*: The HTML file to be uploaded. Only
        files with content type 'text/html' are accepted.

        - **session_id** *(string, required)*: The session ID associated with
        the uploaded HTML file.


        ### Response (HTTP 201)

        On success, returns a JSON object containing:

        - **message** *(string)*: A confirmation message indicating that the
        file was uploaded successfully.

        - **token** *(string)*: An encrypted token representing the file and
        session information.


        ### Error Handling


        - **400 Bad Request**: Returned if required fields are missing (e.g. no
        file or session ID provided), if the file type is not 'text/html', or if
        the admin UID is invalid.

        - **404 Not Found**: Returned if the session ID does not exist in
        Firestore. This indicates that the session ID provided does not match
        any existing session in the database.

        - **422 Unprocessable Entity**: Returned if the HTML file processing
        (e.g., encryption) fails.

        - **500 Internal Server Error**: Returned if an unexpected error occurs
        on the server.


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: html_file
          in: formData
          description: The HTML file to upload. Must have the content type 'text/html'.
          required: true
          type: file
        - name: session_id
          in: formData
          description: The session ID to associate with the uploaded HTML file.
          required: true
          type: string
      responses:
        '201':
          description: File uploaded successfully.
          schema:
            type: object
            properties:
              message:
                description: A confirmation message.
                type: string
              token:
                description: Encrypted token representing the file and session information.
                type: string
          examples:
            application/json:
              message: File uploaded successfully
              token: gAAAAABhX9s8...
        '400':
          description: >-
            Bad Request - Returned if required fields are missing (e.g., no file
            provided, session ID missing), if the file type is invalid (only
            HTML files are allowed), or if the admin UID is invalid.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message explaining the invalid request.
                type: string
          examples:
            application/json:
              error: No file provided
        '404':
          description: Not Found - Returned if the session ID does not exist in Firestore.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the session ID was not found.
                type: string
          examples:
            application/json:
              error: Session not found in Firestore.
        '422':
          description: >-
            Unprocessable Entity - Returned if the HTML file processing (e.g.,
            encryption) fails.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message describing the processing failure.
                type: string
          examples:
            application/json:
              error: Encryption failed
        '500':
          description: >-
            Internal Server Error - Returned if an unexpected error occurs on
            the server.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      consumes:
        - multipart/form-data
        - application/x-www-form-urlencoded
      tags:
        - helper
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /helper/sessions/{session_id}/report-comments/:
    get:
      operationId: helper_sessions_report-comments_list
      summary: Retrieve Session Comments
      description: >-
        Retrieves the report comments for a specific session. 


        ### Path Parameter

        - **session_id** *(string, required)*: The unique identifier of the
        session for which comments are requested.


        ### Response Structure (HTTP 200)


        On success, the response is a JSON object containing language-specific
        comments. For example:


        - **text_summary** *(object)*: Contains summary comments in different
        languages.
            - **en** *(string)*: Summary in English.
            - **ru** *(string)*: Summary in Russian.
        - **text_contact_angle** *(object)*: Contact angle comments.

        - **text_push_angle** *(object)*: Push angle comments.

        - **text_knee_ankle** *(object)*: Knee-ankle comments.

        - **text_hip_angle** *(object)*: Hip angle comments.

        - **text_left_ankle_angle** *(object)*: Left ankle angle comments.

        - **text_left_knee_angle** *(object)*: Left knee angle comments.

        - **text_right_ankle_angle** *(object)*: Right ankle angle comments.

        - **text_right_knee_angle** *(object)*: Right knee angle comments.


        ### Error Handling


        - **400 Bad Request**: Invalid request parameters.

        - **401 Unauthorized**: Missing or invalid access token.

        - **403 Forbidden**: Insufficient privileges (admin access required).

        - **404 Not Found**: Comments not found for the given session.

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


        ### Security


        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: session_id
          in: path
          description: The unique session identifier.
          required: true
          type: string
      responses:
        '200':
          description: Session comments retrieved successfully.
          schema:
            type: object
            properties:
              text_summary:
                description: Summary comments in multiple languages.
                type: object
                properties:
                  en:
                    description: Summary in English.
                    type: string
                  ru:
                    description: Summary in Russian.
                    type: string
              text_contact_angle:
                description: Contact angle comments.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_push_angle:
                description: Push angle comments.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_knee_ankle:
                description: Knee ankle comments.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_hip_angle:
                description: Hip angle comments.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_left_ankle_angle:
                description: Left ankle angle comments.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_left_knee_angle:
                description: Left knee angle comments.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_right_ankle_angle:
                description: Right ankle angle comments.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_right_knee_angle:
                description: Right knee angle comments.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
          examples:
            application/json:
              text_summary:
                en: Summary text in English
                ru: Summary text in Russian
              text_contact_angle:
                en: Contact angle text in English
                ru: Contact angle text in Russian
              text_push_angle:
                en: Push angle text in English
                ru: Push angle text in Russian
              text_knee_ankle:
                en: Knee ankle text in English
                ru: Knee ankle text in Russian
              text_hip_angle:
                en: Hip angle text in English
                ru: Hip angle text in Russian
              text_left_ankle_angle:
                en: Left ankle angle text in English
                ru: Left ankle angle text in Russian
              text_left_knee_angle:
                en: Left knee angle text in English
                ru: Left knee angle text in Russian
              text_right_ankle_angle:
                en: Right ankle angle text in English
                ru: Right ankle angle text in Russian
              text_right_knee_angle:
                en: Right knee angle text in English
                ru: Right knee angle text in Russian
        '400':
          description: Bad Request - Error getting comments due to invalid parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message.
                type: string
          examples:
            application/json:
              error: Error getting comments
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: User does not have admin privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - Comments not found for the given session.
          schema:
            type: object
            properties:
              error:
                description: Comments not found.
                type: string
          examples:
            application/json:
              error: Comments not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred.
      tags:
        - helper
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: helper_sessions_report-comments_create
      summary: Update Session Comments
      description: >-
        Updates the report comments for a specific session. The request body
        must include the comment fields for various aspects of the session
        (e.g., summary, contact angle, push angle, etc.) in multiple languages. 


        ### Request Body (JSON)


        The following fields are expected (all fields are objects with language
        keys):


        - **text_summary** *(object)*: Summary comments (e.g., `{'en': 'English
        text', 'ru': 'Russian text'}`).

        - **text_contact_angle** *(object)*: Contact angle comments.

        - **text_push_angle** *(object)*: Push angle comments.

        - **text_knee_ankle** *(object)*: Knee ankle comments.

        - **text_hip_angle** *(object)*: Hip angle comments.

        - **text_left_ankle_angle** *(object)*: Left ankle angle comments.

        - **text_left_knee_angle** *(object)*: Left knee angle comments.

        - **text_right_ankle_angle** *(object)*: Right ankle angle comments.

        - **text_right_knee_angle** *(object)*: Right knee angle comments.


        ### Response Structure (HTTP 200)


        On success, the response is a JSON object with:

        - **message** *(string)*: A confirmation message indicating that
        comments were updated.


        ### Error Handling


        - **400 Bad Request**: If the input data is missing or invalid.

        - **401 Unauthorized**: If the access token is missing or invalid.

        - **403 Forbidden**: If the user does not have admin privileges.

        - **500 Internal Server Error**: If an unexpected error occurs on the
        server.


        ### Security


        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            type: object
            properties:
              text_summary:
                description: Summary comments in different languages.
                type: object
                properties:
                  en:
                    description: English summary text.
                    type: string
                  ru:
                    description: Russian summary text.
                    type: string
              text_contact_angle:
                description: Contact angle comments in different languages.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_push_angle:
                description: Push angle comments in different languages.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_knee_ankle:
                description: Knee ankle comments in different languages.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_hip_angle:
                description: Hip angle comments in different languages.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_left_ankle_angle:
                description: Left ankle angle comments in different languages.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_left_knee_angle:
                description: Left knee angle comments in different languages.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_right_ankle_angle:
                description: Right ankle angle comments in different languages.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
              text_right_knee_angle:
                description: Right knee angle comments in different languages.
                type: object
                properties:
                  en:
                    description: English text.
                    type: string
                  ru:
                    description: Russian text.
                    type: string
            example:
              text_summary:
                en: Summary text in English
                ru: Summary text in Russian
              text_contact_angle:
                en: Contact angle text in English
                ru: Contact angle text in Russian
              text_push_angle:
                en: Push angle text in English
                ru: Push angle text in Russian
              text_knee_ankle:
                en: Knee ankle text in English
                ru: Knee ankle text in Russian
              text_hip_angle:
                en: Hip angle text in English
                ru: Hip angle text in Russian
              text_left_ankle_angle:
                en: Left ankle angle text in English
                ru: Left ankle angle text in Russian
              text_left_knee_angle:
                en: Left knee angle text in English
                ru: Left knee angle text in Russian
              text_right_ankle_angle:
                en: Right ankle angle text in English
                ru: Right ankle angle text in Russian
              text_right_knee_angle:
                en: Right knee angle text in English
                ru: Right knee angle text in Russian
      responses:
        '200':
          description: Comments updated successfully.
          schema:
            required:
              - message
            type: object
            properties:
              message:
                description: A confirmation message indicating the comments were updated.
                type: string
          examples:
            application/json:
              message: Comments updated
        '400':
          description: >-
            Bad Request - Error updating comments due to missing or invalid
            data.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message.
                type: string
          examples:
            application/json:
              error: Error updating comments
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin privileges are required.
          schema:
            type: object
            properties:
              error:
                description: User does not have admin access.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - helper
      security:
        - Bearer: []
        - ApiKeyAuth: []
    delete:
      operationId: helper_sessions_report-comments_delete
      summary: Delete Report Comments
      description: >-
        Deletes all report comments for a given session. 


        ### Request


        - **Path Parameter**:
            - **session_id** *(string, required)*: The unique identifier of the session whose report comments will be deleted.

        ### Response Structure (HTTP 200)


        On success, the response is a JSON object with:

        - **message** *(string)*: A success message indicating that the comments
        have been deleted.


        ### Error Handling


        - **400 Bad Request**: Indicates that the request parameters are invalid
        or that an error occurred during deletion.

        - **401 Unauthorized**: The access token is missing or invalid.

        - **403 Forbidden**: The user does not have admin privileges to delete
        report comments.

        - **404 Not Found**: The session or report comments were not found.

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


        ### Security


        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: session_id
          in: path
          description: >-
            The unique identifier of the session for which report comments will
            be deleted.
          required: true
          type: string
      responses:
        '200':
          description: Comments deleted successfully.
          schema:
            required:
              - message
            type: object
            properties:
              message:
                description: >-
                  A message indicating that the comments were deleted
                  successfully.
                type: string
          examples:
            application/json:
              message: Comments deleted
        '400':
          description: Bad Request - Error deleting comments (e.g., invalid parameters).
          schema:
            type: object
            properties:
              error:
                description: A detailed error message explaining why deletion failed.
                type: string
          examples:
            application/json:
              error: Error deleting comments
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: >-
                  An error message indicating that the token is missing or
                  invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have admin privileges to delete report
            comments.
          schema:
            type: object
            properties:
              error:
                description: An error message indicating that admin access is required.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - The session or report comments were not found.
          schema:
            type: object
            properties:
              error:
                description: >-
                  An error message indicating that the session or comments were
                  not found.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - helper
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  
  /jumping/sessions/:
    post:
      operationId: jumping_sessions_create
      summary: Create a New Video Processing Session
      description: >
        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):


        ```bash

        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):


        ```bash

        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/
        ```
      parameters:
        - name: user_id
          in: formData
          description: >-
            **Required.** The ID of the user for whom this session is created
            (form field: text).
          required: true
          type: string
        - name: video
          in: formData
          description: >-
            **Required.** The raw video file to be processed (form field type:
            file).
          required: true
          type: file
        - name: session_name
          in: formData
          description: '**Optional.** A descriptive name for the session (form field: text).'
          required: false
          type: string
        - name: exercise
          in: formData
          description: >-
            **Required.** The name of the exercise. Choose one of the following:
            'Countermovement Jump' or 'Drop Jump'.
          required: true
          type: string
          enum:
            - Countermovement Jump
            - Drop Jump
        - name: body_joint_angles
          in: formData
          description: >-
            **Optional.** A comma-separated list of joint names. Available
            values: `'ankle'`, `'knee'`, `'elbow'`, `'hip'`, `'shoulder'`.
            Example: `ankle,knee,hip`
          required: false
          type: array
          items:
            type: string
            enum:
              - ankle
              - knee
              - elbow
              - hip
              - shoulder
          collectionFormat: csv
      responses:
        '200':
          description: Video processing session created successfully (HTTP 200).
          schema:
            required:
              - session_id
              - title
            type: object
            properties:
              session_id:
                description: The unique identifier for the created session.
                type: string
              title:
                description: The session title (defaults if not provided).
                type: string
          examples:
            application/json:
              session_id: abcd1234efgh5678
              title: Custom Session
        '400':
          description: >-
            Bad Request - Possibly due to missing `user_id`, missing `video`, or
            invalid form data.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: user_id is required
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating a missing or invalid token.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have admin permission to create
            sessions for others.
          schema:
            type: object
            properties:
              error:
                description: Error indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: >-
            Not Found - Indicates business logic issues or resource limitations
            (e.g., session limit).
          schema:
            type: object
            properties:
              error:
                description: Error message describing the issue.
                type: string
          examples:
            application/json:
              error: User has reached the maximum number of sessions.
        '500':
          description: Internal Server Error - Unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      consumes:
        - multipart/form-data
        - application/x-www-form-urlencoded
      tags:
        - jumping
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /jumping/sessions/{session_id}/:
    get:
      operationId: jumping_sessions_read
      summary: Get Jumping Session Data
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the session.
          required: true
          type: string
        - name: demo
          in: query
          description: Set to `true` to retrieve the demo session instead of the real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved session data.
          schema:
            required:
              - angles
              - whole_report_metrics
              - all_timestamps
              - analyzed_video_url
              - video_url
              - created_at
              - user_name
              - exercise
              - activity
              - title
              - end_frames
              - all_end_frames
              - metrics
              - all_metrics
            type: object
            properties:
              angles:
                required:
                  - hip_intersection_angle
                  - ank_angle
                  - rkne_angle
                  - lkne_angle
                  - kne_angle
                  - rank_angle
                  - lank_angle
                type: object
                properties:
                  hip_intersection_angle:
                    description: Array of hip intersection angles.
                    type: array
                    items:
                      type: number
                  ank_angle:
                    description: Array of ankle angles.
                    type: array
                    items:
                      type: number
                  rkne_angle:
                    description: Array of right knee angles.
                    type: array
                    items:
                      type: number
                  lkne_angle:
                    description: Array of left knee angles.
                    type: array
                    items:
                      type: number
                  kne_angle:
                    description: Array of knee angles.
                    type: array
                    items:
                      type: number
                  rank_angle:
                    description: Array of right ankle angles.
                    type: array
                    items:
                      type: number
                  lank_angle:
                    description: Array of left ankle angles.
                    type: array
                    items:
                      type: number
              whole_report_metrics:
                required:
                  - hipy
                  - grf
                  - vhipy
                  - toey
                  - ahipy
                  - vtoey
                type: object
                properties:
                  hipy:
                    description: Array of hip height values.
                    type: array
                    items:
                      type: number
                  grf:
                    description: Array of ground reaction forces.
                    type: array
                    items:
                      type: number
                  vhipy:
                    description: Array of hip speed values.
                    type: array
                    items:
                      type: number
                  toey:
                    description: Array of toe Y-axis positions.
                    type: array
                    items:
                      type: number
                  ahipy:
                    description: Array of average hip Y-axis positions.
                    type: array
                    items:
                      type: number
                  vtoey:
                    description: Array of vertical toe velocities.
                    type: array
                    items:
                      type: number
              all_timestamps:
                description: Array of timestamps for each frame.
                type: array
                items:
                  type: number
              analyzed_video_url:
                description: URL of the analyzed video.
                type: string
                format: uri
              video_url:
                description: URL of the original video.
                type: string
                format: uri
              created_at:
                description: Object containing the date and time of session creation.
                required:
                  - date
                  - time
                type: object
                properties:
                  date:
                    description: Date when the session was created, in 'YYYY-MM-DD' format.
                    type: string
                    format: date
                  time:
                    description: >-
                      Time when the session was created, in 'HH:MM AM/PM'
                      format.
                    type: string
                    format: time
              exercise:
                description: Type of exercise being analyzed in the session.
                type: string
              user_name:
                description: Name of the user associated with the session.
                type: string
              activity:
                description: Type of activity being analyzed in the session.
                type: string
              title:
                description: Title of the session.
                type: string
              end_frames:
                description: Array of frame numbers where each segment ends.
                type: array
                items:
                  type: integer
              all_end_frames:
                description: Array of all frame numbers where segments end.
                type: array
                items:
                  type: integer
              metrics:
                description: Object containing various performance metrics.
                type: object
                additionalProperties:
                  description: Array of numeric values for each metric.
                  type: array
                  items:
                    type: number
              all_metrics:
                description: Object containing all performance metrics.
                type: object
                additionalProperties:
                  description: Array of numeric values for each metric.
                  type: array
                  items:
                    type: number
        '400':
          description: Bad Request - Invalid `session_id` provided.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid session ID
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Unauthorized access
        '403':
          description: Forbidden - User lacks necessary permissions.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this page.
        '404':
          description: Not Found - No session data found for the provided `session_id`.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Session data not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred
      tags:
        - jumping
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /jumping/sessions/{session_id}/export/:
    get:
      operationId: jumping_sessions_export_list
      summary: Export Jumping Session Data
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the session.
          required: true
          type: string
        - name: demo
          in: query
          description: Set to `true` to retrieve the demo session instead of the real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved session data.
          schema:
            required:
              - keypoints
              - angles
              - all_timestamps
              - analyzed_video_url
              - video_url
              - created_at
              - user_name
              - activity
              - title
              - end_frames
              - metrics
            type: object
            properties:
              keypoints:
                required:
                  - lknev
                  - ltoev
                  - relbv
                  - rtoey
                  - headv
                  - rearv
                  - rshox
                  - etc
                type: object
                properties:
                  lknev:
                    description: Array of left knee landmark points.
                    type: array
                    items:
                      type: number
                  ltoev:
                    description: Array of left toe landmark points.
                    type: array
                    items:
                      type: number
                  relbv:
                    description: Array of right elbow landmark points.
                    type: array
                    items:
                      type: number
                  rtoey:
                    description: Array of right toe landmark points.
                    type: array
                    items:
                      type: number
                  headv:
                    description: Array of head landmark points.
                    type: array
                    items:
                      type: number
                  rearv:
                    description: Array of right ear landmark points.
                    type: array
                    items:
                      type: number
                  rshox:
                    description: Array of right shoulder landmark points.
                    type: array
                    items:
                      type: number
                  etc:
                    description: All other landmark points.
                    type: array
                    items:
                      type: number
              angles:
                required:
                  - hip_intersection_angle
                  - ank_angle
                  - rkne_angle
                  - lkne_angle
                  - kne_angle
                  - rank_angle
                  - lank_angle
                type: object
                properties:
                  hip_intersection_angle:
                    description: Array of hip intersection angles.
                    type: array
                    items:
                      type: number
                  ank_angle:
                    description: Array of ankle angles.
                    type: array
                    items:
                      type: number
                  rkne_angle:
                    description: Array of right knee angles.
                    type: array
                    items:
                      type: number
                  lkne_angle:
                    description: Array of left knee angles.
                    type: array
                    items:
                      type: number
                  kne_angle:
                    description: Array of knee angles.
                    type: array
                    items:
                      type: number
                  rank_angle:
                    description: Array of right ankle angles.
                    type: array
                    items:
                      type: number
                  lank_angle:
                    description: Array of left ankle angles.
                    type: array
                    items:
                      type: number
              all_timestamps:
                description: Array of timestamps for each frame.
                type: array
                items:
                  type: number
              analyzed_video_url:
                description: URL of the analyzed video.
                type: string
                format: uri
              video_url:
                description: URL of the original video.
                type: string
                format: uri
              created_at:
                description: Object containing the date and time of session creation.
                required:
                  - date
                  - time
                type: object
                properties:
                  date:
                    description: Date when the session was created, in 'YYYY-MM-DD' format.
                    type: string
                    format: date
                  time:
                    description: >-
                      Time when the session was created, in 'HH:MM AM/PM'
                      format.
                    type: string
                    format: time
              user_name:
                description: Name of the user associated with the session.
                type: string
              activity:
                description: Type of activity being analyzed in the session.
                type: string
              title:
                description: Title of the session.
                type: string
              end_frames:
                description: Array of frame numbers where each segment ends.
                type: array
                items:
                  type: integer
              metrics:
                description: Object containing various performance metrics.
                type: object
                additionalProperties:
                  description: Array of numeric values for each metric.
                  type: array
                  items:
                    type: number
        '400':
          description: Bad Request - Invalid `session_id` provided.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid session ID
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Unauthorized access
        '403':
          description: Forbidden - User lacks necessary permissions.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this page.
        '404':
          description: Not Found - No session data found for the provided `session_id`.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Session data not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred
      tags:
        - jumping
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /jumping/sessions/{session_id}/jump-analysis/:
    post:
      operationId: jumping_sessions_jump-analysis_create
      summary: Get Jump Analysis Report
      description: >-
        ### 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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the session.
          required: true
          type: string
        - name: demo
          in: query
          description: Set to `true` to retrieve the demo report.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved jump analysis report.
          schema:
            required:
              - exercise
              - graph_data
              - min_frame
              - max_frame
              - phase_data
              - user_information
              - session_date
              - comments
            type: object
            properties:
              exercise:
                description: Which exercise this report is for.
                type: string
                enum:
                  - Countermovement Jump
                  - Drop Jump
              graph_data:
                description: Metric time-series for each jump.
                type: object
                properties:
                  hip_height:
                    description: Hip vertical displacement over time.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  hip_speed:
                    description: Hip vertical velocity over time.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  hip_trajectory:
                    description: Hip trajectory across multiple drop jumps.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  hip_velocity:
                    description: Hip velocity across multiple drop jumps.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  toe_trajectory:
                    description: Toe trajectory across multiple drop jumps.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  grf:
                    description: Ground Reaction Force data.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  power:
                    description: Power output data.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  kne_angle:
                    description: Knee angle over time.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  ank_angle:
                    description: Ankle angle over time.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                  hip_angle:
                    description: Hip angle over time.
                    type: object
                    additionalProperties:
                      required:
                        - times
                        - data
                      type: object
                      properties:
                        times:
                          description: Timestamps for data points.
                          type: array
                          items:
                            type: number
                        data:
                          description: Metric values at those times.
                          type: array
                          items:
                            type: number
                additionalProperties: false
              min_frame:
                description: Minimum frame number in the video.
                type: integer
              max_frame:
                description: Maximum frame number in the video.
                type: integer
              phase_data:
                description: Detailed information about each jump phase.
                required:
                  - start_of_preparation
                  - braking
                  - zero_velocity
                  - takeoff
                  - peak
                  - landing
                  - damping
                  - recuperation
                type: object
                properties:
                  start_of_preparation:
                    required:
                      - video_frame
                      - graph_phase
                      - image_url
                    type: object
                    properties:
                      video_frame:
                        type: integer
                      graph_phase:
                        type: integer
                      image_url:
                        type: string
                        format: uri
                  braking:
                    required:
                      - video_frame
                      - graph_phase
                      - image_url
                    type: object
                    properties:
                      video_frame:
                        type: integer
                      graph_phase:
                        type: integer
                      image_url:
                        type: string
                        format: uri
                  zero_velocity:
                    required:
                      - video_frame
                      - graph_phase
                      - image_url
                    type: object
                    properties:
                      video_frame:
                        type: integer
                      graph_phase:
                        type: integer
                      image_url:
                        type: string
                        format: uri
                  takeoff:
                    required:
                      - video_frame
                      - graph_phase
                      - image_url
                    type: object
                    properties:
                      video_frame:
                        type: integer
                      graph_phase:
                        type: integer
                      image_url:
                        type: string
                        format: uri
                  peak:
                    required:
                      - video_frame
                      - graph_phase
                      - image_url
                    type: object
                    properties:
                      video_frame:
                        type: integer
                      graph_phase:
                        type: integer
                      image_url:
                        type: string
                        format: uri
                  landing:
                    required:
                      - video_frame
                      - graph_phase
                      - image_url
                    type: object
                    properties:
                      video_frame:
                        type: integer
                      graph_phase:
                        type: integer
                      image_url:
                        type: string
                        format: uri
                  damping:
                    required:
                      - video_frame
                      - graph_phase
                      - image_url
                    type: object
                    properties:
                      video_frame:
                        type: integer
                      graph_phase:
                        type: integer
                      image_url:
                        type: string
                        format: uri
                  recuperation:
                    required:
                      - video_frame
                      - graph_phase
                      - image_url
                    type: object
                    properties:
                      video_frame:
                        type: integer
                      graph_phase:
                        type: integer
                      image_url:
                        type: string
                        format: uri
              user_information:
                description: Personal details of the user.
                required:
                  - name
                  - age
                  - weight
                  - height
                  - gender
                type: object
                properties:
                  name:
                    type: string
                  age:
                    type: integer
                  weight:
                    type: number
                  height:
                    type: number
                  gender:
                    type: string
              session_date:
                description: Date of the session (DD/MM/YYYY).
                type: string
                format: date
              comments:
                description: Feedback comments based on session metrics.
                type: object
                properties:
                  power:
                    type: string
                  grf:
                    type: string
        '400':
          description: Bad Request - Invalid `session_id` provided.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid session ID
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Unauthorized access
        '403':
          description: Forbidden - User lacks necessary permissions.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this page.
        '404':
          description: Not Found - No session data found for the provided `session_id`.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Session data not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred
      tags:
        - jumping
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /jumping/sessions/{session_id}/recommendation/:
    post:
      operationId: jumping_sessions_recommendation_create
      summary: Create Recommendations Threads
      description: >-
        ### 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:**

        ```json

        {
            "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:**

        ```json

        {
            "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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the session.
          required: true
          type: string
      responses:
        '200':
          description: Threads created successfully.
          schema:
            description: Mapping of metric names to recommendation thread IDs.
            required:
              - grf
              - power
              - kne_angle
              - ank_angle
              - hip_angle
            type: object
            properties:
              hip_height:
                description: Thread ID for hip height recommendations.
                type: string
              hip_speed:
                description: Thread ID for hip speed recommendations.
                type: string
              hip_trajectory:
                description: Thread ID for hip trajectory recommendations.
                type: string
              hip_velocity:
                description: Thread ID for hip velocity recommendations.
                type: string
              toe_trajectory:
                description: Thread ID for toe trajectory recommendations.
                type: string
              grf:
                description: Thread ID for ground reaction force (GRF) recommendations.
                type: string
              power:
                description: Thread ID for power recommendations.
                type: string
              kne_angle:
                description: Thread ID for knee angle recommendations.
                type: string
              ank_angle:
                description: Thread ID for ankle angle recommendations.
                type: string
              hip_angle:
                description: Thread ID for hip angle recommendations.
                type: string
          examples:
            application/json:
              hip_height: thread_PTM1RSDzrQzkNOHqxfE3D2zR
              hip_speed: thread_crf5abOg4VrCNt2SelwrgSVG
              grf: thread_EqqsrqF1sepCAJqE1JP1uxXo
              power: thread_8TDo3YPs9Y9vWICrgPQxRoaJ
              kne_angle: thread_NEbOwtuUp3u08GGDoAcwlCVl
              ank_angle: thread_58PANLkrtTNH3u6cEU2hn2i2
              hip_angle: thread_kZuGM9F21GxEKSSbSG9cFEbc
            drop_jump:
              hip_trajectory: thread_M1FDzL0TQgOkuOnNev2tm931
              hip_velocity: thread_UgOIdadz9F1hvvJ9Pk5KmTJ2
              toe_trajectory: thread_yyQ9Y2QCTry6M6yQjnNQnPvG
              grf: thread_ypYn0lHApwLFKwJGK9IiPUqY
              power: thread_ROSeZNzjfsZmO297qdJtOSgH
              kne_angle: thread_5HsGrlKmO0Ux2i0iHoNjlmm1
              ank_angle: thread_DBgtLdP8YQpS8qBxJDpE6R2B
              hip_angle: thread_kBi2ihB0znCK2uagrTmKdJa0
        '400':
          description: Bad Request - Invalid `session_id` provided.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid session ID
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Unauthorized access
        '403':
          description: Forbidden - User lacks necessary permissions.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this page.
        '404':
          description: Not Found - No session data found for the provided `session_id`.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Session data not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred
      tags:
        - jumping
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /jumping/sessions/{session_id}/summary/:
    get:
      operationId: jumping_sessions_summary_list
      summary: Get Summary of a Session
      description: >-
        ### 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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the session.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve the demo session summary instead of a real
            one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved session summary.
          schema:
            description: Object containing session summary details.
            required:
              - metrics
              - summary
              - user_info
              - created_at
            type: object
            properties:
              exercise:
                description: Type of exercise being summarized.
                type: string
              metrics:
                description: Object containing various performance metrics.
                type: object
                additionalProperties:
                  description: Array of numeric values for each metric.
                  type: array
                  items:
                    type: number
              summary:
                description: Object containing summary details of the session.
                type: object
                additionalProperties:
                  description: Summary information for each key.
                  type: string
              user_info:
                description: Object containing user information.
                required:
                  - name
                  - age
                  - weight
                  - height
                  - gender
                type: object
                properties:
                  name:
                    description: Full name of the user.
                    type: string
                  age:
                    description: Age of the user.
                    type: integer
                  weight:
                    description: Weight of the user in kilograms.
                    type: number
                  height:
                    description: Height of the user in centimeters.
                    type: number
                  gender:
                    description: Gender of the user.
                    type: string
              created_at:
                description: Object containing the date and time of session creation.
                required:
                  - date
                  - time
                type: object
                properties:
                  date:
                    description: Date when the session was created, in 'YYYY-MM-DD' format.
                    type: string
                    format: date
                  time:
                    description: >-
                      Time when the session was created, in 'HH:MM AM/PM'
                      format.
                    type: string
                    format: time
          examples:
            application/json:
              exercise: Countermovement Jump
              metrics:
                hip_height:
                  - 0.5
                  - 0.6
                  - 0.7
                hip_speed:
                  - 0.2
                  - 0.3
                  - 0.4
                grf:
                  - 100
                  - 150
                  - 200
              summary:
                jump_height: High
                power: Average
                balance: Good
              user_info:
                name: John Doe
                age: 25
                weight: 70.5
                height: 175
              created_at:
                date: '2022-01-01'
                time: 10:30 AM
        '400':
          description: Bad Request - Invalid `session_id` provided.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid session ID
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Unauthorized access
        '403':
          description: Forbidden - User lacks necessary permissions.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this page.
        '404':
          description: Not Found - No session data found for the provided `session_id`.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Session data not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred
      tags:
        - jumping
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: jumping_sessions_summary_create
      summary: Generate Summary Threads for a Session
      description: >-
        ### 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:**

        ```json

        {
            "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:**

        ```json

        {
            "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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the session.
          required: true
          type: string
        - name: measurement_system
          in: query
          description: 'Measurement system: ''metric'' or ''imperial'''
          required: false
          type: string
          enum:
            - metric
            - imperial
          default: metric
      responses:
        '201':
          description: Successfully generated summary threads.
          schema:
            description: >-
              Dictionary mapping block names to their corresponding thread IDs,
              including a final summary thread.
            type: object
            additionalProperties:
              description: Thread ID corresponding to the block name.
              type: string
          examples:
            application/json:
              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
        '400':
          description: Bad Request - Invalid `session_id` provided.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Invalid session ID
        '401':
          description: Unauthorized - Access token is missing or invalid.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Unauthorized access
        '403':
          description: Forbidden - User lacks necessary permissions.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this page.
        '404':
          description: Not Found - No session data found for the provided `session_id`.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: Session data not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            required:
              - error
            type: object
            properties:
              error:
                description: Error message.
                type: string
          examples:
            application/json:
              error: An unexpected error occurred
      tags:
        - jumping
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  
  /mobility-assessment/sessions/:
    post:
      operationId: mobility-assessment_sessions_create
      summary: Create a New Video Processing Session
      description: >
        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:


        ```bash

        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/
        ```
      parameters:
        - name: user_id
          in: formData
          description: >-
            **Required.** The ID of the user for whom this session is created
            (form field: text).
          required: true
          type: string
        - name: video
          in: formData
          description: >-
            **Required.** The raw video file to be processed (form field type:
            file).
          required: true
          type: file
        - name: session_name
          in: formData
          description: '**Optional.** A descriptive name for the session (form field: text).'
          required: false
          type: string
        - name: exercise
          in: formData
          description: >-
            **Required.** The name of the exercise. Choose one of the following:
            'Overhead Squat', 'Joint Angle Mobility'
          required: true
          type: string
          enum:
            - Overhead Squat
            - Joint Angle Mobility
        - name: body_joint_angles
          in: formData
          description: >-
            **Optional.** A comma-separated list of joint names. Available
            values: `'ankle'`, `'knee'`, `'elbow'`, `'hip'`, `'shoulder'`.
            Example: `ankle,knee,hip`
          required: false
          type: array
          items:
            type: string
            enum:
              - ankle
              - knee
              - elbow
              - hip
              - shoulder
          collectionFormat: csv
      responses:
        '200':
          description: Video processing session created successfully (HTTP 200).
          schema:
            required:
              - session_id
              - title
            type: object
            properties:
              session_id:
                description: The unique identifier for the created session.
                type: string
              title:
                description: The session title (defaults if not provided).
                type: string
          examples:
            application/json:
              session_id: abcd1234efgh5678
              title: Custom Session
        '400':
          description: >-
            Bad Request - Possibly due to missing `user_id`, missing `video`, or
            invalid form data.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: user_id is required
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating a missing or invalid token.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have admin permission to create
            sessions for others.
          schema:
            type: object
            properties:
              error:
                description: Error indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: >-
            Not Found - Indicates business logic issues or resource limitations
            (e.g., session limit).
          schema:
            type: object
            properties:
              error:
                description: Error message describing the issue.
                type: string
          examples:
            application/json:
              error: User has reached the maximum number of sessions.
        '500':
          description: Internal Server Error - Unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      consumes:
        - multipart/form-data
        - application/x-www-form-urlencoded
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /mobility-assessment/sessions/{session_id}/:
    get:
      operationId: mobility-assessment_sessions_read
      summary: Retrieve Mobility Assessment Session
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: >-
            The unique identifier of the Mobility Assessment session to
            retrieve.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve the pre-generated demo session instead of
            a real session.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved Mobility Assessment session data.
          schema:
            required:
              - segments
              - video_url
              - activity
              - title
              - user_name
              - created_at
              - exercise
              - angles
              - all_timestamps
            type: object
            properties:
              segments:
                description: Number of segments in this mobility assessment.
                type: integer
              video_url:
                description: URL of the original video.
                type: string
                format: uri
              analyzed_video_url:
                description: Optional URL of the processed video.
                type: string
                format: uri
              activity:
                description: Type of activity, e.g., 'Mobility Assessment'.
                type: string
              title:
                description: A user-friendly session title.
                type: string
              user_name:
                description: Name of the user associated with this session.
                type: string
              created_at:
                description: A date/time object indicating when this session was created.
                type: object
                properties:
                  date:
                    description: Date of creation, format 'DD/MM/YYYY'.
                    type: string
                  time:
                    description: Time of creation, format 'HH:MM AM/PM'.
                    type: string
              exercise:
                description: The exercise name, e.g. 'Overhead Squad'.
                type: string
              angles:
                description: >-
                  Object containing arrays of angle data relevant to the
                  mobility assessment.
                type: object
                additionalProperties:
                  description: An array of numeric values for a specific angle metric.
                  type: array
                  items:
                    type: number
              all_timestamps:
                description: >-
                  Array of numeric timestamps corresponding to each angle data
                  entry.
                type: array
                items:
                  type: number
          examples:
            application/json:
              segments: 3
              video_url: https://example.com/original.mp4
              analyzed_video_url: https://example.com/analyzed.mp4
              activity: Mobility Assessment
              title: My Overhead Squad Session
              user_name: Test User
              created_at:
                date: 02/10/2023
                time: 09:45 AM
              exercise: Overhead Squad
              angles:
                hip_angle:
                  - 12.5
                  - 13.1
                  - 15
                ankle_angle:
                  - 5.5
                  - 6.2
                  - 7.8
              all_timestamps:
                - 0
                - 33
                - 66
        '400':
          description: Bad Request - Invalid or missing parameters.
          schema:
            type: object
            properties:
              error:
                description: A descriptive error message.
                type: string
          examples:
            application/json:
              error: Missing or invalid session_id parameter.
        '401':
          description: Unauthorized - Missing or invalid authentication token.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error indicating that token credentials are missing or
                  invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have permission to retrieve this
            session.
          schema:
            type: object
            properties:
              error:
                description: User is not allowed to retrieve this session.
                type: string
          examples:
            application/json:
              error: You are not allowed to retrieve this session.
        '404':
          description: Not Found - The session was not found or does not exist.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating the session could not be located.
                type: string
          examples:
            application/json:
              error: The session does not exist.
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /mobility-assessment/sessions/{session_id}/export/:
    get:
      operationId: mobility-assessment_sessions_export_list
      summary: Export Session Data (Mobility Assessment)
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: The unique identifier of the session whose data is being exported.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve the demo session data instead of a real
            one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Session data exported successfully.
          schema:
            required:
              - activity
              - angles
              - all_timestamps
              - keypoints
            type: object
            properties:
              activity:
                description: Type of activity (e.g., 'Mobility Assessment').
                type: string
              angles:
                description: >-
                  Key-value pairs for angle metrics. Each value is an array of
                  numbers.
                type: object
                additionalProperties:
                  description: An array of numeric angle values.
                  type: array
                  items:
                    type: number
              all_timestamps:
                description: Array of numeric timestamps corresponding to each data point.
                type: array
                items:
                  type: number
              keypoints:
                description: Contains arrays of landmark points for each tracked body part.
                type: object
                additionalProperties:
                  description: An array of numeric values for the specified landmark key.
                  type: array
                  items:
                    type: number
          examples:
            application/json:
              activity: Mobility Assessment
              angles:
                hip_angle:
                  - 15.1
                  - 14.7
                  - 16
                knee_angle:
                  - 42
                  - 40.5
                  - 43.2
              all_timestamps:
                - 0
                - 33
                - 66
                - 99
              keypoints:
                lknev:
                  - 0.12
                  - 0.15
                  - 0.11
                ltoev:
                  - 1.22
                  - 1.1
                  - 1.35
                relbv:
                  - 0.05
                  - 0.07
                  - 0.06
                rtoey:
                  - 1.12
                  - 1.09
                  - 1.25
                headv:
                  - 0.9
                  - 0.88
                  - 0.95
                rearv:
                  - 0.52
                  - 0.53
                  - 0.5
                rshox:
                  - 0.45
                  - 0.46
                  - 0.44
                etc:
                  - 0.34
                  - 0.35
                  - 0.33
        '400':
          description: Bad Request - Possibly due to invalid or missing session_id.
          schema:
            type: object
            properties:
              error:
                description: A descriptive error message.
                type: string
          examples:
            application/json:
              error: Missing or invalid session_id parameter.
        '401':
          description: Unauthorized - Missing or invalid authentication token.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating missing or invalid token credentials.
                type: string
          examples:
            application/json:
              error: Authentication credentials were not provided.
        '403':
          description: Forbidden - Insufficient privileges to retrieve session data.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the user is not allowed to
                  access this data.
                type: string
          examples:
            application/json:
              error: You do not have permission to perform this action.
        '404':
          description: Not Found - The session does not exist.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the requested session could not
                  be found.
                type: string
          examples:
            application/json:
              error: The session does not exist.
        '500':
          description: Internal Server Error - Unexpected error on the server.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /mobility-assessment/sessions/{session_id}/joint-mobility-config/:
    get:
      operationId: mobility-assessment_sessions_joint-mobility-config_list
      summary: Retrieve the saved report configuration for a session
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: Mobility session identifier
          required: true
          type: string
      responses:
        '200':
          description: Configuration retrieved successfully.
          schema:
            required:
              - shown_angles
              - comments
            type: object
            properties:
              shown_angles:
                description: Selected joint-angle keys
                type: array
                items:
                  type: string
              comments:
                description: Optional notes for each angle
                type: object
                additionalProperties:
                  type: string
            example:
              shown_angles:
                - knee_angle
                - hip_angle
              comments:
                knee_angle: Check alignment on flexion.
        '401':
          description: Unauthorized – Authentication credentials were missing or invalid.
          schema:
            type: object
            properties:
              detail:
                type: string
        '403':
          description: Forbidden – You do not have permission to view this configuration.
          schema:
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: Insufficient privileges.
        '404':
          description: Not Found – No report configuration exists for that session.
          schema:
            type: object
            properties:
              error:
                type: string
        '500':
          description: Internal Server Error – Something went wrong on our end.
          schema:
            type: object
            properties:
              error:
                type: string
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: mobility-assessment_sessions_joint-mobility-config_create
      summary: Create or update the report configuration for a session
      description: >-
        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.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            type: object
            properties:
              shown_angles:
                description: Angles to show
                type: array
                items:
                  type: string
                example:
                  - shoulder_angle
                  - ankle_angle
              comments:
                description: Optional comments keyed by angle
                type: object
                additionalProperties:
                  type: string
                example:
                  shoulder_angle: Use gentle movement.
            example:
              shown_angles:
                - hip_angle
                - knee_angle
              comments:
                hip_angle: Monitor range of motion.
        - name: session_id
          in: path
          description: Mobility session identifier
          required: true
          type: string
      responses:
        '200':
          description: Configuration saved and returned.
          schema:
            required:
              - shown_angles
              - comments
            type: object
            properties:
              shown_angles:
                description: Updated list of displayed angles
                type: array
                items:
                  type: string
              comments:
                description: Updated notes per angle
                type: object
                additionalProperties:
                  type: string
            example:
              shown_angles:
                - hip_angle
                - knee_angle
              comments:
                hip_angle: Range improved.
        '400':
          description: Bad Request – Validation failed for one or more fields.
          schema:
            type: object
            properties:
              errors:
                description: Mapping of field names to error messages
                type: object
                additionalProperties:
                  type: string
            example:
              errors:
                shown_angles.0: Invalid angle key.
        '401':
          description: Unauthorized – Authentication credentials were missing or invalid.
          schema:
            type: object
            properties:
              detail:
                type: string
        '403':
          description: Forbidden – You do not have permission to modify this configuration.
          schema:
            type: object
            properties:
              error:
                type: string
        '500':
          description: Internal Server Error – Something went wrong saving your data.
          schema:
            type: object
            properties:
              error:
                type: string
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /mobility-assessment/sessions/{session_id}/joint-mobility/:
    post:
      operationId: mobility-assessment_sessions_joint-mobility_create
      summary: Generate Joint Angle Mobility Report
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the mobility session
          required: true
          type: string
      responses:
        '200':
          description: Joint Angle Mobility report retrieved successfully.
          schema:
            required:
              - title
              - angles
              - exercise
              - user_info
              - date
              - uploaded_date
            type: object
            properties:
              title:
                description: Session title
                type: string
              angles:
                description: Summary of joint angles keyed by joint name.
                type: object
                additionalProperties:
                  required:
                    - max
                    - min
                    - values
                  type: object
                  properties:
                    max:
                      description: Maximum angle or null
                      type: number
                    min:
                      description: Minimum angle or null
                      type: number
                    values:
                      description: Original angle values
                      type: array
                      items:
                        type: number
              exercise:
                description: Exercise name, 'Joint Angle Mobility'
                type: string
              user_info:
                description: User details associated with the session
                type: object
                additionalProperties:
                  description: User field value
                  type: string
              date:
                description: Session date in DD/MM/YYYY format
                type: string
              uploaded_date:
                description: Raw ISO timestamp of upload
                type: string
                format: date-time
              shown_angles:
                description: Angles the user has chosen to display
                type: array
                items:
                  type: string
              comments:
                description: Per-angle comments
                type: object
                additionalProperties:
                  description: Comment text
                  type: string
        '400':
          description: Bad Request - Invalid exercise type or parameters.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating the request was malformed or invalid.
                type: string
        '403':
          description: Forbidden - Insufficient privileges to retrieve session data.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the user is not allowed to
                  access this data.
                type: string
          examples:
            application/json:
              error: You must be an admin or sub-admin to access this data.
        '404':
          description: Not Found - Session data not found.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the requested session could not
                  be found.
                type: string
        '500':
          description: Internal Server Error - Unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating an unexpected server error.
                type: string
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /mobility-assessment/sessions/{session_id}/recommendation/:
    post:
      operationId: mobility-assessment_sessions_recommendation_create
      summary: Create Recommendations Threads
      description: >-
        ### 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:**

        ```json

        {
            "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.
      parameters:
        - name: session_id
          in: path
          description: >-
            Unique identifier of the session for which recommendation threads
            are to be created.
          required: true
          type: string
      responses:
        '200':
          description: Threads created successfully.
          schema:
            description: A dictionary mapping each metric to its corresponding thread ID.
            required:
              - ankle_dorsiflexion
              - hip_abduction
              - hip_flexion
              - knee_flexion
              - knee_movement
              - final_summary
            type: object
            properties:
              ankle_dorsiflexion:
                description: >-
                  Unique identifier for the ankle dorsiflexion recommendation
                  thread.
                type: string
              hip_abduction:
                description: Unique identifier for the hip abduction recommendation thread.
                type: string
              hip_flexion:
                description: Unique identifier for the hip flexion recommendation thread.
                type: string
              knee_flexion:
                description: Unique identifier for the knee flexion recommendation thread.
                type: string
              knee_movement:
                description: Unique identifier for the knee movement recommendation thread.
                type: string
              final_summary:
                description: Unique identifier for the final summary recommendation thread.
                type: string
          examples:
            application/json:
              ankle_dorsiflexion: thread_boQ0PSivWvPHIx4MQ02HqSEX
              hip_abduction: thread_eoTqfX3qWuT2IrEhZpGcem7L
              hip_flexion: thread_0pJjWIs5ybuo5gzRJd1ykgaB
              knee_flexion: thread_8gp2spSn8XasAOafDwwzw5QT
              knee_movement: thread_8gp2spSn8XasAOafDwwzw5QT
              final_summary: thread_P3MqG76m9s6qlYwINJrlNomB
        '401':
          description: Unauthorized - Missing or invalid token.
          schema:
            type: object
            properties:
              error:
                description: >-
                  An error message indicating that credentials were not provided
                  or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - Invalid payment plan or insufficient privileges to
            create recommendation threads.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating user cannot access the resource.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - Session not found or missing metrics.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating the session does not exist or lacks
                  data.
                type: string
          examples:
            application/json:
              error: No session data returned from Firebase
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /mobility-assessment/sessions/{session_id}/report/:
    post:
      operationId: mobility-assessment_sessions_report_create
      summary: Generate Overhead Squat Report
      description: >-
        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


        ```json

        {
          "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": "natalia3@gmail.com",
            ...
          },
          "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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the Overhead Squat session.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve the demo Overhead Squat report instead of
            a real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Overhead Squat report generated/retrieved successfully.
          schema:
            required:
              - grouped_data
              - graph_timestamps
              - knee_movement_phases
              - user_info
              - exercise
              - output_quality
              - date
            type: object
            properties:
              grouped_data:
                description: >-
                  Groups of metrics and graph data related to Overhead Squat
                  performance.
                type: object
                additionalProperties:
                  required:
                    - metrics
                    - graph_data
                  type: object
                  properties:
                    metrics:
                      description: Aggregated metric results (e.g., left/right asymmetry).
                      type: object
                      additionalProperties:
                        description: A numeric metric value.
                        type: number
                    graph_data:
                      description: Arrays of numeric values for plotting graphs.
                      type: object
                      additionalProperties:
                        description: An array of numbers for plotting one metric graph.
                        type: array
                        items:
                          type: number
              graph_timestamps:
                description: >-
                  A list of timestamps (in milliseconds) corresponding to each
                  graph data.
                type: array
                items:
                  type: number
              knee_movement_phases:
                description: >-
                  URLs of visualization images showing different views of knee
                  movement phases.
                type: object
                properties:
                  left:
                    description: Left view image URL
                    type: string
                  right:
                    description: Right view image URL
                    type: string
                  front:
                    description: Front view image URL
                    type: string
              user_info:
                description: Optional basic user details (e.g., weight, age, email).
                type: object
                additionalProperties:
                  description: Key-value pairs of user data.
                  type: string
              exercise:
                description: Name/type of the exercise (e.g., 'Overhead Squat').
                type: string
              output_quality:
                description: Optional object containing scoring metrics or indices.
                type: object
                additionalProperties:
                  description: A numeric score or index related to output quality.
                  type: number
              report_comments:
                description: Detailed feedback for different movement aspects.
                type: object
                properties:
                  hip_flexion:
                    description: Recommendations for improving hip flexion.
                    type: string
                  ankle_dorsiflexion:
                    description: Assessment and improvements for ankle dorsiflexion.
                    type: string
                  final_summary:
                    description: Overall session summary and recommendations.
                    type: string
                  hip_abduction:
                    description: Guidance for improving hip abduction.
                    type: string
              date:
                description: A string representing the session date in DD/MM/YYYY format.
                type: string
          examples:
            application/json:
              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
                - 5
                - 10
                - 15
                - 20
                - 25
              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: natalia3@gmail.com
                display_name: Natalia Alioth
              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
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating a missing or invalid token.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have permission to create sessions
            (admin-only).
          schema:
            type: object
            properties:
              error:
                description: Error indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - Session data cannot be found or no metrics returned.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating session or metrics missing.
                type: string
          examples:
            application/json:
              error: No session data returned from Firebase
        '500':
          description: Internal Server Error - Unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /mobility-assessment/sessions/{session_id}/summary/:
    get:
      operationId: mobility-assessment_sessions_summary_list
      summary: Retrieve Overhead Squat Summary
      description: >-
        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.

          ```json
          {
            "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


        ```json

        {
          "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": "natalia3@gmail.com",
            ...
          },
          "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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the Overhead Squat session.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve the pre-generated demo Overhead Squat
            summary instead of a real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Overhead Squat summary retrieved successfully.
          schema:
            required:
              - grouped_data
              - knee_movement_phases
              - exercise
              - date
            type: object
            properties:
              grouped_data:
                description: High-level metrics grouped by category (no graph data).
                type: object
                additionalProperties:
                  description: >-
                    An object where each key is a metric name and the value is
                    numeric.
                  type: object
                  additionalProperties:
                    description: Numeric value for the metric.
                    type: number
              knee_movement_phases:
                description: >-
                  URLs of visualization images showing different views of knee
                  movement phases.
                type: object
                properties:
                  left:
                    description: Left view image URL
                    type: string
                  right:
                    description: Right view image URL
                    type: string
                  front:
                    description: Front view image URL
                    type: string
              user_info:
                description: Optional user information (e.g., weight, email).
                type: object
                additionalProperties:
                  description: A key-value pair of user metadata.
                  type: string
              exercise:
                description: The exercise name/type, e.g. 'Overhead Squat'.
                type: string
              output_quality:
                description: Optional object containing numeric scoring or quality indexes.
                type: object
                additionalProperties:
                  description: A numeric score or index related to output quality.
                  type: number
              summary:
                description: Detailed feedback on different movement aspects.
                type: object
                properties:
                  hip_flexion:
                    description: Recommendations for improving hip flexion.
                    type: string
                  ankle_dorsiflexion:
                    description: Assessment and improvements for ankle dorsiflexion.
                    type: string
                  final_summary:
                    description: Overall session summary and recommendations.
                    type: string
                  hip_abduction:
                    description: Guidance for improving hip abduction.
                    type: string
              date:
                description: Session date in 'DD/MM/YYYY' format.
                type: string
          examples:
            application/json:
              grouped_data:
                hip_flexion:
                  left_hip_flexion: 84
                  right_hip_flexion: 80
                  hip_flexion_asymmetry: 4
                hip_adduction:
                  left_hip_abduction: 9
                  right_hip_abduction: 16
                  hip_abduction_asymmetry: 7
                knee_flexion:
                  left_knee_flexion: 79
                  right_knee_flexion: 82
                  knee_flexion_asymmetry: 3
                ankle_dorsiflexion:
                  left_ankle_flexion: 9
                  right_ankle_flexion: 15
                  ankle_flexion_asymmetry: 6
              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
                email: natalia3@gmail.com
                ...: ...
              exercise: Overhead Squat
              output_quality:
                mobility_index: 46
                quality_index: 67
              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
        '401':
          description: Unauthorized - Missing or invalid token.
          schema:
            type: object
            properties:
              error:
                description: >-
                  An error message indicating that credentials were not provided
                  or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - Invalid payment plan or insufficient privileges to
            retrieve the summary.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating user cannot access the resource.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - Session not found or missing metrics.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating the session does not exist or lacks
                  data.
                type: string
          examples:
            application/json:
              error: No session data returned from Firebase
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: mobility-assessment_sessions_summary_create
      summary: Generate Summary Threads for a Session
      description: >-
        ### 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:**

        ```json

        {
            "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.
      parameters:
        - name: session_id
          in: path
          description: >-
            Unique identifier of the session for which summary threads are to be
            generated.
          required: true
          type: string
        - name: measurement_system
          in: query
          description: 'Measurement system: ''metric'' or ''imperial'''
          required: false
          type: string
          enum:
            - metric
            - imperial
          default: metric
      responses:
        '201':
          description: Successfully generated summary threads.
          schema:
            description: Dictionary mapping each metric to its corresponding thread ID.
            required:
              - hip_flexion
              - hip_abduction
              - knee_flexion
              - knee_movement
              - ankle_dorsiflexion
              - final_summary
            type: object
            properties:
              hip_flexion:
                description: Unique identifier for the hip flexion summary thread.
                type: string
              hip_abduction:
                description: Unique identifier for the hip abduction summary thread.
                type: string
              knee_flexion:
                description: Unique identifier for the knee flexion summary thread.
                type: string
              knee_movement:
                description: Unique identifier for the knee movement summary thread.
                type: string
              ankle_dorsiflexion:
                description: Unique identifier for the ankle dorsiflexion summary thread.
                type: string
              final_summary:
                description: Unique identifier for the final summary thread.
                type: string
          examples:
            application/json:
              hip_flexion: thread_x7C4p5ancmeluBmEJgmFwXra
              hip_abduction: thread_lth8oxKfnktwne9ryGZefd6V
              knee_flexion: thread_cM4jY2RLfVNeFIImJXaIinMK
              knee_movement: thread_8gp2spSn8XasAOafDwwzw5QT
              ankle_dorsiflexion: thread_EIwgj822ZHtGCTMucHZDtatH
              final_summary: thread_2XwSNDNrclHgakiBFm4o9K65
        '401':
          description: Unauthorized - Missing or invalid token.
          schema:
            type: object
            properties:
              error:
                description: >-
                  An error message indicating that credentials were not provided
                  or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - Invalid payment plan or insufficient privileges to
            create recommendation threads.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating user cannot access the resource.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - Session not found or missing metrics.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating the session does not exist or lacks
                  data.
                type: string
          examples:
            application/json:
              error: No session data returned from Firebase
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - mobility-assessment
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string

  /running/sessions/:
    post:
      operationId: running_sessions_create
      summary: Create a New Video Processing Session
      description: >
        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.

        - **incline_degree** *(string or number, optional)*: Numeric value
        representing the incline degree.

        - **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:


        ```bash

        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 'incline_degree=5' \
             -F 'body_joint_angles=elbow, knee, ankle' \
             https://<backend-link>/running/management/sessions/
        ```
      parameters:
        - name: user_id
          in: formData
          description: >-
            **Required.** The ID of the user for whom this session is created
            (form field: text).
          required: true
          type: string
        - name: video
          in: formData
          description: >-
            **Required.** The raw video file to be processed (form field type:
            file).
          required: true
          type: file
        - name: session_name
          in: formData
          description: '**Optional.** A descriptive name for the session (form field: text).'
          required: false
          type: string
        - name: incline_degree
          in: formData
          description: >-
            **Optional.** A numeric string indicating the incline degree (form
            field: text).
          required: false
          type: string
        - name: body_joint_angles
          in: formData
          description: >-
            **Optional.** A comma-separated list of joint names. Available
            values: `'ankle'`, `'knee'`, `'elbow'`, `'hip'`, `'shoulder'`.
            Example: `ankle,knee,hip`
          required: false
          type: array
          items:
            type: string
            enum:
              - ankle
              - knee
              - elbow
              - hip
              - shoulder
          collectionFormat: csv
      responses:
        '200':
          description: Video processing session created successfully (HTTP 200).
          schema:
            required:
              - session_id
              - title
            type: object
            properties:
              session_id:
                description: The unique identifier for the created session.
                type: string
              title:
                description: The session title (defaults if not provided).
                type: string
          examples:
            application/json:
              session_id: abcd1234efgh5678
              title: Custom Session
        '400':
          description: >-
            Bad Request - Possibly due to missing `user_id`, missing `video`, or
            invalid form data.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: user_id is required
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating a missing or invalid token.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have admin permission to create
            sessions for others.
          schema:
            type: object
            properties:
              error:
                description: Error indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: >-
            Not Found - Indicates business logic issues or resource limitations
            (e.g., session limit).
          schema:
            type: object
            properties:
              error:
                description: Error message describing the issue.
                type: string
          examples:
            application/json:
              error: User has reached the maximum number of sessions.
        '500':
          description: Internal Server Error - Unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      consumes:
        - multipart/form-data
        - application/x-www-form-urlencoded
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /running/sessions/metrics/total/:
    get:
      operationId: running_sessions_metrics_total_list
      summary: Retrieve Total Metrics
      description: >-
        Calculates and returns the average metrics for all running sessions of
        the admin user, along with the detailed metrics and creation timestamp
        of the most recent session.


        ### Response Structure (HTTP 200)


        The response is a JSON object with the following structure:


        - **avg_metrics** *(object)*: Contains the average values calculated
        across all sessions.
          - **avg_speed** *(number)*: Average speed.
          - **avg_power** *(number)*: Average power.
          - **avg_cadence** *(number)*: Average cadence.
          - **avg_flight_time** *(number)*: Average flight time.

        - **last_session_metrics** *(object)*: Contains detailed metrics for the
        most recent session.
          - **speed** *(object)*: Speed metrics with:
              - **avg** *(number)*: Average speed.
              - **min** *(number)*: Minimum speed.
              - **max** *(number)*: Maximum speed.
          - **normalized_power** *(object)*: Normalized power metrics with keys `avg`, `min`, `max`.
          - **cadence** *(object)*: Cadence metrics with keys `avg`, `min`, `max`.
          - **total_distance** *(number)*: Total distance.
          - **power** *(object)*: Power metrics with keys `avg`, `min`, `max`.
          - **stride_time** *(object)*: Stride time metrics with keys `avg`, `min`, `max`.
          - **total_time** *(number)*: Total session time.
          - **contact_time** *(object)*: Contact time metrics with keys `avg`, `min`, `max`.
          - **contact_angle** *(object)*: Contact angle metrics with keys `avg`, `min`, `max`.
          - **incline** *(object)*: Incline metrics with keys `avg`, `min`, `max`.
          - **pace** *(object)*: Pace metrics with keys `avg`, `min`, `max`.
          - **stride_length** *(object)*: Stride length metrics with keys `avg`, `min`, `max`.
          - **rbalance** *(object)*: Balance metrics with keys `avg`, `min`, `max`.
          - **flight_time** *(object)*: Flight time metrics with keys `avg`, `min`, `max`.
          - **footstrike** *(string)*: The footstrike type (e.g., 'midfoot').

        - **last_session_created_at** *(object)*: The creation timestamp of the
        most recent session, containing:
          - **date** *(string)*: Date in DD/MM/YYYY format.
          - **time** *(string)*: Time in HH:MM AM/PM format.

        ### Error Handling


        - **400 Bad Request**: Invalid request parameters (e.g., invalid admin
        UID).

        - **401 Unauthorized**: Missing or invalid access token.

        - **403 Forbidden**: Insufficient privileges to retrieve total metrics.

        - **404 Not Found**: No sessions found or metrics unavailable.

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


        ### Security


        A valid API-KEY token must be provided in the `Authorization` header.
      parameters: []
      responses:
        '200':
          description: Total metrics successfully retrieved.
          schema:
            required:
              - avg_metrics
              - last_session_metrics
              - last_session_created_at
            type: object
            properties:
              avg_metrics:
                description: Average metrics across all sessions.
                required:
                  - avg_speed
                  - avg_power
                  - avg_cadence
                  - avg_flight_time
                type: object
                properties:
                  avg_speed:
                    description: Average speed.
                    type: number
                  avg_power:
                    description: Average power.
                    type: number
                  avg_cadence:
                    description: Average cadence.
                    type: number
                  avg_flight_time:
                    description: Average flight time.
                    type: number
              last_session_metrics:
                description: Detailed metrics for the most recent session.
                required:
                  - speed
                  - normalized_power
                  - cadence
                  - total_distance
                  - power
                  - stride_time
                  - total_time
                  - contact_time
                  - contact_angle
                  - incline
                  - pace
                  - stride_length
                  - rbalance
                  - flight_time
                  - footstrike
                type: object
                properties:
                  speed:
                    description: Speed metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average speed.
                        type: number
                      min:
                        description: Minimum speed.
                        type: number
                      max:
                        description: Maximum speed.
                        type: number
                  normalized_power:
                    description: Normalized power metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average normalized power.
                        type: number
                      min:
                        description: Minimum normalized power.
                        type: number
                      max:
                        description: Maximum normalized power.
                        type: number
                  cadence:
                    description: Cadence metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average cadence.
                        type: number
                      min:
                        description: Minimum cadence.
                        type: number
                      max:
                        description: Maximum cadence.
                        type: number
                  total_distance:
                    description: Total distance covered in the session.
                    type: number
                  power:
                    description: Power metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average power.
                        type: number
                      min:
                        description: Minimum power.
                        type: number
                      max:
                        description: Maximum power.
                        type: number
                  stride_time:
                    description: Stride time metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average stride time.
                        type: number
                      min:
                        description: Minimum stride time.
                        type: number
                      max:
                        description: Maximum stride time.
                        type: number
                  total_time:
                    description: Total time of the session.
                    type: number
                  contact_time:
                    description: Contact time metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average contact time.
                        type: number
                      min:
                        description: Minimum contact time.
                        type: number
                      max:
                        description: Maximum contact time.
                        type: number
                  contact_angle:
                    description: Contact angle metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average contact angle.
                        type: number
                      min:
                        description: Minimum contact angle.
                        type: number
                      max:
                        description: Maximum contact angle.
                        type: number
                  incline:
                    description: Incline metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average incline.
                        type: number
                      min:
                        description: Minimum incline.
                        type: number
                      max:
                        description: Maximum incline.
                        type: number
                  pace:
                    description: Pace metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average pace.
                        type: number
                      min:
                        description: Minimum pace.
                        type: number
                      max:
                        description: Maximum pace.
                        type: number
                  stride_length:
                    description: Stride length metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average stride length.
                        type: number
                      min:
                        description: Minimum stride length.
                        type: number
                      max:
                        description: Maximum stride length.
                        type: number
                  rbalance:
                    description: Balance metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average balance.
                        type: number
                      min:
                        description: Minimum balance.
                        type: number
                      max:
                        description: Maximum balance.
                        type: number
                  flight_time:
                    description: Flight time metrics.
                    required:
                      - avg
                      - min
                      - max
                    type: object
                    properties:
                      avg:
                        description: Average flight time.
                        type: number
                      min:
                        description: Minimum flight time.
                        type: number
                      max:
                        description: Maximum flight time.
                        type: number
                  footstrike:
                    description: The footstrike type (e.g., 'midfoot').
                    type: string
              last_session_created_at:
                description: Creation timestamp of the most recent session.
                required:
                  - date
                  - time
                type: object
                properties:
                  date:
                    description: Creation date in DD/MM/YYYY format.
                    type: string
                  time:
                    description: Creation time in HH:MM AM/PM format.
                    type: string
          examples:
            application/json:
              avg_metrics:
                avg_speed: 2.4107943924101263
                avg_power: 299.24035514304535
                avg_cadence: 157.35377125682285
                avg_flight_time: 0.10803262246023908
              last_session_metrics:
                speed:
                  avg: 2.760333333333333
                  min: 2.693
                  max: 2.828
                normalized_power:
                  avg: 3.04
                  min: 2.99
                  max: 3.13
                cadence:
                  avg: 169.96666666666667
                  min: 167.8
                  max: 173.9
                total_distance: 24.802
                power:
                  avg: 212.66666666666666
                  min: 209
                  max: 219
                stride_time:
                  avg: 0.35305666666666663
                  min: 0.345
                  max: 0.3575
                total_time: 8.985
                contact_time:
                  avg: 0.23916666666666667
                  min: 0.23688
                  max: 0.24312
                contact_angle:
                  avg: 84.581
                  min: 84.06
                  max: 85.514
                incline:
                  avg: 0
                  min: 0
                  max: 0
                pace:
                  avg: 6.040326197822259
                  min: 5.893446487505894
                  max: 6.188884762965713
                stride_length:
                  avg: 0.6600536533333333
                  min: 0.6537888
                  max: 0.67165
                rbalance:
                  avg: 45.86
                  min: 44.47
                  max: 46.67
                flight_time:
                  avg: 0.11389
                  min: 0.10812
                  max: 0.11917
                footstrike: midfoot
              last_session_created_at:
                date: 05/02/2025
                time: 06:00 PM
        '400':
          description: Bad Request - Invalid parameters (e.g., invalid admin UID).
          schema:
            type: object
            properties:
              error:
                description: A detailed error message explaining the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid admin UID.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that A valid API-KEY token was not provided.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have sufficient privileges to retrieve
            total metrics.
          schema:
            type: object
            properties:
              error:
                description: Error indicating insufficient permissions.
                type: string
          examples:
            application/json:
              error: Access denied.
        '404':
          description: Not Found - No sessions found or metrics unavailable.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that no sessions or metrics were
                  found.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /running/sessions/{session_id}/:
    get:
      operationId: running_sessions_read
      summary: Retrieve Running Session Details
      description: >-
        Retrieves detailed information for a specific running session identified
        by the `session_id`.


        ### Path Parameter

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


        ### Query Parameter

        - **demo** *(boolean, optional)*: Set to `true` to retrieve the demo
        running session data instead of a real one.


        ### Response Structure

        On success (HTTP 200), the response is a JSON object containing the
        following fields:


        - **metrics** *(object)*: A dictionary of metric arrays (e.g., speed,
        cadence, distance). Each key maps to an array of numbers.

        - **angles** *(object)*: A dictionary of angle arrays (e.g., lhip_angle,
        rsho_angle). Each key maps to an array of numbers.

        - **all_timestamps** *(array[number])*: A list of timestamps (in
        seconds) for the session data.

        - **analyzed_video_url** *(string, URI)*: The URL for the analyzed video
        (with keypoints overlay).

        - **video_url** *(string, URI)*: The URL for the original uploaded
        video.

        - **segments** *(integer)*: The number of segments processed.

        - **created_at** *(object)*: An object containing:
            - **date** *(string)*: The creation date in DD/MM/YYYY format.
            - **time** *(string)*: The creation time in HH:MM AM/PM format.
        - **user_name** *(string)*: The name of the user associated with the
        session.

        - **activity** *(string)*: The activity type (e.g., 'Running').

        - **title** *(string)*: The title of the session.

        - **calculated_metrics** *(object)*: A dictionary containing computed
        statistics (such as averages, minima, and maxima) for various metrics.

        - **summary** *(string)*: An optional textual summary of the session.


        ### Error Handling

        - **400 Bad Request**: The request parameters are invalid (e.g., invalid
        admin UID).

        - **401 Unauthorized**: The access token is missing or invalid.

        - **403 Forbidden**: The user does not have sufficient privileges to
        access the session.

        - **404 Not Found**: The session does not exist or is not valid for the
        specified activity.

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


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: session_id
          in: path
          description: The unique session identifier.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve the demo running session data instead of a
            real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Session data successfully retrieved.
          schema:
            required:
              - metrics
              - angles
              - all_timestamps
              - activity
            type: object
            properties:
              metrics:
                description: A dictionary of metric arrays.
                type: object
                additionalProperties:
                  type: number
              angles:
                description: A dictionary of angle arrays.
                type: object
                additionalProperties:
                  type: number
              all_timestamps:
                description: List of timestamps associated with the session.
                type: array
                items:
                  type: number
              analyzed_video_url:
                description: The public URL of the analyzed video.
                type: string
                format: uri
              video_url:
                description: The public URL of the original video.
                type: string
                format: uri
              segments:
                description: The number of segments processed.
                type: integer
              created_at:
                description: Timestamp when the session was created.
                type: object
                properties:
                  date:
                    description: Creation date in DD/MM/YYYY format.
                    type: string
                  time:
                    description: Creation time in HH:MM AM/PM format.
                    type: string
              user_name:
                description: The name of the user associated with this session.
                type: string
              activity:
                description: The type of activity (e.g., 'Running').
                type: string
              title:
                description: The session title.
                type: string
              calculated_metrics:
                description: Computed metrics (average, min, max values) for the session.
                type: object
                additionalProperties:
                  type: number
              summary:
                description: An optional summary of the session.
                type: string
          examples:
            application/json:
              metrics:
                speed:
                  - 2.899
                  - 3.047
                  - 2.905
                cadence:
                  - 173.9
                  - 168.6
                  - 170.2
              angles:
                lelb_angle:
                  - 30
                  - 35
                  - 33
                lhip_angle:
                  - 40
                  - 42
                  - 41
              all_timestamps:
                - 0.033
                - 0.067
                - 0.1
              analyzed_video_url: https://storage.googleapis.com/your-bucket/analyzed_video.mp4
              video_url: https://storage.googleapis.com/your-bucket/original_video.mov
              segments: 3
              created_at:
                date: 19/12/2024
                time: 11:57 PM
              user_name: Lee Jhon
              activity: Running
              title: Session Title
              calculated_metrics:
                speed:
                  avg: 2.95
                  min: 2.899
                  max: 3.047
                cadence:
                  avg: 170.9
                  min: 168.6
                  max: 173.9
                total_distance: 26.509
                total_time: 8.985
              summary: Optional session summary text.
        '400':
          description: Bad Request - Invalid parameters or admin UID.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message explaining the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid admin UID.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that A valid API-KEY token was not provided.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - The user is not authorized to access this session.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error indicating insufficient permissions to access the
                  session data.
                type: string
          examples:
            application/json:
              error: Access denied.
        '404':
          description: >-
            Not Found - The requested session does not exist or the activity is
            not 'Running'.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the session was not found.
                type: string
          examples:
            application/json:
              error: The session does not exist.
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /running/sessions/{session_id}/export/:
    get:
      operationId: running_sessions_export_list
      summary: Export Running Session Data
      description: >-
        Retrieves detailed session data for exporting a specific running session
        identified by the `session_id`.


        ### Path Parameter

        - **session_id** *(string, required)*: The unique identifier of the
        session to export.


        ### Query Parameter

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


        ### Response Structure (HTTP 200)

        The response is a JSON object that includes:


        - **metrics** *(object)*: A dictionary where each key represents a
        metric (e.g., 'speed', 'cadence') and its value is an array of numbers.

        - **keypoints** *(object)*: A dictionary where each key represents a
        keypoint (e.g., 'lknev', 'ltoev') and its value is an array of numbers.

        - **angles** *(object)*: A dictionary where each key represents an angle
        (e.g., 'lelb_angle', 'lhip_angle') and its value is an array of numbers.

        - **all_timestamps** *(array[number])*: An array of timestamps (in
        seconds) corresponding to the data points.

        - **contact** *(array[boolean])*: An array of boolean values indicating
        contact status.

        - **activity** *(string)*: The activity type (e.g., 'Running').


        ### Error Handling

        - **400 Bad Request**: The request parameters are invalid (e.g., an
        invalid admin UID).

        - **401 Unauthorized**: The access token is missing or invalid.

        - **403 Forbidden**: The user does not have sufficient privileges to
        access this session data.

        - **404 Not Found**: The requested session does not exist or is invalid
        for the activity.

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


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: session_id
          in: path
          description: The unique session identifier.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve the pre-generated demo running session
            instead of a real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Session data successfully exported.
          schema:
            required:
              - metrics
              - keypoints
              - angles
              - all_timestamps
              - contact
              - activity
            type: object
            properties:
              metrics:
                description: A dictionary of metric arrays (e.g., speed, cadence, etc.).
                type: object
                additionalProperties:
                  type: number
              keypoints:
                description: A dictionary of keypoint arrays.
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              angles:
                description: A dictionary of angle arrays.
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              all_timestamps:
                description: List of timestamps (in seconds).
                type: array
                items:
                  type: number
              contact:
                description: Array indicating contact status (true/false).
                type: array
                items:
                  type: boolean
              activity:
                description: The activity type (e.g., 'Running').
                type: string
          examples:
            application/json:
              metrics:
                technique:
                  - 0
                  - 0
                  - 0
                push_angle:
                  - 72.035
                  - 71.204
                  - 71.663
                contact_stability:
                  - 0.604
                  - 0.793
                  - 0.511
                power:
                  - 209
                  - 219
                  - 210
              keypoints:
                lknev:
                  - 0.1
                  - 0.2
                  - 0.3
                ltoev:
                  - 0.4
                  - 0.5
                  - 0.6
                relbv:
                  - 0.7
                  - 0.8
                  - 0.9
                rtoey:
                  - 1
                  - 1.1
                  - 1.2
                headv:
                  - 1.3
                  - 1.4
                  - 1.5
              angles:
                lelb_angle:
                  - 30
                  - 35
                  - 33
                lhip_angle:
                  - 40
                  - 42
                  - 41
              all_timestamps:
                - 0.033
                - 0.067
                - 0.1
              contact:
                - false
                - true
                - false
              activity: Running
        '400':
          description: >-
            Bad Request - The request parameters are invalid (e.g., invalid
            admin UID).
          schema:
            type: object
            properties:
              error:
                description: A detailed error message explaining the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid admin UID.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the access token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have sufficient privileges to access
            this session data.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating insufficient permissions.
                type: string
          examples:
            application/json:
              error: Access denied.
        '404':
          description: >-
            Not Found - The requested session does not exist or the activity is
            not valid.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the session was not found.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /running/sessions/{session_id}/form-analysis/:
    post:
      operationId: running_sessions_form-analysis_create
      summary: Running-Form Analysis Report
      description: >-
        Retrieves a detailed running-form analysis report for a given session.
        The endpoint requires the user to have a valid admin token and an active
        subscription plan (Pro, Premium, Enterprise, or Standard).


        ### Request

        - **Path Parameter**:
          - **session_id** *(string, required)*: The unique identifier of the session for which the running-form analysis report is requested.

        - **Query Parameter**:
          - **demo** *(boolean, optional)*: Set to `true` to retrieve a pre-generated demo running-form analysis report instead of a real one.

        ### Response Structure (HTTP 200)

        The response is a JSON object containing:


        - **metrics** *(object)*: Stride-averaged values such as `speed`,
        `balance`, `cadence`, `contact_angle`, `eversion_velocity`,
        `knee_flexion`, `posture_angle`, `ankle_angle`, `com_oscillation`,
        `stride_angle`, `mean_h`.

        - **images** *(object)*: Three representative snapshots keyed
        `contact_angle`, `push_angle`, `knee_ankle`; each value is a public
        image URL.

        - **user_info** *(object)*: Information about the user who submitted the
        session, including:
          - **age** *(integer)*
          - **gender** *(string)*
          - **height** *(number, cm)*
          - **weight** *(number, kg)*
          - **email** *(string, email)*
          - **uid**, **display_name**, **admin_name**, **last_session**, **phone**, **brand**, **shoeModel**, **shoeSize**, **leg_length**, **ycom** *(various types)*

        - **form_comments** *(object, optional)*: GenAI recommendations for
        blocks `contact_angle`, `hip_extension_at_foot_takeoff`,
        `foot_contact_angle_and_torso_lean`.

        - **date** *(string)*: The date the report was generated in DD/MM/YYYY
        format.


        ### Error Handling

        - **400 Bad Request**: Invalid token or parameters.

        - **401 Unauthorized**: Token is missing or invalid.

        - **403 Forbidden**: Admin access is required.

        - **404 Not Found**: The session was not found or the user does not have
        a valid payment plan.

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


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: session_id
          in: path
          description: >-
            The unique identifier of the session for which the running-form
            analysis report is requested.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve a pre-generated demo running-form analysis
            report instead of a real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Running-Form Analysis Report retrieved successfully.
          schema:
            required:
              - metrics
              - images
              - user_info
              - date
            type: object
            properties:
              metrics:
                description: Stride-averaged metrics.
                required:
                  - speed
                  - balance
                  - cadence
                  - contact_angle
                  - eversion_velocity
                  - knee_flexion
                  - posture_angle
                  - ankle_angle
                  - com_oscillation
                  - stride_angle
                  - mean_h
                type: object
                properties:
                  speed:
                    type: number
                  balance:
                    type: number
                  cadence:
                    type: number
                  contact_angle:
                    type: number
                  eversion_velocity:
                    type: number
                  knee_flexion:
                    type: number
                  posture_angle:
                    type: number
                  ankle_angle:
                    type: number
                  com_oscillation:
                    type: number
                  stride_angle:
                    type: number
                  mean_h:
                    type: number
              images:
                description: Three representative frame URLs.
                type: object
                additionalProperties:
                  type: string
                  format: uri
                example:
                  contact_angle: https://storage.googleapis.com/.../contact_angle.png
                  push_angle: https://storage.googleapis.com/.../push_angle.png
                  knee_ankle: https://storage.googleapis.com/.../knee_ankle.png
              user_info:
                description: User information associated with the session.
                required:
                  - age
                  - height
                  - weight
                  - email
                  - uid
                type: object
                properties:
                  age:
                    type: integer
                  gender:
                    type: string
                  height:
                    type: number
                  weight:
                    type: number
                  email:
                    type: string
                    format: email
                  uid:
                    type: string
                  display_name:
                    type: string
                  admin_name:
                    type: string
                  last_session:
                    type: string
                  phone:
                    type: string
                  brand:
                    type: string
                  shoeModel:
                    type: string
                  shoeSize:
                    type: integer
                  leg_length:
                    type: number
                  ycom:
                    type: number
              form_comments:
                description: (Optional) Block-level recommendations.
                type: object
                additionalProperties:
                  type: string
                example:
                  contact_angle: Recommendation …
                  hip_extension_at_foot_takeoff: Recommendation …
                  foot_contact_angle_and_torso_lean: Recommendation …
              date:
                description: Report date in DD/MM/YYYY format.
                type: string
                example: 13/07/2025
        '400':
          description: Bad Request - Invalid token or parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that admin privileges are required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: >-
            Not Found - Session not found or user does not have a valid payment
            plan.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the session was not found or
                  payment plan is invalid.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /running/sessions/{session_id}/form-recommendations/:
    post:
      operationId: running_sessions_form-recommendations_create
      summary: Create Form-Analysis Comment Threads
      description: >-
        Generate GenAI threads that produce personalised commentary for each
        running-form block (contact-angle, hip-extension at foot take-off,
        foot-contact angle & torso lean) **plus** an overall recommendation.
        Returns a mapping from block keys to thread IDs.


        ### Request

        - **session_id** (path parameter, required): The ID of the running
        session for which to generate comment threads.


        ### Response (201)

        A JSON object mapping each form block key to its corresponding GenAI
        thread ID:

        - **contact_angle**: Thread ID for the contact angle block.

        - **push_angle**: Thread ID for the push angle block.

        - **knee_ankle**: Thread ID for the knee-ankle block.

        - **general_form_recommendation**: Thread ID for the overall form
        recommendation.


        ### Error Handling

        - **403 Forbidden**: User lacks a valid payment plan.

        - **404 Not Found**: Session not found or retrieval error.

        - **500 Internal Server Error**: Unexpected server error.


        ### Security

        Requires A valid API-KEY token or API key in the request headers.
      parameters:
        - name: session_id
          in: path
          description: Target session ID
          required: true
          type: string
      responses:
        '201':
          description: Threads created successfully
          schema:
            description: Mapping from form block keys to GenAI thread IDs.
            required:
              - contact_angle
              - push_angle
              - knee_ankle
              - general_form_recommendation
            type: object
            properties:
              contact_angle:
                description: Thread ID for contact angle block.
                type: string
              push_angle:
                description: Thread ID for push angle block.
                type: string
              knee_ankle:
                description: Thread ID for knee-ankle block.
                type: string
              general_form_recommendation:
                description: Thread ID for overall form recommendation.
                type: string
            example:
              contact_angle: thread_abc123
              push_angle: thread_def456
              knee_ankle: thread_ghi789
              general_form_recommendation: thread_jkl012
        '403':
          description: User lacks a valid payment plan
          schema:
            type: object
            properties:
              error:
                type: string
            example:
              error: User does not have a valid payment plan
        '404':
          description: Session not found or other retrieval error
          schema:
            type: object
            properties:
              error:
                type: string
            example:
              error: Session not found
        '500':
          description: Unexpected server error
          schema:
            type: object
            properties:
              error:
                type: string
            example:
              error: Internal server error.
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /running/sessions/{session_id}/gait-analysis/:
    post:
      operationId: running_sessions_gait-analysis_create
      summary: Gait Analysis Report
      description: >-
        Retrieves a detailed gait analysis report for a given session. The
        endpoint requires the user to have a valid admin token and an active
        subscription plan (Pro, Premium, Enterprise, or Standard).


        ### Request

        - **Path Parameter**:
          - **session_id** *(string, required)*: The unique identifier of the session for which the gait analysis report is requested.

        - **Query Parameter**:
          - **demo** *(boolean, optional)*: Set to `true` to retrieve a pre-generated demo gait analysis report instead of a real one.

        ### Response Structure (HTTP 200)

        The response is a JSON object containing:


        - **left** *(object)* and **right** *(object)*: Each side contains gait
        analysis data with the following fields:
          - **peak_time** *(number)*: The peak time value identified in the gait analysis.
          - **initiator** *(string)*: Indicates which side initiated the gait cycle.
          - **phases** *(object)*: An object with named phases (e.g., `flight`, `takeoff`, `mid_stance`, `strike`, `new_strike`), where each phase contains:
            - **video_frame** *(integer)*: The corresponding video frame.
            - **graph_phase** *(integer)*: The phase value used in graphs.
            - **video_phase** *(integer)*: The phase value in video timeline.
            - **image_url** *(string, URI)*: Public image URL for the phase snapshot.
          - **angles** *(object)*: Angle measurements for joints like `posture_angle`, `lhip_angle`, etc. Each includes:
            - **current** *(array[number])*: Current frame angle values.
            - **next** *(array[number])*: Next predicted values.
            - **std_dev** *(array[number])*: Standard deviation values.
          - **graph_timestamps** *(array[number])*: Timestamps (ms) aligned with graph data.

        - **user_info** *(object)*: Information about the user who submitted the
        session, including:
          - **age** *(integer)*
          - **gender** *(string)*
          - **height** *(number, cm)*
          - **weight** *(number, kg)*
          - **email** *(string, email)*
          - **uid**, **display_name**, **admin_name**, **last_session**, **session_count**, **phone**, **brand**, **shoeModel**, **shoeSize**, **leg_length**, **ycom** *(various types)*

        - **report_comments** *(object, optional)*: Suggestions or notes for
        angles such as `right_posture_angle`, `left_knee_angle`, etc.

        - **date** *(string)*: The date the report was generated in DD/MM/YYYY
        format.


        ### Error Handling

        - **400 Bad Request**: Invalid token or parameters.

        - **401 Unauthorized**: Token is missing or invalid.

        - **403 Forbidden**: Admin access is required.

        - **404 Not Found**: The session was not found or the user does not have
        a valid payment plan.

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


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: session_id
          in: path
          description: >-
            The unique identifier of the session for which the gait analysis
            report is requested.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve a pre-generated demo gait analysis report
            instead of a real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Gait Analysis Report retrieved successfully.
          schema:
            required:
              - left
              - right
              - user_info
              - date
            type: object
            properties:
              left:
                description: Gait analysis data for the left side.
                required:
                  - peak_time
                  - phases
                  - initiator
                  - angles
                  - graph_timestamps
                type: object
                properties:
                  peak_time:
                    type: number
                  phases:
                    description: Phases of the gait cycle with video and graph data.
                    type: object
                    properties:
                      flight:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                      takeoff:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                      mid_stance:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                      new_strike:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                      strike:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                  initiator:
                    type: string
                  angles:
                    type: object
                  graph_timestamps:
                    type: array
                    items:
                      type: number
              right:
                description: Gait analysis data for the right side.
                required:
                  - peak_time
                  - phases
                  - initiator
                  - angles
                  - graph_timestamps
                type: object
                properties:
                  peak_time:
                    type: number
                  phases:
                    description: Phases of the gait cycle with video and graph data.
                    type: object
                    properties:
                      flight:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                      takeoff:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                      mid_stance:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                      new_strike:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                      strike:
                        required:
                          - video_frame
                          - graph_phase
                          - video_phase
                          - image_url
                        type: object
                        properties:
                          video_frame:
                            type: integer
                          graph_phase:
                            type: integer
                          video_phase:
                            type: integer
                          image_url:
                            type: string
                            format: uri
                  initiator:
                    type: string
                  angles:
                    type: object
                  graph_timestamps:
                    type: array
                    items:
                      type: number
              user_info:
                description: User information associated with the session.
                required:
                  - age
                  - height
                  - weight
                  - email
                  - uid
                type: object
                properties:
                  age:
                    type: integer
                  gender:
                    type: string
                  height:
                    type: number
                  weight:
                    type: number
                  email:
                    type: string
                    format: email
                  uid:
                    type: string
                  display_name:
                    type: string
                  admin_name:
                    type: string
                  last_session:
                    type: string
                  session_count:
                    type: number
                  phone:
                    type: string
                  brand:
                    type: string
                  shoeModel:
                    type: string
                  shoeSize:
                    type: integer
                  leg_length:
                    type: number
                  ycom:
                    type: number
              report_comments:
                description: (Optional) Recommendations for joint angles.
                type: object
              date:
                description: The date of the gait analysis report in DD/MM/YYYY format.
                type: string
          examples:
            application/json:
              left:
                peak_time: 0
                phases:
                  flight:
                    video_frame: 116
                    graph_phase: 275
                    video_phase: 165
                    image_url: https://storage.googleapis.com/.../left/flight.png
                  takeoff:
                    video_frame: 113
                    graph_phase: 175
                    video_phase: 145
                    image_url: https://storage.googleapis.com/.../left/takeoff.png
                  mid_stance:
                    video_frame: 112
                    graph_phase: 140
                    video_phase: 138
                    image_url: https://storage.googleapis.com/.../left/mid_stance.png
                  new_strike:
                    video_frame: 119
                    graph_phase: 370
                    video_phase: 184
                    image_url: https://storage.googleapis.com/.../left/new_strike.png
                  strike:
                    video_frame: 107
                    graph_phase: 0
                    video_phase: 110
                    image_url: https://storage.googleapis.com/.../left/strike.png
                initiator: left
                angles:
                  posture_angle:
                    current:
                      - 6.64
                      - 6.65
                      - 6.66
                    next:
                      - 7.74
                      - 7.76
                      - 7.78
                    std_dev:
                      - 0.91
                      - 0.92
                      - 0.93
                graph_timestamps:
                  - 0
                  - 5
                  - 10
              right:
                peak_time: 70
                phases:
                  flight:
                    video_frame: 106
                    graph_phase: 280
                    video_phase: 100
                    image_url: https://storage.googleapis.com/.../right/flight.png
                  takeoff:
                    video_frame: 104
                    graph_phase: 230
                    video_phase: 90
                    image_url: https://storage.googleapis.com/.../right/takeoff.png
                  mid_stance:
                    video_frame: 101
                    graph_phase: 130
                    video_phase: 70
                    image_url: https://storage.googleapis.com/.../right/mid_stance.png
                  new_strike:
                    video_frame: 107
                    graph_phase: 330
                    video_phase: 110
                    image_url: https://storage.googleapis.com/.../right/new_strike.png
                  strike:
                    video_frame: 98
                    graph_phase: 0
                    video_phase: 44
                    image_url: https://storage.googleapis.com/.../right/strike.png
                initiator: right
                angles:
                  posture_angle:
                    current:
                      - 7.39
                      - 7.38
                      - 7.37
                    next:
                      - 6.64
                      - 6.65
                      - 6.66
                    std_dev:
                      - 0.49
                      - 0.5
                      - 0.51
                graph_timestamps:
                  - 0
                  - 5
                  - 10
              user_info:
                age: 20
                gender: male
                height: 180
                weight: 80
                email: example@gmail.com
                uid: pijd32df3j2d3f2j2
                display_name: Simple User
                admin_name: Admin User
                last_session: '2025-06-11'
                session_count: 12
                shoeSize: 7
                leg_length: 0.9747
                ycom: 1.026
              report_comments:
                right_posture_angle: >-
                  Simple User's right posture angle is stable but should be
                  improved with core exercises.
              date: 11/06/2025
        '400':
          description: Bad Request - Invalid token or parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that admin privileges are required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: >-
            Not Found - Session not found or user does not have a valid payment
            plan.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the session was not found or
                  payment plan is invalid.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /running/sessions/{session_id}/recommendation/:
    post:
      operationId: running_sessions_recommendation_create
      summary: Create Gait Analysis Recommendations Threads
      description: >-
        ### Create Gait Analysis Recommendations Threads


        This endpoint generates personalized recommendation threads for a
        specific session based on the user's running gait analysis. Each thread
        offers biomechanical insights, posture tips, and training guidance for
        different joint angles.


        **Usage Example:**

        Send a `POST` request to
        `/running/sessions/{session_id}/recommendation/` where `{session_id}` is
        the session’s unique identifier.


        **Parameters:**

        - `session_id` *(string, required)*: The unique ID of the session to
        generate threads for.


        **Response Structure (HTTP 201):**

        Returns a JSON object mapping each gait angle metric to a thread ID,
        including both left and right sides:

        - **left_posture_angle**, **left_hip_angle**, **left_knee_angle**,
        **left_ankle_angle**

        - **right_posture_angle**, **right_hip_angle**, **right_knee_angle**,
        **right_ankle_angle**


        **Notes:**

        - The session must be valid and correspond to a gait analysis report.

        - Requires an active payment plan (Pro, Premium, Enterprise, or
        Standard).
      parameters:
        - name: session_id
          in: path
          description: The unique identifier of the session.
          required: true
          type: string
      responses:
        '201':
          description: Threads created successfully.
          schema:
            description: A dictionary mapping gait analysis metrics to thread IDs.
            required:
              - left_hip_angle
              - left_posture_angle
              - left_ankle_angle
              - left_knee_angle
              - right_posture_angle
              - right_knee_angle
              - right_hip_angle
              - right_ankle_angle
            type: object
            properties:
              left_hip_angle:
                description: Thread ID for the left hip angle recommendations.
                type: string
              left_posture_angle:
                description: Thread ID for the left posture angle recommendations.
                type: string
              left_ankle_angle:
                description: Thread ID for the left ankle angle recommendations.
                type: string
              left_knee_angle:
                description: Thread ID for the left knee angle recommendations.
                type: string
              right_posture_angle:
                description: Thread ID for the right posture angle recommendations.
                type: string
              right_knee_angle:
                description: Thread ID for the right knee angle recommendations.
                type: string
              right_hip_angle:
                description: Thread ID for the right hip angle recommendations.
                type: string
              right_ankle_angle:
                description: Thread ID for the right ankle angle recommendations.
                type: string
          examples:
            application/json:
              left_hip_angle: thread_bzU869ggmuATEs2lX7Tl8mPp
              left_posture_angle: thread_2W6ZbA8TmAIscNPmZpY3z24p
              left_ankle_angle: thread_RlBp9Wzo0DkTWWBaLyF9cllJ
              left_knee_angle: thread_iqZ3pJBn86eqok3vw9x8Dv5E
              right_posture_angle: thread_ktbEoLWoCJsGNNSYVHfOAYNH
              right_knee_angle: thread_Q6NADbLhGrGedhUh6BeqdbXD
              right_hip_angle: thread_UtDug6am5H8h5thg04fAH3w0
              right_ankle_angle: thread_VYMXUKkBdoNBAej6haqwVpNn
        '400':
          description: Bad Request - Invalid token or parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that admin privileges are required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: >-
            Not Found - Session not found or user does not have a valid payment
            plan.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the session was not found or
                  payment plan is invalid.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /running/sessions/{session_id}/summary/:
    get:
      operationId: running_sessions_summary_list
      summary: Get Summary of a Running Session
      description: >-
        Retrieve a detailed summary of a running session using its unique
        `session_id`. This summary includes both quantitative performance
        metrics and an optional qualitative summary generated by GenAI if
        available.


        **Usage Instructions:**

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

        2. The endpoint will return a JSON object that includes various sections
        of the session summary.


        ### Query Parameter

        - **demo** *(boolean, optional)*: Set to `true` to retrieve a
        pre-generated demo summary for this running session.


        **Response Structure:**


        - **summary_text** *(object, optional)*: Contains GenAI-generated
        commentary if available. This object may include the following keys:
            - **balance_and_posture**: Comments on the athlete's balance and posture (e.g. suggestions to improve running balance).
            - **performance_metrics**: Overall performance comments such as changes in speed, cadence, and power output.
            - **running_mechanics**: Observations on running form, including contact time, flight time, stride time, and stride length.
            - **final_summary**: A final overall assessment remark summarizing the session performance.
            - **distance_and_duration**: Comments on the total distance covered and session duration.

        - **performance_metrics** *(object)*: Contains aggregated performance
        metrics with their minimum, maximum, average values, and the raw data as
        an array, covering the following:
            - **speed** (in m/s)
            - **pace** (in min/km)
            - **cadence** (steps/min)
            - **power** (in Watts)
            - **normalized_power** (in W/kg)

        - **running_mechanics** *(object)*: Contains the following running
        mechanics data:
            - **contact_time** (in seconds)
            - **flight_time** (in seconds)
            - **stride_time** (in seconds)
            - **stride_length** (in meters)
            - **footstrike**: A string describing the most common footstrike type (e.g. 'forefoot').

        - **balance_and_posture** *(object)*: Contains metrics related to
        balance and posture:
            - **balance**: Includes minimum, maximum, average, and array of balance scores.
            - **contact_angle**: Includes the minimum, maximum, average, and array of contact angle values (in degrees).

        - **distance_and_duration** *(object)*: Contains raw values for:
            - **total_distance** (in meters)
            - **total_time** (in seconds)

        - **user_information** *(object)*: Contains detailed user data,
        including:
            - **ycom**: User's YCOM value
            - **weight**: User's weight in kilograms
            - **age**: User's age
            - **height**: User's height in centimeters
            - **leg_length**: User's leg length
            - **shoeSize**: User's shoe size
            - **gender**: User's gender
            - **user**: The unique user ID
            - **brand**: Shoe brand information (if any)
            - **shoeModel**: Shoe model information (if any)
            - **email**: User's email address
            - **display_name**: User's display name

        - **session_date** *(string)*: The date of the session in a formatted
        string (e.g. 'DD/MM/YYYY').


        **Note:** The `summary_text` field will only be present if
        GenAI-generated summary comments have been saved for the session.
      parameters:
        - name: session_id
          in: path
          description: The unique identifier of the session
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve a pre-generated demo summary for this
            running session.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved session summary
          schema:
            required:
              - summary_text
              - performance_metrics
              - running_mechanics
              - balance_and_posture
              - distance_and_duration
              - user_information
              - session_date
            type: object
            properties:
              summary_text:
                description: >-
                  Optional textual summary of the session (only present if GenAI
                  comments are available).
                type: object
                properties:
                  balance_and_posture:
                    description: Comments regarding the athlete's balance and posture.
                    type: string
                  performance_metrics:
                    description: >-
                      Comments on speed, cadence, power, and overall
                      performance.
                    type: string
                  running_mechanics:
                    description: >-
                      Comments on running mechanics, including contact and
                      flight times, and stride details.
                    type: string
                  final_summary:
                    description: Overall concluding summary of the session.
                    type: string
                  distance_and_duration:
                    description: >-
                      Summary commentary on the total distance and duration of
                      the session.
                    type: string
              performance_metrics:
                type: object
                properties:
                  speed:
                    type: object
                    properties:
                      min:
                        description: Minimum speed (m/s)
                        type: number
                      max:
                        description: Maximum speed (m/s)
                        type: number
                      avg:
                        description: Average speed (m/s)
                        type: number
                      values:
                        description: Array of individual speed values
                        type: array
                        items:
                          type: number
                  pace:
                    type: object
                    properties:
                      min:
                        description: Minimum pace (min/km)
                        type: number
                      max:
                        description: Maximum pace (min/km)
                        type: number
                      avg:
                        description: Average pace (min/km)
                        type: number
                      values:
                        description: Array of individual pace values
                        type: array
                        items:
                          type: number
                  cadence:
                    type: object
                    properties:
                      min:
                        description: Minimum cadence (steps/min)
                        type: number
                      max:
                        description: Maximum cadence (steps/min)
                        type: number
                      avg:
                        description: Average cadence (steps/min)
                        type: number
                      values:
                        description: Array of individual cadence values
                        type: array
                        items:
                          type: number
                  power:
                    type: object
                    properties:
                      min:
                        description: Minimum power (W)
                        type: number
                      max:
                        description: Maximum power (W)
                        type: number
                      avg:
                        description: Average power (W)
                        type: number
                      values:
                        description: Array of individual power values
                        type: array
                        items:
                          type: number
                  normalized_power:
                    type: object
                    properties:
                      min:
                        description: Minimum normalized power (W/kg)
                        type: number
                      max:
                        description: Maximum normalized power (W/kg)
                        type: number
                      avg:
                        description: Average normalized power (W/kg)
                        type: number
                      values:
                        description: Array of individual normalized power values
                        type: array
                        items:
                          type: number
              running_mechanics:
                type: object
                properties:
                  contact_time:
                    type: object
                    properties:
                      min:
                        description: Minimum contact time (s)
                        type: number
                      max:
                        description: Maximum contact time (s)
                        type: number
                      avg:
                        description: Average contact time (s)
                        type: number
                      values:
                        description: Array of contact time values
                        type: array
                        items:
                          type: number
                  flight_time:
                    type: object
                    properties:
                      min:
                        description: Minimum flight time (s)
                        type: number
                      max:
                        description: Maximum flight time (s)
                        type: number
                      avg:
                        description: Average flight time (s)
                        type: number
                      values:
                        description: Array of flight time values
                        type: array
                        items:
                          type: number
                  stride_time:
                    type: object
                    properties:
                      min:
                        description: Minimum stride time (s)
                        type: number
                      max:
                        description: Maximum stride time (s)
                        type: number
                      avg:
                        description: Average stride time (s)
                        type: number
                      values:
                        description: Array of stride time measurements
                        type: array
                        items:
                          type: number
                  stride_length:
                    type: object
                    properties:
                      min:
                        description: Minimum stride length (m)
                        type: number
                      max:
                        description: Maximum stride length (m)
                        type: number
                      avg:
                        description: Average stride length (m)
                        type: number
                      values:
                        description: Array of stride length measurements
                        type: array
                        items:
                          type: number
                  footstrike:
                    description: The most common footstrike type (e.g. 'forefoot')
                    type: string
              balance_and_posture:
                type: object
                properties:
                  balance:
                    type: object
                    properties:
                      min:
                        description: Minimum running balance score
                        type: number
                      max:
                        description: Maximum running balance score
                        type: number
                      avg:
                        description: Average running balance score
                        type: number
                      values:
                        description: Array of running balance values
                        type: array
                        items:
                          type: number
                  contact_angle:
                    type: object
                    properties:
                      min:
                        description: Minimum contact angle (degrees)
                        type: number
                      max:
                        description: Maximum contact angle (degrees)
                        type: number
                      avg:
                        description: Average contact angle (degrees)
                        type: number
                      values:
                        description: Array of contact angle values
                        type: array
                        items:
                          type: number
              distance_and_duration:
                type: object
                properties:
                  total_distance:
                    description: Total distance covered (m)
                    type: number
                  total_time:
                    description: Total duration of the session (s)
                    type: number
              user_information:
                description: Detailed user information from the session data.
                type: object
                properties:
                  ycom:
                    description: User's YCOM value
                    type: number
                  weight:
                    description: User's weight (kg)
                    type: number
                  age:
                    description: User's age
                    type: string
                  height:
                    description: User's height (cm)
                    type: number
                  leg_length:
                    description: User's leg length (m)
                    type: number
                  shoeSize:
                    description: User's shoe size
                    type: number
                  gender:
                    description: User's gender
                    type: string
                  user:
                    description: Unique user identifier
                    type: string
                  brand:
                    description: Preferred shoe brand (if available)
                    type: string
                  shoeModel:
                    description: Shoe model (if available)
                    type: string
                  email:
                    description: User's email address
                    type: string
                  display_name:
                    description: User's display name
                    type: string
              session_date:
                description: Formatted date of the session (e.g., '07/04/2025')
                type: string
          examples:
            application/json:
              summary_text:
                balance_and_posture: >-
                  For Ahror, focus on enhancing balance and posture through
                  specific drills. Incorporate single-leg balance exercises and
                  stability training to improve your Running Balance, aiming for
                  a minimum of 50. Practice form drills like high knees and butt
                  kicks to refine your Contact Angle, targeting at least 86
                  degrees. Regular yoga or Pilates can also help in developing
                  core strength and overall stability.
                performance_metrics: >-
                  For Ahror Jabborov, focus on improving speed and power output
                  during runs. To achieve a faster pace, aim to reach a cadence
                  of at least 165 steps/min, along with increasing power above
                  240 W. Incorporate interval training and hill sprints to
                  enhance speed and normalized power above 3.2 W/kg.
                running_mechanics: >-
                  To enhance your running mechanics, Ahror, focus on optimizing
                  your contact time, which currently averages 0.258 s. Aim to
                  reduce it below 0.25 s for improved efficiency. Additionally,
                  work on increasing your flight time above the excellent
                  threshold of 0.115 s. Strive to achieve a stride length of at
                  least 0.72 m to maximize propulsion while maintaining an ideal
                  stride time of 0.37 s or less for better pacing.
                final_summary: >-
                  Ahror, you exhibit excellent running metrics, particularly in
                  speed, cadence, and power output, indicating a solid
                  foundation for performance. Your average pace of 6.14 min/km
                  and normalized power of 3.086 W/kg reflect strong endurance
                  and efficiency. However, focus on improving your stride time,
                  currently averaging 0.369 s, which may enhance overall
                  efficiency and speed. Incorporating drills like high-knee
                  sprints or stride-outs can help to refine your mechanics.
                  Additionally, maintaining a balanced and consistent training
                  regimen while monitoring your contact and flight times will
                  support injury prevention and recovery, ensuring sustained
                  progress in your running.
                distance_and_duration: >-
                  For Ahror Jabborov, given a total distance of 81.33 km over
                  29.95 hours, maintain a consistent weekly mileage of around
                  60-70 km, ensuring at least one long run to build endurance.
                  Incorporate rest days and vary intensity to enhance recovery
                  and overall performance, optimizing distance and duration for
                  injury prevention.
              performance_metrics:
                speed:
                  min: 2.627
                  max: 2.833
                  avg: 2.7157
                  values:
                    - 2.651
                    - 2.63
                    - 2.627
                    - 2.714
                    - 2.737
                    - 2.735
                    - 2.833
                    - 2.76
                    - 2.721
                    - 2.749
                pace:
                  min: 5.883
                  max: 6.344
                  avg: 6.1402
                  values:
                    - 6.287
                    - 6.337
                    - 6.344
                    - 6.141
                    - 6.089
                    - 6.094
                    - 5.883
                    - 6.039
                    - 6.125
                    - 6.0628
                cadence:
                  min: 160.4
                  max: 165.1
                  avg: 162.43
                  values:
                    - 161.8
                    - 164
                    - 165.1
                    - 164
                    - 161.1
                    - 160.4
                    - 161.8
                    - 161.1
                    - 162.5
                    - 162.5
                power:
                  min: 219
                  max: 242
                  avg: 231.4
                  values:
                    - 227
                    - 222
                    - 219
                    - 229
                    - 235
                    - 237
                    - 242
                    - 237
                    - 232
                    - 234
                normalized_power:
                  min: 2.93
                  max: 3.22
                  avg: 3.086
                  values: []
              running_mechanics:
                contact_time:
                  min: 0.2525
                  max: 0.265
                  avg: 0.258001
                  values:
                    - 0.25917
                    - 0.25667
                    - 0.265
                    - 0.25833
                    - 0.25917
                    - 0.255
                    - 0.25667
                    - 0.26083
                    - 0.25667
                    - 0.2525
                flight_time:
                  min: 0.09833
                  max: 0.11917
                  avg: 0.111418
                  values:
                    - 0.11167
                    - 0.10917
                    - 0.09833
                    - 0.1075
                    - 0.11333
                    - 0.11917
                    - 0.11417
                    - 0.11167
                    - 0.1125
                    - 0.11667
                stride_time:
                  min: 0.36333
                  max: 0.37417
                  avg: 0.369416
                  values:
                    - 0.37083
                    - 0.36583
                    - 0.36333
                    - 0.36583
                    - 0.3725
                    - 0.37417
                    - 0.37083
                    - 0.3725
                    - 0.36917
                    - 0.36917
                stride_length:
                  min: 0.6750421
                  max: 0.72714611
                  avg: 0.70057
                  values:
                    - 0.68706
                    - 0.6750421
                    - 0.696155
                    - 0.70110762
                    - 0.70934829
                    - 0.697425
                    - 0.72714611
                    - 0.7198908
                    - 0.69839907
                    - 0.6941225
                footstrike: forefoot
              balance_and_posture:
                balance:
                  min: 46.23
                  max: 49.83
                  avg: 47.587
                  values:
                    - 46.95
                    - 46.75
                    - 46.23
                    - 47.42
                    - 47.91
                    - 48.04
                    - 47.73
                    - 46.96
                    - 48.05
                    - 49.83
                contact_angle:
                  min: 83.731
                  max: 86.554
                  avg: 85.4171
                  values:
                    - 86.554
                    - 85.834
                    - 85.613
                    - 85.555
                    - 84.975
                    - 86.548
                    - 86.155
                    - 83.731
                    - 84.204
                    - 85.002
              distance_and_duration:
                total_distance: 81.333
                total_time: 29.95
              user_information:
                ycom: 0.979
                weight: 75
                age: '28'
                height: 178
                leg_length: 0.93
                shoeSize: 9.5
                gender: ''
                user: pkihvA0wBphODJpq79ojYqSi1rF3
                brand: ''
                shoeModel: ''
                email: ahror@aikynetix.com
                display_name: Ahror Jabborov
              session_date: 07/04/2025
        '400':
          description: Bad Request - Invalid token or parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that admin privileges are required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: >-
            Not Found - Session not found or user does not have a valid payment
            plan.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the session was not found or
                  payment plan is invalid.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: running_sessions_summary_create
      summary: Generate Summary for a Running Session
      description: >-
        Trigger the generation of summary threads for a running session. This
        endpoint creates separate summary threads for each summary block based
        on session metrics, including performance metrics, running mechanics,
        balance and posture, and distance/duration, as well as a final overall
        summary. Returns a JSON object containing thread IDs for each summary
        block.
      parameters:
        - name: session_id
          in: path
          description: The unique identifier of the session
          required: true
          type: string
        - name: measurement_system
          in: query
          description: 'Measurement system: ''metric'' or ''imperial'''
          required: false
          type: string
          enum:
            - metric
            - imperial
          default: metric
      responses:
        '201':
          description: Summary threads generated successfully.
          schema:
            type: object
            additionalProperties:
              description: Thread ID corresponding to a summary block
              type: string
            example:
              performance_metrics: thread_id_1
              running_mechanics: thread_id_2
              balance_and_posture: thread_id_3
              final_summary: thread_id_5
        '400':
          description: Bad Request - Invalid token or parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that admin privileges are required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: >-
            Not Found - Session not found or user does not have a valid payment
            plan.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the session was not found or
                  payment plan is invalid.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - running
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  
  /session-management/sessions/:
    get:
      operationId: session-management_sessions_list
      summary: Retrieve User Sessions
      description: >-
        Retrieves all sessions for the authenticated user, ordered by
        `created_at` in descending order.


        ### Response Structure


        On success (HTTP 200), the response is a JSON object containing:


        ```json

        {
          "sessions": {
            "<session_id>": {
              "created_at": {
                "date": "DD/MM/YYYY",
                "time": "HH:MM AM/PM"
              },
              "video_url": "...",
              "segments": <number>,
              "analyzed_video_url": "...",
              "activity": "...",
              "title": "...",
              "user_id": "...",
              "user_name": "...",
              "report_comments": {...},
              "metrics": {...}
              // other session fields
            },
            "...": {...}
          }
        }

        ```


        ### Error Handling

        - **400 Bad Request**: Invalid parameters (e.g., missing or malformed
        token).

        - **401 Unauthorized**: The token is missing or invalid.

        - **403 Forbidden**: The user lacks admin privileges.

        - **404 Not Found**: Unable to retrieve sessions (e.g., no sessions
        found).

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


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters: []
      responses:
        '200':
          description: User sessions retrieved successfully.
          schema:
            type: object
            properties:
              sessions:
                description: A dictionary of sessions keyed by their session IDs.
                type: object
                additionalProperties:
                  type: object
          examples:
            application/json:
              sessions:
                5d5c8d7fcd6945f2936ced84f9a20562:
                  video_url: ...
                  analyzed_video_url: ...
                  segments: 10
                  created_at:
                    date: 10/01/2025
                    time: 04:39 PM
                  exercise: clean_and_jerk
                  user_name: Lee Jhon
                  report_comments: {}
                  activity: Weightlifting
                  user_id: JDis9d2k3h4j5k6l7m8nD
                  title: new-test-w
                  metrics: {}
                eb10229c6bf04c4394b547201d1a96f7:
                  video_url: ...
                  analyzed_video_url: ...
                  segments: 5
                  created_at:
                    date: 26/12/2024
                    time: 08:48 PM
                  user_name: Suzan
                  activity: Vertical Jump
                  user_id: hLT10sKbCumCUIsNAk3h
                  title: djias-jump
                  report_comments: {}
                  metrics: {}
        '400':
          description: Bad Request - Invalid parameters or missing token.
          schema:
            type: object
            properties:
              error:
                description: Explanation of the bad request.
                type: string
          examples:
            application/json:
              error: Invalid or missing token.
        '401':
          description: Unauthorized - The token is missing or invalid.
          schema:
            type: object
            properties:
              error:
                description: Error message for authentication failure.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - The user lacks the required privileges.
          schema:
            type: object
            properties:
              error:
                description: User is not permitted to access sessions.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - Sessions could not be retrieved (e.g., none found).
          schema:
            type: object
            properties:
              error:
                description: Error message if sessions are not found.
                type: string
          examples:
            application/json:
              error: No sessions found for this user.
        '500':
          description: Internal Server Error - An unexpected issue occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message for server-side failures.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error>'
      tags:
        - session-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /session-management/sessions/by-ids/:
    post:
      operationId: session-management_sessions_by-ids_create
      summary: Fetch Sessions by IDs
      description: >-
        Retrieve detailed session data for a list of session IDs. This endpoint
        is used when the client already has specific session IDs (e.g., from
        saved reports or analytics) and wants to retrieve their complete data.


        ### Request Body

        - **session_ids** *(required)*: A list of session document IDs to fetch.


        ### Security

        Requires Bearer Token in the `Authorization` header.


        ### Errors

        - **400 Bad Request**: Invalid input.

        - **401 Unauthorized**: Missing or invalid token.

        - **403 Forbidden**: The user is not authorized.

        - **500 Internal Server Error**: An unexpected error occurred.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            required:
              - session_ids
            type: object
            properties:
              session_ids:
                description: List of session document IDs to retrieve.
                type: array
                items:
                  type: string
      responses:
        '200':
          description: Sessions retrieved successfully.
          schema:
            type: object
            properties:
              sessions:
                description: Dictionary of session data keyed by session ID.
                type: object
                additionalProperties:
                  type: object
                  properties:
                    session_id:
                      type: string
                    activity:
                      type: string
                    created_at:
                      type: string
                      format: date-time
                    uploaded_date:
                      type: string
                      format: date-time
                    video_url:
                      type: string
                      format: uri
                    thumbnail_url:
                      type: string
                      format: uri
                    analyzed_video_url:
                      type: string
                      format: uri
                    title:
                      type: string
                    user_id:
                      type: string
                    user_name:
                      type: string
                    uploaded_name:
                      type: string
                    uploaded_uid:
                      type: string
                    user_status:
                      type: string
                    video_status:
                      type: string
                      enum:
                        - Processed
                        - Failed
                    exercise:
                      description: Exercise name (optional, only for certain activities).
                      type: string
          examples:
            application/json:
              sessions:
                c896d6d700894e268ab76e0e271a2f79:
                  session_id: c896d6d700894e268ab76e0e271a2f79
                  activity: Weightlifting
                  created_at: '2025-05-21T20:00:00Z'
                  uploaded_date: '2025-05-21T20:00:00Z'
                  video_url: https://storage.googleapis.com/.../clean.MOV
                  thumbnail_url: https://storage.googleapis.com/.../thumbnail.jpg
                  analyzed_video_url: https://storage.googleapis.com/.../analyzed_video.mp4
                  title: pip
                  user_id: MamqGb2NxgTfyyjCntHi
                  user_name: Natalia Alioth
                  uploaded_name: Emma Watson
                  uploaded_uid: 7GTtytPMT9cPOpBtr0Hq6it2ZzG3
                  user_status: user
                  exercise: clean_and_jerk
                  video_status: Processed
                37ed720f1e9a4a168784137b637fc1b4:
                  session_id: 37ed720f1e9a4a168784137b637fc1b4
                  activity: Vertical Jump
                  created_at: '2025-05-21T20:00:00Z'
                  uploaded_date: '2025-05-21T20:00:00Z'
                  video_url: https://storage.googleapis.com/.../jump.mov
                  thumbnail_url: https://storage.googleapis.com/.../thumbnail.jpg
                  analyzed_video_url: https://storage.googleapis.com/.../analyzed_video.mp4
                  title: anton-jump
                  user_id: nnzlRZX8Z1ubyDh3aguE
                  user_name: Suzan
                  uploaded_name: Oliver Kent
                  uploaded_uid: 7GTtytPMT9cPOpBtr0Hq6it2ZzG3
                  user_status: user
                  video_status: Processed
        '400':
          description: Bad Request - session_ids missing or invalid.
          schema:
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: session_ids must be a non-empty list
        '401':
          description: Unauthorized - No token provided.
          schema:
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User is not an admin.
          schema:
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '500':
          description: Internal Server Error - Something went wrong on the server.
          schema:
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: ''some internal error'''
      tags:
        - session-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /session-management/sessions/filter/:
    get:
      operationId: session-management_sessions_filter_list
      summary: Fetch Filtered Sessions
      description: >-
        Retrieves user sessions filtered by optional parameters such as date
        range, activity type, title, or user ID. It also supports pagination via
        `start_after_id` or `end_before_id` when no filters are applied.


        ### Query Parameters

        - **start_after_id** *(string, optional)*: Session ID after which to
        start pagination. Used only if no filters are set.

        - **end_before_id** *(string, optional)*: Session ID before which to end
        pagination. Used only if no filters are set.

        - **limit** *(integer, optional)*: Maximum number of sessions to fetch
        (default=10).

        - **activity** *(string, optional)*: Filter by activity type (e.g.,
        'Running', 'Vertical Jump').

        - **start_date** *(string, optional, format: dd/mm/yyyy)*: Filter
        sessions created on or after this date.

        - **end_date** *(string, optional, format: dd/mm/yyyy)*: Filter sessions
        created on or before this date.

        - **title** *(string, optional)*: Filter by sessions whose title
        contains this substring (case-insensitive).

        - **user_id** *(string, optional)*: Filter by user ID stored in the
        session.

        | **uploaded_by** | string | **NEW**&nbsp;UID that uploaded the raw
        video. |

        | **video_status** | string `processed\|failed` | **NEW** current state.
        |


        ### Response Structure (HTTP 200)


        On success, the response is a JSON object containing:

        - **query_count** *(integer)*: The total number of matching sessions.

        - **sessions** *(object)*: A dictionary of session documents keyed by
        their session IDs.

        - **first_doc_id** *(string or null)*: The ID of the first document in
        the returned set.

        - **last_doc_id** *(string or null)*: The ID of the last document in the
        returned set.


        Each session object may include fields such as `video_url`, `activity`,
        `created_at`, `title`, etc., plus nested data (e.g. `report_comments`,
        `metrics`). Note that `created_at` is returned as a nested object with
        `date` and `time`.


        ### Error Handling


        - **400 Bad Request**: Invalid parameters (e.g., malformed date string)
        or missing user token.

        - **401 Unauthorized**: The token is missing or invalid.

        - **403 Forbidden**: The user lacks admin privileges.

        - **404 Not Found**: No matching sessions found.

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


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: start_after_id
          in: query
          description: >-
            Session ID after which to start pagination (only used if no filters
            are set).
          required: false
          type: string
        - name: end_before_id
          in: query
          description: >-
            Session ID before which to end pagination (only used if no filters
            are set).
          required: false
          type: string
        - name: limit
          in: query
          description: Maximum number of sessions to fetch (default=10).
          required: false
          type: integer
        - name: activity
          in: query
          description: >-
            Activity type filter (e.g., 'Running', 'Weightlifting', 'Vertical
            Jump', or 'Mobility Assessment').
          required: false
          type: string
          enum:
            - Running
            - Weightlifting
            - Vertical Jump
            - Mobility Assessment
        - name: start_date
          in: query
          description: Filter sessions created on or after this date (dd/mm/yyyy).
          required: false
          type: string
        - name: end_date
          in: query
          description: Filter sessions created on or before this date (dd/mm/yyyy).
          required: false
          type: string
        - name: title
          in: query
          description: >-
            Filter by sessions whose title contains this substring
            (case-insensitive).
          required: false
          type: string
        - name: user_id
          in: query
          description: Filter by user ID stored in the session document.
          required: false
          type: string
        - name: uploaded_by
          in: query
          description: ID of the user (admin / sub-admin) who uploaded the video.
          required: false
          type: string
        - name: video_status
          in: query
          description: Processing state of the session video.
          required: false
          type: string
          enum:
            - processed
            - failed
      responses:
        '200':
          description: Filtered sessions retrieved successfully.
          schema:
            type: object
            properties:
              query_count:
                description: Total matching sessions.
                type: integer
              sessions:
                description: Dictionary of session documents keyed by their IDs.
                type: object
                additionalProperties:
                  type: object
              first_doc_id:
                description: ID of the first session in the result or null if none.
                type: string
              last_doc_id:
                description: ID of the last session in the result or null if none.
                type: string
          examples:
            application/json:
              query_count: 111
              sessions:
                5d5c8d7fcd6945f2936ced84f9a20562:
                  activity: Weightlifting
                  created_at:
                    date: 10/01/2025
                    time: 04:39 PM
                  analyzed_video_url: ...
                  video_url: ...
                  segments: 10
                  exercise: clean_and_jerk
                  user_name: Lee Jhon
                  report_comments:
                    ...: ...
                  metrics:
                    ...: ...
                  user_status: admin
                  user_id: Jdpajd2k3h4j5k6l7m8nD
                  title: new-test-w
                ...:
                  ...: ...
              first_doc_id: 5d5c8d7fcd6945f2936ced84f9a20562
              last_doc_id: bd977842e3e64845991b77d78db8b7e9
        '400':
          description: >-
            Bad Request - Potentially invalid parameters (malformed date, etc.)
            or missing user token.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Detailed error message describing the reason for the invalid
                  request.
                type: string
          examples:
            application/json:
              error: Invalid date format (expected dd/mm/yyyy).
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Authentication error.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - The user lacks admin privileges.
          schema:
            type: object
            properties:
              error:
                description: Authorization error.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: Not Found - No matching sessions found or resource unavailable.
          schema:
            type: object
            properties:
              error:
                description: Message indicating the sessions could not be retrieved.
                type: string
          examples:
            application/json:
              error: No sessions found for the given criteria.
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message for server-side issues.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      tags:
        - session-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /session-management/sessions/{session_id}:
    put:
      operationId: session-management_sessions_update
      summary: Update Session Data
      description: >-
        Updates session details (such as title and created_at timestamp) for a
        specific session. Requires admin privileges and a valid payment plan.


        ### Path Parameter

        - **session_id** *(string, required)*: The unique session identifier.


        ### Request Body (JSON)

        - **title** *(string, optional)*: The updated title for the session.

        - **created_at** *(string, optional, format: `YYYY-MM-DD HH:MM:SS`)*:
        The updated session timestamp.


        ### Response Structure


        On success, the response contains:

        - **success** *(string)*: Confirmation that the session was updated.


        ### Error Responses

        - **400 Bad Request**: Invalid request parameters or missing required
        data.

        - **401 Unauthorized**: Missing or invalid access token.

        - **403 Forbidden**: Insufficient privileges or invalid payment plan.

        - **404 Not Found**: Session not found.

        - **500 Internal Server Error**: An unexpected error occurred.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            type: object
            properties:
              title:
                description: New title for the session.
                type: string
              created_at:
                description: Updated session timestamp in `YYYY-MM-DD HH:MM:SS` format.
                type: string
                format: date-time
            example:
              title: Updated Running Session
              created_at: '2025-02-06 14:30:00'
        - name: session_id
          in: path
          description: The session ID for which details will be updated.
          required: true
          type: string
      responses:
        '200':
          description: Session updated successfully.
          schema:
            type: object
            properties:
              success:
                description: Confirmation message.
                type: string
          examples:
            application/json:
              success: session_123 was successfully updated
        '400':
          description: Bad Request - Invalid parameters or missing data.
          schema:
            type: object
            properties:
              error:
                description: Error message explaining why the request was invalid.
                type: string
          examples:
            application/json:
              error: Invalid admin UID
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that A valid API-KEY token was not provided.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have sufficient privileges to retrieve
            total metrics.
          schema:
            type: object
            properties:
              error:
                description: Error indicating insufficient permissions.
                type: string
          examples:
            application/json:
              error: Access denied.
        '404':
          description: Not Found - The specified session ID does not exist.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating session was not found.
                type: string
          examples:
            application/json:
              error: Session session_123 not found
        '500':
          description: Internal Server Error - An unexpected issue occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: Error message for debugging.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error>'
      tags:
        - session-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    delete:
      operationId: session-management_sessions_delete
      summary: Delete a Session
      description: >-
        Deletes a specified session and all associated resources, including
        session data, video files, subcollections, and reports.


        ### Path Parameter

        - **session_id** *(string, required)*: The unique session identifier.


        ### Response Structure


        On success, the response contains:

        - **success** *(string)*: Confirmation that the session was deleted.


        ### Error Responses

        - **400 Bad Request**: Invalid request parameters.

        - **401 Unauthorized**: Token is invalid or missing.

        - **403 Forbidden**: User does not have admin privileges.

        - **404 Not Found**: Session not found.

        - **500 Internal Server Error**: An unexpected error occurred.
      parameters:
        - name: session_id
          in: path
          description: The session ID to be deleted.
          required: true
          type: string
      responses:
        '200':
          description: Session deleted successfully.
          schema:
            type: object
            properties:
              success:
                description: Confirmation message.
                type: string
          examples:
            application/json:
              success: session_123 was successfully deleted
        '400':
          description: Bad Request - Invalid parameters or missing data.
          schema:
            type: object
            properties:
              error:
                description: Error message explaining why the request was invalid.
                type: string
          examples:
            application/json:
              error: Invalid admin UID
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Authentication error.
                type: string
          examples:
            application/json:
              error: 'Unauthorized: Token is missing or invalid'
        '403':
          description: Forbidden - User lacks necessary privileges.
          schema:
            type: object
            properties:
              error:
                description: Authorization error.
                type: string
          examples:
            application/json:
              error: 'Forbidden: You must be an admin to delete this session'
        '404':
          description: Not Found - The specified session ID does not exist.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating session was not found.
                type: string
          examples:
            application/json:
              error: Session session_123 not found
        '500':
          description: Internal Server Error - An unexpected issue occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: Error message for debugging.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error>'
      tags:
        - session-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /session-management/sessions/{session_id}/analyzed-video/:
    get:
      operationId: session-management_sessions_analyzed-video_list
      summary: Retrieve Analyzed Video URL
      description: >-
        Retrieves the analyzed video URL for a specific session, or attempts to
        create it if it does not exist.


        ### Path Parameter

        - **session_id** *(string, required)*: The unique identifier of the
        session.


        ### Query Parameters

        These optional flags determine which kind of analysis to perform if the
        video doesn't exist:

        - **is_jump** *(boolean, optional)*: Indicates whether this session is
        for jump analysis.

        - **is_weight** *(boolean, optional)*: Indicates whether this session is
        for weightlifting analysis.

        - **download** *(boolean, optional)*: If `true`, returns a signed URL
        that forces the browser to download the video instead of displaying it.


        ### Response (HTTP 200)


        Returns a JSON object with an `analyzed_video_url` key if successful:


        ```json

        {
          "analyzed_video_url": "https://storage.googleapis.com/.../analyzed_video.mp4"
        }

        ```


        ### Error Handling


        - **400 Bad Request**: Invalid parameters (e.g., missing or invalid
        admin UID).

        - **401 Unauthorized**: Token is missing or invalid.

        - **403 Forbidden**: The user does not have the right privileges or
        plan.

        - **404 Not Found**: The session data or resources could not be found.

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


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: session_id
          in: path
          description: The session ID for which to retrieve or create an analyzed video.
          required: true
          type: string
        - name: is_jump
          in: query
          description: Indicates whether this session is for jump analysis.
          required: false
          type: boolean
        - name: is_weight
          in: query
          description: Indicates whether this session is for weightlifting analysis.
          required: false
          type: boolean
        - name: download
          in: query
          description: If true, returns a signed URL that forces download of the video.
          required: false
          type: boolean
      responses:
        '200':
          description: Analyzed video URL retrieved successfully.
          schema:
            type: object
            properties:
              analyzed_video_url:
                description: URL of the analyzed video.
                type: string
                format: uri
          examples:
            application/json:
              analyzed_video_url: https://storage.googleapis.com/.../analyzed_video.mp4
        '400':
          description: Bad Request - Possibly invalid parameters.
          schema:
            description: Error schema for invalid requests (e.g., malformed UID)
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: Invalid admin UID
        '401':
          description: Unauthorized - Token is invalid or missing.
          schema:
            description: Error schema for missing or invalid token
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User lacks privileges or plan.
          schema:
            description: Error schema for forbidden access
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: User does not have a valid payment plan
        '404':
          description: Not Found - Session data or resource not found.
          schema:
            description: Error schema for missing session or resource
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: Session data not found
        '500':
          description: Internal Server Error - A server-side error occurred.
          schema:
            description: Error schema for unexpected server failures
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error>'
      tags:
        - session-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: session-management_sessions_analyzed-video_create
      summary: Upload/Generate Analyzed Video
      description: >-
        Uploads or generates an analyzed video for a specific session, returning
        its URL.


        ### Path Parameter

        - **session_id** *(string, required)*: The unique identifier of the
        session.


        ### Request Body (JSON)

        ```json

        {
          "is_jump": true,
          "is_weight": false
        }

        ```

        - **is_jump** *(boolean, optional)*: If true, treat this as a jump
        session.

        - **is_weight** *(boolean, optional)*: If true, treat this as a
        weightlifting session.


        ### Response Structure (HTTP 200)

        On success, returns a JSON object with the `analyzed_video_url`:


        ```json

        {
          "analyzed_video_url": "https://storage.googleapis.com/.../analyzed_video.mp4"
        }

        ```

        ### Error Handling


        - **400 Bad Request**: Invalid parameters or session already analyzed.

        - **401 Unauthorized**: Token is missing or invalid.

        - **403 Forbidden**: The user does not have a valid plan.

        - **404 Not Found**: Session data not found.

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


        ### Security

        A valid API-KEY token must be provided in the `Authorization` header.
      parameters:
        - name: data
          in: body
          required: true
          schema:
            type: object
            properties:
              is_jump:
                description: Whether this session is jump-related.
                type: boolean
              is_weight:
                description: Whether this session is weightlifting-related.
                type: boolean
            example:
              is_jump: true
              is_weight: false
        - name: session_id
          in: path
          description: The session ID for which to upload/generate an analyzed video.
          required: true
          type: string
      responses:
        '200':
          description: Analyzed video URL generated or updated successfully.
          schema:
            type: object
            properties:
              analyzed_video_url:
                description: URL of the newly generated or updated analyzed video.
                type: string
                format: uri
          examples:
            application/json:
              analyzed_video_url: https://storage.googleapis.com/.../analyzed_video.mp4
        '400':
          description: >-
            Bad Request - Possibly invalid session data or video already
            analyzed.
          schema:
            description: Error schema for invalid requests or already analyzed video
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: Video already analyzed
        '401':
          description: Unauthorized - The token is missing or invalid.
          schema:
            description: Error schema for missing or invalid token
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - The user does not have a valid payment plan.
          schema:
            description: Error schema for insufficient plan privileges
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: User does not have a valid payment plan
        '404':
          description: Not Found - Session not found or creation failed.
          schema:
            description: Error schema for missing session data or resource
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: Session data not found
        '500':
          description: Internal Server Error - A server-side error occurred.
          schema:
            description: Error schema for unexpected server failures
            type: object
            properties:
              error:
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error>'
      tags:
        - session-management
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  
  /weightlifting/sessions/:
    post:
      operationId: weightlifting_sessions_create
      summary: Create a New Video Processing Session
      description: >
        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:


        ```bash

        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/
        ```
      parameters:
        - name: user_id
          in: formData
          description: >-
            **Required.** The ID of the user for whom this session is created
            (form field: text).
          required: true
          type: string
        - name: video
          in: formData
          description: >-
            **Required.** The raw video file to be processed (form field type:
            file).
          required: true
          type: file
        - name: session_name
          in: formData
          description: '**Optional.** A descriptive name for the session (form field: text).'
          required: false
          type: string
        - name: exercise_name
          in: formData
          description: >-
            **Required.** The name of the exercise. Choose one of the following:
            'snatch', 'clean', or 'clean_and_jerk'.
          required: true
          type: string
          enum:
            - snatch
            - clean
            - clean_and_jerk
        - name: barbell_mass
          in: formData
          description: >-
            **Optional.** The mass of the barbell used (numeric string).
            Defaults to 100 kg (or 220 lb) if not provided.
          required: false
          type: string
        - name: body_joint_angles
          in: formData
          description: >-
            **Optional.** A comma-separated list of joint names. Available
            values: `'ankle'`, `'knee'`, `'elbow'`, `'hip'`, `'shoulder'`.
            Example: `ankle,knee,hip`
          required: false
          type: array
          items:
            type: string
            enum:
              - ankle
              - knee
              - elbow
              - hip
              - shoulder
          collectionFormat: csv
      responses:
        '200':
          description: Video processing session created successfully (HTTP 200).
          schema:
            required:
              - session_id
              - title
            type: object
            properties:
              session_id:
                description: The unique identifier for the created session.
                type: string
              title:
                description: The session title (defaults if not provided).
                type: string
          examples:
            application/json:
              session_id: abcd1234efgh5678
              title: Custom Session
        '400':
          description: >-
            Bad Request - Possibly due to missing `user_id`, missing `video`, or
            invalid form data.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: user_id is required
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Error indicating a missing or invalid token.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: >-
            Forbidden - The user does not have admin permission to create
            sessions for others.
          schema:
            type: object
            properties:
              error:
                description: Error indicating insufficient privileges.
                type: string
          examples:
            application/json:
              error: You must be an admin to access this data.
        '404':
          description: >-
            Not Found - Indicates business logic issues or resource limitations
            (e.g., session limit).
          schema:
            type: object
            properties:
              error:
                description: Error message describing the issue.
                type: string
          examples:
            application/json:
              error: User has reached the maximum number of sessions.
        '500':
          description: Internal Server Error - Unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      consumes:
        - multipart/form-data
        - application/x-www-form-urlencoded
      tags:
        - weightlifting
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters: []
  /weightlifting/sessions/{session_id}/:
    get:
      operationId: weightlifting_sessions_read
      summary: Retrieve Weightlifting Session Details
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: The unique identifier of the weightlifting session to retrieve.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve a pre-generated demo session instead of a
            real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Weightlifting session details retrieved successfully.
          schema:
            required:
              - analyzed_video_url
              - video_url
              - created_at
              - exercise
              - user_name
              - activity
              - title
              - metrics
              - angles
              - report_metrics
              - all_timestamps
            type: object
            properties:
              analyzed_video_url:
                description: Public URL of the analyzed video.
                type: string
                format: uri
              video_url:
                description: Public URL of the original video.
                type: string
                format: uri
              created_at:
                description: Session creation timestamp.
                required:
                  - date
                  - time
                type: object
                properties:
                  date:
                    description: Date in DD/MM/YYYY format.
                    type: string
                  time:
                    description: Time in HH:MM AM/PM format.
                    type: string
              exercise:
                description: The exercise performed (e.g., 'snatch').
                type: string
              user_name:
                description: Name of the user associated with the session.
                type: string
              activity:
                description: Activity type, expected to be 'Weightlifting'.
                type: string
              title:
                description: The title of the session.
                type: string
              metrics:
                description: A dictionary of numeric metrics.
                type: object
                additionalProperties:
                  type: number
              angles:
                description: A dictionary where keys map to arrays of angle values.
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              report_metrics:
                description: A dictionary where keys map to arrays of report metric values.
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              all_timestamps:
                description: List of timestamps corresponding to session data.
                type: array
                items:
                  type: number
          examples:
            application/json:
              analyzed_video_url: >-
                https://storage.googleapis.com/aikonweb001.appspot.com/analyzed_videos/.../analyzed_video.mp4
              video_url: >-
                https://storage.googleapis.com/aikonweb001.appspot.com/analyzed_videos/.../snatch_weightlift.MOV
              created_at:
                date: 08/02/2025
                time: 02:17 AM
              exercise: snatch
              user_name: Violet Snow
              activity: Weightlifting
              title: snatch-w
              metrics:
                bar_past_the_knee_speed: 1.2634576485766442
                bar_past_the_knee_acceleration: -0.9553989355246633
                max_GRF: 1090205.6278922595
                first_pull_end: 954
                second_pull_end: 1036
                scale: 1.98963
                total_time: 3200
                transition: 983
                barbell_weight: 50
                start_of_lifting: 537
                catch_end: 1089
                max_power: 10633983.025107784
                clean_time: 2760
                recovery_end: 1177
                mean_markers_validity: 0.612
                max_bar_speed: 33.22927464315564
              angles:
                lank_angle:
                  - 30
                  - 35
                  - 33
                lkne_angle:
                  - 40
                  - 42
                  - 41
                rank_angle:
                  - 38
                  - 40
                  - 39
                hip_intersection_angle:
                  - 50
                  - 55
                  - 52
                rkne_angle:
                  - 42
                  - 44
                  - 43
              report_metrics:
                bar:
                  - 0.5
                  - 0.6
                  - 0.7
                vhipy:
                  - 1.2
                  - 1.3
                  - 1.1
              all_timestamps:
                - 16
                - 25
        '400':
          description: Bad Request - Invalid parameters or admin UID.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message for invalid requests.
                type: string
          examples:
            application/json:
              error: Invalid admin UID.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Access token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Insufficient privileges.
          schema:
            type: object
            properties:
              error:
                description: User is not permitted to access this data.
                type: string
          examples:
            application/json:
              error: Access denied.
        '404':
          description: Not Found - Session not found or invalid activity.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating that the session was not found.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error message>'
      tags:
        - weightlifting
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /weightlifting/sessions/{session_id}/export/:
    get:
      operationId: weightlifting_sessions_export_list
      summary: Export Weightlifting Session Data
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: The session ID for which to export weightlifting data.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve a pre-generated demo session instead of a
            real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Weightlifting session data retrieved successfully.
          schema:
            required:
              - keypoints
              - angles
              - all_timestamps
              - metrics
              - activity
            type: object
            properties:
              keypoints:
                description: >-
                  A dictionary of keypoints. Each key maps to an array of
                  numeric values.
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              angles:
                description: >-
                  A dictionary of angles. Each key maps to an array of numeric
                  values.
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              all_timestamps:
                description: An array of timestamps (in seconds) for the session data.
                type: array
                items:
                  type: number
              metrics:
                description: A dictionary of numeric metrics. Each key maps to a number.
                type: object
                additionalProperties:
                  type: number
              activity:
                description: The session activity (expected to be 'Weightlifting').
                type: string
          examples:
            application/json:
              keypoints:
                lknev:
                  - 1
                  - 2
                  - 3
                lknex:
                  - 1.5
                  - 2.5
                  - 3.5
              angles:
                lank_angle:
                  - 30
                  - 35
                  - 33
                lkne_angle:
                  - 40
                  - 42
                  - 41
                rank_angle:
                  - 38
                  - 40
                  - 39
                hip_intersection_angle:
                  - 50
                  - 55
                  - 52
                rkne_angle:
                  - 42
                  - 44
                  - 43
              all_timestamps:
                - 16
                - 25
              metrics:
                bar_past_the_knee_speed: 1.2634576485766442
                bar_past_the_knee_acceleration: -0.9553989355246633
                max_GRF: 1090205.6278922595
                first_pull_end: 954
                second_pull_end: 1036
                scale: 1.98963
                total_time: 3200
                transition: 983
                barbell_weight: 50
                start_of_lifting: 537
                catch_end: 1089
                max_power: 10633983.025107784
                clean_time: 2760
                recovery_end: 1177
                mean_markers_validity: 0.612
                max_bar_speed: 33.22927464315564
              activity: Weightlifting
        '400':
          description: Bad Request - Invalid parameters or admin UID error.
          schema:
            type: object
            properties:
              error:
                description: Error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid admin UID.
        '401':
          description: Unauthorized - Missing or invalid access token.
          schema:
            type: object
            properties:
              error:
                description: Token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User does not have sufficient privileges.
          schema:
            type: object
            properties:
              error:
                description: User is not authorized to access this data.
                type: string
          examples:
            application/json:
              error: Access denied.
        '404':
          description: >-
            Not Found - The session was not found or its activity is not
            'Weightlifting'.
          schema:
            type: object
            properties:
              error:
                description: Error message indicating the session was not found.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred on the server.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: 'An unexpected error occurred: <error details>'
      tags:
        - weightlifting
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /weightlifting/sessions/{session_id}/lift-analysis/:
    post:
      operationId: weightlifting_sessions_lift-analysis_create
      summary: Analyze Weightlifting Lift
      description: >-
        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.


        ```json

        {
          "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.
      parameters:
        - name: session_id
          in: path
          description: Identifier of the session to analyze.
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve the pre-generated demo lift analysis
            instead of a real one.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Lift analysis report generated successfully.
          schema:
            type: object
            properties:
              exercise:
                type: string
              key_metrics:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              body_positioning:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              joint_angles:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              barbell_positioning:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: number
              phase_data:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    average_time_ms:
                      type: integer
              chart_data:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    start:
                      type: integer
                    end:
                      type: integer
              user_information:
                type: object
                additionalProperties:
                  type: string
              session_date:
                type: string
                format: date
              comments:
                type: object
          examples:
            application/json:
              exercise: snatch
              key_metrics:
                power_output:
                  - 2350
                  - 2600
                  - 2705
                ground_reaction_force:
                  - 1120
                  - 1260
                  - 1300
                barbell_velocity:
                  - 0.9
                  - 1.55
                  - 2.02
              body_positioning:
                hip_velocity:
                  - 0.45
                  - 0.88
                  - 1.02
                shin_angle:
                  - 75
                  - 68.8
                  - 67.5
              joint_angles:
                hip_angle:
                  - 165
                  - 152
                  - 145
                knee_angle:
                  - 155
                  - 138
                  - 130
              barbell_positioning:
                bar_height:
                  - 120
                  - 515
                  - 610
              phase_data:
                setup:
                  average_time_ms: 536
              chart_data:
                setup:
                  start: 0
                  end: 536
              user_information:
                display_name: Ahror Jabborov
                age: 28
              session_date: 18/05/2025
              comments: {}
        '400':
          description: Bad Request - Invalid token or parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that admin privileges are required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: >-
            Not Found - Session not found or user does not have a valid payment
            plan.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the session was not found or
                  payment plan is invalid.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - weightlifting
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /weightlifting/sessions/{session_id}/recommendation/:
    post:
      operationId: weightlifting_sessions_recommendation_create
      summary: Generate lift-analysis comment threads for a Weightlifting Session
      description: >-
        ### 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:**

        ```json

        {
          "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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the session
          required: true
          type: string
        - name: measurement_system
          in: query
          description: Measurement system used inside the prompts
          required: false
          type: string
          enum:
            - metric
            - imperial
          default: metric
      responses:
        '201':
          description: Threads created successfully.
          schema:
            description: Dictionary mapping lift metrics to thread IDs.
            required:
              - power_output
              - ground_reaction_force
              - barbell_velocity
              - hip_velocity
              - shin_angle
              - hip_height
              - torso_angle
              - hip_angle
              - knee_angle
              - bar_height
              - barbell_trajectory
              - vertical_shoulder_height
            type: object
            properties:
              power_output:
                description: Thread ID for power output.
                type: string
              ground_reaction_force:
                description: Thread ID for GRF.
                type: string
              barbell_velocity:
                description: Thread ID for barbell velocity.
                type: string
              hip_velocity:
                description: Thread ID for hip velocity.
                type: string
              shin_angle:
                description: Thread ID for shin angle.
                type: string
              hip_height:
                description: Thread ID for hip height.
                type: string
              torso_angle:
                description: Thread ID for torso angle.
                type: string
              hip_angle:
                description: Thread ID for hip joint angle.
                type: string
              knee_angle:
                description: Thread ID for knee joint angle.
                type: string
              bar_height:
                description: Thread ID for max bar height.
                type: string
              barbell_trajectory:
                description: Thread ID for bar path.
                type: string
              vertical_shoulder_height:
                description: Thread ID for shoulder height.
                type: string
          examples:
            application/json:
              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
        '400':
          description: Bad Request - Invalid token or parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that admin privileges are required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: >-
            Not Found - Session not found or user does not have a valid payment
            plan.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the session was not found or
                  payment plan is invalid.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - weightlifting
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string
  /weightlifting/sessions/{session_id}/summary/:
    get:
      operationId: weightlifting_sessions_summary_list
      summary: Get Summary of a Weightlifting Session
      description: >-
        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.
      parameters:
        - name: session_id
          in: path
          description: Unique identifier of the session
          required: true
          type: string
        - name: demo
          in: query
          description: >-
            Set to `true` to retrieve a pre-generated demo summary for this
            weightlifting session.
          required: false
          type: boolean
          default: false
      responses:
        '200':
          description: Successfully retrieved weightlifting session summary
          schema:
            required:
              - exercise_type
              - velocity
              - power
              - stability
              - user_information
              - session_date
            type: object
            properties:
              summary_text:
                description: Optional GenAI commentary on the lift.
                type: object
                properties:
                  velocity:
                    description: Narrative on bar velocity performance.
                    type: string
                  power:
                    description: Narrative on force & power production.
                    type: string
                  stability:
                    description: Narrative on bar path stability & control.
                    type: string
                  final_summary:
                    description: Overall coaching remarks.
                    type: string
              exercise_type:
                description: Type of lift/exercise performed.
                type: string
              velocity:
                type: object
                properties:
                  bar_velocity:
                    type: object
                    properties:
                      min:
                        description: Minimum bar velocity (m/s).
                        type: number
                      max:
                        description: Maximum bar velocity (m/s).
                        type: number
                      values:
                        description: Array of bar velocity samples (m/s).
                        type: array
                        items:
                          type: number
              power:
                type: object
                properties:
                  ground_reaction_force:
                    type: object
                    properties:
                      min:
                        description: Minimum ground reaction force (N).
                        type: number
                      max:
                        description: Maximum ground reaction force (N).
                        type: number
                      values:
                        description: Array of force samples (N).
                        type: array
                        items:
                          type: number
                  power:
                    type: object
                    properties:
                      min:
                        description: Minimum power output (W).
                        type: number
                      max:
                        description: Maximum power output (W).
                        type: number
                      values:
                        description: Array of instantaneous power samples (W).
                        type: array
                        items:
                          type: number
              stability:
                type: object
                properties:
                  total_time:
                    description: Total lift duration (s).
                    type: number
                  bar_height:
                    type: object
                    properties:
                      max:
                        description: Maximum bar height (m).
                        type: number
                      values:
                        description: Array of bar height samples (m).
                        type: array
                        items:
                          type: number
                  bar_trajectory:
                    type: object
                    properties:
                      xAxis:
                        description: Bar trajectory on the x-axis (m).
                        type: array
                        items:
                          type: number
                      yAxis:
                        description: Bar trajectory on the y-axis (m).
                        type: array
                        items:
                          type: number
              user_information:
                description: Detailed user profile at the time of session.
                type: object
                properties:
                  weight:
                    description: Weight (kg)
                    type: number
                  height:
                    description: Height (cm)
                    type: number
                  age:
                    description: Age
                    type: string
                  gender:
                    description: Gender
                    type: string
                  email:
                    description: Email address
                    type: string
                  display_name:
                    description: Display name
                    type: string
              session_date:
                description: Date of the session (e.g. '07/04/2025').
                type: string
          examples:
            application/json:
              exercise_type: Clean and Jerk
              velocity:
                bar_velocity:
                  min: 0.74
                  max: 1.32
                  values:
                    - 0.74
                    - 0.88
                    - 1.02
                    - 1.15
                    - 1.32
              power:
                ground_reaction_force:
                  min: 980
                  max: 1450
                  values:
                    - 980
                    - 1100
                    - 1210
                    - 1340
                    - 1450
                power:
                  min: 930
                  max: 1650
                  values:
                    - 930
                    - 1140
                    - 1385
                    - 1520
                    - 1650
              stability:
                total_time: 2.76
                bar_height:
                  max: 1.12
                  values:
                    - 0.88
                    - 0.95
                    - 1.02
                    - 1.08
                    - 1.12
                bar_trajectory:
                  xAxis:
                    - 0
                    - 0.1
                    - 0.2
                    - 0.3
                    - 0.4
                  yAxis:
                    - 0
                    - 0.05
                    - 0.1
                    - 0.15
                    - 0.2
              user_information:
                weight: 78
                height: 180
                age: '26'
                gender: male
                email: alex@aikynetix.com
                display_name: Alex P.
              session_date: 07/04/2025
              summary_text:
                velocity: Bar speed peaked at 1.32 m/s—excellent explosiveness.
                power: >-
                  Top power output reached 1.65 kW; aim for more consistency
                  across reps.
                stability: Bar path shows minimal height variance; control is solid.
                final_summary: Strong lift overall. Keep refining second pull speed.
        '400':
          description: Bad Request - Invalid parameters.
          schema:
            type: object
            properties:
              error:
                description: Detailed error message.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token missing or expired.
          schema:
            type: object
            properties:
              error:
                description: Authentication error message.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - User lacks a valid payment plan.
          schema:
            type: object
            properties:
              error:
                description: Payment-plan error message.
                type: string
          examples:
            application/json:
              error: User plan invalid.
        '404':
          description: Not Found - Session not located.
          schema:
            type: object
            properties:
              error:
                description: Not-found error message.
                type: string
          examples:
            application/json:
              error: Session not found.
        '500':
          description: Internal Server Error.
          schema:
            type: object
            properties:
              error:
                description: Server-side failure message.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - weightlifting
      security:
        - Bearer: []
        - ApiKeyAuth: []
    post:
      operationId: weightlifting_sessions_summary_create
      summary: Generate Summary for a WeightLifting Session
      description: >-
        ### 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:**

        ```json

        {
            "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.
      parameters:
        - name: session_id
          in: path
          description: The unique identifier of the session
          required: true
          type: string
        - name: measurement_system
          in: query
          description: 'Measurement system: ''metric'' or ''imperial'''
          required: false
          type: string
          enum:
            - metric
            - imperial
          default: metric
      responses:
        '201':
          description: Summary threads generated successfully.
          schema:
            type: object
            additionalProperties:
              description: Thread ID corresponding to a summary block
              type: string
            example:
              velocity: thread_id_1
              power: thread_id_2
              stability: thread_id_3
              final_summary: thread_id_4
        '400':
          description: Bad Request - Invalid token or parameters.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message describing the invalid request.
                type: string
          examples:
            application/json:
              error: Invalid session data.
        '401':
          description: Unauthorized - Token is invalid or expired.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that the token is missing or invalid.
                type: string
          examples:
            application/json:
              error: No token provided.
        '403':
          description: Forbidden - Admin access is required.
          schema:
            type: object
            properties:
              error:
                description: Error indicating that admin privileges are required.
                type: string
          examples:
            application/json:
              error: Admin access required.
        '404':
          description: >-
            Not Found - Session not found or user does not have a valid payment
            plan.
          schema:
            type: object
            properties:
              error:
                description: >-
                  Error message indicating that the session was not found or
                  payment plan is invalid.
                type: string
          examples:
            application/json:
              error: Session not found
        '500':
          description: Internal Server Error - An unexpected error occurred.
          schema:
            type: object
            properties:
              error:
                description: A detailed error message indicating a server-side failure.
                type: string
          examples:
            application/json:
              error: Internal server error.
      tags:
        - weightlifting
      security:
        - Bearer: []
        - ApiKeyAuth: []
    parameters:
      - name: session_id
        in: path
        required: true
        type: string

definitions: {}






