# Semantic Exercise Search

**Semantic (vector) search** over the exercises accessible to your company. Unlike keyword search, it understands the *meaning* of your query — searching for `"exercises for bad knees"` returns relevant low-impact exercises even if they don't contain those exact words.

The AI Trainer runs this search internally when building workouts — you don't need to call it yourself for that. Use it directly when building your **own** agent, or a search/browse experience on top of the exercise library.

```
GET https://data.kinestex.com/api/exercises/search
```

Requires the same JWT Bearer token as the trainer endpoints (see [Authentication](/docs/trainer-api/trainer-api-auth)).

**Query parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | **Yes** | — | Natural-language search query, 1–500 characters |
| `limit` | integer | No | `20` | Max exercises to return (capped at 100) |
| `lang` | string | No | `"en"` | Language code for returned translations (e.g. `"es"`, `"de"`, `"fr"`) |
| `basic_info` | boolean | No | `false` | When `true`, returns a lightweight response with only ID, title, description, and media URLs |
| `categories` | string | No | — | Comma-separated category filter, e.g. `categories=Strength,Cardio` |

**Lightweight response** (`basic_info=true`) — ideal as LLM context:

```json
{
  "exercises": [
    {
      "id": "123",
      "title": "Squat",
      "description": "A fundamental lower-body exercise targeting the quads, glutes, and hamstrings.",
      "thumbnail_url": "https://cdn.kinestex.com/exercises/squat-thumbnail.jpg",
      "video_url": "https://cdn.kinestex.com/exercises/squat.mp4",
      "male_thumbnail_url": "https://cdn.kinestex.com/exercises/squat-male-thumbnail.jpg",
      "male_video_url": "https://cdn.kinestex.com/exercises/squat-male.mp4"
    }
  ],
  "count": 1
}
```

The **full response** (default) additionally includes per exercise: `difficulty_level`, `position`, `calories_per_rep`, `body_parts`, `categories`, `contraindications`, `equipment` (empty array = bodyweight), `repeats`, `countdown`, and a `translation` object for the requested `lang` with `title`, `description`, `tips`, `exercise_steps`, `common_mistakes`, and rest-speech audio URLs.

**Rate limiting:** 50 semantic searches per user per day (resets at UTC midnight) → `429` when exceeded. A company-level daily read quota also applies.

**Errors:** `400` (missing/too-long `query`, invalid `limit`), `401` (missing/invalid JWT), `429`, `500`.

**Examples:**

```bash
# Basic search
curl "https://data.kinestex.com/api/exercises/search?query=core+exercises+for+beginners&limit=10" \
  -H "Authorization: Bearer <jwt>"

# Localized, lightweight, category-filtered
curl "https://data.kinestex.com/api/exercises/search?query=knee+friendly+exercises&lang=es&basic_info=true&categories=Strength,Cardio&limit=5" \
  -H "Authorization: Bearer <jwt>"
```

See [Build a workout-recommendation chatbot](/docs/guides/guide-trainer-chatbot) for a complete example pairing this endpoint with an LLM.

---
Source: https://www.kinestex.com/docs/trainer-api/trainer-api-search · Index: https://www.kinestex.com/llms.txt