# Hevy

> Hevy is a gym workout tracker and planner app (iOS, Android, web) operated by Hevy Studios, S.L.
> Hevy Pro subscribers can call a public REST API covering workouts, routines, routine folders,
> exercise templates, exercise history and body measurements.

Provenance: GENERATED by the API Evangelist enrichment pipeline on 2026-08-27 from this repo's
apis.yml and captured artifacts. Hevy publishes no llms.txt of its own — https://www.hevyapp.com/llms.txt
and https://api.hevyapp.com/llms.txt both returned 404 on 2026-08-27.

## Getting started

- Base URL: https://api.hevyapp.com
- Interactive reference (Swagger UI): https://api.hevyapp.com/docs
- Authentication: send your key in an `api-key` request header. The value is a UUID.
- Get a key: https://hevy.com/settings?developer — requires an active Hevy Pro subscription.
- Contact: pavel@hevyapp.com (named in the API's own description)

The provider's stability warning, verbatim from the contract: "we make no guarantees that we won't
completely change the structure or abandon the project entirely so use it at your own risk."

## Operations (22)

Workouts
- GET  /v1/workouts — paginated list of workouts
- POST /v1/workouts — create a workout
- GET  /v1/workouts/count — total number of workouts on the account
- GET  /v1/workouts/events — paged change feed (updated | deleted) since a timestamp, newest first
- GET  /v1/workouts/{workoutId} — one workout in full
- PUT  /v1/workouts/{workoutId} — update a workout

Routines
- GET  /v1/routines — paginated list of routines
- POST /v1/routines — create a routine (403 "Routine limit exceeded" when the account cap is hit)
- GET  /v1/routines/{routineId} — one routine
- PUT  /v1/routines/{routineId} — update a routine

Routine folders
- GET  /v1/routine_folders — paginated list of folders
- POST /v1/routine_folders — create a folder (created at index 0)
- GET  /v1/routine_folders/{folderId} — one folder

Exercise templates
- GET  /v1/exercise_templates — paginated catalogue (pageSize max 100)
- POST /v1/exercise_templates — create a custom exercise (403 when the custom-exercise cap is hit)
- GET  /v1/exercise_templates/{exerciseTemplateId} — one template

Exercise history
- GET  /v1/exercise_history/{exerciseTemplateId} — set-level history for one exercise, optional
  start_date / end_date

Body measurements
- GET  /v1/body_measurements — paginated list
- POST /v1/body_measurements — create an entry for a date (409 if that date already has one)
- GET  /v1/body_measurements/{date} — one entry
- PUT  /v1/body_measurements/{date} — update the entry for a date

Account
- GET  /v1/user/info — the authenticated account's id, name and profile URL

## Conventions

- Pagination: `page` (>=1, default 1) and `pageSize` (default 5, max 10; max 100 on
  /v1/exercise_templates). Responses carry `page`, `page_count` and the resource array.
- Fields are snake_case. Weights are kilograms (weight_kg), distances metres, durations seconds.
- Exercise templates use short stable ids, e.g. 79D0BB3A = "Bench Press (Barbell)".
- Body measurements are keyed by date (YYYY-MM-DD), not by a synthetic id.
- Errors: status code only. No JSON error envelope, no error codes, no RFC 9457. An invalid key
  returns HTTP 401 with the bare body `InvalidApiKey` under a text/html content type — do not call
  .json() on a Hevy error response.

## What this API does NOT have — read before writing

- NO delete operation of any kind. Not one DELETE verb exists. A workout, routine, folder or custom
  exercise created by mistake cannot be removed through the API; a human must delete it in the app.
- NO idempotency key and no conditional requests. Retrying a POST after a timeout creates a
  duplicate. Confirm with a GET before retrying a write.
- NO sandbox or test mode. Every write lands on a real person's training log.
- NO published rate limit and no rate-limit headers. Self-throttle anyway; the origin is a single
  Express app with no gateway.
- NO webhooks. Use GET /v1/workouts/events with `since` to stay in sync — but note it covers
  workouts only, not routines, folders, templates or measurements.
- NO scopes. One key is full read/write over the whole account.
- Social feed, followers and Hevy Coach are not exposed by the API.

## Agent surfaces

- Hevy operates NO MCP server. Community MCP servers exist (npm `hevy-mcp`) but are third-party.
- Hevy DOES operate a first-party ChatGPT Custom GPT, "Hevy - Gym workout planner", whose OAuth
  action schema it publishes at https://github.com/hevyapp/hevy-gpt. It deliberately exposes only 6
  operations and forbids routine updates.
- No A2A agent card is served: /.well-known/agent-card.json and /.well-known/agent.json 404 on every
  Hevy host.

## Company

- Website: https://www.hevyapp.com
- Help center: https://www.hevyapp.com/help/ and https://hevyapp.zendesk.com/hc/en-us
- Blog: https://www.hevyapp.com/blog/
- Product updates: https://www.hevyapp.com/community-updates/ (app releases, not API changes)
- Status: https://www.hevyapp.com/status/ (hand-maintained page; not machine-readable)
- Pricing: https://www.hevy.com/pricing (Hevy Pro; prices rendered client-side by Paddle)
- Terms: https://www.hevyapp.com/legal/terms-and-conditions/
- Privacy: https://www.hevyapp.com/legal/privacy-policy/
- GitHub: https://github.com/hevyapp
- Hevy Coach (trainer product, no public API): https://hevycoach.com/