# 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"
```

**Response:**
```json
{
    "data": {
        "id": "Barbell_Full_Squat",
        "name": "Barbell Full Squat",
        "force": "push",
        "level": "intermediate",
        "images": [
            "https://raw.githubusercontent.com/yuhonas/free-exercise-db/main/exercises/Barbell_Full_Squat/0.jpg",
            "https://raw.githubusercontent.com/yuhonas/free-exercise-db/main/exercises/Barbell_Full_Squat/1.jpg"
        ],
        "category": "strength",
        "mechanic": "compound",
        "equipment": "barbell",
        "instructions": [
            "This exercise is best performed inside a squat rack for safety purposes. To begin, first set the bar on a rack just above shoulder level. Once the correct height is chosen and the bar is loaded, step under the bar and place the back of your shoulders (slightly below the neck) across it.",
            "Hold on to the bar using both arms at each side and lift it off the rack by first pushing with your legs and at the same time straightening your torso.",
            "Step away from the rack and position your legs using a shoulder-width medium stance with the toes slightly pointed out. Keep your head up at all times and maintain a straight back. This will be your starting position.",
            "Begin to slowly lower the bar by bending the knees and sitting back with your hips as you maintain a straight posture with the head up. Continue down until your hamstrings are on your calves. Inhale as you perform this portion of the movement.",
          
…(truncated, see openapi.json for full schema)
```

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

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

**Response:**
```json
{
    "data": {
        "total": 873,
        "forces": [
            "pull",
            "push",
            "static"
        ],
        "levels": [
            "beginner",
            "expert",
            "intermediate"
        ],
        "muscles": [
            "abdominals",
            "abductors",
            "adductors",
            "biceps",
            "calves",
            "chest",
            "forearms",
            "glutes",
            "hamstrings",
            "lats",
            "lower back",
            "middle back",
            "neck",
            "quadriceps",
            "shoulders",
            "traps",
            "triceps"
        ],
        "equipment": [
            "bands",
            "barbell",
            "body only",
            "cable",
            "dumbbell",
            "e-z curl bar",
            "exercise ball",
            "foam roll",
            "kettlebells",
            "machine",
            "medicine ball",
            "other"
        ],
        "mechanics": [
            "compound",
            "isolation"
        ],
        "categories": [
            "cardio",
            "olympic weightlifting",
            "plyometrics",
            "powerlifting",
            "strength",
            "stretching",
            "strongman"
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:34.474Z",
        "request_id": "38168f9e-62b3-4ea1-ad13-cddb3179a3dc"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "succe
…(truncated, see openapi.json for full schema)
```

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

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

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

**Response:**
```json
{
    "data": {
        "count": 1,
        "filters": {
            "q": null,
            "force": null,
            "level": null,
            "muscle": null,
            "category": null,
            "mechanic": null,
            "equipment": null
        },
        "results": [
            {
                "id": "Dynamic_Chest_Stretch",
                "name": "Dynamic Chest Stretch",
                "force": "pull",
                "level": "beginner",
                "images": [
                    "https://raw.githubusercontent.com/yuhonas/free-exercise-db/main/exercises/Dynamic_Chest_Stretch/0.jpg",
                    "https://raw.githubusercontent.com/yuhonas/free-exercise-db/main/exercises/Dynamic_Chest_Stretch/1.jpg"
                ],
                "category": "stretching",
                "mechanic": null,
                "equipment": null,
                "instructions": [
                    "Stand with your hands together, arms extended directly in front of you. This will be your starting position.",
                    "Keeping your arms straight, quickly move your arms back as far as possible and back in again, similar to an exaggerated clapping motion. Repeat 5-10 times, increasing speed as you do so."
                ],
                "primaryMuscles": [
                    "chest"
                ],
                "secondaryMuscles": [
                    "middle back"
                ]
            }
        ]
    },
    "meta": {
        "timestam
…(truncated, see openapi.json for full schema)
```

#### `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"
```

**Response:**
```json
{
    "data": {
        "count": 0,
        "limit": 20,
        "total": 0,
        "offset": 0,
        "filters": {
            "q": "squat",
            "force": "push",
            "level": "beginner",
            "muscle": "chest",
            "category": "strength",
            "mechanic": "compound",
            "equipment": "barbell"
        },
        "results": []
    },
    "meta": {
        "timestamp": "2026-05-30T22:48:34.597Z",
        "request_id": "02050a16-1362-44a1-ac41-82803ed72186"
    },
    "status": "ok",
    "message": "Search completed",
    "success": true
}
```


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