| name | hevy-api |
| description | Interact with Hevy fitness API to fetch workouts, routines, exercise data, and more. Requires HEVY_API_KEY in .env file. Use when analyzing training history, checking recent workouts, exploring exercise history, or managing routines and folders. |
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:
- Ask if they have one
- If yes: ask them to provide it, then write to
.env
- If no: suggest using the
hevy-export skill instead (CSV export via browser)
Available Scripts
All scripts are TypeScript and should be run with npx tsx from the project root.
Workouts
Fetch Workouts
npx tsx .opencode/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 data/workouts.json and outputs JSON array.
Fetch Workout Count
npx tsx .opencode/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 .opencode/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 .opencode/skills/hevy-api/scripts/fetch-user-info.ts
Returns the authenticated user's profile: { id, name, url }.
Routines
Fetch Routines (all)
npx tsx .opencode/skills/hevy-api/scripts/fetch-routines.ts
Fetches all user routines with full exercise and set data. Saves to data/routines.json.
Fetch Routine (single)
npx tsx .opencode/skills/hevy-api/scripts/fetch-routine.ts --id=<routineId>
Fetches a single routine by ID.
Create Routine
npx tsx .opencode/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 .opencode/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)
npx tsx .opencode/skills/hevy-api/scripts/fetch-exercise-templates.ts
npx tsx .opencode/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 .opencode/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_durationequipment_category: barbell, dumbbell, cable, machine, smith_machine, ez_bar, trap_bar, kettlebell, plate, resistance_band, suspension, other, nonemuscle_group: primary muscle groupother_muscles: array of secondary muscle groups
Returns { id: <newId> }.
Routine Folders
Fetch Routine Folders (all or single)
npx tsx .opencode/skills/hevy-api/scripts/fetch-routine-folders.ts
npx tsx .opencode/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 .opencode/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 .opencode/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 .opencode/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 .opencode/skills/hevy-api/scripts/check-goal-progress.ts
Compares recent workout performance against goals in data/goals.md. Returns progress percentage and recommendations.
Suggest Updates
npx tsx .opencode/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.
