Exercises

Use POST /exercises to retrieve recommended exercises from Ochy’s catalog. Each exercise is matched when its lookup_keys contain at least one of the strings you pass in search_keys. The values you send in search_keys are the same stable identifiers as search_key in analysis results (texts.search_key). See the full catalog of keys and meanings in Search key mapping.

Map analysis items by search_key, then call this endpoint with those keys to fetch titles, media, difficulty, series, and duration or repetition ranges—without relying on localized labels from the analysis response.

Authentication

Same as the rest of the Partner API: pass your API key in the Authorization: Bearer header (or X-API-Key) on every request. The apiKey query parameter is deprecated. See Authentication.

Request

Item	Value
Method	`POST`
Path	`/exercises`
Auth	`Authorization: Bearer <API_KEY>` header (required)
Body	JSON `application/json`

Body schema

Field	Type	Description
`search_keys`	`string[]`	At least one lookup key (e.g. values from Search key mapping).
`language`	`string`	Locale for the exercise `title` (e.g. `en`, `fr`). Falls back to English if the locale is missing.

Example body

{
  "language": "en",
  "search_keys": [
    "HeadG",
    "PelvicB"
  ]
}

Response

200 OK — JSON array of exercise objects. Each object includes id (UUID), lookup_keys, and a localized title.
lookup_keys lists the stable identifiers used to match this exercise (same values as search_keys in the request and search_key in analysis results).
media may include image, video, and optionally video_portrait.

Example response (200)

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "lookup_keys": ["PelvicB", "HeadG"],
    "difficulty": "easy",
    "effort_per_rep": {
      "max_ms": 15000,
      "min_ms": 10000
    },
    "exercise_format": "duration",
    "kind": "exercise",
    "media": {
      "image": "https://firebasestorage.googleapis.com/v0/b/ochy-7871a.appspot.com/o/assets%2Fexercises%2Fbackview%2Fthumbnails%2FWall%20Assist%20Stork%20Balance.png?alt=media",
      "video": "https://firebasestorage.googleapis.com/v0/b/ochy-7871a.appspot.com/o/assets%2Fexercises%2Fbackview%2Fvideos%2FWall-Assisted-Stork-Balance.mp4?alt=media&token=1c016167-d868-429d-9afb-1d2af1373a1a"
    },
    "number_of_series": 4,
    "title": "Wall Assist Stork Balance"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "lookup_keys": ["PelvicB"],
    "difficulty": "medium",
    "exercise_format": "repetitions",
    "kind": "exercise",
    "media": {
      "image": "https://firebasestorage.googleapis.com/v0/b/ochy-7871a.appspot.com/o/assets%2Fexercises%2Fbackview%2Fthumbnails%2FStep%20Up%20to%20Balance.png?alt=media&token=c6de01b3-f5f7-4fec-95f2-41f50283b718",
      "video": "https://firebasestorage.googleapis.com/v0/b/ochy-7871a.appspot.com/o/assets%2Fexercises%2Fbackview%2Fvideos%2FStep%20Up%20to%20Balance.mp4?alt=media&token=cb8972bf-c8b3-4fcb-89e9-b591c4b4cd5d"
    },
    "number_of_series": 4,
    "repetitions": {
      "max": 10,
      "min": 6
    },
    "title": "Step Up to Balance"
  }
]

A larger catalog match can return many items in one array; the shape is always the same.

Errors

HTTP	`code`	When
400	`invalid_body`	Malformed JSON or missing required fields.
400	`language_required`	`language` is empty.
400	`search_keys_empty`	No usable values in `search_keys`.
404	`no_exercises_found`	No exercises matched the given keys.

Example — nothing matched (404)

{
  "code": "no_exercises_found",
  "detail": "No exercises found for the given search keys"
}

Other errors (e.g. invalid API key, internal failure) follow the same detail / code pattern as the rest of the Partner API.

Example request (cURL)

curl -sS -X POST 'https://partner-api.ochy-prod.com/exercises' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"language":"en","search_keys":["HeadG","PelvicB"]}'

Replace the base URL with your environment (e.g. staging) if needed.

Getting started

Guides

Authentication

Request

Body schema

Example body

Response

Example response (200)

Errors

Example — nothing matched (404)

Example request (cURL)

​Authentication

​Request

​Body schema

​Example body

​Response

​Example response (200)

​Errors

​Example — nothing matched (404)

​Example request (cURL)

Authentication

Request

Body schema

Example body

Response

Example response (200)

Errors

Example — nothing matched (404)

Example request (cURL)