hevy-api

name	hevy-api
description	Interact with the Hevy fitness API to fetch workouts, workout events, routines, folders, exercise templates, and exercise history. Requires HEVY_API_KEY in .env file. Use when analyzing training history, checking recent workouts, tracking exercise progression, inspecting workout stats, or managing routines and folders.
metadata	{"tags":"hevy, fitness, workout tracker, workouts, exercise, training, progression, routines, api"}

Hevy API Skill

This skill provides full access to the Hevy fitness tracking API.

Prerequisites

This skill requires a Hevy API key stored in .env:

HEVY_API_KEY=your-api-key-here

Getting an API Key

If the user doesn't have an API key:

1. Ask if they have one
2. If yes: ask them to provide it, then write to .env
3. If no: suggest using the hevy-export skill instead (CSV export via browser)

Available Scripts

All scripts are TypeScript and should be run from the workspace root using the workspace-relative paths below.

---

Workouts

Fetch Workouts

npx tsx skills/hevy-api/scripts/fetch-workouts.ts [--days=N] [--limit=N]

Fetches recent workouts with full exercise and set data.

• --days=N: Workouts from last N days (default: 30)
• --limit=N: Max workouts to return (default: 50)

Saves to the workspace data/workouts.json file and outputs JSON array.

Fetch Workout Count

npx tsx skills/hevy-api/scripts/fetch-workout-count.ts

Returns the total number of workouts on the account: { "workout_count": 42 }.

Fetch Workout Events

npx tsx skills/hevy-api/scripts/fetch-workout-events.ts [--since=<ISO8601>]

Returns paginated workout events (updates or deletes) since a given date. Use to keep a local cache up to date without re-fetching all workouts.

• --since: ISO 8601 date (default: 1970-01-01T00:00:00Z)

Returns a JSON array of events, each with type: "updated" | "deleted" and either a full workout object or { id, deleted_at }.

---

Users

Fetch User Info

npx tsx skills/hevy-api/scripts/fetch-user-info.ts

Returns the authenticated user's profile: { id, name, url }.

---

Routines

Fetch Routines (all)

npx tsx skills/hevy-api/scripts/fetch-routines.ts

Fetches all user routines with full exercise and set data. Saves to the workspace data/routines.json.

Fetch Routine (single)

npx tsx skills/hevy-api/scripts/fetch-routine.ts --id=<routineId>

Fetches a single routine by ID.

Create Routine

npx tsx skills/hevy-api/scripts/create-routine.ts --routine=<json>

Creates a new routine via POST /routines. The --routine JSON must include:

• title (required)
• folder_id (optional integer)
• notes (optional)
• exercises[] — each with exercise_template_id, rest_seconds, notes, sets[]
• Each set: type, weight_kg, reps, distance_meters, duration_seconds, custom_metric, rep_range: { start, end }

Returns the created routine.

Update Routine

npx tsx skills/hevy-api/scripts/update-routine.ts --id=<routineId> --routine=<json>

Replaces an existing routine via PUT /routines/{id}. Same JSON shape as Create Routine.

• --id: Routine ID (from Fetch Routines)
• --routine: Full routine JSON

Returns the updated routine.

---

Exercise Templates

Fetch Exercise Templates (all or single)

# All templates (cached to workspace `data/exercise_templates.json`)
npx tsx skills/hevy-api/scripts/fetch-exercise-templates.ts

# Single template by ID
npx tsx skills/hevy-api/scripts/fetch-exercise-templates.ts --id=<templateId>

Lists available exercise templates (built-in + custom). Use to look up exercise_template_id values when building routines.

• pageSize is 100 per page (max allowed), so most accounts fetch in 1-2 pages.

Each template: { id, title, type, primary_muscle_group, secondary_muscle_groups, is_custom }.

Create Custom Exercise Template

npx tsx skills/hevy-api/scripts/create-exercise-template.ts --exercise=<json>

Creates a new custom exercise template via POST /exercise_templates. The --exercise JSON:

• title (required)
• exercise_type: one of weight_reps, bodyweight_reps, weighted_bodyweight, assisted_bodyweight, duration, distance_duration, weight_distance, weight_duration
• equipment_category: barbell, dumbbell, cable, machine, smith_machine, ez_bar, trap_bar, kettlebell, plate, resistance_band, suspension, other, none
• muscle_group: primary muscle group
• other_muscles: array of secondary muscle groups

Returns { id: <newId> }.

---

Routine Folders

Fetch Routine Folders (all or single)

# All folders (cached to workspace `data/routine_folders.json`)
npx tsx skills/hevy-api/scripts/fetch-routine-folders.ts

# Single folder by ID
npx tsx skills/hevy-api/scripts/fetch-routine-folders.ts --id=<folderId>

Lists routine folders. Each folder: { id, index, title, updated_at, created_at }.

Create Routine Folder

npx tsx skills/hevy-api/scripts/create-routine-folder.ts --title="Folder Name"

Creates a new routine folder at index 0 (all others shift). Returns the created folder.

---

Exercise History

Fetch Exercise History

npx tsx skills/hevy-api/scripts/fetch-exercise-history.ts --id=<exerciseTemplateId> [--start=<ISO8601>] [--end=<ISO8601>]

Fetches all historical sets logged for a specific exercise (by template ID).

• --id: Exercise template ID (required — get from fetch-exercise-templates.ts)
• --start: Filter from date (e.g. 2024-01-01T00:00:00Z)
• --end: Filter to date (e.g. 2024-12-31T23:59:59Z)

Returns a JSON array of entries: { workout_id, workout_title, workout_start_time, workout_end_time, exercise_template_id, weight_kg, reps, distance_meters, duration_seconds, rpe, custom_metric, set_type }.

---

Analysis

Analyze Progress

npx tsx skills/hevy-api/scripts/analyze-progress.ts --exercise="Exercise Name"

Analyzes progress for a specific exercise over time. Returns volume trends, weight progression, rep improvements, and estimated 1RM changes (Brzycki formula).

Check Goal Progress

npx tsx skills/hevy-api/scripts/check-goal-progress.ts

Compares recent workout performance against goals in the workspace data/goals.md. Returns progress percentage and recommendations.

Suggest Updates

npx tsx skills/hevy-api/scripts/suggest-updates.ts

Analyzes recent performance and suggests progressive overload, deload, or plateau-breaking changes.

---

Output Format

All scripts output JSON to stdout. Parse the output to use in recommendations.

Error Handling

Scripts exit with code 1 and print error JSON if:

• API key is missing
• API request fails
• Invalid parameters provided

API Reference

See references/HEVY-API.md for full API documentation.