# Exercises API
> A complete exercise and workout database covering 870+ exercises: search and filter by target muscle, required equipment, category, difficulty level, force type and mechanic, fetch a single exercise with step-by-step instructions, primary and secondary muscles and demonstration images, pull a random exercise matching any filter, and read all available facet values to build filter UIs. Every endpoint accepts input via the query string or the request body and returns lean, predictable JSON. Pure server-side data (no third-party upstream), so responses are instant and always available. Ideal for fitness and gym apps, workout planners, personal-trainer tools and health platforms.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/exercises-api/..."
```

## Pricing
- **Free** (Free) — 15,000 calls/Mo, 2 req/s
- **Basic** ($7/Mo) — 200,000 calls/Mo, 8 req/s
- **Pro** ($22/Mo) — 1,500,000 calls/Mo, 25 req/s
- **Mega** ($55/Mo) — 7,000,000 calls/Mo, 60 req/s

## Endpoints

### Exercises

#### `GET /v1/exercise` — Single exercise (full detail) by id

**Parameters:**
- `id` (query, required, string) — Exercise id Example: `Barbell_Full_Squat`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/exercises-api/v1/exercise?id=Barbell_Full_Squat"
```

#### `GET /v1/meta` — Facet values (muscles/equipment/categories/...)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/exercises-api/v1/meta"
```

#### `GET /v1/random` — Random exercise(s) by filter

**Parameters:**
- `muscle` (query, optional, string) — Target muscle Example: `biceps`
- `equipment` (query, optional, string) — Equipment Example: `dumbbell`
- `category` (query, optional, string) — Category Example: `cardio`
- `size` (query, optional, string) — 1..10 (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/exercises-api/v1/random?muscle=biceps&equipment=dumbbell&category=cardio&size=1"
```

#### `GET /v1/search` — Search & filter exercises

**Parameters:**
- `q` (query, optional, string) — Free-text Example: `squat`
- `muscle` (query, optional, string) — Target muscle Example: `chest`
- `equipment` (query, optional, string) — Equipment Example: `barbell`
- `category` (query, optional, string) — Category Example: `strength`
- `level` (query, optional, string) — beginner|intermediate|expert Example: `beginner`
- `force` (query, optional, string) — push|pull|static Example: `push`
- `mechanic` (query, optional, string) — compound|isolation Example: `compound`
- `limit` (query, optional, string) — 1..100 (default 20) Example: `20`
- `offset` (query, optional, string) — Offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/exercises-api/v1/search?q=squat&muscle=chest&equipment=barbell&category=strength&level=beginner&force=push&mechanic=compound&limit=20&offset=0"
```


---
Marketplace page: https://www.oanor.com/api/exercises-api
OpenAPI spec: https://www.oanor.com/api/exercises-api/openapi.json