> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hevy

> Connect Serval to Hevy with an API key so workflows can read workouts, routines, exercise templates, and profile data from a Hevy Pro account.

## About Hevy

Hevy is a workout tracking app for logging strength training. The Serval Hevy integration connects to the Hevy API at `api.hevyapp.com` using an API key from a **Hevy Pro** subscription. Once connected, workflows can read workouts, routines, exercise templates, body measurements, and account info for the authenticated user. The integration is marked **Beta** in Serval's connect UI.

**Authentication:** API key sent in the `api-key` HTTP header. Serval stores the key encrypted and attaches it to every request automatically.

**Data sync:** On demand only. There is no background sync — workflows fetch Hevy data live when they run.

## What the Hevy integration enables

| Capability                         | Description                                                                                                                                   |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Hevy Workouts bundle               | Prebuilt workflows to list workouts, fetch a workout by ID, and get the total workout count.                                                  |
| Hevy Routines bundle               | List routines, fetch a routine by ID, and list routine folders.                                                                               |
| Hevy Exercises bundle              | List exercise templates, fetch a template by ID, and retrieve exercise history with optional date filters.                                    |
| Hevy Profile & Measurements bundle | Read the authenticated user's profile info and list logged body measurements.                                                                 |
| Hevy API request                   | Typed access to the Hevy API v1 from custom workflows — workouts, routines, exercise templates, and user endpoints supported by your API key. |

See Hevy's [developer settings](https://hevy.com/settings?developer) for API key generation requirements.

## Get your credentials

You need an active **Hevy Pro** subscription and an API key generated in the Hevy web app.

<Steps>
  <Step title="Confirm Hevy Pro">
    API access requires Hevy Pro. Upgrade in the Hevy app if the developer settings page is unavailable.
  </Step>

  <Step title="Open developer settings">
    In the Hevy web app, go to [Settings → Developer](https://hevy.com/settings?developer).
  </Step>

  <Step title="Generate an API key">
    Create a new API key and copy it immediately.
  </Step>

  <Step title="Paste the key into Serval">
    Use the **API Key** password field in Serval's Hevy connect form.
  </Step>
</Steps>

<Warning>
  Hevy API keys are tied to the account that created them. Workflows operate on that user's workout data only.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the Hevy connect form">
    In Serval, add the Hevy integration. It is labeled **Beta**.
  </Step>

  <Step title="API Key (required)">
    Paste your Hevy API key into the password field. Helper text points to `hevy.com/settings?developer`.
  </Step>

  <Step title="Save and verify">
    Submit the form. Serval runs four health checks against the Hevy API (see below).
  </Step>
</Steps>

<Note>
  When editing an existing connection, the stored API key is shown obfuscated. Re-paste the full key to rotate it.
</Note>

## Verifying the connection

Four health checks run after you connect:

1. **Test Connection** — calls `GET /v1/user/info`. Success includes the authenticated user's display name. Failure: `Unable to connect to Hevy. Please verify your API key is valid and that you have an active Hevy Pro subscription.`
2. **List Workouts** — fetches a page of logged workouts.
3. **List Routines** — fetches saved workout routines.
4. **List Exercise Templates** — fetches available exercise templates.

<Tip>
  If the connection test fails, confirm Hevy Pro is active and regenerate the API key in Hevy developer settings before updating the integration in Serval.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Hevy Pro is required">
    Without an active Pro subscription, key generation and API calls fail. The connection test message explicitly calls this out.
  </Accordion>

  <Accordion title="Read-only prebuilt workflows">
    The shipped Hevy workflow bundles read data only. Creating or editing workouts through Serval requires custom workflows that call write endpoints, if Hevy exposes them for your key.
  </Accordion>

  <Accordion title="Pagination on list endpoints">
    Hevy list endpoints return paginated results. Prebuilt list workflows handle paging; custom workflows should follow the API's page parameters until a page returns fewer rows than the limit.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Hevy integration.