torus-api/docs/paths/workout-session.yaml

get:
  summary: List sessions for a workout (paginated, filtered by date range)
  operationId: listWorkoutSessions
  tags:
    - Sessions
  security:
    - cookieAuth: []
  parameters:
    - name: workout_id
      in: path
      required: true
      description: UUID of the workout.
      schema:
        type: string
        format: uuid
        example: 0191a23b-dead-7000-beef-000000000002
    - name: start
      in: query
      required: false
      description: Start date (ISO 8601) to filter sessions (on start_time). Beginning of time if omitted.
      schema:
        type: string
        format: date-time
        example: '2026-01-01T00:00:00Z'
    - name: end
      in: query
      required: false
      description: End date (ISO 8601) to filter sessions (on start_time). End of time if omitted.
      schema:
        type: string
        format: date-time
        example: '2026-12-31T23:59:59Z'
    - name: page
      in: query
      required: false
      description: 1-indexed page number for pagination (defaults to 1). Returns up to 50 results per page.
      schema:
        type: integer
        example: 1
  responses:
    '200':
      description: List of matching sessions plus total count for pagination.
      content:
        application/json:
          schema:
            type: object
            required:
              - sessions
              - total
            properties:
              sessions:
                type: array
                items:
                  $ref: '../components/schemas/Session.yaml'
              total:
                type: integer
                description: Total number of sessions matching the query (for the workout).
                example: 12
          example:
            sessions:
              - id: 0191a23b-dead-7000-beef-000000000005
                workout: 0191a23b-dead-7000-beef-000000000002
                start_time: '2026-01-15T09:00:00Z'
                end_time: '2026-01-15T09:45:00Z'
              - id: 0191a23b-dead-7000-beef-000000000008
                workout: 0191a23b-dead-7000-beef-000000000002
                start_time: '2026-01-10T10:00:00Z'
                end_time: '2026-01-10T10:30:00Z'
            total: 12
    '400':
      description: Invalid query parameter (e.g. bad date format).
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          example:
            error: Invalid start date
    '401':
      description: Missing or invalid auth token.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          examples:
            missing:
              summary: No cookie present
              value:
                error: Missing auth token
            invalid:
              summary: Token invalid or expired
              value:
                error: Invalid auth token
    '403':
      description: Authenticated user does not own this workout.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          example:
            error: You do not have permission to access this workout
    '404':
      description: Workout not found.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          example:
            error: Workout not found
    '500':
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'

post:
  summary: Create a new session (after completing the workout on the front-end)
  operationId: createWorkoutSession
  tags:
    - Sessions
  security:
    - cookieAuth: []
  parameters:
    - name: workout_id
      in: path
      required: true
      description: UUID of the workout this session belongs to.
      schema:
        type: string
        format: uuid
        example: 0191a23b-dead-7000-beef-000000000002
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          required:
            - start_time
            - end_time
            - exercises
          properties:
            start_time:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the session started.
              example: '2026-01-15T09:00:00Z'
            end_time:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the session ended.
              example: '2026-01-15T09:45:00Z'
            exercises:
              type: array
              description: List of completed exercises with what was actually performed.
              items:
                type: object
                required:
                  - exercise_id
                properties:
                  exercise_id:
                    type: string
                    format: uuid
                    description: ID of the original exercise definition from the workout.
                    example: 0191a23b-dead-7000-beef-000000000003
                  sets:
                    type: array
                    nullable: true
                    description: Array of sets performed for this exercise. Each set can include reps/weight for strength or duration/distance for cardio.
                    items:
                      $ref: '../components/schemas/SessionSet.yaml'
        example:
          start_time: '2026-01-15T09:00:00Z'
          end_time: '2026-01-15T09:45:00Z'
          exercises:
            - exercise_id: 0191a23b-dead-7000-beef-000000000003
              sets:
                - reps: 12
                  weight: 120
                - reps: 11
                  weight: 120
                - reps: 10
                  weight: 120
            - exercise_id: 0191a23b-dead-7000-beef-000000000004
              sets:
                - reps: 15
                - reps: 12
  responses:
    '201':
      description: Session created successfully. Returns the generated session ID.
      content:
        application/json:
          schema:
            type: object
            required:
              - id
            properties:
              id:
                type: string
                format: uuid
                example: 0191a23b-dead-7000-beef-000000000005
    '400':
      description: Invalid request body.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          example:
            error: Invalid request body. Please check your data and try again.
    '401':
      description: Missing or invalid auth token.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          examples:
            missing:
              summary: No cookie present
              value:
                error: Missing auth token
            invalid:
              summary: Token invalid or expired
              value:
                error: Invalid auth token
    '403':
      description: Authenticated user does not own this workout.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          example:
            error: You do not have permission to access this workout
    '404':
      description: Workout or exercise not found.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          example:
            error: Workout not found
    '422':
      description: One of the exercises does not belong to the workout.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'
          example:
            error: Exercise does not belong to this workout
    '500':
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '../components/schemas/ErrorResponse.yaml'