openapi: 3.2.0
info:
  title: Hevy Workouts API
  version: '1.0'
  description: 'Operations tagged Workouts across 2 of this provider''s published API definitions: hevy-gpt-action-openapi.json, hevy-public-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://hevy.com
tags:
- name: Workouts
paths:
  /api/v1/workouts:
    get:
      operationId: get-workouts
      security:
      - oauth2:
        - read:workouts
      summary: Get a paginated list of workouts
      tags:
      - Workouts
      parameters:
      - in: query
        name: page
        schema:
          type: integer
          default: 1
        description: Page number (Must be 1 or greater)
      - in: query
        name: pageSize
        schema:
          type: integer
          default: 5
        description: Number of items on the requested page (Max 10)
      responses:
        '200':
          description: A paginated list of workouts
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                    example: 1
                    description: Current page number
                  page_count:
                    type: integer
                    example: 5
                    description: Total number of pages
                  workouts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workout'
        '400':
          description: Invalid page size
    servers:
    - url: https://hevy.com
  /v1/workouts:
    get:
      summary: Get a paginated list of workouts
      tags:
      - Workouts
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      - in: query
        name: page
        schema:
          type: integer
          default: 1
        description: Page number (Must be 1 or greater)
      - in: query
        name: pageSize
        schema:
          type: integer
          default: 5
        description: Number of items on the requested page (Max 10)
      responses:
        '200':
          description: A paginated list of workouts
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                    example: 1
                    description: Current page number
                  page_count:
                    type: integer
                    example: 5
                    description: Total number of pages
                  workouts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workout_2'
        '400':
          description: Invalid page size
    post:
      summary: Create a new workout
      tags:
      - Workouts
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostWorkoutsRequestBody'
      responses:
        '201':
          description: The workout was successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workout_2'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
  /v1/workouts/count:
    get:
      summary: Get the total number of workouts on the account
      tags:
      - Workouts
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      responses:
        '200':
          description: The total count of workouts
          content:
            application/json:
              schema:
                type: object
                properties:
                  workout_count:
                    type: integer
                    default: 42
                    description: The total number of workouts
  /v1/workouts/events:
    get:
      summary: Retrieve a paged list of workout events (updates or deletes) since a given date. Events are ordered from newest to oldest. The intention is to allow clients to keep their local cache of workouts up to date without having to fetch the entire list of workouts.
      tags:
      - Workouts
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      - in: query
        name: page
        schema:
          type: integer
          default: 1
        description: Page number (Must be 1 or greater)
      - in: query
        name: pageSize
        schema:
          type: integer
          default: 5
        description: Number of items on the requested page (Max 10)
      - in: query
        name: since
        schema:
          type: string
          default: '1970-01-01T00:00:00Z'
      description: Returns a paginated array of workout events, indicating updates or deletions.
      responses:
        '200':
          description: A paginated list of workout events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedWorkoutEvents'
        '500':
          description: Internal Server Error
  /v1/workouts/{workoutId}:
    get:
      tags:
      - Workouts
      summary: Get a single workout’s complete details by the workoutId
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      - name: workoutId
        in: path
        description: The id of the workout
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workout_2'
        '404':
          description: Workout not found
    put:
      summary: Update an existing workout
      tags:
      - Workouts
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: workoutId
        description: The id of the workout
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostWorkoutsRequestBody'
      responses:
        '200':
          description: The workout was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workout_2'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
components:
  schemas:
    Workout:
      type: object
      properties:
        id:
          type: string
          description: The workout ID.
          example: b459cba5-cd6d-463c-abd6-54f8eafcadcb
        title:
          type: string
          description: The workout title.
          example: Morning Workout 💪
        description:
          type: string
          description: The workout description.
          example: Pushed myself to the limit today!
        start_time:
          type: number
          description: ISO 8601 timestamp of when the workout was recorded to have started.
          example: '2021-09-14T12:00:00Z'
        end_time:
          type: number
          description: ISO 8601 timestamp of when the workout was recorded to have ended.
          example: '2021-09-14T12:00:00Z'
        updated_at:
          type: string
          description: ISO 8601 timestamp of when the workout was last updated.
          example: '2021-09-14T12:00:00Z'
        created_at:
          type: string
          description: ISO 8601 timestamp of when the workout was created.
          example: '2021-09-14T12:00:00Z'
        exercises:
          type: array
          items:
            type: object
            properties:
              index:
                type: number
                description: Index indicating the order of the exercise in the workout.
                example: 0
              title:
                type: string
                description: Title of the exercise
                example: Bench Press (Barbell)
              notes:
                type: string
                description: Notes on the exercise
                example: Paid closer attention to form today. Felt great!
              exercise_template_id:
                type: string
                description: The id of the exercise template. This can be used to fetch the exercise template.
                example: 05293BCA
              supersets_id:
                type: number
                nullable: true
                description: The id of the superset that the exercise belongs to. A value of null indicates the exercise is not part of a superset.
                example: 0
              sets:
                type: array
                items:
                  type: object
                  properties:
                    index:
                      type: number
                      description: Index indicating the order of the set in the workout.
                      example: 0
                    type:
                      type: string
                      description: The type of set. This can be one of 'normal', 'warmup', 'dropset', 'failure'
                      example: normal
                    weight_kg:
                      type: number
                      nullable: true
                      description: Weight lifted in kilograms.
                      example: 100
                    reps:
                      type: number
                      nullable: true
                      description: Number of reps logged for the set
                      example: 10
                    distance_meters:
                      type: number
                      nullable: true
                      description: Number of meters logged for the set
                      example: null
                    duration_seconds:
                      type: number
                      nullable: true
                      description: Number of seconds logged for the set
                      example: null
                    rpe:
                      type: number
                      nullable: true
                      description: RPE (Relative perceived exertion) value logged for the set
                      example: 9.5
                    custom_metric:
                      type: number
                      nullable: true
                      description: Custom metric logged for the set (Currently only used to log floors or steps for stair machine exercises)
                      example: 50
    Workout_2:
      type: object
      properties:
        id:
          type: string
          description: The workout ID.
          example: b459cba5-cd6d-463c-abd6-54f8eafcadcb
        title:
          type: string
          description: The workout title.
          example: Morning Workout 💪
        routine_id:
          type: string
          description: The ID of the routine that this workout belongs to.
          example: b459cba5-cd6d-463c-abd6-54f8eafcadcb
        description:
          type: string
          description: The workout description.
          example: Pushed myself to the limit today!
        start_time:
          type: string
          description: ISO 8601 timestamp of when the workout was recorded to have started.
          example: '2021-09-14T12:00:00Z'
        end_time:
          type: string
          description: ISO 8601 timestamp of when the workout was recorded to have ended.
          example: '2021-09-14T12:00:00Z'
        updated_at:
          type: string
          description: ISO 8601 timestamp of when the workout was last updated.
          example: '2021-09-14T12:00:00Z'
        created_at:
          type: string
          description: ISO 8601 timestamp of when the workout was created.
          example: '2021-09-14T12:00:00Z'
        exercises:
          type: array
          items:
            type: object
            properties:
              index:
                type: number
                description: Index indicating the order of the exercise in the workout.
                example: 0
              title:
                type: string
                description: Title of the exercise
                example: Bench Press (Barbell)
              notes:
                type: string
                description: Notes on the exercise
                example: Paid closer attention to form today. Felt great!
              exercise_template_id:
                type: string
                description: The id of the exercise template. This can be used to fetch the exercise template.
                example: 05293BCA
              supersets_id:
                type:
                - number
                - 'null'
                description: The id of the superset that the exercise belongs to. A value of null indicates the exercise is not part of a superset.
                example: 0
              sets:
                type: array
                items:
                  type: object
                  properties:
                    index:
                      type: number
                      description: Index indicating the order of the set in the workout.
                      example: 0
                    type:
                      type: string
                      description: The type of set. This can be one of 'normal', 'warmup', 'dropset', 'failure'
                      example: normal
                    weight_kg:
                      type:
                      - number
                      - 'null'
                      description: Weight lifted in kilograms.
                      example: 100
                    reps:
                      type:
                      - number
                      - 'null'
                      description: Number of reps logged for the set
                      example: 10
                    distance_meters:
                      type:
                      - number
                      - 'null'
                      description: Number of meters logged for the set
                      example: null
                    duration_seconds:
                      type:
                      - number
                      - 'null'
                      description: Number of seconds logged for the set
                      example: null
                    rpe:
                      type:
                      - number
                      - 'null'
                      description: RPE (Relative perceived exertion) value logged for the set
                      example: 9.5
                    custom_metric:
                      type:
                      - number
                      - 'null'
                      description: Custom metric logged for the set (Currently only used to log floors or steps for stair machine exercises)
                      example: 50
    DeletedWorkout:
      type: object
      required:
      - type
      - id
      properties:
        type:
          type: string
          description: Indicates the type of the event (deleted)
          example: deleted
        id:
          type: string
          description: The unique identifier of the deleted workout
          example: efe6801c-4aee-4959-bcdd-fca3f272821b
        deleted_at:
          type: string
          description: A date string indicating when the workout was deleted
          example: '2021-09-13T12:00:00Z'
    PostWorkoutsRequestSet:
      type: object
      properties:
        type:
          type: string
          description: The type of the set.
          enum:
          - warmup
          - normal
          - failure
          - dropset
          example: normal
        weight_kg:
          type:
          - number
          - 'null'
          description: The weight in kilograms.
          example: 100
        reps:
          type:
          - integer
          - 'null'
          description: The number of repetitions.
          example: 10
        distance_meters:
          type:
          - integer
          - 'null'
          description: The distance in meters.
          example: null
        duration_seconds:
          type:
          - integer
          - 'null'
          description: The duration in seconds.
          example: null
        custom_metric:
          type:
          - number
          - 'null'
          description: A custom metric for the set. Currently used for steps and floors.
          example: null
        rpe:
          type:
          - number
          - 'null'
          description: The Rating of Perceived Exertion (RPE).
          enum:
          - 6
          - 7
          - 7.5
          - 8
          - 8.5
          - 9
          - 9.5
          - 10
          example: null
    PostWorkoutsRequestBody:
      type: object
      properties:
        workout:
          type: object
          properties:
            title:
              type: string
              description: The title of the workout.
              example: Friday Leg Day 🔥
            description:
              type:
              - string
              - 'null'
              description: A description for the workout workout.
              example: Medium intensity leg day focusing on quads.
            start_time:
              type: string
              description: The time the workout started.
              example: '2024-08-14T12:00:00Z'
            end_time:
              type: string
              description: The time the workout ended.
              example: '2024-08-14T12:30:00Z'
            is_private:
              type: boolean
              description: A boolean indicating if the workout is private.
              example: false
            exercises:
              type: array
              items:
                $ref: '#/components/schemas/PostWorkoutsRequestExercise'
    PaginatedWorkoutEvents:
      type: object
      required:
      - page
      - page_count
      - events
      properties:
        page:
          type: integer
          description: The current page number
          example: 1
        page_count:
          type: integer
          description: The total number of pages available
          example: 5
        events:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/UpdatedWorkout'
            - $ref: '#/components/schemas/DeletedWorkout'
          description: An array of workout events (either updated or deleted)
    PostWorkoutsRequestExercise:
      type: object
      properties:
        exercise_template_id:
          type: string
          description: The ID of the exercise template.
          example: D04AC939
        superset_id:
          type:
          - integer
          - 'null'
          description: The ID of the superset.
          example: null
        notes:
          type:
          - string
          - 'null'
          description: Additional notes for the exercise.
          example: Felt good today. Form was on point.
        sets:
          type: array
          items:
            $ref: '#/components/schemas/PostWorkoutsRequestSet'
    UpdatedWorkout:
      type: object
      required:
      - type
      - workout
      properties:
        type:
          type: string
          description: Indicates the type of the event (updated)
          example: updated
        workout:
          $ref: '#/components/schemas/Workout_2'
x-refined-from:
- hevy-gpt-action-openapi.json
- hevy-public-api-openapi.json