Hevy Routines API

openapi: 3.2.0
info:
  title: Hevy Routines API
  version: '1.0'
  description: 'Operations tagged Routines 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: Routines
paths:
  /api/v1/routines:
    get:
      operationId: get-routines
      security:
      - oauth2:
        - read:routines
      summary: Get a paginated list of routines
      tags:
      - Routines
      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 routines
          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
                  routines:
                    type: array
                    items:
                      $ref: '#/components/schemas/Routine'
        '400':
          description: Invalid page size
    post:
      operationId: post-routine
      security:
      - oauth2:
        - write:routines
      summary: Create a new routine
      tags:
      - Routines
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRoutinesRequestBody'
      responses:
        '201':
          description: The routine was successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Routine'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
        '403':
          description: Routine limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
    servers:
    - url: https://hevy.com
  /v1/routines:
    get:
      summary: Get a paginated list of routines
      tags:
      - Routines
      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 routines
          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
                  routines:
                    type: array
                    items:
                      $ref: '#/components/schemas/Routine_2'
        '400':
          description: Invalid page size
    post:
      summary: Create a new routine
      tags:
      - Routines
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRoutinesRequestBody_2'
      responses:
        '201':
          description: The routine was successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Routine_2'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
        '403':
          description: Routine limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
  /v1/routines/{routineId}:
    get:
      summary: Get a routine by its Id
      tags:
      - Routines
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: routineId
        description: The id of the routine
        required: true
      responses:
        '200':
          description: The routine with the provided id
          content:
            application/json:
              schema:
                type: object
                properties:
                  routine:
                    $ref: '#/components/schemas/Routine_2'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
    put:
      summary: Update an existing routine
      tags:
      - Routines
      parameters:
      - in: header
        name: api-key
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: routineId
        description: The id of the routine
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutRoutinesRequestBody'
      responses:
        '200':
          description: The routine was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Routine_2'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
        '404':
          description: Routine doesn't exist or doesn't belong to the user
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
components:
  schemas:
    PostRoutinesRequestExercise:
      type: object
      properties:
        exercise_template_id:
          type: string
          description: The ID of the exercise template.
          example: D04AC939
        superset_id:
          enum:
          - null
          description: The ID of the superset.
          example: null
        rest_seconds:
          type: integer
          nullable: true
          description: The rest time in seconds.
          example: 90
        notes:
          type: string
          nullable: false
          description: Additional notes for the exercise.
          example: Stay slow and controlled.
        sets:
          type: array
          items:
            $ref: '#/components/schemas/PostRoutinesRequestSet'
    Routine:
      type: object
      properties:
        id:
          type: string
          description: The routine ID.
          example: b459cba5-cd6d-463c-abd6-54f8eafcadcb
        title:
          type: string
          description: The routine title.
          example: Upper Body 💪
        folder_id:
          type: number
          nullable: true
          description: The routine folder ID.
          example: 42
        updated_at:
          type: string
          description: ISO 8601 timestamp of when the routine was last updated.
          example: '2021-09-14T12:00:00Z'
        created_at:
          type: string
          description: ISO 8601 timestamp of when the routine 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 routine.
                example: 0
              title:
                type: string
                description: Title of the exercise
                example: Bench Press (Barbell)
              rest_seconds:
                type: string
                description: The rest time in seconds between sets of the exercise
                example: 60
              notes:
                type: string
                description: Routine notes on the exercise
                example: Focus on form. Go down to 90 degrees.
              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 routine.
                      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
    PostRoutinesRequestSet:
      type: object
      properties:
        type:
          type: string
          description: The type of the set.
          enum:
          - warmup
          - normal
          - failure
          - dropset
          example: normal
        weight_kg:
          type: number
          nullable: true
          description: The weight in kilograms.
          example: 100
        reps:
          type: integer
          nullable: true
          description: The number of repetitions.
          example: 10
        distance_meters:
          type: integer
          nullable: true
          description: The distance in meters.
          example: null
        duration_seconds:
          type: integer
          nullable: true
          description: The duration in seconds.
          example: null
        custom_metric:
          type: number
          nullable: true
          description: A custom metric for the set. Currently used for steps and floors.
          example: null
    PostRoutinesRequestBody:
      type: object
      properties:
        routine:
          type: object
          properties:
            title:
              type: string
              description: The title of the routine.
              example: April Leg Day 🔥
            folder_id:
              enum:
              - null
              description: The folder id the routine should be added to. Only null is accepted to insert the routine into default "My Routines" folder
              example: null
            notes:
              type: string
              description: Additional notes for the routine.
              example: Focus on form over weight. Remember to stretch.
            source:
              type: string
              description: The source of the routine.
              enum:
              - chatgpt
              example: chatgpt
            exercises:
              type: array
              items:
                $ref: '#/components/schemas/PostRoutinesRequestExercise'
    PutRoutinesRequestExercise:
      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
        rest_seconds:
          type:
          - integer
          - 'null'
          description: The rest time in seconds.
          example: 90
        notes:
          type:
          - string
          - 'null'
          description: Additional notes for the exercise.
          example: Stay slow and controlled.
        sets:
          type: array
          items:
            $ref: '#/components/schemas/PutRoutinesRequestSet'
    PostRoutinesRequestExercise_2:
      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
        rest_seconds:
          type:
          - integer
          - 'null'
          description: The rest time in seconds.
          example: 90
        notes:
          type:
          - string
          - 'null'
          description: Additional notes for the exercise.
          example: Stay slow and controlled.
        sets:
          type: array
          items:
            $ref: '#/components/schemas/PostRoutinesRequestSet_2'
    Routine_2:
      type: object
      properties:
        id:
          type: string
          description: The routine ID.
          example: b459cba5-cd6d-463c-abd6-54f8eafcadcb
        title:
          type: string
          description: The routine title.
          example: Upper Body 💪
        folder_id:
          type:
          - number
          - 'null'
          description: The routine folder ID.
          example: 42
        updated_at:
          type: string
          description: ISO 8601 timestamp of when the routine was last updated.
          example: '2021-09-14T12:00:00Z'
        created_at:
          type: string
          description: ISO 8601 timestamp of when the routine 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 routine.
                example: 0
              title:
                type: string
                description: Title of the exercise
                example: Bench Press (Barbell)
              rest_seconds:
                type: string
                description: The rest time in seconds between sets of the exercise
                example: 60
              notes:
                type: string
                description: Routine notes on the exercise
                example: Focus on form. Go down to 90 degrees.
              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 routine.
                      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
                    rep_range:
                      type:
                      - object
                      - 'null'
                      description: Range of reps for the set, if applicable
                      properties:
                        start:
                          type:
                          - number
                          - 'null'
                          description: Starting rep count for the range
                          example: 8
                        end:
                          type:
                          - number
                          - 'null'
                          description: Ending rep count for the range
                          example: 12
                    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
    PostRoutinesRequestSet_2:
      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
        rep_range:
          type:
          - object
          - 'null'
          description: Range of reps for the set, if applicable
          properties:
            start:
              type: number
              description: Starting rep count for the range
              example: 8
            end:
              type: number
              description: Ending rep count for the range
              example: 12
    PutRoutinesRequestSet:
      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
        rep_range:
          type:
          - object
          - 'null'
          description: Range of reps for the set, if applicable
          properties:
            start:
              type:
              - number
              - 'null'
              description: Starting rep count for the range
              example: 8
            end:
              type:
              - number
              - 'null'
              description: Ending rep count for the range
              example: 12
    PostRoutinesRequestBody_2:
      type: object
      properties:
        routine:
          type: object
          properties:
            title:
              type: string
              description: The title of the routine.
              example: April Leg Day 🔥
            folder_id:
              type:
              - number
              - 'null'
              description: The folder id the routine should be added to. Pass null to insert the routine into default "My Routines" folder
              example: null
            notes:
              type: string
              description: Additional notes for the routine.
              example: Focus on form over weight. Remember to stretch.
            exercises:
              type: array
              items:
                $ref: '#/components/schemas/PostRoutinesRequestExercise_2'
    PutRoutinesRequestBody:
      type: object
      properties:
        routine:
          type: object
          properties:
            title:
              type: string
              description: The title of the routine.
              example: April Leg Day 🔥
            folder_id:
              type:
              - number
              - 'null'
              description: The folder id the routine should be added to. Pass null to insert the routine into default "My Routines" folder
              example: null
            notes:
              type:
              - string
              - 'null'
              description: Additional notes for the routine.
              example: Focus on form over weight. Remember to stretch.
            exercises:
              type: array
              items:
                $ref: '#/components/schemas/PutRoutinesRequestExercise'
x-refined-from:
- hevy-gpt-action-openapi.json
- hevy-public-api-openapi.json