{"openapi":"3.0.0","paths":{"/v1/workouts/metadata":{"get":{"operationId":"WorkoutsApi_getWorkoutMetadata","summary":"Get available workout categories and difficulties","description":"\nRetrieves all unique workout categories (e.g., HIIT, Strength, Mobility, Cardio) and difficulty levels available across workouts.\n\n**Use this endpoint to populate:**\n- `categoryId` parameter in `POST /v1/orgs/{orgId}/workouts/generate`\n- Workout category filters in your UI\n\n**Response includes:**\n- `categories`: Array of {id, name} objects for each workout category\n- `difficulties`: Array of difficulty strings (beginner, intermediate, advanced)\n\n**Example Categories:**\n- HIIT (615aa3f0dbe7140012c59e94)\n- Strength (615aa3dadbe7140012c59e90)\n- Mobility (615aa3e5dbe7140012c59e92)\n- Cardio (615aa3ebdbe7140012c59e93)\n- Yoga (649edb81733e2e007a30ab8d)\n- Pilates (615aa3f5dbe7140012c59e95)\n\n**Related Metadata Endpoints:**\n- `GET /v1/workouts/metadata` - Categories & difficulties (for workout generation/filtering)\n- `GET /v1/workouts/equipment/metadata` - Equipment items & categories\n- `GET /v1/workouts/exercises/metadata` - Muscle groups & collections\n- `GET /v1/plans/metadata` - Goals & difficulties (for plan generation)\n\n**For Workout Generation:** Call this endpoint + equipment/metadata + exercises/metadata (advanced)\n\n---\n\n### 🌍 Localization\n\nContent localized based on `locale` query parameter:\n- **Supported**: 13 languages (en-US, fr-FR, de-DE, es-ES, etc.)\n- **Fallback**: English if locale unsupported\n- **Affects**: Category names\n\n---\n\n**Related Endpoints:**\n- Generate: `POST /v1/orgs/{orgId}/workouts/generate`\n- List: `GET /v1/orgs/{orgId}/workouts`\n- Recommend: `POST /v1/orgs/{orgId}/workouts/recommend`\n ","parameters":[{"name":"locale","required":false,"in":"query","description":"Preferred language locale (e.g., fr-FR)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved category and difficulty lists.","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","description":"List of all available workout categories.","items":{"type":"object","properties":{"id":{"type":"string","description":"Category ID","example":"615aa3f0dbe7140012c59e94"},"name":{"type":"string","description":"Category display name","example":"HIIT"}},"required":["id","name"]}},"difficulties":{"type":"array","description":"List of all available difficulty levels.","items":{"type":"string","example":"intermediate"}}},"example":{"categories":[{"id":"615aa3f0dbe7140012c59e94","name":"HIIT"},{"id":"615aa3dadbe7140012c59e90","name":"Strength"},{"id":"615aa3e5dbe7140012c59e92","name":"Mobility"}],"difficulties":["beginner","intermediate","advanced"]}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts/metadata' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getWorkoutMetadata() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts/metadata', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts/metadata\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/equipment/metadata":{"get":{"operationId":"WorkoutsApi_getEquipmentMetadata","summary":"Get available equipment categories and equipment items","description":"\nRetrieves all equipment items (e.g., Dumbbells, Kettlebells, Resistance Bands) and their categories (e.g., Free Weights, Bodyweight, Gym Equipment).\n\n**Use this endpoint to populate:**\n- `preferredEquipmentCategoryIds` in workout generation requests\n- Equipment filters in your application UI\n\n**Response includes:**\n- `categories`: Equipment categories with {id, name, category} \n- `equipment`: Individual equipment items with {id, name, equipmentCategoryId}\n\n**Example Equipment Categories:**\n- Bodyweight (67deb36a6a5e49797c122f56)\n- Free Weights (67deb3696a5e49797c122f55)\n- Gym Equipment (67deb36a6a5e49797c122f57)\n\n**Example Equipment Items:**\n- Dumbbell (60812dea606fc90011eb4405) β†’ Free Weights\n- Kettlebell (60812dd5606fc90011eb4404) β†’ Free Weights\n- Mat (60812e08606fc90011eb4408) β†’ Bodyweight\n- Resistance Band (64f9800b3b07122623b91c7d) β†’ Free Weights\n\n---\n\n### 🌍 Localization\n\nContent localized based on `locale` query parameter:\n- **Supported**: 13 languages (en-US, fr-FR, de-DE, es-ES, etc.)\n- **Fallback**: English if locale unsupported\n- **Affects**: Equipment names, equipment category names\n\n---\n\n**Related Metadata Endpoints:**\n- `GET /v1/workouts/equipment/metadata` - Equipment items & categories\n- `GET /v1/workouts/metadata` - Categories & difficulties\n- `GET /v1/workouts/exercises/metadata` - Muscle groups & collections\n\n**Related Endpoints:**\n- Generate: `POST /v1/orgs/{orgId}/workouts/generate`\n- List: `GET /v1/orgs/{orgId}/workouts`\n ","parameters":[{"name":"locale","required":false,"in":"query","description":"Preferred language locale (e.g., fr-FR)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved equipment and category lists.","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","description":"List of all available equipment categories.","items":{"type":"object","properties":{"id":{"type":"string","description":"Category ID","example":"67deb36a6a5e49797c122f56"},"name":{"type":"string","description":"Category display name","example":"Bodyweight"},"category":{"type":"string","description":"Broader category grouping","example":"bodyweight"}},"required":["id","name","category"]}},"equipment":{"type":"array","description":"List of all available equipment items.","items":{"type":"object","properties":{"id":{"type":"string","description":"Equipment ID","example":"60812dea606fc90011eb4405"},"name":{"type":"string","description":"Equipment display name","example":"Dumbbell"},"equipmentCategoryId":{"type":"string","description":"ID of the category this equipment belongs to (optional)","example":"67deb3696a5e49797c122f55","nullable":true}},"required":["id","name"]}}},"example":{"categories":[{"id":"67deb36a6a5e49797c122f56","name":"Bodyweight","category":"bodyweight"},{"id":"67deb3696a5e49797c122f55","name":"Free Weights","category":"free_weights"},{"id":"67deb36a6a5e49797c122f57","name":"Gym Equipment","category":"gym"}],"equipment":[{"id":"60812dea606fc90011eb4405","name":"Dumbbell","equipmentCategoryId":"67deb3696a5e49797c122f55"},{"id":"60812dd5606fc90011eb4404","name":"Kettlebell","equipmentCategoryId":"67deb3696a5e49797c122f55"},{"id":"60812e08606fc90011eb4408","name":"Mat","equipmentCategoryId":"67deb36a6a5e49797c122f56"}]}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts/equipment/metadata' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getEquipmentMetadata() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts/equipment/metadata', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts/equipment/metadata\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}":{"get":{"operationId":"WorkoutsApi_getWorkout","summary":"Get workout details","description":"\n## Complete Workout Details\n\nRetrieves comprehensive workout information including metadata, equipment requirements, muscle group distribution, and media assets.\n\n---\n\n### πŸ“‹ What's Included\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| **Core Info** | Name, description, duration, difficulty | \"Full Body HIIT\", 1800 seconds |\n| **Categories** | Workout type classifications | [\"HIIT\", \"Cardio\"] |\n| **Equipment** | Required/recommended gear | [\"Dumbbells\", \"Mat\"] |\n| **Muscle Groups** | Percentage distribution (sorted) | Chest: 35%, Arms: 25% |\n| **Media Assets** | Preview videos, images, audio | HLS streams, thumbnails |\n| **Trainer Info** | Coach details and organization | Name, bio, team |\n\n---\n\n### 🎯 Use Cases\n\nβœ… **Workout Preview** - Show details before starting \nβœ… **Equipment Check** - Verify user has required gear \nβœ… **Difficulty Assessment** - Match to user fitness level \nβœ… **Content Discovery** - Browse workout library\n\n---\n\n### πŸ”„ Integration Flow\n\n1. **Browse Workouts**: `GET /v1/workouts` β†’ Get workout list\n2. **Get Details**: `GET /v1/workouts/{id}` β†’ **This endpoint** (full details)\n3. **Check Equipment**: Review equipment array for user compatibility\n4. **Start Session**: `POST /v1/workouts/{id}/sessions/start`\n5. **Get Playlist**: `GET /v1/workouts/{id}/playlist` β†’ Detailed segments\n\n---\n\n### 🌍 Localization\n\nContent localized based on `locale` query parameter:\n- **Supported**: 13 languages (en-US, fr-FR, de-DE, es-ES, etc.)\n- **Fallback**: English if locale unsupported\n- **Affects**: Name, description, equipment names, muscle group names\n\n---\n\n### πŸ”— Related Endpoints\n\n- Workout List: `GET /v1/workouts` - Browse all workouts\n- Workout Playlist: `GET /v1/workouts/{id}/playlist` - Get detailed segments\n- Start Session: `POST /v1/workouts/{id}/sessions/start` - Begin tracking\n- Submit Feedback: `POST /v1/workouts/{id}/feedback` - Rate workout\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout to retrieve.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"Preferred language locale (e.g., fr-FR)","schema":{"type":"string"}}],"responses":{"200":{"description":"Workout details retrieved successfully.","schema":{"example":{"data":{"id":"12ab3efd45c67c1234566cd1","name":"Full Body HIIT Power","description":"A high-intensity interval training session targeting full body strength and cardiovascular fitness","duration":1800,"difficulty":"intermediate","visibility":"public","locked":false,"createdAt":"2023-10-26T10:00:00.000Z","updatedAt":"2023-10-27T11:30:00.000Z","trainer":{"id":"64f1a2b3c4d5e6f7a8b9c0d4","name":"Sarah Johnson"},"categories":[{"id":"615aa3f0dbe7140012c59e94","name":"HIIT"},{"id":"615aa3ebdbe7140012c59e93","name":"Cardio"}],"equipment":[{"id":"60812dea606fc90011eb4405","name":"Dumbbell","equipmentCategoryId":"67deb3696a5e49797c122f55"},{"id":"60812e08606fc90011eb4408","name":"Mat","equipmentCategoryId":"67deb36a6a5e49797c122f56"}],"muscleGroupPercentages":[{"muscleGroupId":"604b0129beaba770c284ff40","muscleGroupName":"Arms","percentage":25.5},{"muscleGroupId":"604b0169076fe2727354d740","muscleGroupName":"Chest","percentage":20},{"muscleGroupId":"604b0177076fe2727354d743","muscleGroupName":"Legs","percentage":30},{"muscleGroupId":"604b0170076fe2727354d741","muscleGroupName":"Core","percentage":24.5}],"preview":{"url":"https://stream.hyperhuman.cc/workout-preview.m3u8","poster":"https://images.hyperhuman.cc/workout-poster.jpg","thumbnail":"https://images.hyperhuman.cc/workout-thumb.jpg"},"images":{"thumbnail":"https://images.hyperhuman.cc/workout-thumb.jpg","cover":"https://images.hyperhuman.cc/workout-cover.jpg"},"shareLink":{"url":"https://app.hyperhuman.cc/workouts/12ab3efd45c67c1234566cd1"},"organization":null,"rating":4.5,"mixBgMusic":true,"presentationStyle":"full","skipWorkoutPreview":false,"skipWorkoutCompletionScreen":false,"videoAudioMode":"full","allowAssessment":false,"assessmentType":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutResponse"}}}},"401":{"description":"Authentication failed - API key is missing, invalid, or Bearer token is missing/invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getWorkout() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts/', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/export/video/stream_url":{"get":{"operationId":"WorkoutsApi_getExportVideoStream","summary":"Get complete workout video export URL","description":"\n## Full Workout Video Export\n\nReturns a pre-signed S3 URL to a **complete, fully-rendered workout video** for the requested locale. This is typically a single file containing the entire workout from start to finish, including all exercises, rest periods, audio narration, graphics, and timing overlays.\n\n**Response shape:** HTTP **200** with **Content-Type: text/plain**. The body is a **single** URL string (not JSON). The URL is presigned and valid for **7 days**. The object at that URL matches whatever the export pipeline stored (commonly **MP4**; **HLS** or other packaging is possible in some casesβ€”use the file extension and response headers when fetching the URL).\n\n---\n\n### πŸ“‹ Video Details\n\n**Format:** MP4 (H.264) \n**Resolution:** 1080p (1920x1080) \n**Frame Rate:** 30 fps \n**Codec:** H.264 (High Profile) \n**Audio:** AAC stereo, embedded in video \n**File Size:** Typically 100-500 MB depending on workout length \n**Expiration:** Pre-signed URL valid for 7 days \n**Protocol:** HTTPS \n**Content Type:** video/mp4\n\n---\n\n### 🎯 Use Cases\n\nThis endpoint is ideal for:\n- **Simple video playback** - Direct download and play the complete workout\n- **Offline viewing** - Download the full video for offline use\n- **Social sharing** - Share the complete workout video\n- **Video archival** - Store the full workout as a single file\n- **Third-party players** - Use any standard MP4-compatible video player\n\n---\n\n### 🎬 Integration Examples\n\n**Basic HTML5 Video Player:**\n```javascript\n// Fetch the video URL\nconst videoUrl = await fetch(\n `/v1/workouts/${workoutId}/export/video/stream_url?locale=en-US`,\n { headers: { 'X-Api-Key': apiKey } }\n).then(r => r.text());\n\n// Use standard HTML5 video player\nconst video = document.createElement('video');\nvideo.src = videoUrl;\nvideo.controls = true;\nvideo.width = 1920;\nvideo.height = 1080;\ndocument.body.appendChild(video);\n```\n\n**iOS/Swift AVPlayer:**\n```swift\nlet videoURL = URL(string: videoUrlString)!\nlet player = AVPlayer(url: videoURL)\nlet playerViewController = AVPlayerViewController()\nplayerViewController.player = player\npresent(playerViewController, animated: true) {\n player.play()\n}\n```\n\n**Android/Kotlin ExoPlayer:**\n```kotlin\nval player = ExoPlayer.Builder(context).build()\nplayerView.player = player\nval mediaItem = MediaItem.fromUri(videoUrl)\nplayer.setMediaItem(mediaItem)\nplayer.prepare()\nplayer.play()\n```\n\n**Download for Offline Use:**\n```javascript\nasync function downloadWorkoutVideo(workoutId, filename) {\n const videoUrl = await fetch(\n `/v1/workouts/${workoutId}/export/video/stream_url`,\n { headers: { 'X-Api-Key': apiKey } }\n ).then(r => r.text());\n \n const response = await fetch(videoUrl);\n const blob = await response.blob();\n const url = window.URL.createObjectURL(blob);\n const a = document.createElement('a');\n a.href = url;\n a.download = filename || 'workout.mp4';\n a.click();\n}\n```\n\n---\n\n### 🌍 Localization Support\n\nThe video export includes localized content based on the `locale` parameter:\n- **Audio narration** - Voice instructions in the requested language\n- **Text overlays** - Exercise names, timers, and instructions in local language\n- **Exercise names** - Localized exercise titles\n\n**Supported locales:**\nen-US, en-GB, en-AU, fr-FR, de-DE, es-ES, it-IT, pt-PT, he-IL, ro-RO, cs-CZ, fi-FI, nl-NL\n\n**Locale fallback behavior:**\n1. If requested locale exists β†’ return that version\n2. If requested locale not available but user's preferred locale exists β†’ return preferred version\n3. Otherwise β†’ return English (en-US) version\n4. If no export available β†’ return 404\n\n---\n\n### ⚑ Video Generation Status\n\nWorkout videos are **pre-generated asynchronously** after workout creation or modification. \n\n**Possible scenarios:**\n- βœ… **Video ready** - Returns URL immediately (typical case)\n- ⏳ **Video processing** - Returns 404 if generation still in progress (usually 2-5 minutes)\n- ❌ **Generation failed** - Returns 404 if export job failed\n\n**Best practice:** Check `GET /v1/workouts/{id}` response for video availability before requesting stream URL.\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Cache the URL** - Save in memory/storage for up to 6 days \nβœ… **Refresh before expiration** - Fetch new URL when approaching 7-day limit \nβœ… **Handle 404 gracefully** - Video may still be processing \nβœ… **Support offline download** - Allow users to download for offline viewing \nβœ… **Show file size** - Inform users about download size (typically 100-500 MB) \nβœ… **Implement retry logic** - Retry with exponential backoff if initial request fails \nβœ… **Consider bandwidth** - These are large files; provide quality/size warnings on mobile\n\n---\n\n### πŸ”„ Workflow Comparison\n\n**Option A: Complete Video (This Endpoint)**\n```\nGET /v1/workouts/{id}/export/video/stream_url\nβ†’ Single presigned URL to the full-workout video export\nβ†’ Simple playback, no segment control\nβ†’ Ideal for: Downloads, simple players, sharing\n```\n\n**Option B: Segmented Playlist**\n```\nGET /v1/workouts/{id}/playlist\nβ†’ Individual exercise videos + timing\nβ†’ Full control over each segment\nβ†’ Ideal for: Custom players, skip exercises, progress tracking\n```\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### πŸ”— Related Endpoints\n\n- **Workout Details:** `GET /v1/workouts/{id}` - Get workout metadata\n- **Workout Playlist:** `GET /v1/workouts/{id}/playlist` - Get segment-by-segment structure\n- **Audio Only:** `GET /v1/workouts/{id}/export/audio/stream_url` - Get audio-only version\n- **Start Session:** `POST /v1/workouts/{id}/sessions/start` - Track workout session\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier of the workout.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"Preferred language locale (e.g., de-DE, fr-FR, en-US). If specified and no export exists for this locale, returns 404. Falls back to user's preferred locale or en-US.","example":"en-US","schema":{"type":"string"}}],"responses":{"200":{"description":"text/plain body: a single presigned HTTPS URL to the full video export (valid 7 days). Format of the linked asset matches the stored render (commonly MP4; see operation description).","content":{"application/json":{"schema":{"type":"string"}}}},"401":{"description":"Authentication failed - API key is missing, invalid, or Bearer token is missing/invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Workout not found, video export not available for the requested locale, or video is still being generated (processing typically takes 2-5 minutes after workout creation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts//export/video/stream_url' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getExportVideoStream() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//export/video/stream_url', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts//export/video/stream_url\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/export/audio/stream_url":{"get":{"operationId":"WorkoutsApi_getExportAudioStream","summary":"Get audio-only workout export URL","description":"\n## Audio-Only Workout Export\n\nReturns a pre-signed S3 URL to the **complete audio narrative** for the workout. This is ideal for audio-guided workout experiences where users prefer voice-only instruction without video.\n\n**Response shape:** HTTP **200** with **Content-Type: text/plain**. The body is a **single** URL string (not JSON), presigned and valid for **7 days**, pointing at the generated narrative audio object (commonly **M4A**).\n\n---\n\n### πŸ“‹ Audio Details\n\n**Format:** M4A (AAC) \n**Quality:** 128 kbps stereo \n**File Size:** Typically 5-20 MB depending on workout length \n**Content:** Voice narration, exercise instructions, timing cues, background audio \n**Expiration:** Pre-signed URL valid for 7 days \n**Protocol:** HTTPS \n**Content Type:** audio/mp4\n\n---\n\n### 🎧 Use Cases\n\nPerfect for:\n- **Audio-only workouts** - Voice-guided training without video overhead\n- **Background play** - Users can multitask while working out\n- **Low bandwidth** - Only 5-20 MB vs 100-500 MB for video\n- **Accessibility** - Screen-free workout experience for visually impaired users\n- **Outdoor activities** - Listen while running, cycling, or hiking\n- **Podcast-style workouts** - Portable fitness content\n- **Mobile data savings** - Significantly reduced data consumption\n\n---\n\n### 🎬 Integration Examples\n\n**Basic HTML5 Audio:**\n```javascript\n// Fetch audio URL\nconst audioUrl = await fetch(\n `/v1/workouts/${workoutId}/export/audio/stream_url?locale=en-US`,\n { headers: { 'X-Api-Key': apiKey } }\n).then(r => r.text());\n\n// Simple audio player\nconst audio = new Audio(audioUrl);\naudio.play();\n\n// Or with controls\nconst player = document.createElement('audio');\nplayer.src = audioUrl;\nplayer.controls = true;\ndocument.body.appendChild(player);\n```\n\n**Custom Audio Player with Progress Tracking:**\n```javascript\nconst audio = new Audio(audioUrl);\n\n// Track progress\naudio.addEventListener('timeupdate', () => {\n const progress = (audio.currentTime / audio.duration) * 100;\n console.log(`Workout progress: ${progress.toFixed(1)}%`);\n});\n\n// Handle completion\naudio.addEventListener('ended', () => {\n console.log('Workout completed!');\n // Submit workout session completion\n});\n\n// Play with controls\naudio.play();\n```\n\n**iOS/Swift AVAudioPlayer:**\n```swift\nlet audioURL = URL(string: audioUrlString)!\ndo {\n let audioData = try Data(contentsOf: audioURL)\n audioPlayer = try AVAudioPlayer(data: audioData)\n audioPlayer?.prepareToPlay()\n audioPlayer?.play()\n} catch {\n print(\"Error loading audio: \\(error)\")\n}\n```\n\n**Android/Kotlin MediaPlayer:**\n```kotlin\nval mediaPlayer = MediaPlayer().apply {\n setDataSource(audioUrl)\n prepareAsync()\n setOnPreparedListener { start() }\n}\n```\n\n**Background Audio with Web Audio API:**\n```javascript\nconst audioContext = new (window.AudioContext || window.webkitAudioContext)();\nconst audioElement = new Audio(audioUrl);\nconst track = audioContext.createMediaElementSource(audioElement);\ntrack.connect(audioContext.destination);\n\n// Enable background playback\nif ('mediaSession' in navigator) {\n navigator.mediaSession.metadata = new MediaMetadata({\n title: 'HIIT Workout',\n artist: 'Hyperhuman',\n album: 'Workout Audio',\n });\n}\n\naudioElement.play();\n```\n\n---\n\n### 🌍 Localization Support\n\nAudio includes localized voice narration in the requested language:\n- **Voice instructions** - Exercise cues in native language\n- **Counting** - Rep counts and timers in local language\n- **Motivational cues** - Encouragement in native language\n\n**Supported locales:**\nen-US, en-GB, en-AU, fr-FR, de-DE, es-ES, it-IT, pt-PT, he-IL, ro-RO, cs-CZ, fi-FI, nl-NL\n\n**Locale fallback behavior:**\n1. If requested locale exists β†’ return that version\n2. If requested locale not available but user's preferred locale exists β†’ return preferred version\n3. Otherwise β†’ return English (en-US) version\n4. If no audio export available β†’ return 404\n\n---\n\n### ⚑ Audio Generation Status\n\nAudio files are **pre-generated asynchronously** after workout creation.\n\n**Possible scenarios:**\n- βœ… **Audio ready** - Returns URL immediately (typical case)\n- ⏳ **Audio processing** - Returns 404 if generation in progress (usually 1-3 minutes)\n- ❌ **Generation failed** - Returns 404 if export job failed\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Cache the URL** - Save in memory/storage for up to 6 days \nβœ… **Refresh before expiration** - Fetch new URL after 6 days \nβœ… **Enable background playback** - Allow app to continue playing when screen is off \nβœ… **Handle network errors** - Implement retry logic with exponential backoff \nβœ… **Show progress** - Display current time and duration \nβœ… **Support playback controls** - Play, pause, seek, speed adjustment \nβœ… **Lock screen controls** - Integrate with OS media controls \nβœ… **Download option** - Allow offline download for gym use with no connectivity\n\n---\n\n### πŸ”„ Content Comparison\n\n**Audio Export (This Endpoint):**\n- Complete audio narrative in one file\n- Voice instructions + timing cues + background audio\n- 5-20 MB file size\n- Simple streaming/download\n\n**Playlist Audio:**\n- Individual audio clips per segment\n- Requires assembly and synchronization\n- More control but more complexity\n\n---\n\n### πŸ”— Related Endpoints\n\n- **Workout Details:** `GET /v1/workouts/{id}` - Get workout metadata\n- **Workout Playlist:** `GET /v1/workouts/{id}/playlist` - Get segment-by-segment structure\n- **Video Export:** `GET /v1/workouts/{id}/export/video/stream_url` - Get full video version\n- **Start Session:** `POST /v1/workouts/{id}/sessions/start` - Track workout session\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier of the workout.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"Preferred language locale for audio narration (e.g., de-DE, fr-FR, en-US). If specified and no export exists for this locale, returns 404. Falls back to user's preferred locale or en-US.","example":"en-US","schema":{"type":"string"}}],"responses":{"200":{"description":"text/plain body: a single presigned HTTPS URL to the full narrative audio export (valid 7 days; commonly M4A/AAC).","content":{"application/json":{"schema":{"type":"string"}}}},"401":{"description":"Authentication failed - API key is missing, invalid, or Bearer token is missing/invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Workout not found, audio export not available for the requested locale, or audio is still being generated (processing typically takes 1-3 minutes after workout creation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts//export/audio/stream_url' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getExportAudioStream() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//export/audio/stream_url', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts//export/audio/stream_url\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/exercises/metadata":{"get":{"operationId":"WorkoutsApi_getExercisesMetadata","summary":"Get available muscle groups and exercise collections","description":"\nRetrieves all muscle groups and exercise collections with counts.\n\n**Use this endpoint to populate:**\n- `muscleGroupIds` for targeted muscle group focus in workout generation\n- `excludeExerciseCollections` to avoid specific trainer styles or backgrounds\n\n**Response includes:**\n- `muscleGroups`: Array of {id, name} for each muscle group (Arms, Chest, Legs, Core, etc.)\n- `collections`: Array of {name, count} for exercise collections (Free/Premium categories)\n\n**Example Muscle Groups:**\n- Arms (604b0129beaba770c284ff40)\n- Chest (604b0169076fe2727354d740)\n- Back (604b016c076fe2727354d740)\n- Core (604b0170076fe2727354d741)\n- Legs (604b0177076fe2727354d743)\n- Shoulders (604b0165076fe2727354d73e)\n- Glutes (604b0173076fe2727354d742)\n\n**Example Collections:**\n- \"Premium - Neutral\" (808 exercises) - Consistent neutral background\n- \"Premium - Industrial\" (200 exercises) - Industrial gym setting\n- \"Premium - White\" (151 exercises) - Clean white background\n- \"Free - Eclectic Home\" (239 exercises) - Varied home settings\n- \"Premium - Advanced Gym\" (120 exercises) - Professional gym equipment\n\n---\n\n### 🌍 Localization\n\nContent localized based on `locale` query parameter:\n- **Supported**: 13 languages (en-US, fr-FR, de-DE, es-ES, etc.)\n- **Fallback**: English if locale unsupported\n- **Affects**: Muscle group names (collections not localized)\n\n---\n\n**Related Metadata Endpoints:**\n- `GET /v1/workouts/exercises/metadata` - Muscle groups & collections\n- `GET /v1/workouts/metadata` - Categories & difficulties\n- `GET /v1/workouts/equipment/metadata` - Equipment items & categories\n\n**Related Endpoints:**\n- Generate: `POST /v1/orgs/{orgId}/workouts/generate`\n- List: `GET /v1/orgs/{orgId}/workouts`\n ","parameters":[{"name":"locale","required":false,"in":"query","description":"Preferred language locale (e.g., fr-FR)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved list of muscle groups and exercise collections.","content":{"application/json":{"schema":{"type":"object","properties":{"muscleGroups":{"type":"array","description":"List of all available muscle groups.","items":{"type":"object","properties":{"id":{"type":"string","description":"Muscle group ID","example":"604b0129beaba770c284ff40"},"name":{"type":"string","description":"Muscle group display name","example":"Arms"}},"required":["id","name"]}},"collections":{"type":"array","description":"List of all available exercise collections with exercise counts.","items":{"type":"object","properties":{"name":{"type":"string","description":"Collection name","example":"Premium - Neutral"},"count":{"type":"number","description":"Number of exercises in this collection","example":808}},"required":["name","count"]}}},"example":{"muscleGroups":[{"id":"604b0129beaba770c284ff40","name":"Arms"},{"id":"604b0169076fe2727354d740","name":"Chest"},{"id":"604b0177076fe2727354d743","name":"Legs"}],"collections":[{"name":"Premium - Neutral","count":808},{"name":"Premium - Industrial","count":200},{"name":"Free - Eclectic Home","count":239}]}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts/exercises/metadata' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getExercisesMetadata() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts/exercises/metadata', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts/exercises/metadata\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/workouts":{"get":{"operationId":"OrganizationWorkoutsApi_getOrganizationWorkouts","summary":"List organization-specific workouts","description":"\n## Organization Workout Library\n\nRetrieves paginated list of workouts specific to your organization. Includes filtering, sorting, and search capabilities.\n\n---\n\n### 🎯 Organization Context\n\n| Aspect | Organization Workouts | Public Workouts |\n|--------|----------------------|-----------------|\n| **Content** | Your branded workouts | Global library |\n| **Customization** | Team-specific exercises | Generic fitness content |\n| **Branding** | Your trainers/style | Mixed sources |\n| **Access Control** | Organization members | Public access |\n\n---\n\n### πŸ“‹ Use Cases\n\nβœ… **White-label Apps** - Show only your organization's content \nβœ… **Corporate Wellness** - Company-specific fitness programs \nβœ… **Trainer Platforms** - Personal trainer's workout library \nβœ… **Gym Management** - Facility-specific workouts\n\n---\n\n### πŸ” Filtering & Pagination\n\n**Visibility Filtering:**\n- `private` - Organization-only content (requires ownership)\n- `public` - Publicly accessible workouts\n- `all` - Both private and public (default)\n\n**Additional Filters:**\n- `difficulty` - Filter by beginner, intermediate, or advanced\n- `categoryIds` - Filter by category IDs (comma-separated)\n- `duration` - Filter by duration range in format \"min-max\" (e.g., \"15-45\")\n- `q` - Search by workout name or description\n\n**Pagination:**\n- `offset` - Number of items to skip (default: 0)\n- `limit` - Items per page (default: 20, max: 50)\n- Prefer following `links.next` from the response over computing offsets manually.\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Cache responses** - Workouts change infrequently \nβœ… **Filter by visibility** - Use `public` for end-user apps, `all` for management \nβœ… **Implement search** - Use `q` parameter for name/description filtering \nβœ… **Handle empty results** - Graceful fallback to public workouts\n\n---\n\n### πŸ”— Related Endpoints\n\n- Generate Workout: `POST /v1/orgs/{orgId}/workouts/generate` - Create new workout\n- Recommend Workout: `POST /v1/orgs/{orgId}/workouts/recommend` - Get suggestions\n- Workout Details: `GET /v1/workouts/{id}` - Get individual workout\n- Workout Metadata: `GET /v1/workouts/metadata` - Get categories and difficulties\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return per page.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search text","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Fields to sort. Prefix them with - (descending) or + (ascending): +someField,-otherField","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"BCP-47 locale (e.g. en-US, fr-FR). Localizes text and locale-aware media when this operation supports it. Falls back to English when unsupported.","example":"en-US","schema":{"type":"string"}},{"name":"visibility","required":false,"in":"query","description":"Filter workouts by their visibility status.","example":"public","schema":{"enum":["private","public","all"],"type":"string"}},{"name":"difficulty","required":false,"in":"query","description":"Filter workouts by difficulty level.","example":"intermediate","schema":{"enum":["beginner","intermediate","advanced"],"type":"string"}},{"name":"categoryIds","required":false,"in":"query","description":"Filter workouts by one or more workout category IDs (comma-separated 24-character hex DB ids). Optional tokens prefixed with `custom:` are filtered in memory (e.g. duration-based buckets).","example":"615aa3f0dbe7140012c59e94,custom:duration_short","schema":{"type":"string"}},{"name":"duration","required":false,"in":"query","description":"Filter workouts by duration range in minutes. Use format \"min-max\" (e.g., \"10-30\").","example":"15-45","schema":{"pattern":"^\\d+-\\d+$","type":"string"}},{"name":"allowAssessment","required":false,"in":"query","description":"Filter workouts by assessment support","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successfully retrieved paginated list of workouts for the organization.","schema":{"example":{"data":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","name":"Morning Power HIIT","duration":1800,"difficulty":"intermediate","categories":[{"id":"615aa3f0dbe7140012c59e94","name":"HIIT"}],"trainer":{"id":"trainer123","name":"Sarah Johnson"},"thumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/...","previewVideoUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/...","createdAt":"2025-09-15T10:30:00Z"}],"links":{"next":"https://content.api.hyperhuman.cc/v1/orgs/63415bf67a9c7000126616c1/workouts?offset=20&limit=20","total":45}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutListResponse"}}}},"400":{"description":"Invalid pagination or filter parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified organization ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//workouts' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationWorkouts() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//workouts', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//workouts\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/workouts/recommend":{"post":{"operationId":"OrganizationWorkoutRecommendation_getWorkoutRecommendations","summary":"Get workout recommendations from existing library","description":"\n## Smart Matching to Existing Content\n\nReturns ranked workout suggestions from your organization's library based on user profile analysis.\n\n---\n\n### 🎯 Recommendations vs. Generation\n\n| Aspect | **Recommendations** (This Endpoint) | **Generation** (`/generate`) |\n|--------|-------------------------------------|-------------------------------|\n| **Speed** | Instant (<100ms) | 2-5 seconds |\n| **Content** | Existing library workouts | New, unique workouts |\n| **Customization** | Matches to closest fit | Exact specifications |\n| **Use Case** | Browse & discover | On-demand custom |\n| **Requires** | Pre-built workout library | Just metadata IDs |\n\n---\n\n### πŸ“‹ When to Use Recommendations\n\nβœ… **Quick browsing experience** - Show options immediately \nβœ… **Large workout library** - You have 20+ workouts \nβœ… **Consistency** - Same workout for multiple users \nβœ… **Analytics tracking** - See which workouts are popular\n\n---\n\n### πŸ“‹ When to Use Generation\n\nβœ… **Unique per user** - Every workout is personalized \nβœ… **Specific requirements** - Exact duration, muscle groups \nβœ… **No library** - You don't have pre-built workouts \nβœ… **Dynamic content** - New workouts every session\n\n---\n\n### πŸ” How Matching Works\n\n1. **Analyzes** user profile (age, fitness level, goals, equipment)\n2. **Scores** each workout in your library (0.0 - 1.0)\n3. **Ranks** by match score\n4. **Returns** top 12 with match reasons\n\n**Match Factors:**\n- Fitness level alignment (35% weight)\n- Equipment compatibility (25% weight)\n- Goal alignment (20% weight)\n- Age appropriateness (10% weight)\n- Duration preference (10% weight)\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### πŸ”— Related Endpoints\n\n- Generate Workout: `POST /v1/orgs/{orgId}/workouts/generate`\n- List Workouts: `GET /v1/orgs/{orgId}/workouts`\n- Workout Metadata: `GET /v1/workouts/metadata`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"Organization/Team unique identifier","example":"67e2e9d0e23f010013e19dec","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutRecommendationRequestDto"}}}},"responses":{"200":{"description":"Ranked list of recommended workouts with match scores and reasons","schema":{"example":{"workouts":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","name":"Full Body HIIT Power","description":"High-intensity interval training for full body conditioning","duration":1800,"difficulty":"intermediate","thumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/workouts/64f1a2b3c4d5e6f7a8b9c0d1/thumbnail.jpg","recommendation":"Matches your intermediate fitness level and preferred equipment","categories":[{"id":"615aa3f0dbe7140012c59e94","name":"HIIT"}],"preview":{"url":"https://example.com/preview.m3u8","poster":"https://hhcontent.s3.eu-central-1.amazonaws.com/workouts/64f1a2b3c4d5e6f7a8b9c0d1/thumbnail.jpg","thumbnail":"https://hhcontent.s3.eu-central-1.amazonaws.com/workouts/64f1a2b3c4d5e6f7a8b9c0d1/thumbnail.jpg"}},{"id":"64f1a2b3c4d5e6f7a8b9c0d2","name":"Upper Body Strength","description":"Focused strength training for chest, back, and arms","duration":2400,"difficulty":"intermediate","thumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/workouts/64f1a2b3c4d5e6f7a8b9c0d2/thumbnail.jpg","recommendation":"Aligns with your strength goals and available equipment","categories":[{"id":"615aa3dadbe7140012c59e90","name":"Strength"}]},{"id":"64f1a2b3c4d5e6f7a8b9c0d3","name":"Cardio Blast","description":"Fast-paced cardio workout for endurance","duration":1500,"difficulty":"beginner","thumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/workouts/64f1a2b3c4d5e6f7a8b9c0d3/thumbnail.jpg","recommendation":"Suitable for your fitness level with bodyweight exercises","categories":[{"id":"615aa3ebdbe7140012c59e93","name":"Cardio"}]}],"reasoning":"Workouts recommended based on your profile and preferences. Top matches align with your intermediate fitness level and available equipment. The recommendations prioritize workouts that match your training goals while considering your current fitness capabilities."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutRecommendationResponseDto"}}}},"401":{"description":"Unauthorized - Invalid API key"},"404":{"description":"Organization/Team not found"}},"tags":["ai-recommendation"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//workouts/recommend' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getWorkoutRecommendations() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//workouts/recommend', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//workouts/recommend\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/workouts/generate":{"post":{"operationId":"OrganizationWorkoutGeneration_generateWorkout","summary":"Generate personalized on-the-fly workouts based on user profile details, duration preferences, and exercise sources.","description":"\n## Generate Personalized Workouts\n\nCreate AI-powered workout plans tailored to user profiles, equipment, fitness levels, and duration preferences.\n\n---\n\n### ⚠️ Storage Note\n\nGenerated workouts are returned directly (not saved to organization library). \nIf you need to reference the workout later, store the returned workout structure in your database.\n\n---\n\n### 🎯 What's Generated\n\n- **Duration**: 10-90 minute workout with automatic warm-up/cooldown\n- **Personalized**: Matched to category, difficulty, age, equipment, muscle groups\n- **Complete**: Ready-to-use workout structure with exercises, sets, reps, timing\n- **Safe**: Every workout includes 3-5 warm-up and cooldown exercises\n\n**User Profile:**\n- Age β†’ Appropriate exercise intensity (16-24 Young, 25-34 Young Adult, etc.)\n- Fitness level β†’ Uses first level if multiple provided\n- Equipment β†’ Guides exercise selection (bodyweight always included)\n- Muscle groups β†’ Prioritizes specified groups (optional guidance)\n\n**Duration Logic:**\n- Both min/max provided β†’ AI selects optimal in range\n- Only one value β†’ Uses as target\n- Smart adjustment to meet constraints\n\n---\n\n### πŸ“‹ Quick Start\n\n1. **Fetch Metadata**: \n - `GET /v1/workouts/metadata` β†’ Category IDs (required)\n - `GET /v1/workouts/equipment/metadata` β†’ Equipment category IDs (optional)\n - `GET /v1/workouts/exercises/metadata` β†’ Muscle group IDs (advanced)\n\n2. **Build Request** with metadata IDs\n\n3. **POST to this endpoint**\n\n---\n\n### πŸ“¦ Exercise Sources\n\n| Source | Description | Use Case |\n|--------|-------------|----------|\n| `premium_stock` | High-quality professional content with consistent trainers/backgrounds | **Production (Recommended)** |\n| `free_stock` | Varied quality with mixed trainers/backgrounds | Development/testing only |\n| `team_exercises` | Your organization's custom content | Maximum brand consistency |\n\n**Default**: If omitted, uses both free and premium stock (not recommended for production)\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… Use `premium_stock` for consistent quality \nβœ… Use `team_exercises` for brand consistency \nβœ… Specify both min and max duration for predictable results \n❌ Avoid mixing `free_stock` with `premium_stock` (visual inconsistency)\n\n**Advanced Options:**\n\n- `muscleGroupIds`: Prioritize specific muscle groups (guidance, not strict filter)\n- `excludeExerciseCollections`: Exclude trainer styles (e.g., [\"Free - Outdoor\"])\n- `userRequirements`: High-level context and guidelines for customer-specific training definitions (e.g., \"intermediate osteoporosis strength training\", \"CRITICAL: USE up to 3 unique exercises\"). Overrides default AI behavior. Max 2000 characters.\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### πŸ”— Related Endpoints\n\n- **Metadata**: `GET /v1/workouts/metadata` - Get category IDs\n- **Metadata**: `GET /v1/workouts/equipment/metadata` - Get equipment IDs\n- **Metadata**: `GET /v1/workouts/exercises/metadata` - Get muscle group IDs\n- **List**: `GET /v1/orgs/{orgId}/workouts` - Browse organization workouts\n- **Recommend**: `POST /v1/orgs/{orgId}/workouts/recommend` - Smart suggestions\n","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"67e2e9d0e23f010013e19dec","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Workout generation request with user profile and preferences.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutGenerationRequestDto"},"examples":{"beginner-hiit-20min":{"summary":"Beginner HIIT - 20 Minutes","description":"Full-body HIIT workout for beginners with minimal equipment","value":{"endUserProfileDetails":{"age":28,"gender":"female","fitnessLevels":["beginner"],"trainingDaysPerWeek":3,"preferredEquipmentCategoryIds":["67deb36a6a5e49797c122f56"]},"exerciseSources":["premium_stock"],"durationOptions":{"minMinutes":15,"maxMinutes":20},"categoryId":"615aa3f0dbe7140012c59e94"}},"advanced-strength-upper-body":{"summary":"Advanced Strength - Upper Body Focus","description":"Advanced strength training targeting chest, arms, and shoulders with free weights","value":{"endUserProfileDetails":{"age":35,"gender":"male","fitnessLevels":["advanced"],"trainingDaysPerWeek":5,"preferredEquipmentCategoryIds":["67deb3696a5e49797c122f55"]},"exerciseSources":["premium_stock"],"durationOptions":{"minMinutes":30,"maxMinutes":45},"categoryId":"615aa3dadbe7140012c59e90","muscleGroupIds":["604b0169076fe2727354d740","604b0129beaba770c284ff40","604b0165076fe2727354d73e"],"excludeExerciseCollections":["Free - Outdoor"]}},"intermediate-mobility-recovery":{"summary":"Intermediate Mobility & Recovery","description":"Low-intensity mobility workout for active recovery","value":{"endUserProfileDetails":{"age":42,"gender":"female","fitnessLevels":["intermediate"],"trainingDaysPerWeek":4,"preferredEquipmentCategoryIds":["67deb36a6a5e49797c122f56"]},"exerciseSources":["premium_stock"],"durationOptions":{"minMinutes":10,"maxMinutes":15},"categoryId":"615aa3e5dbe7140012c59e92","userRequirements":"Focus on low-impact movements. Emphasize flexibility and joint mobility. Avoid high-intensity exercises."}},"team-branded-workout":{"summary":"Custom Team Exercises Only","description":"Use your organization's exercises for complete brand alignment","value":{"endUserProfileDetails":{"age":30,"gender":"male","fitnessLevels":["intermediate"],"trainingDaysPerWeek":3,"preferredEquipmentCategoryIds":["67deb3696a5e49797c122f55"]},"exerciseSources":["team_exercises"],"durationOptions":{"minMinutes":20,"maxMinutes":30},"categoryId":"615aa3f0dbe7140012c59e94"}},"cardio-legs-focus":{"summary":"Cardio with Legs Focus","description":"Cardio workout emphasizing leg muscles","value":{"endUserProfileDetails":{"age":26,"gender":"female","fitnessLevels":["intermediate"],"trainingDaysPerWeek":4,"preferredEquipmentCategoryIds":["67deb36a6a5e49797c122f56"]},"exerciseSources":["premium_stock"],"durationOptions":{"minMinutes":25,"maxMinutes":35},"categoryId":"615aa3ebdbe7140012c59e93","muscleGroupIds":["604b0177076fe2727354d743","604b0173076fe2727354d742"],"excludeExerciseCollections":["Premium - Industrial"]}},"complete-all-parameters":{"summary":"Complete Example - All Parameters","description":"Real-world example with ALL available parameters filled out to demonstrate the full API capability. This shows every possible field that can be included in a workout generation request.","value":{"endUserProfileDetails":{"age":32,"gender":"male","fitnessLevels":["intermediate","advanced"],"goalIds":["63c92926f920a9005c4e619c","63c92926f920a9005c4e619d"],"trainingDaysPerWeek":5,"preferredEquipmentCategoryIds":["67deb36a6a5e49797c122f56","67deb3696a5e49797c122f55"],"endUserId":"64e3bca9d1b7e600141a9712"},"exerciseSources":["premium_stock","team_exercises"],"durationOptions":{"minMinutes":30,"maxMinutes":45},"categoryId":"615aa3dadbe7140012c59e90","muscleGroupIds":["604b0169076fe2727354d740","604b0129beaba770c284ff40","604b0165076fe2727354d73e","604b016c076fe2727354d740","604b0170076fe2727354d741"],"excludeExerciseCollections":["Free - Eclectic Home","Free - Outdoor","Premium - Industrial"],"userRequirements":"Intermediate strength / stimulus, one-sided exercises, rep schemes. Focus on controlled movements suitable for osteoporosis patients. CRITICAL: USE up to 3 unique exercises in the whole workout."}}}}}},"responses":{"200":{"description":"Successfully generated workout plan with automatic warm-up and cooldown sections. AI may adjust final difficulty based on exercise availability and safety considerations.","schema":{"example":{"name":"Full Body HIIT Power","totalDurationSeconds":1200,"difficulty":"beginner","categoryId":"615aa3f0dbe7140012c59e94","instances":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","kind":"singleExercise","durationSeconds":30,"skipIntro":false,"pace":"normal","exercise":{"id":"60812dea606fc90011eb4405","name":"Jumping Jacks","description":"Full body cardio warm-up exercise","thumbnailUrl":"https://cdn.example.com/exercises/thumbnails/jumping-jacks.jpg","videoUri":"https://cdn.example.com/exercises/videos/jumping-jacks/master.m3u8","estimatedRepDuration":1500,"muscleGroups":["Full Body","Cardio"],"equipment":["Bodyweight"],"collectionName":"Premium - Neutral","coach":"female","skillLevel":"beginner","categories":["warmup","cardio"]}},{"id":"64f1a2b3c4d5e6f7a8b9c0d2","kind":"rest","durationSeconds":15},{"id":"64f1a2b3c4d5e6f7a8b9c0d3","kind":"singleExercise","reps":12,"skipIntro":true,"weightLevel":"medium","exercise":{"id":"60812dea606fc90011eb4406","name":"Push-ups","description":"Upper body strength exercise","thumbnailUrl":"https://cdn.example.com/exercises/thumbnails/push-ups.jpg","videoUri":"https://cdn.example.com/exercises/videos/push-ups/master.m3u8","estimatedRepDuration":2000,"muscleGroups":["Chest","Arms","Core"],"equipment":["Bodyweight"],"collectionName":"Premium - Neutral","coach":"female","skillLevel":"beginner","categories":["strength"],"showcasedReps":12}},{"id":"64f1a2b3c4d5e6f7a8b9c0d4","kind":"rest","durationSeconds":30},{"id":"64f1a2b3c4d5e6f7a8b9c0d5","kind":"singleExercise","durationSeconds":40,"skipIntro":false,"pace":"fast","exercise":{"id":"60812dea606fc90011eb4407","name":"High Knees","description":"Cardio exercise for legs and core","thumbnailUrl":"https://cdn.example.com/exercises/thumbnails/high-knees.jpg","videoUri":"https://cdn.example.com/exercises/videos/high-knees/master.m3u8","estimatedRepDuration":1000,"muscleGroups":["Legs","Core","Cardio"],"equipment":["Bodyweight"],"collectionName":"Premium - Neutral","coach":"female","skillLevel":"beginner","categories":["cardio"],"executionSide":"both"}},{"id":"64f1a2b3c4d5e6f7a8b9c0d6","kind":"rest","durationSeconds":20},{"id":"64f1a2b3c4d5e6f7a8b9c0d7","kind":"singleExercise","reps":15,"skipIntro":false,"weightLevel":"light","exercise":{"id":"60812dea606fc90011eb4408","name":"Bodyweight Squats","description":"Lower body strength exercise","thumbnailUrl":"https://cdn.example.com/exercises/thumbnails/squats.jpg","videoUri":"https://cdn.example.com/exercises/videos/squats/master.m3u8","estimatedRepDuration":2500,"muscleGroups":["Legs","Glutes","Core"],"equipment":["Bodyweight"],"collectionName":"Premium - Neutral","coach":"female","skillLevel":"beginner","categories":["strength"],"showcasedReps":15}},{"id":"64f1a2b3c4d5e6f7a8b9c0d8","kind":"rest","durationSeconds":15},{"id":"64f1a2b3c4d5e6f7a8b9c0d9","kind":"singleExercise","durationSeconds":30,"skipIntro":false,"pace":"slow","exercise":{"id":"60812dea606fc90011eb4409","name":"Arm Circles","description":"Cooldown and mobility exercise","thumbnailUrl":"https://cdn.example.com/exercises/thumbnails/arm-circles.jpg","videoUri":"https://cdn.example.com/exercises/videos/arm-circles/master.m3u8","estimatedRepDuration":1500,"muscleGroups":["Shoulders","Arms"],"equipment":["Bodyweight"],"collectionName":"Premium - Neutral","coach":"female","skillLevel":"beginner","categories":["cooldown","mobility"]}}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutGenerationResponseDto"}}}},"400":{"description":"Bad Request - Invalid input parameters.","schema":{"example":{"error":{"message":"Invalid categoryId provided","statusCode":400,"errorCode":"INVALID_CATEGORY_ID","details":"The categoryId '615aa3f0dbe7140012c59e99' does not exist. Please use GET /v1/workouts/metadata to fetch valid category IDs."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid API key.","schema":{"example":{"error":{"message":"Invalid API key","statusCode":401,"errorCode":"UNAUTHORIZED"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - API key required or insufficient permissions.","schema":{"example":{"error":{"message":"API key required","statusCode":403,"errorCode":"FORBIDDEN","details":"This endpoint requires a valid API key. Please include the X-Api-Key header with your request."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Organization or other resources not found.","schema":{"example":{"error":{"message":"Organization not found","statusCode":404,"errorCode":"ORGANIZATION_NOT_FOUND","details":"The organization with ID '67e2e9d0e23f010013e19dec' does not exist or your API key does not have access to it."}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error - Failed to generate workout.","schema":{"example":{"error":{"message":"Failed to generate workout plan due to an internal issue.","statusCode":500,"errorCode":"INTERNAL_SERVER_ERROR"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["ai-generation"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//workouts/generate' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function generateWorkout() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//workouts/generate', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//workouts/generate\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/workouts/{workoutId}/adapt":{"post":{"operationId":"OrganizationWorkoutAdaptation_adaptWorkout","summary":"Adapt an existing team workout based on user profile and data","description":"\n## Workout Adaptation\n\nPersonalizes an existing team workout by adjusting intensity, duration, and exercises based on:\n- User profile (age, fitness level, goals, equipment)\n- Last 60 days of wearable health data (body/sleep/physical scores)\n- Workout feedback and session history\n- User-provided guidance and constraints\n\n---\n\n### Key Differences from Generation\n\n| Aspect | Adaptation | Generation |\n|--------|------------|------------|\n| Source | Existing workout | New from scratch |\n| Goals | Preserved from original | User-specified |\n| Structure | Modified original | AI-created |\n| Use case | Personalize team content | On-demand custom |\n\n---\n\n### What Gets Adapted\n\n- **Intensity**: Reps, duration, rest periods, pace, weight level, RPE\n- **Duration**: Total workout time adjusted for user\n- **Exercises**: Substitutions only when needed (safety, equipment)\n- **NOT Changed**: Workout goals, overall structure intent\n\n---\n\n### Adaptation Factors\n\nBased on user data, the AI considers:\n- **Low sleep scores**: Reduces intensity, adds longer rest\n- **Declining physical scores**: Lowers reps/duration\n- **High difficulty feedback**: Decreases difficulty progressively\n- **Low completion rate**: Shortens workout, adds rest\n- **User injury mention**: Substitutes risky exercises\n- **Equipment constraints**: Replaces with available alternatives\n\n---\n\n### Response Format\n\nReturns same structure as AI workout generation for seamless integration.\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### Related Endpoints\n\n- Generate Workout: `POST /v1/orgs/{orgId}/workouts/generate`\n- Recommend Workout: `POST /v1/orgs/{orgId}/workouts/recommend`\n- List Workouts: `GET /v1/orgs/{orgId}/workouts`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"Organization/Team ID","example":"67e2e9d0e23f010013e19dec","schema":{"type":"string"}},{"name":"workoutId","required":true,"in":"path","description":"Workout ID to adapt","example":"67e2e9d0e23f010013e19def","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Workout adaptation request with user profile and preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutAdaptationRequestDto"},"examples":{"basic-adaptation":{"summary":"Basic Adaptation - Intermediate User","description":"Adapt a workout for an intermediate fitness level user","value":{"endUserProfileDetails":{"age":32,"gender":"female","fitnessLevels":["intermediate"],"trainingDaysPerWeek":4},"exerciseSources":["premium_stock","team_exercises"]}},"injury-adaptation":{"summary":"Adaptation with Injury Guidance","description":"Adapt a workout considering user injury","value":{"endUserProfileId":"64e3bca9d1b7e600141a9712","endUserProfileDetails":{"age":45,"gender":"male","fitnessLevels":["beginner"],"trainingDaysPerWeek":3},"exerciseSources":["premium_stock"],"userGuidance":"I have a slight knee injury. Please avoid high-impact exercises like jumping and running. Prefer low-impact alternatives."}},"full-personalization":{"summary":"Full Personalization with User Data","description":"Adapt using 60-day wearable data and full user profile","value":{"endUserProfileId":"64e3bca9d1b7e600141a9712","endUserProfileDetails":{"age":28,"gender":"female","fitnessLevels":["advanced"],"goalIds":["63c92926f920a9005c4e619c"],"trainingDaysPerWeek":5,"preferredEquipmentCategoryIds":["67deb36a6a5e49797c122f56","67deb3696a5e49797c122f55"]},"exerciseSources":["premium_stock","team_exercises"],"userGuidance":"Training for a 10K run in 2 months. Focus on building endurance. Limited time today, prefer shorter workout."}}}}}},"responses":{"200":{"description":"Adapted workout with personalized adjustments","schema":{"example":{"name":"Adapted: Full Body HIIT Power","totalDurationSeconds":1050,"difficulty":"intermediate","categoryId":"615aa3f0dbe7140012c59e94","adaptationReasoning":"Reduced workout duration from 20 to 17.5 minutes to accommodate your current fitness level. Adjusted rest periods to 20 seconds (from 15) to allow better recovery. Modified exercise intensity by reducing reps for high-impact movements to protect your knee. Substituted jumping exercises with low-impact alternatives.","instances":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","kind":"singleExercise","durationSeconds":30,"skipIntro":false,"pace":"normal","exercise":{"id":"60812dea606fc90011eb4405","name":"Jumping Jacks","description":"Full body cardio warm-up exercise","thumbnailUrl":"https://cdn.example.com/exercises/thumbnails/jumping-jacks.jpg","videoUri":"https://cdn.example.com/exercises/videos/jumping-jacks/master.m3u8","estimatedRepDuration":1500,"muscleGroups":["Full Body","Cardio"],"equipment":["Bodyweight"],"collectionName":"Premium - Neutral","coach":"female","skillLevel":"beginner","categories":["warmup","cardio"]}},{"id":"64f1a2b3c4d5e6f7a8b9c0d2","kind":"rest","durationSeconds":20},{"id":"64f1a2b3c4d5e6f7a8b9c0d3","kind":"singleExercise","reps":10,"skipIntro":true,"weightLevel":"medium","rpe":7,"exercise":{"id":"60812dea606fc90011eb4406","name":"Modified Push-ups","description":"Upper body strength exercise adapted for lower intensity","thumbnailUrl":"https://cdn.example.com/exercises/thumbnails/push-ups.jpg","videoUri":"https://cdn.example.com/exercises/videos/push-ups/master.m3u8","estimatedRepDuration":2000,"muscleGroups":["Chest","Arms"],"equipment":["Bodyweight"],"collectionName":"Premium - Neutral","coach":"female","skillLevel":"intermediate","categories":["strength"]}}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutAdaptationResponseDto"}}}},"400":{"description":"Invalid request or workout not eligible for adaptation (only team workouts can be adapted)"},"401":{"description":"Unauthorized - Invalid API key"},"404":{"description":"Workout or organization not found"}},"tags":["ai-adaptation"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//workouts//adapt' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function adaptWorkout() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//workouts//adapt', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//workouts//adapt\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/content-autopilot":{"get":{"operationId":"OrganizationContentAutopilotApi_listTasks","summary":"List content autopilot tasks","description":"\n## Content Autopilot Tasks\n\nRetrieves a paginated list of content autopilot tasks for your organization. Autopilot tasks automate the creation, adaptation, and publishing of workouts and programs on a configurable schedule.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Use Cases\n\n- **Dashboard views** - List all scheduled content automation tasks\n- **Status monitoring** - Filter by active/draft to see running vs paused tasks\n- **Content type filtering** - Show only workout or program automation tasks\n- **Audit and review** - Browse task configurations for the organization\n\n---\n\n### Filtering and Pagination\n\n**Filters:**\n- `status` - active, draft\n- `scope` - ai_generate, create_similar, publish_existing\n- `contentType` - workout, program\n\n**Sort:** `sortBy` (updatedAt, createdAt) + `sortOrder` (ascend, descend)\n\n**Pagination:**\n- `limit` - Items per page (default: 20, max: 50)\n- `offset` - Pagination offset (default: 0)\n\n---\n\n### Related Endpoints\n\n- Get Task: `GET /v1/orgs/{orgId}/content-autopilot/{taskId}`\n- Create Task: `POST /v1/orgs/{orgId}/content-autopilot`\n- Task Events: `GET /v1/orgs/{orgId}/content-autopilot/{taskId}/events`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Defaults to 20, max 50.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by task status","schema":{"enum":["active","draft"],"type":"string"}},{"name":"scope","required":false,"in":"query","description":"Filter by task scope","schema":{"enum":["ai_generate","create_similar","publish_existing"],"type":"string"}},{"name":"contentType","required":false,"in":"query","description":"Filter by content type","schema":{"enum":["workout","program"],"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort by field","schema":{"enum":["updatedAt","createdAt"],"type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order","schema":{"enum":["ascend","descend"],"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Defaults to 0.","example":0,"schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully retrieved paginated list of autopilot tasks.","content":{"application/json":{"examples":{"default":{"summary":"List of autopilot tasks","value":{"data":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","organizationId":"63415bf67a9c7000126616c1","ownerId":"507f1f77bcf86cd799439011","name":"Daily HIIT Generator","status":"active","scope":"ai_generate","contentType":"workout","difficultyOptions":["beginner","intermediate"],"includeFreeStock":true,"includePremiumStock":false,"includeTeamContent":false,"repeatMode":"daily","nextRunAt":"2026-04-06T10:00:00.000Z","createdAt":"2026-04-01T08:00:00.000Z","updatedAt":"2026-04-05T14:00:00.000Z"}],"links":{"next":null,"total":1},"explanation":"Showing 1 autopilot task for your organization."}}}}}},"400":{"description":"Invalid filter or pagination parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function listTasks() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]},"post":{"operationId":"OrganizationContentAutopilotApi_createTask","summary":"Create content autopilot task","description":"\n## Create Autopilot Task\n\nCreates a new content autopilot task in `draft` status. Use the activate endpoint to start the scheduling.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Task Scopes\n\n| Scope | Description | Required Fields |\n|-------|-------------|-----------------|\n| `ai_generate` | Generate new content using AI | categoryIds/goalIds, difficultyOptions |\n| `create_similar` | Adapt an existing workout/program | `sourceContentId` |\n| `publish_existing` | Flip visibility to public on schedule | `existingContentId` |\n\n---\n\n### Prompt Guidance Modes\n\n| Mode | Description |\n|------|-------------|\n| `none` | No additional prompt context |\n| `custom` | User-written free text (`customPromptGuidance`) |\n| `ai_tuned` | 30-day analytics context appended to prompt |\n| `ai_driven` | Fully autonomous - AI decides category, difficulty, duration |\n\n---\n\n### Validation\n\n- `minutesLimit` entitlement must have remaining capacity\n- `premiumStock` entitlement required if `includePremiumStock` is true\n- `sourceContentId` / `existingContentId` must belong to the organization\n\n---\n\n### Related Endpoints\n\n- Activate: `POST /v1/orgs/{orgId}/content-autopilot/{taskId}/activate`\n- Update: `PATCH /v1/orgs/{orgId}/content-autopilot/{taskId}`\n- List: `GET /v1/orgs/{orgId}/content-autopilot`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAutopilotTaskDto"},"examples":{"aiGenerate":{"summary":"AI-generated daily workout","value":{"name":"Daily HIIT Generator","scope":"ai_generate","contentType":"workout","categoryIds":["615aa3f0dbe7140012c59e94"],"difficultyOptions":["beginner","intermediate"],"durationMin":15,"durationMax":30,"includeFreeStock":true,"repeatMode":"daily","promptGuidanceMode":"ai_driven"}},"createSimilar":{"summary":"Weekly workout variation","value":{"name":"Monday Strength Variation","scope":"create_similar","contentType":"workout","sourceContentId":"507f1f77bcf86cd799439011","difficultyOptions":["intermediate"],"repeatMode":"weekly"}},"publishExisting":{"summary":"Scheduled publish","value":{"name":"Publish Friday Program","scope":"publish_existing","contentType":"program","existingContentId":"507f1f77bcf86cd799439012","difficultyOptions":["beginner"],"repeatMode":"once","nextRunAt":"2026-04-10T09:00:00.000Z"}}}}}},"responses":{"201":{"description":"Task created in draft status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutopilotTaskResponseDto"}}}},"400":{"description":"Invalid input or missing required fields for scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Entitlement limit exceeded or API key not authorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function createTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/content-autopilot/events":{"get":{"operationId":"OrganizationContentAutopilotApi_listTeamEvents","summary":"List execution events across all tasks","description":"\n## Organization Autopilot Events\n\nRetrieves execution history across all content autopilot tasks for the organization. Each event records a task execution outcome: success, failure, or skip.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Use Cases\n\n- **Execution dashboard** - View recent automation activity across all tasks\n- **Failure monitoring** - Filter by `failed` to identify issues\n- **Audit trail** - Review content creation history with content IDs\n\n---\n\n### Filtering\n\n- `taskId` - Filter events to a specific task\n- `eventType` - success, failed, skipped_limit, skipped_premium_lost\n\n---\n\n### Related Endpoints\n\n- List Tasks: `GET /v1/orgs/{orgId}/content-autopilot`\n- Task Events: `GET /v1/orgs/{orgId}/content-autopilot/{taskId}/events`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Defaults to 20, max 50.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"eventType","required":false,"in":"query","description":"Filter by event type","schema":{"enum":["success","failed","skipped_limit","skipped_premium_lost"],"type":"string"}},{"name":"taskId","required":false,"in":"query","description":"Filter events to a specific task","schema":{"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Defaults to 0.","example":0,"schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully retrieved execution events.","content":{"application/json":{"examples":{"default":{"summary":"Execution event list","value":{"data":[{"id":"64f1a2b3c4d5e6f7a8b9c0e1","taskId":"64f1a2b3c4d5e6f7a8b9c0d1","organizationId":"63415bf67a9c7000126616c1","ownerId":"507f1f77bcf86cd799439011","eventType":"success","resultContentId":"64f1a2b3c4d5e6f7a8b9c0f1","resultContentType":"workout","createdAt":"2026-04-05T10:00:00.000Z"}],"links":{"next":null,"total":1}}}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/events' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function listTeamEvents() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/events', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/events\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}":{"get":{"operationId":"OrganizationContentAutopilotApi_getTask","summary":"Get autopilot task by ID","description":"\n## Autopilot Task Detail\n\nReturns full configuration of a content autopilot task including schedule, content parameters, and prompt guidance settings.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Related Endpoints\n\n- List Tasks: `GET /v1/orgs/{orgId}/content-autopilot`\n- Update Task: `PATCH /v1/orgs/{orgId}/content-autopilot/{taskId}`\n- Task Events: `GET /v1/orgs/{orgId}/content-autopilot/{taskId}/events`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the autopilot task.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved autopilot task detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutopilotTaskResponseDto"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]},"patch":{"operationId":"OrganizationContentAutopilotApi_updateTask","summary":"Update autopilot task configuration","description":"\n## Update Autopilot Task\n\nPartially updates an autopilot task's configuration. All fields are optional. Fields not included in the request body remain unchanged.\n\nNotable: update `nextRunAt` to reschedule an active task to a different day without affecting its repeat configuration.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Related Endpoints\n\n- Get Task: `GET /v1/orgs/{orgId}/content-autopilot/{taskId}`\n- Activate: `POST /v1/orgs/{orgId}/content-autopilot/{taskId}/activate`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the autopilot task.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAutopilotTaskDto"},"examples":{"reschedule":{"summary":"Reschedule to a different date","value":{"nextRunAt":"2026-04-12T09:00:00.000Z"}},"updateConfig":{"summary":"Update difficulty and duration","value":{"difficultyOptions":["intermediate","advanced"],"durationMin":20,"durationMax":40}}}}}},"responses":{"200":{"description":"Task updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutopilotTaskResponseDto"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PATCH 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function updateTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/', {\n method: 'PATCH',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.patch(\n \"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]},"delete":{"operationId":"OrganizationContentAutopilotApi_deleteTask","summary":"Delete autopilot task (soft delete)","description":"\n## Delete Autopilot Task\n\nSoft-deletes a content autopilot task. The task will no longer execute and will not appear in list results.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Related Endpoints\n\n- List Tasks: `GET /v1/orgs/{orgId}/content-autopilot`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the autopilot task.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"responses":{"204":{"description":"Task deleted."},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found or already deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function deleteTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/', {\n method: 'DELETE',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.delete(\"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}/activate":{"post":{"operationId":"OrganizationContentAutopilotApi_activateTask","summary":"Activate autopilot task","description":"\n## Activate Task\n\nSets the task status to `active` and determines the next scheduled execution time.\n\n**Schedule resolution:**\n1. If the task already has a `nextRunAt` in the future, it is preserved.\n2. Otherwise, `nextRunAt` is computed from the task's `repeatMode`.\n3. For `once` mode, defaults to now.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Related Endpoints\n\n- Deactivate: `POST /v1/orgs/{orgId}/content-autopilot/{taskId}/deactivate`\n- Run Now: `POST /v1/orgs/{orgId}/content-autopilot/{taskId}/run-now`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the autopilot task.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"responses":{"200":{"description":"Task activated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutopilotTaskResponseDto"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//activate' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function activateTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//activate', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//activate\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}/deactivate":{"post":{"operationId":"OrganizationContentAutopilotApi_deactivateTask","summary":"Deactivate autopilot task","description":"\n## Deactivate Task\n\nSets the task status to `draft` and clears the `nextRunAt` schedule. The task will stop executing until activated again.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Related Endpoints\n\n- Activate: `POST /v1/orgs/{orgId}/content-autopilot/{taskId}/activate`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the autopilot task.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"responses":{"200":{"description":"Task deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutopilotTaskResponseDto"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//deactivate' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function deactivateTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//deactivate', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//deactivate\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}/run-now":{"post":{"operationId":"OrganizationContentAutopilotApi_runNow","summary":"Manually trigger task execution","description":"\n## Run Now\n\nExecutes a content autopilot task immediately, bypassing the cron schedule. Respects all entitlement limits and daily execution caps (max 20 per user per day).\n\nThe task can be in any status (active or draft) -- this allows testing a task configuration before activating it on a schedule.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Rate Limit\n\nThis endpoint triggers AI content generation and counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### Related Endpoints\n\n- Activate: `POST /v1/orgs/{orgId}/content-autopilot/{taskId}/activate`\n- Task Events: `GET /v1/orgs/{orgId}/content-autopilot/{taskId}/events`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the autopilot task.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"responses":{"200":{"description":"Task executed successfully."},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Entitlement limit exceeded or API key not authorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//run-now' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function runNow() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//run-now', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//run-now\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}/events":{"get":{"operationId":"OrganizationContentAutopilotApi_listTaskEvents","summary":"List execution events for a task","description":"\n## Task Execution History\n\nRetrieves the execution event log for a specific autopilot task. Each event records a task run outcome.\n\n**Event types:**\n- `success` - Content created and published successfully. `resultContentId` contains the new content ID.\n- `failed` - Execution failed. `errorMessage` contains the reason.\n- `skipped_limit` - Daily execution limit (20/day) reached. Task retries next day.\n- `skipped_premium_lost` - Premium stock entitlement lost. Schedule advanced.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n\n---\n\n### Related Endpoints\n\n- Get Task: `GET /v1/orgs/{orgId}/content-autopilot/{taskId}`\n- Team Events: `GET /v1/orgs/{orgId}/content-autopilot/events`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the autopilot task.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Defaults to 20, max 50.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"eventType","required":false,"in":"query","description":"Filter by event type","schema":{"enum":["success","failed","skipped_limit","skipped_premium_lost"],"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Defaults to 0.","example":0,"schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully retrieved task execution events.","content":{"application/json":{"examples":{"default":{"summary":"Task execution history","value":{"data":[{"id":"64f1a2b3c4d5e6f7a8b9c0e1","taskId":"64f1a2b3c4d5e6f7a8b9c0d1","organizationId":"63415bf67a9c7000126616c1","ownerId":"507f1f77bcf86cd799439011","eventType":"success","resultContentId":"64f1a2b3c4d5e6f7a8b9c0f1","resultContentType":"workout","createdAt":"2026-04-05T10:00:00.000Z"},{"id":"64f1a2b3c4d5e6f7a8b9c0e2","taskId":"64f1a2b3c4d5e6f7a8b9c0d1","organizationId":"63415bf67a9c7000126616c1","ownerId":"507f1f77bcf86cd799439011","eventType":"failed","errorMessage":"Content minutes limit reached","createdAt":"2026-04-04T10:00:00.000Z"}],"links":{"next":null,"total":2}}}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task not found or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["content-autopilot"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//events' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function listTaskEvents() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//events', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//content-autopilot//events\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/drops":{"get":{"operationId":"OrganizationDropsApi_getOrganizationDrops","summary":"List organization social drops","description":"\n## Organization Social Drops\n\nRetrieves paginated list of ready social drops for your organization. A drop is a publish-ready package (video variants, covers, copy packs) linked to an Exercise, Collection (Micro Workout), Workout, or Program.\n\n**Note:** Only drops with status `ready` are returned. Draft, processing, and failed drops are excluded.\n\n---\n\n### Access and Auth\n\n- **Auth:** API key (X-Api-Key header)\n- **Scope:** Organization (organizationId)\n- **Capabilities:** List ready drops, get drop detail, export channel bundle (video, cover, copy pack)\n\n---\n\n### Use Cases\n\n- **Social scheduling tools** - List drops for content calendar\n- **Content management dashboards** - Browse and export ready assets\n- **Bulk export workflows** - Get video + cover + copy for channel publishing\n- **Channel-specific discovery** - Filter by aspect ratio and duration\n\n---\n\n### Filtering and Pagination\n\n**Filters:**\n- `sourceType` - exercise, exerciseCollection, workout, workoutCollection\n- `sourceId` - Filter by source entity ID (use with sourceType for entity-context views)\n- `aspectRatio` - 9:16, 1:1, 16:9 (drops that have this variant)\n- `duration` - 15, 30, 60 (seconds; drops that have this variant)\n- `q` - Search by drop title (min 3 characters)\n\n**Sort:** Use `sort` with +field (asc) or -field (desc), e.g. `-updatedAt`, `+createdAt`\n\n**Pagination:**\n- `limit` - Items per page (default: 20, max: 50)\n- `offset` - Pagination offset (default: 0)\n\n---\n\n### Best Practices\n\n- **Cache responses** - Drops change when new content is published\n- **Use sourceId** - Filter by source when showing drops in entity-context modals\n- **Handle empty results** - Graceful fallback when no ready drops exist\n\n---\n\n### Related Endpoints\n\n- Get Drop: `GET /v1/orgs/{orgId}/drops/{dropId}` - Full detail with variants and copy packs\n- Export Drop: `POST /v1/orgs/{orgId}/drops/{dropId}/export` - Channel bundle (video, cover, copy)\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Defaults to 20, max 50.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search by drop title (min 3 characters)","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort: +updatedAt, -createdAt","schema":{"type":"string"}},{"name":"sourceType","required":false,"in":"query","description":"Filter by source type","schema":{"enum":["exercise","exerciseCollection","workout","workoutCollection"],"type":"string"}},{"name":"sourceId","required":false,"in":"query","description":"Filter by source entity ID","schema":{"type":"string"}},{"name":"aspectRatio","required":false,"in":"query","description":"Filter by aspect ratio","schema":{"enum":["9:16","1:1","16:9"],"type":"string"}},{"name":"duration","required":false,"in":"query","description":"Filter by duration in seconds","schema":{"enum":[15,30,60],"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Defaults to 0.","example":0,"schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully retrieved paginated list of ready drops for the organization.","content":{"application/json":{"examples":{"default":{"summary":"List of ready drops","value":{"data":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","organizationId":"63415bf67a9c7000126616c1","sourceType":"exercise","sourceId":"507f1f77bcf86cd799439011","sourceName":"Jumping Jacks","title":"Jumping Jacks","sourceThumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/...","sourceTypeLabel":"Exercise","locale":"en-US","channelPreset":"ig_reels","channelPresetLabel":"Instagram Reels","availableVariants":["9:16_30000","9:16_15000","1:1_30000"],"createdAt":"2025-09-15T10:30:00Z","updatedAt":"2025-09-16T14:20:00Z"},{"id":"64f1a2b3c4d5e6f7a8b9c0d2","organizationId":"63415bf67a9c7000126616c1","sourceType":"workout","sourceId":"12ab3efd45c67c1234566cd1","sourceName":"Morning Power HIIT","title":"Morning Power HIIT","sourceThumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/...","sourceTypeLabel":"Workout","locale":"en-US","channelPreset":"ig_reels","channelPresetLabel":"Instagram Reels","availableVariants":["9:16_60000","1:1_30000"],"createdAt":"2025-09-14T08:00:00Z","updatedAt":"2025-09-15T11:45:00Z"}],"links":{"next":"https://content.api.hyperhuman.cc/v1/orgs/63415bf67a9c7000126616c1/drops?limit=20&offset=20","total":42},"explanation":"Your ready social drops - video variants, covers, and copy packs for channel publishing."}}}}}},"400":{"description":"Invalid filter or pagination parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified organization ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["social"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//drops' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationDrops() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//drops', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//drops\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/drops/{dropId}":{"get":{"operationId":"OrganizationDropsApi_getOrganizationDropById","summary":"Get drop by ID","description":"\n## Drop Detail\n\nReturns full drop detail including video variants with presigned download and poster URLs, and copy packs per channel.\n\n**Response structure:**\n- `copyPack` - Copy pack for the default channel (channelPreset)\n- `copyPacks` - Copy packs per channel; use `copyPacks[viewChannel] ?? copyPack` for channel switching\n- `variants` - Video variants with aspectRatio, duration, downloadLink, posterLink, posterLinksByChannel, size\n\n**URL expiration:** Presigned URLs are valid for 7 days.\n\n---\n\n### Related Endpoints\n\n- List Drops: `GET /v1/orgs/{orgId}/drops` - Browse organization drops\n- Export Drop: `POST /v1/orgs/{orgId}/drops/{dropId}/export` - Get channel bundle\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"dropId","required":true,"in":"path","description":"The unique identifier of the drop.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved drop detail.","content":{"application/json":{"examples":{"default":{"summary":"Drop detail with variants and copy packs","value":{"id":"64f1a2b3c4d5e6f7a8b9c0d1","organizationId":"63415bf67a9c7000126616c1","sourceType":"exercise","sourceId":"507f1f77bcf86cd799439011","sourceName":"Jumping Jacks","title":"Jumping Jacks","sourceThumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/...","sourceTypeLabel":"Exercise","locale":"en-US","channelPreset":"ig_reels","channelPresetLabel":"Instagram Reels","availableVariants":["9:16_30000","9:16_15000","1:1_30000"],"copyPack":{"hook":"Get fit in 30 seconds!","caption":"30 seconds of Jumping Jacks to get your heart pumping. Perfect for a quick warm-up or standalone cardio burst. Try it now and feel the burn.","hashtags":"#fitness #workout #hiit #cardio","cta":"Link in bio","posterTagline":{"primaryLine":"30s HIIT","secondaryLine":"Jumping Jacks"}},"copyPacks":{"ig_reels":{"hook":"Get fit in 30 seconds!","caption":"30 seconds of Jumping Jacks to get your heart pumping. Perfect for a quick warm-up or standalone cardio burst. Try it now and feel the burn.","hashtags":"#fitness #workout #hiit #cardio","cta":"Link in bio","posterTagline":{"primaryLine":"30s HIIT","secondaryLine":"Jumping Jacks"}},"tiktok":{"hook":"30 sec cardio burst","caption":"Jumping Jacks - no equipment needed. Drop a heart if you finished it.","hashtags":"#fitness #workout #cardio #30secondchallenge","cta":"Full workout in bio","posterTagline":{"primaryLine":"30s HIIT","secondaryLine":"Jumping Jacks"}}},"variants":[{"aspectRatio":"9:16","duration":30000,"downloadLink":"https://hhcontent.s3.../drop_9x16_30.mp4?X-Amz-...","posterLink":"https://hhcontent.s3.../poster.png?X-Amz-...","posterLinksByChannel":{"tiktok":"https://hhcontent.s3.../poster_tiktok.png?X-Amz-..."},"size":1234567},{"aspectRatio":"9:16","duration":15000,"downloadLink":"https://hhcontent.s3.../drop_9x16_15.mp4?X-Amz-...","posterLink":"https://hhcontent.s3.../poster_15.png?X-Amz-...","size":654321},{"aspectRatio":"1:1","duration":30000,"downloadLink":"https://hhcontent.s3.../drop_1x1_30.mp4?X-Amz-...","posterLink":"https://hhcontent.s3.../poster_1x1.png?X-Amz-...","size":987654}],"createdAt":"2025-09-15T10:30:00Z","updatedAt":"2025-09-16T14:20:00Z"}}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Drop not found or not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["social"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//drops/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationDropById() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//drops/', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//drops/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/drops/{dropId}/export":{"post":{"operationId":"OrganizationDropsApi_exportDrop","summary":"Export drop for channel bundle","description":"\n## Export for Channel Bundle\n\nReturns presigned video download URL, cover image URL, and copy pack for the specified channel. Use for one-click export to Reels, Shorts, TikTok, etc.\n\n**Response contents:**\n- `videoDownloadLink` - Presigned S3 URL for MP4 video (valid 7 days)\n- `coverLink` - Presigned S3 URL for cover/poster image\n- `copyPack` - Hook, caption, hashtags, CTA, poster tagline\n- `ctaUrl` - Optional CTA URL from team settings (when configured)\n\n**Channel presets:** ig_reels, ig_stories, ig_carousel, tiktok, yt_shorts, fb_reels, yt_longform. Each has default aspect ratio and duration; override via body.\n\n---\n\n### Integration Example\n\n```javascript\nconst res = await fetch(\n `/v1/orgs/${orgId}/drops/${dropId}/export`,\n {\n method: 'POST',\n headers: {\n 'X-Api-Key': apiKey,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ channelPreset: 'ig_reels' }),\n }\n);\nconst { videoDownloadLink, coverLink, copyPack } = await res.json();\n// Download video, copy caption to clipboard\n```\n\n---\n\n### Best Practices\n\n- **Refresh URLs before expiry** - Presigned URLs valid for 7 days\n- **Use channel preset** - Platform-specific defaults (aspect ratio, duration)\n- **Handle 400** - Requested variant may not be available for this drop\n\n---\n\n### Related Endpoints\n\n- Get Drop: `GET /v1/orgs/{orgId}/drops/{dropId}` - Full detail before export\n- List Drops: `GET /v1/orgs/{orgId}/drops` - Browse organization drops\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"dropId","required":true,"in":"path","description":"The unique identifier of the drop.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"requestBody":{"required":false,"description":"Optional overrides. Omit to use drop defaults.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportDropDto"},"examples":{"default":{"summary":"Use drop defaults","value":{}},"igReels":{"summary":"Instagram Reels","value":{"channelPreset":"ig_reels"}},"customVariant":{"summary":"Custom variant","value":{"channelPreset":"tiktok","aspectRatio":"9:16","duration":15}}}}}},"responses":{"200":{"description":"Channel bundle with presigned URLs and copy pack.","content":{"application/json":{"examples":{"default":{"summary":"Export bundle for Instagram Reels","value":{"videoDownloadLink":"https://hhcontent.s3.../drop_9x16_30.mp4?X-Amz-...","coverLink":"https://hhcontent.s3.../cover.png?X-Amz-...","ctaUrl":"https://mybrand.com/fitness","copyPack":{"hook":"Get fit in 30 seconds!","caption":"30 seconds of Jumping Jacks to get your heart pumping. Perfect for a quick warm-up or standalone cardio burst. Try it now and feel the burn.","hashtags":"#fitness #workout #hiit","cta":"Link in bio","posterTagline":{"primaryLine":"30s HIIT","secondaryLine":"Jumping Jacks"}}}}}}}},"400":{"description":"Requested variant not available for this drop.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Drop not found or not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["social"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//drops//export' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function exportDrop() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//drops//export', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//drops//export\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/social-publish/connected-platforms":{"get":{"operationId":"OrganizationSocialPublishApi_getConnectedPlatforms","summary":"List connected social platforms","description":"Returns which platforms (instagram, tiktok, youtube, facebook) have a stored account id for this organization. Account connection is managed in the Hyperhuman team app, not via this API.","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationConnectedPlatformsResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["social-publish"],"security":[{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//social-publish/connected-platforms' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getConnectedPlatforms() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//social-publish/connected-platforms', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//social-publish/connected-platforms\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/social-publish":{"get":{"operationId":"OrganizationSocialPublishApi_listTasks","summary":"List scheduled social publish automations","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return per page.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter by task status","schema":{"enum":["active","draft"],"type":"string"}},{"name":"sourceMode","required":false,"in":"query","description":"Filter by source mode","schema":{"enum":["manual_fixed","random_ready","ai_insights","ai_pick"],"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort by field","schema":{"enum":["updatedAt","createdAt"],"type":"string"}},{"name":"sortOrder","required":false,"in":"query","description":"Sort order","schema":{"enum":["ascend","descend"],"type":"string"}},{"name":"search","required":false,"in":"query","description":"Case-insensitive substring match on automation name (min 1 character after trim)","schema":{"maxLength":200,"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationSocialPublishTaskListResponse"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["social-publish"],"security":[{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//social-publish' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function listTasks() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//social-publish', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//social-publish\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]},"post":{"operationId":"OrganizationSocialPublishApi_createTask","summary":"Create a social publish automation (draft)","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSocialDropPublishTaskDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationSocialPublishTaskResponseDto"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["social-publish"],"security":[{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//social-publish' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function createTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//social-publish', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//social-publish\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/social-publish/{taskId}":{"get":{"operationId":"OrganizationSocialPublishApi_getTask","summary":"Get one social publish automation","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the scheduled social publish automation.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationSocialPublishTaskResponseDto"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["social-publish"],"security":[{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//social-publish/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//social-publish/', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//social-publish/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]},"patch":{"operationId":"OrganizationSocialPublishApi_patchTask","summary":"Update a social publish automation","description":"Use `status: active` to schedule (requires connected accounts for all target platforms). Use `status: draft` to pause. Other fields follow the same rules as the team internal API.","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the scheduled social publish automation.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationPatchSocialPublishTaskDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationSocialPublishTaskResponseDto"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["social-publish"],"security":[{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PATCH 'https://content.api.hyperhuman.cc/v1/orgs//social-publish/' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function patchTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//social-publish/', {\n method: 'PATCH',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.patch(\n \"https://content.api.hyperhuman.cc/v1/orgs//social-publish/\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]},"delete":{"operationId":"OrganizationSocialPublishApi_deleteTask","summary":"Delete a social publish automation (soft delete)","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"taskId","required":true,"in":"path","description":"The unique identifier of the scheduled social publish automation.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"tags":["social-publish"],"security":[{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE 'https://content.api.hyperhuman.cc/v1/orgs//social-publish/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function deleteTask() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//social-publish/', {\n method: 'DELETE',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.delete(\"https://content.api.hyperhuman.cc/v1/orgs//social-publish/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/playlist":{"get":{"operationId":"WorkoutContentApi_getWorkoutPlaylist","summary":"Retrieve Detailed Workout Playlist Structure","description":"\n## Workout Playlist with Media Assets\n\nEssential endpoint for building workout video players. Returns the complete, ordered sequence of workout segments with all media assets.\n\n---\n\n### πŸ“‹ Typical Integration Flow\n\n1. **Get Workout Metadata**: `GET /v1/workouts/{id}` β†’ Basic info (name, duration, difficulty)\n2. **Get Playlist**: `GET /v1/workouts/{id}/playlist` β†’ **This endpoint** (complete playback structure)\n3. **Build Player**: Use segments array to create video player experience\n4. **Track Session**: `POST /v1/workouts/{id}/sessions/start`\n5. **Submit Feedback**: `POST /v1/workouts/{id}/feedback`\n\n---\n\n### 🎬 Segment Types\n\n| Type | Description | Contains |\n|------|-------------|----------|\n| `intro` | Workout introduction | Video/audio intro, workout overview |\n| `exercise` | Exercise performance | Name, reps/duration, **rpe**, **amrap**, video (intro+main), audio cues, equipment, muscle groups |\n| `break` | Rest period | Duration, optional video/audio |\n| `outro` | Workout conclusion | Cooldown, summary |\n\n---\n\n### πŸ“¦ What's Included\n\n- **Video URLs**: Pre-signed S3 URLs for HLS master playlists\n- **Audio URLs**: Instruction audio, background music, voice cues\n- **Timing**: Precise duration for each segment in seconds\n- **Exercise Metadata**: Muscle groups, equipment, difficulty\n- **Localization**: All content in requested locale (13 languages)\n\n---\n\n### 🌍 Localization\n\nSupports 13 locales: en-US, en-GB, en-AU, fr-FR, de-DE, es-ES, it-IT, pt-PT, he-IL, ro-RO, cs-CZ, fi-FI, nl-NL\n\nFalls back to English if locale unsupported.\n\n---\n\n### πŸ”— Related Endpoints\n\n- Get Workout: `GET /v1/workouts/{id}`\n- Workout Metadata: `GET /v1/workouts/metadata`\n- Start Session: `POST /v1/workouts/{id}/sessions/start`\n- Full audio export: `GET /v1/workouts/{id}/export/audio/stream_url`\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique workout id (24-character hex DB id) whose playlist is required.","example":"a1b2c3d4e5f6a7b8c9d0e1f2","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"Language locale for localized content (BCP-47 format). Affects exercise names, equipment names, muscle group names, and audio selection. Supported: en-US, en-GB, en-AU, fr-FR, de-DE, es-ES, it-IT, pt-PT, he-IL, ro-RO, cs-CZ, fi-FI, nl-NL. Falls back to English if unsupported.","example":"fr-FR","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the detailed workout playlist structure. `data` is an ordered array; each item is an object with a single key indicating the segment kind (one of `intro`, `narrative`, `exercise`, `multiExercise`, `class`, `promo`, `educational`, `break`, `outro`). The value under that key is the segment payload (see schema for the per-kind shape).","schema":{"example":{"data":[{"intro":{"kind":"workout-intro","id":"intro","duration":5.2,"audio":{"url":"https://hhcontent.s3.eu-central-1.amazonaws.com/audio/intro.m4a"},"video":{"url":"https://stream.hyperhuman.cc/intro.m3u8","poster":"https://images.hyperhuman.cc/intro-poster.jpg","thumbnail":"https://images.hyperhuman.cc/intro-thumb.jpg"}}},{"exercise":{"kind":"exercise","id":"exercise_squats_1","exerciseId":"507f1f77bcf86cd799439011","duration":45,"name":"Bodyweight Squats","reps":12,"pace":"medium","weightLevel":null,"rpe":7,"amrap":false,"equipment":[{"id":"60812e08606fc90011eb4408","name":"Mat"}],"muscleGroups":[{"id":"604b0177076fe2727354d743","name":"Legs"}],"intro":{"audio":{"url":"https://hhcontent.s3.eu-central-1.amazonaws.com/audio/squat-cue.m4a"},"video":{"url":"https://stream.hyperhuman.cc/squat-intro.m3u8","poster":"https://images.hyperhuman.cc/squat-poster.jpg","thumbnail":"https://images.hyperhuman.cc/squat-thumb.jpg","loop":-1}},"main":{"video":{"url":"https://stream.hyperhuman.cc/squat-main.m3u8","poster":"https://images.hyperhuman.cc/squat-poster.jpg","thumbnail":"https://images.hyperhuman.cc/squat-thumb.jpg","loop":-1},"instructionAudio":[{"url":"https://hhcontent.s3.eu-central-1.amazonaws.com/audio/squat-instruction-1.m4a"}]}}},{"break":{"kind":"break","id":"break_1","duration":30,"video":null}},{"outro":{"kind":"workout-outro","id":"outro","duration":45.5,"audio":{"url":"https://hhcontent.s3.eu-central-1.amazonaws.com/audio/outro-cooldown.m4a"},"video":{"url":"https://stream.hyperhuman.cc/outro.m3u8","poster":"https://images.hyperhuman.cc/outro-poster.jpg","thumbnail":"https://images.hyperhuman.cc/outro-thumb.jpg"}}}],"presentationStyle":"full","links":{}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutPlaylistResponse"}}}},"401":{"description":"Authentication failed. API key or Bearer token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID does not exist or a playlist could not be generated for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"X-Api-Key":["X-Api-Key"]},{"AccessToken":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts//playlist' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getWorkoutPlaylist() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//playlist', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts//playlist\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/music":{"get":{"operationId":"WorkoutContentApi_getWorkoutMusic","summary":"Get workout music playlist","description":"\n## Workout Music Playlist\n\nReturns a shuffled playlist of music tracks selected to fill the workout duration. \nUses the trainer's music preferences and workout categories to select appropriate tracks.\n\n### Music Selection\n- **User Preferences**: Respects trainer's music settings and category mappings\n- **Category Filtering**: Selects tracks matching workout categories (HIIT, Strength, etc.)\n- **Duration Filling**: Shuffled, deduplicated track list whose total duration generously exceeds the workout duration so the player always has headroom for runtime track selection (do not rely on a specific buffer ratio)\n- **Fallback**: Uses stock music if no user preferences set\n\n### πŸ“± Mobile Ready\n- Pre-signed S3 URLs (7-day expiration)\n- Simple JSON response\n- Track metadata (name, duration, filename)\n- Total playlist duration for player setup\n\n### πŸ”— Related Endpoints\n- Workout Details: `GET /v1/workouts/{id}`\n- Workout Playlist: `GET /v1/workouts/{id}/playlist`\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier of the workout","example":"a1b2c3d4e5f6a7b8c9d0e1f2","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved workout music playlist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutMusicPlaylistResponse"}}}},"401":{"description":"Authentication failed. API key or Bearer token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"X-Api-Key":["X-Api-Key"]},{"AccessToken":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts//music' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getWorkoutMusic() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//music', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts//music\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/sessions/start":{"post":{"operationId":"WorkoutsSessionsApi_startWorkoutSession","summary":"Start workout session","description":"\n## Begin Workout Tracking\n\nInitiates a new workout session for progress tracking, analytics, and completion monitoring. Handles both authenticated and anonymous users.\n\n---\n\n### πŸ”„ Session Lifecycle\n\n1. **Start Session**: `POST /v1/workouts/{id}/sessions/start` β†’ **This endpoint**\n2. **Track Progress**: `PATCH /v1/workouts/{id}/sessions/{sessionId}` β†’ Update completion\n3. **End Session**: `POST /v1/workouts/{id}/sessions/end` β†’ Mark complete\n4. **Submit Feedback**: `POST /v1/workouts/{id}/feedback` β†’ Rate experience\n\n---\n\n### πŸ‘€ Authentication Scenarios\n\n**Authenticated Users:**\n- Closes any previous incomplete sessions automatically\n- Links session to user profile for history tracking\n- Enables progress sync across devices\n\n**Anonymous Users:**\n- Creates temporary session without user linkage\n- Limited to single-device tracking\n- No historical data retention\n\n---\n\n### πŸ“Š What Gets Tracked\n\n| Data Point | Description | Use Case |\n|------------|-------------|----------|\n| **Start Time** | Session initiation timestamp | Duration calculation |\n| **User ID** | Authenticated user (if logged in) | Progress history |\n| **Workout ID** | Which workout being performed | Analytics |\n| **Session ID** | Unique session identifier | Progress updates |\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Start immediately** - Call when user begins workout \nβœ… **Handle failures** - Graceful degradation if session fails \nβœ… **Update progress** - Use PATCH endpoint during workout \nβœ… **Complete session** - Always call end endpoint\n\n---\n\n### πŸ”— Related Endpoints\n\n- Get Workout: `GET /v1/workouts/{id}` - Workout details before starting\n- Update Session: `PATCH /v1/workouts/{id}/sessions/{sessionId}` - Track progress\n- End Session: `POST /v1/workouts/{id}/sessions/end` - Mark complete\n- Submit Feedback: `POST /v1/workouts/{id}/feedback` - Rate workout\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout to start a session for.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"requestBody":{"required":false,"description":"Session start request. No body required - workout ID from URL parameter.","content":{"application/json":{"schema":{"type":"string"},"examples":{"authenticated-user":{"summary":"Authenticated User Session","description":"Standard session start for logged-in user with automatic session management","value":{}},"anonymous-user":{"summary":"Anonymous User Session","description":"Session start without authentication - limited tracking capabilities","value":{}}}}}},"responses":{"201":{"description":"Workout session successfully started. Any previous incomplete sessions for this workout are automatically closed.","schema":{"example":{"data":{"id":"67d1a2b3c4e5f6789abc0d1","createdAt":"2025-01-10T08:30:00.000Z","updatedAt":"2025-01-10T08:30:00.000Z","workoutId":"12ab3efd45c67c1234566cd1","workoutSegmentId":"intro","status":"started","duration":0,"progress":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutSessionResponse"}}}},"401":{"description":"Authentication failed (API key invalid or Bearer token invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/workouts//sessions/start' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function startWorkoutSession() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//sessions/start', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/workouts//sessions/start\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/sessions/{sessionId}":{"patch":{"operationId":"WorkoutsSessionsApi_patchWorkoutSession","summary":"Update a workout session","description":"\nUpdates an active workout session to track playback progress.\n\n**Primary Use:**\n- Send `progressSeconds` with actual playback time during workout\n- Update `workoutSegmentId` to track current segment\n\n**Duration Tracking:**\n- `progressSeconds` should represent total actual playback time (excluding pauses)\n- Duration is capped at 2x the expected workout duration to prevent outliers\n- On end session, the last known duration from PATCH is preserved\n\n**Best Practices:**\n- PATCH every 10-30 seconds during active playback\n- PATCH on segment transitions\n- Send final PATCH before calling end session\n\n**Related Endpoints:**\n- Start Session: `POST /v1/workouts/{id}/sessions/start`\n- End Session: `POST /v1/workouts/{id}/sessions/end`\n- Complete Session: `POST /v1/workouts/{id}/sessions/complete`\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout associated with the session.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}},{"name":"sessionId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout session to update.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Update session progress. Send progressSeconds to track actual playback time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchWorkoutSessionBody"},"examples":{"updateProgress":{"summary":"Update playback progress (recommended)","description":"Track actual playback time. This is the primary method for accurate duration tracking.","value":{"workoutSegmentId":"seg-exercise-2","progressSeconds":125.5}},"updateSegmentOnly":{"summary":"Update segment only","description":"Track which segment user is on without updating playback time.","value":{"workoutSegmentId":"seg-exercise-3"}}}}}},"responses":{"200":{"description":"Workout session updated successfully.","schema":{"example":{"data":{"id":"67d1a2b3c4e5f6789abc0d1","createdAt":"2025-01-10T08:30:00.000Z","updatedAt":"2025-01-10T08:32:45.500Z","workoutId":"12ab3efd45c67c1234566cd1","workoutSegmentId":"seg-exercise-2","status":"started","duration":125.5,"progress":0.15}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutSessionResponse"}}}},"400":{"description":"Invalid data provided in the request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed (API key invalid or Bearer token invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID or session ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Session is already completed and cannot be updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PATCH 'https://content.api.hyperhuman.cc/v1/workouts//sessions/' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function patchWorkoutSession() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//sessions/', {\n method: 'PATCH',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.patch(\n \"https://content.api.hyperhuman.cc/v1/workouts//sessions/\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]},"get":{"operationId":"WorkoutsSessionsApi_getWorkoutSession","summary":"Get specific workout session details","description":"\n## Get Specific Session Details\n\nRetrieves details of a specific workout session by its unique ID. Includes status, duration, progress, and timestamps.\n\n---\n\n### 🎯 Use Cases\n\n**Session Inspection:**\n- View detailed session information\n- Check current status and progress\n- Verify session duration\n\n**Progress Tracking:**\n- Display session statistics\n- Track completion percentage\n- Show duration in seconds\n\n---\n\n### πŸ“Š Response Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| id | string | Session unique identifier |\n| createdAt | date | When session was started |\n| updatedAt | date | Last update timestamp |\n| workoutId | string | Associated workout ID |\n| workoutSegmentId | string | Current segment ID |\n| status | string | 'started' or 'completed' |\n| duration | number | Playback time in seconds |\n| progress | number | Completion fraction (0-1) |\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Handle 404 gracefully** - Session may not exist or be accessible \nβœ… **Check status field** - Verify session is 'started' before updates \nβœ… **Use duration** - Duration is in seconds (actual playback time)\n\n---\n\n### πŸ”— Related Endpoints\n\n- Recent Session: `GET /v1/workouts/{id}/sessions/recent` - Most recent active session\n- Update Session: `PATCH /v1/workouts/{id}/sessions/{sessionId}` - Track progress\n- End Session: `POST /v1/workouts/{id}/sessions/end` - Complete session\n- Start Session: `POST /v1/workouts/{id}/sessions/start` - Begin new session\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout associated with the session.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}},{"name":"sessionId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout session to retrieve.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"responses":{"200":{"description":"Workout session details retrieved successfully.","schema":{"example":{"data":{"id":"67d1a2b3c4e5f6789abc0d1","createdAt":"2025-01-10T08:30:00.000Z","updatedAt":"2025-01-10T08:45:30.500Z","workoutId":"12ab3efd45c67c1234566cd1","workoutSegmentId":"seg-exercise-3","status":"started","duration":930,"progress":0.52}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutSessionResponse"}}}},"401":{"description":"Authentication failed (API key invalid or Bearer token invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated user is not authorized to view this session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID or session ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts//sessions/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getWorkoutSession() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//sessions/', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts//sessions/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/sessions/end":{"post":{"operationId":"WorkoutsSessionsApi_endWorkoutSession","summary":"End a workout session","description":"\nMarks an active workout session as completed. The duration is preserved from the last PATCH call.\n\n**Duration Behavior:**\n- Uses the duration from the most recent PATCH (progressSeconds-based)\n- Does NOT recalculate duration from wall-clock time\n- If no PATCH was called, duration will be 0\n\n**Typical Flow:**\n1. Start session: `POST /v1/workouts/{id}/sessions/start`\n2. Update progress: `PATCH /v1/workouts/{id}/sessions/{sessionId}` with progressSeconds\n3. **End session**: `POST /v1/workouts/{id}/sessions/end` (this endpoint)\n4. Submit feedback: `POST /v1/workouts/{id}/feedback`\n\n**Best Practice:** Send a final PATCH with current progressSeconds before calling end.\n\n**Related Endpoints:**\n- Start Session: `POST /v1/workouts/{id}/sessions/start`\n- Update Session: `PATCH /v1/workouts/{id}/sessions/{sessionId}`\n- Complete Session: `POST /v1/workouts/{id}/sessions/complete` (force 100%)\n- Submit Feedback: `POST /v1/workouts/{id}/feedback`\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout associated with the session.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Data required to end the session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndWorkoutSessionBody"},"examples":{"endSession":{"summary":"End a session","description":"Ends the session with duration from last PATCH.","value":{"sessionId":"12ab3efd45c67c1234566cd1"}}}}}},"responses":{"200":{"description":"Workout session successfully marked as completed.","schema":{"example":{"data":{"id":"67d1a2b3c4e5f6789abc0d1","createdAt":"2025-01-10T08:30:00.000Z","updatedAt":"2025-01-10T09:15:30.000Z","workoutId":"12ab3efd45c67c1234566cd1","workoutSegmentId":"seg-outro","status":"completed","duration":2730,"progress":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutSessionResponse"}}}},"400":{"description":"Invalid request data (e.g., missing sessionId).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed (API key invalid or Bearer token invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID or session ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Session is already completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/workouts//sessions/end' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function endWorkoutSession() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//sessions/end', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/workouts//sessions/end\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/sessions/complete":{"post":{"operationId":"WorkoutsSessionsApi_completeWorkoutSession","summary":"Complete workout session with 100% progress","description":"\n## Force Complete Session\n\nMarks a session as fully completed (100% progress) regardless of actual elapsed time. Use this when you need to guarantee a workout shows as complete in user history.\n\n---\n\n### 🎯 When to Use\n\n**Use `/sessions/complete` when:**\n- βœ… User manually marks workout as done\n- βœ… Workout completed outside the app (e.g., offline)\n- βœ… Need to force 100% completion for user's history\n- βœ… Retroactive completion (user forgot to track)\n\n**Use `/sessions/end` instead when:**\n- βœ… Normal workout completion flow\n- βœ… Want to preserve actual progress percentage\n- βœ… User stopped mid-workout\n- βœ… Tracking actual time and progress\n\n---\n\n### πŸ“Š Endpoint Comparison\n\n| Aspect | complete | end |\n|--------|----------|-----|\n| **Progress** | Always 100% | Actual progress |\n| **Duration** | Full workout duration | Actual elapsed time |\n| **Use Case** | Manual/forced completion | Natural completion |\n| **User Experience** | \"Mark as done\" button | Workout timer ends |\n\n---\n\n### πŸ”„ Integration Flow\n\n**Normal Flow (Use /end):**\n```\n1. POST /sessions/start β†’ Start tracking\n2. PATCH /sessions/{id} β†’ Update progress\n3. POST /sessions/end β†’ Natural completion\n4. POST /feedback β†’ Collect feedback\n```\n\n**Force Complete Flow (Use /complete):**\n```\n1. POST /sessions/start β†’ May have happened earlier\n2. POST /sessions/complete β†’ Force to 100%\n3. (Optional) POST /feedback β†’ Collect feedback\n```\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Use sparingly** - Prefer /end for actual completions \nβœ… **Document reason** - Log why forced completion was used \nβœ… **User transparency** - Show \"marked complete\" vs \"completed\" \nβœ… **Analytics distinction** - Track forced vs natural completions separately\n\n---\n\n### πŸ”— Related Endpoints\n\n- Start Session: `POST /v1/workouts/{id}/sessions/start` - Begin workout\n- End Session (natural): `POST /v1/workouts/{id}/sessions/end` - Normal completion\n- Update Session: `PATCH /v1/workouts/{id}/sessions/{sessionId}` - Track progress\n- Get Session: `GET /v1/workouts/{id}/sessions/{sessionId}` - Check status\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout associated with the session.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Data required to complete the session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteWorkoutSessionBody"},"examples":{"completeSession":{"summary":"Mark a specific session as 100% completed","description":"Force complete a session for user's workout history","value":{"sessionId":"12ab3efd45c67c1234566cd1"}}}}}},"responses":{"200":{"description":"Workout session successfully marked as 100% completed.","schema":{"example":{"data":{"id":"67d1a2b3c4e5f6789abc0d1","createdAt":"2025-01-10T08:30:00.000Z","updatedAt":"2025-01-10T09:00:00.000Z","workoutId":"12ab3efd45c67c1234566cd1","workoutSegmentId":"seg-outro","status":"completed","duration":1800,"progress":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutSessionResponse"}}}},"400":{"description":"Invalid request data (e.g., missing sessionId) or session is already completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed (API key invalid or Bearer token invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The authenticated user is not authorized to complete this session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID or session ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/workouts//sessions/complete' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function completeWorkoutSession() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//sessions/complete', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/workouts//sessions/complete\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/sessions/recent":{"get":{"operationId":"WorkoutsSessionsApi_getRecentWorkoutSession","summary":"Get most recent workout session","description":"\n## Get Most Recent Session\n\nRetrieves the most recent incomplete (status='started') workout session for a specific workout. Use this to check if there's an active session to resume.\n\n---\n\n### 🎯 Use Cases\n\n**Resume Workout:**\n- Check if user has an active session to resume\n- Display current progress and duration\n- Continue where they left off\n\n**Progress Tracking:**\n- Show current completion status\n- Display workout progress\n- Check session state\n\n---\n\n### πŸ“Š Session States\n\n**Started Sessions:**\n- Session is in progress\n- Can be updated via PATCH to track progress\n- Will be auto-completed if user starts a new session for the same workout\n\n**Completed Sessions:**\n- Session has ended (via /end, /complete, or auto-complete)\n- Duration and progress are finalized\n- Historical record for analytics\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Check before starting** - Use this to offer \"Resume\" vs \"Start New\" \nβœ… **Handle 404 gracefully** - No active session is normal for new workouts \nβœ… **Use for resume flow** - Perfect for \"Continue Workout\" buttons \nβœ… **Check status field** - Verify session is 'started' before resuming\n\n---\n\n### πŸ”— Related Endpoints\n\n- Start Session: `POST /v1/workouts/{id}/sessions/start` - Begin new session\n- Get Session by ID: `GET /v1/workouts/{id}/sessions/{sessionId}` - Specific session\n- Update Session: `PATCH /v1/workouts/{id}/sessions/{sessionId}` - Track progress\n- End Session: `POST /v1/workouts/{id}/sessions/end` - Complete session\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout for which to find the recent session.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"responses":{"200":{"description":"Most recent workout session details retrieved successfully.","schema":{"example":{"data":{"id":"67d1a2b3c4e5f6789abc0d1","createdAt":"2025-01-10T08:30:00.000Z","updatedAt":"2025-01-10T08:45:30.500Z","workoutId":"12ab3efd45c67c1234566cd1","workoutSegmentId":"seg-exercise-3","status":"started","duration":930,"progress":0.52}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutSessionResponse"}}}},"401":{"description":"Authentication failed (API key invalid or Bearer token invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No workout session (active or completed) found for this workout ID and authenticated user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts//sessions/recent' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getRecentWorkoutSession() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//sessions/recent', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts//sessions/recent\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/feedback/options":{"get":{"operationId":"WorkoutsFeedbackApi_getWorkoutFeedbackOptions","summary":"Get workout feedback options","description":"\n## Available Feedback Options\n\nRetrieves the rating scales and options available for workout feedback. Use this to populate your feedback UI dynamically.\n\n---\n\n### πŸ“‹ Response Structure\n\n**Rating Options:**\n- 1 Star - Poor\n- 2 Stars - Fair \n- 3 Stars - Good\n- 4 Stars - Very Good\n- 5 Stars - Excellent\n\n**Difficulty Options:**\n- 1 - Too Easy\n- 2 - Easy\n- 3 - Just Right\n- 4 - Challenging\n- 5 - Too Hard\n\n---\n\n### 🎯 Use Cases\n\nβœ… **Build Feedback UI** - Get all available options dynamically \nβœ… **Validate Submissions** - Ensure feedback IDs are valid before submitting \nβœ… **Localization** - Get translated option labels based on locale \nβœ… **Consistency** - Use platform-standard feedback scales\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Cache options** - They rarely change, cache for 24 hours \nβœ… **Use option IDs** - Submit feedback using IDs not labels \nβœ… **Handle missing options** - Graceful degradation if endpoint fails \nβœ… **Refresh periodically** - Check for new options monthly\n\n---\n\n### πŸ”— Related Endpoints\n\n- Submit Feedback: `POST /v1/workouts/{id}/feedback` - Submit user feedback\n- End Session: `POST /v1/workouts/{id}/sessions/end` - Complete before feedback\n- Start Session: `POST /v1/workouts/{id}/sessions/start` - Begin workout tracking\n ","parameters":[],"responses":{"200":{"description":"Successfully retrieved feedback options with all available rating scales.","schema":{"example":{"ratings":[{"id":"rating-1-star","label":"Poor","value":1},{"id":"rating-2-stars","label":"Fair","value":2},{"id":"rating-3-stars","label":"Good","value":3},{"id":"rating-4-stars","label":"Very Good","value":4},{"id":"rating-5-stars","label":"Excellent","value":5}],"difficulties":[{"id":"difficulty-too-easy","label":"Too Easy","value":1},{"id":"difficulty-easy","label":"Easy","value":2},{"id":"difficulty-just-right","label":"Just Right","value":3},{"id":"difficulty-challenging","label":"Challenging","value":4},{"id":"difficulty-too-hard","label":"Too Hard","value":5}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutFeedbackOptionsResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/workouts/feedback/options' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getWorkoutFeedbackOptions() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts/feedback/options', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/workouts/feedback/options\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/workouts/{workoutId}/feedback":{"post":{"operationId":"WorkoutsFeedbackApi_submitWorkoutFeedback","summary":"Submit workout feedback","description":"\n## Workout Rating & Comments\n\nCollect user feedback after workout completion including ratings, difficulty assessment, exercise performance data (weights and reps), and optional comments for continuous improvement.\n\n---\n\n### πŸ“‹ Feedback Components\n\n| Component | Required | Description | Options |\n|-----------|----------|-------------|---------|\n| **Session ID** | βœ… Yes | Links feedback to completed session | From session start |\n| **Overall Rating** | ❌ Optional | General workout satisfaction | 1-5 stars |\n| **Difficulty Rating** | ❌ Optional | Perceived workout difficulty | Too easy β†’ Too hard |\n| **Weight Unit** | ❌ Optional | Unit system for weights | metric (kg) or imperial (lbs) |\n| **Exercise Data** | ❌ Optional | Per-exercise weights and reps | Array of exercise feedback |\n| **Comments** | ❌ Optional | Free-text feedback | Max 1000 characters |\n\n---\n\n### πŸ‹οΈ Exercise Performance Tracking\n\n**Exercise Data Structure:**\n- Each entry corresponds to an exercise from the workout playlist (excluding rest segments)\n- Maintain the same order as the workout playlist\n- Filter out rest segments and irrelevant exercises client-side before submission\n\n**Weight Tracking:**\n- Required for weight-based exercises\n- Specify `weightUnit` ('metric' for kg, 'imperial' for lbs) when providing weights\n- Weight range: 0-1000 (supports both kg and lbs)\n- Example: `{ instanceId: \"...\", weight: 25.5 }` with `weightUnit: \"metric\"`\n\n**Reps Tracking:**\n- Required for AMRAP/time-based exercises (capture actual reps completed)\n- Required for rep-based exercises (capture actual reps completed)\n- Reps range: 1-100\n- Example: `{ instanceId: \"...\", reps: 15 }`\n\n**Combined:**\n- Some exercises may track both weight and reps\n- Example: `{ instanceId: \"...\", weight: 20.0, reps: 12 }`\n\n---\n\n### 🎯 When to Collect Feedback\n\nβœ… **After completion** - User finished entire workout \nβœ… **After early exit** - User stopped mid-workout \nβœ… **Optional prompts** - Don't force feedback \nβœ… **Quick ratings** - Minimize friction\n\n---\n\n### πŸ”„ Integration Flow\n\n1. **Complete Workout**: User finishes or stops workout\n2. **End Session**: `POST /v1/workouts/{id}/sessions/end` β†’ Get session ID\n3. **Get Playlist**: `GET /v1/workouts/{id}/playlist` β†’ Get exercise order and instance IDs\n4. **Show Feedback UI**: Present rating interface + exercise performance tracking\n5. **Submit Feedback**: `POST /v1/workouts/{id}/feedback` β†’ **This endpoint**\n6. **Thank User**: Acknowledge feedback submission\n\n---\n\n### πŸ“Š Feedback Options\n\n**Get Available Options:**\n`GET /v1/workouts/feedback/options` β†’ Returns current rating scales\n\n**Rating Scales:**\n- Overall: 1 (Poor) β†’ 5 (Excellent)\n- Difficulty: 1 (Too Easy) β†’ 5 (Too Hard)\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Make optional** - Don't require feedback to proceed \nβœ… **Quick UI** - Star ratings over complex forms \nβœ… **Contextual timing** - Collect when experience is fresh \nβœ… **Anonymous option** - Allow feedback without login \nβœ… **Order matters** - Maintain playlist order when submitting exerciseData \nβœ… **Filter client-side** - Remove rest segments before submission \nβœ… **Validate instanceIds** - Ensure instanceIds match workout playlist \nβœ… **Unit consistency** - Use same weightUnit for all exercises in a submission\n\n---\n\n### πŸ”— Related Endpoints\n\n- Feedback Options: `GET /v1/workouts/feedback/options` - Get rating scales\n- End Session: `POST /v1/workouts/{id}/sessions/end` - Complete before feedback\n- Start Session: `POST /v1/workouts/{id}/sessions/start` - Begin tracking\n- Get Workout: `GET /v1/workouts/{id}` - Workout details\n- Get Playlist: `GET /v1/workouts/{id}/playlist` - Get exercise order and instance IDs\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout receiving feedback.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Workout feedback with ratings, optional comments, and exercise performance data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitWorkoutFeedbackBody"},"examples":{"full-feedback":{"summary":"Complete Feedback","description":"Full feedback with rating, difficulty, and comments","value":{"workoutSessionId":"64f1a2b3c4d5e6f7a8b9c0d1","ratingId":"rating-5-stars","difficultyId":"difficulty-just-right","comment":"Great workout! The exercises were challenging but doable. Would love more variety in the warm-up."}},"rating-only":{"summary":"Rating Only","description":"Quick rating without difficulty or comments","value":{"workoutSessionId":"64f1a2b3c4d5e6f7a8b9c0d1","ratingId":"rating-4-stars"}},"anonymous-feedback":{"summary":"Anonymous Feedback","description":"Feedback from non-authenticated user session","value":{"workoutSessionId":"64f1a2b3c4d5e6f7a8b9c0d1","ratingId":"rating-5-stars","difficultyId":"difficulty-moderate","comment":"Perfect for beginners!"}},"with-exercise-data":{"summary":"Feedback with Exercise Performance Data","description":"Feedback including weights and reps tracking","value":{"workoutSessionId":"64f1a2b3c4d5e6f7a8b9c0d1","ratingId":"rating-5-stars","difficultyId":"difficulty-just-right","weightUnit":"metric","exerciseData":[{"instanceId":"64f1a2b3c4d5e6f7a8b9c0d2","weight":25.5},{"instanceId":"64f1a2b3c4d5e6f7a8b9c0d3","reps":15},{"instanceId":"64f1a2b3c4d5e6f7a8b9c0d4","weight":20,"reps":12}],"comment":"Great workout!"}}}}}},"responses":{"201":{"description":"Feedback submitted successfully.","schema":{"example":{"data":{"id":"67d1a2b3c4e5f6789abc0d2","createdAt":"2025-01-10T09:30:00.000Z","updatedAt":"2025-01-10T09:30:00.000Z","workoutId":"12ab3efd45c67c1234566cd1","workoutSessionId":"67d1a2b3c4e5f6789abc0d1","rating":{"id":"rating-4-stars","label":"Very Good","value":4},"difficulty":{"id":"difficulty-challenging","label":"Challenging","value":4},"comment":"Great workout! Felt appropriately challenging.","weightUnit":"metric","exercises":[{"instanceId":"64f1a2b3c4d5e6f7a8b9c0d2","reps":15},{"instanceId":"64f1a2b3c4d5e6f7a8b9c0d3","weight":25,"reps":12}]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutFeedbackResponse"}}}},"400":{"description":"Invalid feedback data provided (e.g., missing required rating, invalid rating value, missing weightUnit when weights provided, invalid instanceIds). Check feedback options endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed (API key invalid or Bearer token invalid if provided).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified workout ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["workouts"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/workouts//feedback' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function submitWorkoutFeedback() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/workouts//feedback', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/workouts//feedback\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/plans/metadata":{"get":{"operationId":"PlansApi_getPlanMetadata","summary":"Get available plan goals and difficulties","description":"\nRetrieves all fitness goals and difficulty levels available across training plans.\n\n**Use this endpoint to populate:**\n- `goalIds` parameter in `POST /v1/orgs/{orgId}/plans/generate`\n- Plan goal filters in your application UI\n\n**Response includes:**\n- `goals`: Array of {id, name} for each fitness goal\n- `difficulties`: Array of difficulty strings (beginner, intermediate, advanced)\n\n**Example Goals:**\n- Lose weight (63c92926f920a9005c4e619c)\n- Build strength (63c92926f920a9005c4e619d)\n- Improve endurance (63c92926f920a9005c4e619e)\n- Increase mobility (63c92926f920a9005c4e619f)\n- Get toned (63c92926f920a9005c4e61a0)\n- Physiotherapy (63c92926f920a9005c4e61a1)\n\n**Related Metadata Endpoints:**\n- `GET /v1/plans/metadata` - Goals & difficulties (for plan generation/filtering)\n- `GET /v1/workouts/metadata` - Categories & difficulties (for workout generation)\n- `GET /v1/workouts/equipment/metadata` - Equipment items & categories\n- `GET /v1/workouts/exercises/metadata` - Muscle groups & collections\n\n**For Plan Generation:** Call this endpoint + equipment/metadata\n**For Workout Generation:** Call workouts/metadata + equipment/metadata + exercises/metadata (advanced)\n\n---\n\n### 🌍 Localization\n\nContent localized based on `locale` query parameter:\n- **Supported**: 13 languages (en-US, fr-FR, de-DE, es-ES, etc.)\n- **Fallback**: English if locale unsupported\n- **Affects**: Goal names\n\n---\n\n**Related Endpoints:**\n- Generate: `POST /v1/orgs/{orgId}/plans/generate`\n- List: `GET /v1/orgs/{orgId}/plans`\n- Recommend: `POST /v1/orgs/{orgId}/plans/recommend`\n ","parameters":[{"name":"locale","required":false,"in":"query","description":"Preferred language locale (e.g., fr-FR)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved plan goals and difficulty lists.","content":{"application/json":{"schema":{"type":"object","properties":{"goals":{"type":"array","description":"List of all available plan goals.","items":{"type":"object","properties":{"id":{"type":"string","description":"Goal ID","example":"63c92926f920a9005c4e619c"},"name":{"type":"string","description":"Goal display name","example":"Lose weight"}},"required":["id","name"]}},"difficulties":{"type":"array","description":"List of all available plan difficulty levels.","items":{"type":"string","example":"intermediate"}}},"example":{"goals":[{"id":"63c92926f920a9005c4e619c","name":"Lose weight"},{"id":"63c92926f920a9005c4e619d","name":"Build strength"},{"id":"63c92926f920a9005c4e619e","name":"Improve endurance"}],"difficulties":["beginner","intermediate","advanced"]}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["plans"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/plans/metadata' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getPlanMetadata() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/plans/metadata', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/plans/metadata\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/plans/{planId}":{"get":{"operationId":"PlansApi_getPlan","summary":"Get training plan details","description":"\n## Complete Training Plan Details\n\nRetrieves comprehensive information about a specific multi-week training program including metadata, goals, and trainer information.\n\n---\n\n### πŸ“‹ What's Included\n\n| Field | Description | Example |\n|-------|-------------|---------|\n| **Core Info** | Name, description, difficulty, visibility | \"4-Week Strength Builder\", intermediate, public |\n| **Program Duration** | Duration in weeks and workouts per week | 8 weeks, 3 workouts/week |\n| **Goals** | Primary fitness objectives | [\"Build Strength\", \"Increase Endurance\"] |\n| **Trainer** | Coach name and ID | \"Sarah Johnson\", trainer123 |\n| **Preview** | Video and thumbnail links | HLS stream URL, poster image |\n| **Share Link** | Shareable URL for the plan | https://app.hyperhuman.cc/plans/... |\n| **Organization** | Team/brand information (if applicable) | Logo URL, organization name |\n\n**Note:** To get the workouts in this plan, call `GET /v1/plans/{id}/workouts`\n\n---\n\n### 🎯 Use Cases\n\nβœ… **Plan Preview** - Show details before starting program \nβœ… **Goal Alignment** - Match plan goals to user objectives \nβœ… **Trainer Information** - Display coach name and credentials \nβœ… **Program Overview** - Understand plan structure and goals \nβœ… **Duration Planning** - Display program length and weekly commitment \nβœ… **Program Comparison** - Compare different program durations and intensities\n\n---\n\n### ⏱️ Program Duration Fields\n\nThe response includes two key duration fields:\n\n- **`durationInWeeks`**: Total program duration (1-24 weeks)\n- **`workoutsPerWeek`**: Weekly workout frequency (1-7 workouts)\n\n**Example Response:**\n```json\n{\n \"data\": {\n \"id\": \"64f1a2b3c4d5e6f7a8b9c0d2\",\n \"name\": \"8-Week Strength Program\",\n \"description\": \"A comprehensive strength building program\",\n \"difficulty\": \"intermediate\",\n \"visibility\": \"public\",\n \"durationInWeeks\": 8,\n \"workoutsPerWeek\": 3,\n \"goals\": [...],\n \"trainer\": {...},\n \"preview\": {...}\n }\n}\n```\n\n---\n\n### πŸ”„ Integration Flow\n\n1. **Browse Plans**: `GET /v1/orgs/{orgId}/plans` β†’ Get plan list (with duration filters)\n2. **Get Plan Details**: `GET /v1/plans/{id}` β†’ **This endpoint** (full details including duration)\n3. **Get Workouts**: `GET /v1/plans/{id}/workouts` β†’ Associated workouts list\n4. **Start Program**: Begin first workout in sequence\n5. **Track Progress**: Monitor completion across weeks\n\n---\n\n### 🌍 Localization\n\nContent localized based on `locale` query parameter:\n- **Supported**: 13 languages (en-US, fr-FR, de-DE, es-ES, etc.)\n- **Fallback**: English if locale unsupported\n- **Affects**: Plan name, description, goal names\n\n---\n\n### πŸ”— Related Endpoints\n\n- Plan List: `GET /v1/orgs/{orgId}/plans` - Browse organization plans (with duration filtering)\n- Plan Workouts: `GET /v1/plans/{id}/workouts` - Get associated workouts\n- Plan Metadata: `GET /v1/plans/metadata` - Get goals and difficulties\n- Generate Plan: `POST /v1/orgs/{orgId}/plans/generate` - Create new plan with duration\n- Filter Plans: `GET /v1/orgs/{orgId}/plans?durationInWeeks=8&workoutsPerWeek=3` - Find specific duration programs\n ","parameters":[{"name":"planId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout plan to retrieve.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"Preferred language locale for localized content (e.g., en-US, fr-FR, de-DE). Affects plan name, description, and goal names.","example":"en-US","schema":{"type":"string","enum":["en-US","en-GB","en-AU","fr-FR","de-DE","es-ES","it-IT","pt-PT","he-IL","ro-RO","cs-CZ","fi-FI","nl-NL"]}}],"responses":{"200":{"description":"Workout plan details retrieved successfully with duration information.","content":{"application/json":{"examples":{"8-week-program":{"summary":"8-Week Strength Program","description":"Example of an 8-week program with 3 workouts per week","value":{"data":{"id":"64f1a2b3c4d5e6f7a8b9c0d2","name":"8-Week Strength Program","description":"A comprehensive strength building program designed for intermediate fitness levels","difficulty":"intermediate","visibility":"public","durationInWeeks":8,"workoutsPerWeek":3,"goals":[{"id":"64f1a2b3c4d5e6f7a8b9c0d3","name":"Build Strength","nameTranslations":{}}],"trainer":{"id":"64f1a2b3c4d5e6f7a8b9c0d4","name":"Sarah Johnson"},"preview":{"url":"https://stream.hyperhuman.cc/plan-preview.m3u8","poster":"https://images.hyperhuman.cc/plan-poster.jpg","thumbnail":"https://images.hyperhuman.cc/plan-thumb.jpg"},"shareLink":{"url":"https://app.hyperhuman.cc/plans/64f1a2b3c4d5e6f7a8b9c0d2"},"organization":{"id":"org-hyperhuman-llc","name":"Hyperhuman LLC","logo":{"url":"https://images.hyperhuman.cc/logo.png"}}}}},"12-week-program":{"summary":"12-Week Transformation Program","description":"Example of a longer 12-week program with 4 workouts per week","value":{"data":{"id":"64f1a2b3c4d5e6f7a8b9c0d5","name":"12-Week Transformation Program","description":"An intensive 12-week program for advanced fitness levels","difficulty":"advanced","visibility":"public","durationInWeeks":12,"workoutsPerWeek":4,"goals":[{"id":"64f1a2b3c4d5e6f7a8b9c0d6","name":"Weight Loss","nameTranslations":{}},{"id":"64f1a2b3c4d5e6f7a8b9c0d7","name":"Build Muscle","nameTranslations":{}}],"trainer":{"id":"64f1a2b3c4d5e6f7a8b9c0d8","name":"Mike Chen"},"preview":{"url":"https://stream.hyperhuman.cc/transformation-preview.m3u8","poster":"https://images.hyperhuman.cc/transformation-poster.jpg","thumbnail":"https://images.hyperhuman.cc/transformation-thumb.jpg"},"shareLink":{"url":"https://app.hyperhuman.cc/plans/64f1a2b3c4d5e6f7a8b9c0d5"},"organization":null}}}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified plan ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["plans"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/plans/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getPlan() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/plans/', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/plans/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/plans/{planId}/workouts":{"get":{"operationId":"PlansApi_getPlanWorkouts","summary":"Get workouts in training plan","description":"\n## Plan Workout Collection\n\nRetrieves the complete list of workouts that comprise a specific training plan, ordered as they appear in the program sequence.\n\n---\n\n### 🎯 Plan Context\n\n| Aspect | Plan Workouts | General Workouts |\n|--------|---------------|------------------|\n| **Ordering** | Sequential program flow | Alphabetical/date |\n| **Progression** | Structured difficulty curve | Independent difficulty |\n| **Coherence** | Designed to work together | Standalone sessions |\n| **Collection** | Returns all workouts in plan | Filtered/paginated results |\n\n---\n\n### πŸ“‹ Use Cases\n\nβœ… **Program Navigation** - Browse workouts in sequence \nβœ… **Progress Tracking** - Show completed vs remaining workouts \nβœ… **Workout Preview** - Display individual workout details \nβœ… **Plan Management** - Admin oversight of program content\n\n---\n\n### πŸ” Response Structure\n\n**Returns:**\n- Complete list of ALL workouts in the plan (no pagination)\n- Workouts ordered as designed in the plan sequence\n- Each workout includes: name, duration, difficulty, categories, trainer, preview\n\n**Note:** This endpoint returns all workouts at once. For plans with many workouts, consider implementing client-side pagination for display purposes.\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Respect workout order** - Maintain the sequence returned by the API \nβœ… **Show progress** - Track which workouts user has completed \nβœ… **Fetch workout details** - Call `GET /v1/workouts/{id}` for full details \nβœ… **Cache workout list** - Workout order rarely changes within a plan \nβœ… **Client-side pagination** - Implement display pagination if needed\n\n---\n\n### πŸ”— Related Endpoints\n\n- Plan Details: `GET /v1/plans/{id}` - Get plan information\n- Workout Details: `GET /v1/workouts/{id}` - Get individual workout\n- Start Session: `POST /v1/workouts/{id}/sessions/start` - Begin workout\n- Plan List: `GET /v1/orgs/{orgId}/plans` - Browse all plans\n ","parameters":[{"name":"planId","required":true,"in":"path","description":"The unique identifier (UUID) of the workout plan.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"Preferred language locale (e.g., fr-FR)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved complete list of workouts for the plan.","schema":{"example":{"data":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","name":"Upper Body Strength","description":"Focus on chest, shoulders, and arms","duration":2700,"difficulty":"intermediate","visibility":"public","locked":false,"createdAt":"2023-10-26T10:00:00.000Z","updatedAt":"2023-10-27T11:30:00.000Z","trainer":{"id":"64f1a2b3c4d5e6f7a8b9c0d4","name":"Sarah Johnson"},"categories":[{"id":"615aa3dadbe7140012c59e90","name":"Strength"}],"preview":{"url":"https://stream.hyperhuman.cc/workout-preview.m3u8","poster":"https://images.hyperhuman.cc/workout-poster.jpg","thumbnail":"https://images.hyperhuman.cc/workout-thumb.jpg"},"images":{"thumbnail":"https://images.hyperhuman.cc/workout-thumb.jpg"},"rating":4.5,"mixBgMusic":true,"presentationStyle":"full","allowAssessment":false},{"id":"64f1a2b3c4d5e6f7a8b9c0d2","name":"Lower Body Power","description":"Intense leg and glute workout","duration":2400,"difficulty":"intermediate","visibility":"public","locked":false,"createdAt":"2023-10-26T10:00:00.000Z","updatedAt":"2023-10-27T11:30:00.000Z","trainer":{"id":"64f1a2b3c4d5e6f7a8b9c0d4","name":"Sarah Johnson"},"categories":[{"id":"615aa3dadbe7140012c59e90","name":"Strength"}],"preview":{"url":"https://stream.hyperhuman.cc/workout-preview-2.m3u8","poster":"https://images.hyperhuman.cc/workout-poster-2.jpg","thumbnail":"https://images.hyperhuman.cc/workout-thumb-2.jpg"},"images":{"thumbnail":"https://images.hyperhuman.cc/workout-thumb-2.jpg"},"rating":4.7,"mixBgMusic":true,"presentationStyle":"full","allowAssessment":false}],"pagination":{"page":1,"limit":20,"total":24,"pages":2}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutListResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified plan ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["plans"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/plans//workouts' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getPlanWorkouts() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/plans//workouts', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/plans//workouts\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/video-assets":{"get":{"operationId":"OrganizationExercisesApi_getOrganizationExercises","summary":"List workspace exercise videos for an organization","description":"\n## Workspace Exercise Library\n\nPaginated **published** workspace exercise videos for `organizationId` - previews, metadata, and creator references for catalogs, workout builders, and players. Sorted newest first.\n\n---\n\n### What you get\n\nOnly the videos this workspace uploaded itself. Use it to power your in-product catalog, workout builder, or video player with content you own.\n\n- `trainer` - the workspace member who uploaded the asset\n- `organization` - the workspace you queried, repeated on every row\n\n---\n\n### Video type guide\n\n| Video type | API `kind` | Audio behavior | Playback notes |\n|---|---|---|---|\n| **EXERCISE** - Smart video for flexible workout building | `single-exercise` | **Original audio removed; multilingual instructions in `audioInstructions[]`** | Configurable reps or duration in workout builder; auto-loops to match your configured time; shows exercise labels and overlays in player |\n| **ORIGINAL** - Video plays as uploaded | `multi-exercise` (no separate `original` enum) | Original audio preserved on the video | Plays once from start to finish; added to workouts as-is |\n| **PROMO** - Clean playback for branding | `promo` | Original audio preserved on the video | No exercise overlays or labels; great for intros, outros, or splash screens |\n| **TUTORIAL** - Educational content | `educational` | Original audio with instructor explanations | Perfect for explaining proper form and technique; great for beginners or complex movements |\n| **CLASS** - Long-format instructor-led workout | `class` | Original audio with instructor guidance | Complete workout session format; ideal for yoga, pilates, dance, or instructor-led classes |\n\n---\n\n### Pagination\n\n- `offset` - number of items to skip (default: `0`)\n- `limit` - items per page (service default: `10`, max: `50`)\n- Prefer following `links.next` from the response over computing offsets manually\n\n---\n\n### Filtering\n\nAll filters AND-combine; multi-value filters are OR-internally (`$in`). Every filter is applied at the DB level so `links.total` stays exact.\n\n| Param | Type | Behavior |\n|---|---|---|\n| `q` | string | Case-insensitive substring on `name`. With `?locale=`, also matches the locale-specific name. |\n| `equipmentIds` | CSV of 24-hex ids | Returns assets whose `equipment[]` includes ANY id. |\n| `muscleGroupIds` | CSV of 24-hex ids | Returns assets whose `muscleGroups[]` includes ANY id. |\n| `kinds` | CSV of `VideoAssetKind` | See **Video type guide** above for the product-name mapping. |\n| `skillLevels` | CSV of `SkillLevel` | `beginner` / `intermediate` / `advanced`. |\n| `executionSides` | CSV of `ExecutionSide` | `both` / `left` / `right` / `alternating`. |\n| `coach` | `male` / `female` | Single value. |\n| `collectionNames` | CSV of strings | Exact match (case-sensitive); rows with empty `collectionName` are excluded when set. |\n\nBad values (non-hex ids, unknown enum members, empty CSV) return `400 ValidationError` with the offending field in `error.target`.\n\n---\n\n### Sorting\n\nUse `?sort=` with `+` / `-` prefix and comma-separated multi-keys.\n\n| Public name | DB field | Notes |\n|---|---|---|\n| `date` (alias of `createdAt`) | `createdAt` | Default: `-date` (newest first). |\n| `name` | `name` | Sorts by canonical `name`. Locale-aware sort is not yet supported. |\n| `kind` | `kind` | Useful for grouping; pair with `+name` for stable secondary order. |\n\nExamples: `?sort=-date`, `?sort=+name`, `?sort=-kind,+name`. Unknown fields return `400 ValidationError`.\n\n---\n\n### Localization\n\nOptional `locale` (BCP-47, e.g. `en-US`) localizes:\n\n- `name`\n- `muscleGroups[].name`\n- `equipment[].name`\n- `audioInstructions[]` (see below)\n\nWhen omitted, raw values fall back to English. Full supported locale list: see `AGENTS.md` section 5.\n\n---\n\n### Audio instructions (`audioInstructions[]`)\n\nPopulated **only** for `kind: single-exercise` rows - the smart-clip product type that strips original audio in favor of multilingual instructions.\n\n- **With `?locale=`** - items narrow to matching locales via the standard locale chain (English fallback)\n- **Without `?locale=`** - returns **all** available locales so catalog UIs can render a \"narrated in N languages\" indicator\n- **Other kinds** (`multi-exercise`, `educational`, `promo`, `class`) keep their original audio baked into the video and return `[]`\n\nEach entry carries:\n\n- `id` - audio resource id (24-character hex)\n- `createdAt` - ISO 8601 timestamp\n- `assetUri` - **short-lived presigned URL** to the encoded MP4A clip (do not cache long-term; refresh by re-listing)\n- `type` - audio role; for instruction tracks this is `exerciseInstruction`\n- `locale` - BCP-47 tag of this specific track (e.g. `en-US`, `fr-FR`)\n- `scriptText` *(optional)* - **verbatim transcript** the narrator reads in `assetUri`. Use it for closed captions, accessibility overlays, search indexing, and AI summarization. Omitted on single exercise clips with no intructions at all, no text based instructions or having recorded or audio file instructions - **always null-check** before rendering.\n\nFull per-asset audio (cues + instructions, including `scriptText` per track) is exposed on the per-asset detail endpoint when listed in `/openapi.json`.\n\n---\n\n### Related Endpoints\n\n- Micro Workouts: `GET /v1/orgs/{organizationId}/groups` - circuit / sets-based collections built on top of these exercises\n- Workout Metadata: `GET /v1/workouts/metadata` - categories and difficulties shared across the catalog\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"Unique organization (workspace) resource id for Hyperhuman Teams - opaque 24-character hex string.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return per page.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search text","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sortable fields (use `+` / `-` prefix, comma-separated for multi-key). Allowed: `date` (alias of `createdAt`), `name`, `kind`. Default: `-date` (newest first). Examples: `-date`, `+name`, `-kind,+name`.","example":"-date","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"BCP-47 locale (e.g. en-US). Localizes text and locale-aware media when supported; falls back to English.","example":"en-US","schema":{"type":"string"}},{"name":"equipmentIds","required":false,"in":"query","description":"Comma-separated equipment ids (24-character hex). Returns assets whose `equipment[]` includes ANY of these.","example":"60d21b4667d0d8992e610c90,60d21b4667d0d8992e610c91","schema":{"type":"string"}},{"name":"muscleGroupIds","required":false,"in":"query","description":"Comma-separated muscle-group ids (24-character hex). Returns assets whose `muscleGroups[]` includes ANY of these.","example":"60d21b4667d0d8992e610c85","schema":{"type":"string"}},{"name":"kinds","required":false,"in":"query","description":"Comma-separated video kinds. Allowed: `single-exercise`, `multi-exercise`, `class`, `promo`, `educational`. See the **Video type guide** in the endpoint description for product-name-to-`kind` mapping.","example":"single-exercise,educational","schema":{"type":"string"}},{"name":"skillLevels","required":false,"in":"query","description":"Comma-separated skill levels. Allowed: `beginner`, `intermediate`, `advanced`.","example":"beginner,intermediate","schema":{"type":"string"}},{"name":"executionSides","required":false,"in":"query","description":"Comma-separated execution sides. Allowed: `both`, `left`, `right`, `alternating`.","example":"both,alternating","schema":{"type":"string"}},{"name":"coach","required":false,"in":"query","description":"Coach gender as recorded on the asset.","example":"female","schema":{"enum":["male","female"],"type":"string"}},{"name":"collectionNames","required":false,"in":"query","description":"Comma-separated collection names (exact match, case-sensitive). Rows with empty `collectionName` are excluded when this filter is set.","example":"Morning cardio,Yoga flow","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated workspace exercise videos with previews and metadata.","schema":{"example":{"data":[{"id":"60812dea606fc90011eb4405","createdAt":"2025-09-15T10:30:00Z","name":"Jumping Jacks","kind":"single-exercise","trainer":{"id":"63a1c2b4f0e1a200126616a1","name":"Sarah Johnson"},"muscleGroups":[{"id":"60d21b4667d0d8992e610c85","name":"Full Body"}],"equipment":[{"id":"60d21b4667d0d8992e610c90","name":"Bodyweight"}],"preview":{"url":"https://stream.hyperhuman.cc/video/ex-60812dea/master.m3u8?token=...","poster":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/ex-60812dea.jpg","thumbnail":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/ex-60812dea.jpg"},"playsInLoop":true,"organization":{"id":"63415bf67a9c7000126616c1","name":"My Gym","logo":{"url":"https://hhcontent.s3.eu-central-1.amazonaws.com/logos/org-63415bf67a9c7000126616c1.png"}},"audioInstructions":[{"id":"65a1b2c3d4e5f600126616a1","createdAt":"2025-09-15T10:31:00Z","assetUri":"https://hhcontent.s3.eu-central-1.amazonaws.com/audio/inst-60812dea-en-US.m4a?token=...","type":"exerciseInstruction","locale":"en-US","scriptText":"Stand tall with your feet shoulder-width apart. Jump up while raising your arms overhead and spreading your legs out to the sides."},{"id":"65a1b2c3d4e5f600126616a2","createdAt":"2025-09-15T10:31:00Z","assetUri":"https://hhcontent.s3.eu-central-1.amazonaws.com/audio/inst-60812dea-fr-FR.m4a?token=...","type":"exerciseInstruction","locale":"fr-FR","scriptText":"Tenez-vous droit, pieds Γ©cartΓ©s Γ  la largeur des Γ©paules. Sautez en levant les bras au-dessus de la tΓͺte et en Γ©cartant les jambes sur les cΓ΄tΓ©s."}],"skillLevel":"beginner","tags":["warmup"],"collectionName":"Morning cardio"}],"links":{"next":"https://content.api.hyperhuman.cc/v1/orgs/63415bf67a9c7000126616c1/video-assets?limit=10&offset=10","total":142},"explanation":"Published exercise videos from your workspace."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoAssetsListResponse"}}}},"400":{"description":"Request validation failed. `error.code` is `ValidationError`; `error.target` is the DTO class name; `error.details[]` lists the offending fields.","schema":{"example":{"error":{"code":"ValidationError","message":"ValidationError","target":"GetVideoAssetsByOrganizationIdParams","details":[{"code":"ConstraintError","message":"organizationId must be a mongodb id","target":"organizationId"}]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, malformed, or unknown `X-Api-Key` header.","schema":{"example":{"error":{"code":"Unauthorized","message":"Unauthorized"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is valid but is not authorized for this `organizationId` (the key belongs to a different workspace, or no API key was sent on a guarded route).","schema":{"example":{"error":{"code":"Forbidden","message":"API key not authorized for this organization"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No workspace exists for the supplied `organizationId`.","schema":{"example":{"error":{"code":"NotFound","message":"Organization not found"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["library-exercises"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//video-assets' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationExercises() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//video-assets', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//video-assets\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/groups":{"get":{"operationId":"OrganizationExerciseGroupsApi_getOrganizationExerciseGroups","summary":"List organization micro workouts (exercise groups)","description":"\n## Micro Workouts (Exercise Groups)\n\n**Micro workouts** are short, focused exercise collections designed for quick sessions. Use these endpoints to surface them in your app.\n\nRetrieves paginated list of exercise collections (micro workouts) for your organization. Each collection has simple execution details: circuit or sets format, rounds, rest periods, and per-exercise config (time-based or reps-based).\n\n---\n\n### Use Cases\n\n- **White-label Apps** - Show organization micro workouts\n- **Quick Workout Browsing** - Circuit and sets-based collections\n- **Integration with Workouts** - Collections can be used in workout generation (excludeExerciseCollections)\n\n---\n\n### Execution Details (per collection)\n\n- **kind**: circuit | sets\n- **rounds**: Number of rounds\n- **roundBreakDuration**: Rest between rounds (ms)\n- **exerciseBreakDuration**: Rest between exercises (ms)\n- **exerciseConfig**: timeBasedConfig (duration, pace, rpe, amrap) or repsBasedConfig (reps, weightLevel, pace, rpe)\n\n---\n\n### Filtering and Pagination\n\n**Visibility:**\n- `public` - Publicly accessible collections (default)\n- `private` - Organization-only (requires API key for same org)\n- `all` - Both (requires API key for same org)\n\n**Pagination:**\n- `offset` - Pagination offset (default: 0)\n- `limit` - Items per page (default: 10, max: 50)\n\n---\n\n### Related Endpoints\n\n- Get Group Detail: `GET /v1/orgs/{orgId}/groups/{groupId}` - Full detail with execution config\n- Get Group Exercises: `GET /v1/orgs/{orgId}/groups/{groupId}/exercises` - Exercises in collection\n- List Workouts: `GET /v1/orgs/{orgId}/workouts` - Organization workouts\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Items per page. Defaults to 10, max 50.","example":10,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"locale","required":false,"in":"query","description":"BCP-47 locale (e.g. en-US, fr-FR). Localizes text and locale-aware media when this operation supports it. Falls back to English when unsupported.","example":"en-US","schema":{"type":"string"}},{"name":"visibility","required":false,"in":"query","description":"Filter groups by their visibility status.","example":"public","schema":{"enum":["private","public","all"],"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset. Defaults to 0.","example":0,"schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully retrieved paginated list of micro workouts (exercise collections).","schema":{"example":{"data":[{"id":"507f1f77bcf86cd799439011","createdAt":"2025-09-15T10:30:00Z","updatedAt":"2025-09-16T14:20:00Z","name":"Quick HIIT Circuit","kind":"circuit","preview":{"url":"https://stream.hyperhuman.cc/video/group-507f1f77/master.m3u8?token=...","poster":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/group-507f1f77.jpg","thumbnail":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/group-507f1f77.jpg"},"rounds":3,"roundBreakDuration":10000,"exerciseBreakDuration":0,"exerciseConfig":{"timeBasedConfig":{"kind":"timeBased","duration":30000,"pace":"medium","rpe":7,"amrap":false}},"trainer":{"id":"trainer123","name":"Sarah Johnson"}},{"id":"507f1f77bcf86cd799439012","createdAt":"2025-09-10T08:00:00Z","updatedAt":"2025-09-12T11:15:00Z","name":"Upper Body Sets","kind":"sets","preview":{"url":"https://stream.hyperhuman.cc/video/group-507f1f78/master.m3u8?token=...","poster":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/group-507f1f78.jpg","thumbnail":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/group-507f1f78.jpg"},"rounds":2,"roundBreakDuration":60000,"exerciseBreakDuration":15000,"exerciseConfig":{"repsBasedConfig":{"kind":"repsBased","reps":12,"weightLevel":"medium","pace":"medium","rpe":8}},"trainer":{"id":"trainer456","name":"Mike Chen"}}],"links":{"next":"https://content.api.hyperhuman.cc/v1/orgs/63415bf67a9c7000126616c1/groups?limit=10&offset=10","total":24},"explanation":"Your organization micro workouts - circuit and sets-based collections for quick sessions."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key not authorized for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["exercise-groups"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//groups' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationExerciseGroups() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//groups', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//groups\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/groups/{groupId}":{"get":{"operationId":"OrganizationExerciseGroupsApi_getOrganizationExerciseGroupById","summary":"Get micro workout (exercise group) by ID","description":"\n## Micro Workout Detail\n\nReturns full detail for a micro workout (exercise collection) belonging to your organization. Includes execution config (circuit/sets, rounds, rest, time-based or reps-based per exercise).\n\n**Response structure:**\n- `kind` - circuit | sets\n- `rounds`, `roundBreakDuration`, `exerciseBreakDuration`\n- `exerciseConfig` - timeBasedConfig (duration, pace, rpe, amrap) or repsBasedConfig (reps, weightLevel, pace, rpe)\n- `preview` - Video preview URLs\n- `trainer`, `organization`\n\n**Access:** Only collections created by organization trainers. Private collections require API key for the same organization.\n\n---\n\n### Related Endpoints\n\n- List Collections: `GET /v1/orgs/{orgId}/groups` - Browse organization collections\n- Get Exercises: `GET /v1/orgs/{orgId}/groups/{groupId}/exercises` - Exercises in this collection\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"groupId","required":true,"in":"path","description":"The unique identifier of the exercise collection (group).","example":"507f1f77bcf86cd799439011","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"BCP-47 locale (e.g. en-US, fr-FR). Localizes text and locale-aware media when this operation supports it. Falls back to English when unsupported.","example":"en-US","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved micro workout (exercise collection) detail.","schema":{"example":{"data":{"id":"507f1f77bcf86cd799439011","createdAt":"2025-09-15T10:30:00Z","updatedAt":"2025-09-16T14:20:00Z","name":"Quick HIIT Circuit","kind":"circuit","preview":{"url":"https://stream.hyperhuman.cc/video/group-507f1f77/master.m3u8?token=...","poster":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/group-507f1f77.jpg","thumbnail":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/group-507f1f77.jpg"},"rounds":3,"roundBreakDuration":10000,"exerciseBreakDuration":0,"exerciseConfig":{"timeBasedConfig":{"kind":"timeBased","duration":30000,"pace":"medium","rpe":7,"amrap":false}},"trainer":{"id":"trainer123","name":"Sarah Johnson"},"organization":{"id":"63415bf67a9c7000126616c1","name":"My Gym","logo":{"url":"https://hhcontent.s3.eu-central-1.amazonaws.com/logos/org-63415bf67a9c7000126616c1.png"}}}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key not authorized for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Group not found or not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["exercise-groups"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//groups/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationExerciseGroupById() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//groups/', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//groups/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/groups/{groupId}/exercises":{"get":{"operationId":"OrganizationExerciseGroupsApi_getOrganizationGroupExercises","summary":"Get exercises in micro workout","description":"\n## Get Micro Workout Exercises\n\nReturns the list of exercises in a micro workout (exercise collection). Each exercise includes video preview, metadata (muscle groups, equipment), and trainer info.\n\n**Use this endpoint to:**\n- Display the exercise sequence for a micro workout\n- Build a preview or playback UI for the collection\n- Get exercise details before starting a session\n\n---\n\n### Related Endpoints\n\n- Get Collection: `GET /v1/orgs/{orgId}/groups/{groupId}` - Collection detail with execution config\n- List Collections: `GET /v1/orgs/{orgId}/groups` - Browse organization collections\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"groupId","required":true,"in":"path","description":"The unique identifier of the exercise collection (group) whose exercises are requested.","example":"507f1f77bcf86cd799439011","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"BCP-47 locale (e.g. en-US, fr-FR). Localizes text and locale-aware media when this operation supports it. Falls back to English when unsupported.","example":"en-US","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved list of exercises in the micro workout with instance config (reps, duration, pace, rpe).","schema":{"example":{"data":[{"id":"60812dea606fc90011eb4405","createdAt":"2025-09-15T10:30:00Z","name":"Jumping Jacks","kind":"singleExercise","muscleGroups":[{"id":"mg_full_body","name":"Full Body"}],"equipment":[{"id":"eq_bodyweight","name":"Bodyweight"}],"trainer":{"id":"trainer123","name":"Sarah Johnson"},"preview":{"url":"https://stream.hyperhuman.cc/video/ex-60812dea/master.m3u8?token=...","poster":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/ex-60812dea.jpg","thumbnail":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/ex-60812dea.jpg"},"duration":30,"reps":null,"pace":"medium","weightLevel":null,"rpe":7,"amrap":false},{"id":"60812dea606fc90011eb4406","createdAt":"2025-09-15T10:30:00Z","name":"Push-ups","kind":"singleExercise","muscleGroups":[{"id":"mg_chest","name":"Chest"}],"equipment":[{"id":"eq_bodyweight","name":"Bodyweight"}],"trainer":{"id":"trainer123","name":"Sarah Johnson"},"preview":{"url":"https://stream.hyperhuman.cc/video/ex-60812dea6/master.m3u8?token=...","poster":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/ex-60812dea6.jpg","thumbnail":"https://hhcontent.s3.eu-central-1.amazonaws.com/thumbnails/ex-60812dea6.jpg"},"duration":24,"reps":12,"pace":"medium","weightLevel":"medium","rpe":8}],"links":{"next":null,"total":5}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupExercisesListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key not authorized for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Group not found or not accessible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["exercise-groups"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//groups//exercises' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationGroupExercises() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//groups//exercises', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//groups//exercises\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/plans":{"get":{"operationId":"OrganizationPlansApi_getOrganizationPlans","summary":"List organization-specific training plans","description":"\n## Organization Training Plans\n\nRetrieves paginated list of multi-week training programs specific to your organization.\n\n**Note:** DTOs reference `WorkoutCollection` types - this is the same as \"Plan\" (historical naming).\n\n---\n\n### πŸ”„ Choose Your Endpoint\n\n| Need | Use | Speed | Result |\n|------|-----|-------|--------|\n| Browse library | `GET /orgs/{id}/plans` | <50ms | Filtered list |\n| Smart match | `POST /plans/recommend` | <100ms | Top 12 matches |\n| Custom program | `POST /plans/generate` | 5-8s | Unique plan |\n\n**Note:** Generated plans are NOT included in this list - use `GET /v1/plans/{id}` with stored ID.\n\n---\n\n### 🎯 Organization Context\n\n| Aspect | Organization Plans | Public Plans |\n|--------|-------------------|--------------|\n| **Content** | Your branded programs | Global library |\n| **Customization** | Team-specific goals | Generic fitness |\n| **Branding** | Your trainers/style | Mixed sources |\n| **Access Control** | Organization members | Public access |\n\n---\n\n### πŸ“‹ Use Cases\n\nβœ… **White-label Apps** - Show only your organization's content \nβœ… **Corporate Wellness** - Company-specific fitness programs \nβœ… **Trainer Platforms** - Personal trainer's program library \nβœ… **Gym Management** - Facility-specific training plans\n\n---\n\n### πŸ” Filtering & Pagination\n\n**Visibility Filtering:**\n- `private` - Organization-only content (requires ownership)\n- `public` - Publicly accessible plans\n- `all` - Both private and public (default)\n\n**Additional Filters:**\n- `difficulties` - Filter by difficulty levels (comma-separated: beginner,intermediate,advanced)\n- `goalIds` - Filter by goal IDs (comma-separated)\n- `durationInWeeks` - Filter by program duration (e.g., ?durationInWeeks=8)\n- `workoutsPerWeek` - Filter by weekly frequency (e.g., ?workoutsPerWeek=3)\n- `q` - Search by plan name or description\n\n**Pagination:**\n- `offset` - Number of items to skip (default: 0)\n- `limit` - Items per page (default: 20, max: 50)\n- `sort` - Sort by: createdAt, updatedAt, name, difficulty, durationInWeeks, workoutsPerWeek\n- Prefer following `links.next` from the response over computing offsets manually.\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Cache responses** - Plans change infrequently \nβœ… **Filter by visibility** - Use `public` for end-user apps, `all` for management \nβœ… **Implement search** - Use `q` parameter for name/description filtering \nβœ… **Handle empty results** - Graceful fallback to public plans\n\n---\n\n### πŸ”— Related Endpoints\n\n- Generate Plan: `POST /v1/orgs/{orgId}/plans/generate` - Create new plan\n- Plan Details: `GET /v1/plans/{id}` - Get individual plan\n- Plan Metadata: `GET /v1/plans/metadata` - Get goals and difficulties\n- Recommend Plans: `POST /v1/orgs/{orgId}/plans/recommend` - Smart suggestions\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"64f1a2b3c4d5e6f7a8b9c0d1","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of items to return per page.","example":20,"schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search text","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Fields to sort. Prefix them with - (descending) or + (ascending): +someField,-otherField","schema":{"type":"string"}},{"name":"locale","required":false,"in":"query","description":"BCP-47 locale (e.g. en-US, fr-FR). Localizes text and locale-aware media when this operation supports it. Falls back to English when unsupported.","example":"en-US","schema":{"type":"string"}},{"name":"visibility","required":false,"in":"query","description":"Filter plans by their visibility status.","example":"public","schema":{"enum":["private","public","all"],"type":"string"}},{"name":"difficulty","required":false,"in":"query","description":"Filter plans by difficulty level (single value). DEPRECATED: Use 'difficulties' for multiple values.","example":"intermediate","deprecated":true,"schema":{"enum":["beginner","intermediate","advanced"],"type":"string"}},{"name":"difficulties","required":false,"in":"query","description":"Filter plans by one or more difficulty levels (comma-separated). Preferred over 'difficulty'.","example":"beginner,intermediate","schema":{"type":"string"}},{"name":"goalIds","required":false,"in":"query","description":"Filter plans by one or more goal IDs (provide comma-separated values if multiple).","example":"64f1a2b3c4d5e6f7a8b9c0d3,64f1a2b3c4d5e6f7a8b9c0d7","schema":{"type":"string"}},{"name":"durationInWeeks","required":false,"in":"query","description":"Filter plans by duration in weeks (1-24)","example":8,"schema":{"minimum":1,"maximum":24,"type":"number"}},{"name":"workoutsPerWeek","required":false,"in":"query","description":"Filter plans by workouts per week (1-7)","example":3,"schema":{"minimum":1,"maximum":7,"type":"number"}}],"responses":{"200":{"description":"Successfully retrieved paginated list of plans for the organization.","schema":{"example":{"data":[{"id":"64f1a2b3c4d5e6f7a8b9c0d2","name":"8-Week Strength Program","description":"A comprehensive strength building program designed for intermediate fitness levels","difficulty":"intermediate","visibility":"public","durationInWeeks":8,"workoutsPerWeek":3,"createdAt":"2023-10-26T10:00:00.000Z","updatedAt":"2023-10-27T11:30:00.000Z","trainer":{"id":"64f1a2b3c4d5e6f7a8b9c0d4","name":"Sarah Johnson"},"goals":[{"id":"64f1a2b3c4d5e6f7a8b9c0d3","name":"Build Strength","nameTranslations":{}}],"preview":{"url":"https://stream.hyperhuman.cc/plan-preview.m3u8","poster":"https://images.hyperhuman.cc/plan-poster.jpg","thumbnail":"https://images.hyperhuman.cc/plan-thumb.jpg"}},{"id":"64f1a2b3c4d5e6f7a8b9c0d5","name":"12-Week Transformation Program","description":"An intensive 12-week program for advanced fitness levels","difficulty":"advanced","visibility":"public","durationInWeeks":12,"workoutsPerWeek":4,"createdAt":"2023-10-26T10:00:00.000Z","updatedAt":"2023-10-27T11:30:00.000Z","trainer":{"id":"64f1a2b3c4d5e6f7a8b9c0d8","name":"Mike Chen"},"goals":[{"id":"64f1a2b3c4d5e6f7a8b9c0d6","name":"Weight Loss","nameTranslations":{}},{"id":"64f1a2b3c4d5e6f7a8b9c0d7","name":"Build Muscle","nameTranslations":{}}],"preview":{"url":"https://stream.hyperhuman.cc/transformation-preview.m3u8","poster":"https://images.hyperhuman.cc/transformation-poster.jpg","thumbnail":"https://images.hyperhuman.cc/transformation-thumb.jpg"}}],"links":{"next":"https://content.api.hyperhuman.cc/v1/orgs/63415bf67a9c7000126616c1/plans?offset=20&limit=20","total":45}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanListResponse"}}}},"400":{"description":"Invalid pagination or filter parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified organization ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["plans"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//plans' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationPlans() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//plans', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//plans\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/plans/recommend":{"post":{"operationId":"OrganizationPlanRecommendation_getPlanRecommendations","summary":"Get training plan recommendations from existing library","description":"\n## Smart Matching to Existing Training Programs\n\nReturns ranked multi-week plan suggestions from your organization's library based on user profile analysis.\n\n---\n\n### πŸ”„ Choose Your Endpoint\n\n| Need | Use | Speed | Result |\n|------|-----|-------|--------|\n| Browse library | `GET /orgs/{id}/plans` | <50ms | Filtered list |\n| Smart match | `POST /plans/recommend` | <100ms | Top 12 matches |\n| Custom program | `POST /plans/generate` | 5-8s | Unique plan |\n\n---\n\n### 🎯 Recommendations vs. Generation\n\n| Aspect | **Recommendations** (This Endpoint) | **Generation** (`/generate`) |\n|--------|-------------------------------------|-------------------------------|\n| **Speed** | Instant (<100ms) | 3-8 seconds |\n| **Content** | Existing plan library | New, unique programs |\n| **Customization** | Matches to closest fit | Exact specifications |\n| **Use Case** | Browse existing programs | Build custom programs |\n| **Requires** | Pre-built plan library | Just metadata IDs |\n\n---\n\n### πŸ“‹ When to Use Recommendations\n\nβœ… **Quick discovery** - Show plan options immediately \nβœ… **Curated programs** - You have expertly designed plans \nβœ… **Consistency** - Multiple users follow same plan \nβœ… **Track analytics** - See which plans are popular\n\n---\n\n### πŸ“‹ When to Use Generation\n\nβœ… **Unique programs** - Every plan is personalized \nβœ… **Specific goals** - Exact duration, frequency, progression \nβœ… **No library** - You don't have pre-built plans \nβœ… **Dynamic content** - New plans every request\n\n---\n\n### πŸ” How Matching Works\n\n1. **Analyzes** user profile (age, fitness level, goals, training frequency)\n2. **Scores** each plan in your library (0.0 - 1.0)\n3. **Ranks** by match score\n4. **Returns** top 12 with match reasons\n\n**Match Factors:**\n- Goal alignment (40% weight)\n- Fitness level match (30% weight)\n- Training frequency compatibility (20% weight)\n- Age appropriateness (10% weight)\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### πŸ”— Related Endpoints\n\n- Generate Plan: `POST /v1/orgs/{orgId}/plans/generate`\n- List Plans: `GET /v1/orgs/{orgId}/plans`\n- Plan Metadata: `GET /v1/plans/metadata`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"Organization/Team unique identifier","example":"67e2e9d0e23f010013e19dec","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanRecommendationRequestDto"}}}},"responses":{"200":{"description":"Ranked list of recommended training plans with match scores and reasons","schema":{"example":{"plans":[{"id":"507f1f77bcf86cd799439017","name":"8-Week Strength Building Program","description":"Progressive strength program with balanced muscle group distribution","difficulty":"intermediate","thumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/plans/507f1f77bcf86cd799439017/thumbnail.jpg","recommendation":"Perfect match for your strength goals and intermediate fitness level","goals":[{"id":"63c92926f920a9005c4e619d","name":"Build Strength"}],"preview":{"url":"https://example.com/plan-preview.m3u8","poster":"https://hhcontent.s3.eu-central-1.amazonaws.com/plans/507f1f77bcf86cd799439017/thumbnail.jpg","thumbnail":"https://hhcontent.s3.eu-central-1.amazonaws.com/plans/507f1f77bcf86cd799439017/thumbnail.jpg"}},{"id":"507f1f77bcf86cd799439018","name":"12-Week Transformation Program","description":"Comprehensive program combining strength and cardio for complete transformation","difficulty":"intermediate","thumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/plans/507f1f77bcf86cd799439018/thumbnail.jpg","recommendation":"Matches your goals and training frequency preferences","goals":[{"id":"63c92926f920a9005c4e619c","name":"Lose Weight"},{"id":"63c92926f920a9005c4e61a0","name":"Get Toned"}]},{"id":"507f1f77bcf86cd799439019","name":"6-Week Beginner Foundation","description":"Structured program for building fitness fundamentals","difficulty":"beginner","thumbnailUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/plans/507f1f77bcf86cd799439019/thumbnail.jpg","recommendation":"Ideal starting point for building a consistent training habit","goals":[{"id":"63c92926f920a9005c4e619e","name":"Improve Endurance"}]}],"reasoning":"Plans recommended based on your profile and preferences. Top matches align with your fitness goals, current fitness level, and training frequency. The recommendations prioritize programs that match your objectives while considering your training schedule and capabilities."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanRecommendationResponseDto"}}}},"400":{"description":"Bad Request - Invalid input data"},"401":{"description":"Unauthorized - Invalid API key"},"404":{"description":"Organization/Team not found"}},"tags":["ai-recommendation"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//plans/recommend' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getPlanRecommendations() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//plans/recommend', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//plans/recommend\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/plans/generate":{"post":{"operationId":"OrganizationPlanGeneration_generatePlan","summary":"Generate personalized training programs based on user profile details, duration preferences, and workout collection sources.","description":"\n## Generate Multi-Week Training Programs\n\nCreate AI-powered, personalized training plans with progressive workout structures.\n\n---\n\n### ⚠️ CRITICAL: Store the Returned Plan ID\n\nGenerated plans are **NOT** included in `GET /v1/orgs/{orgId}/plans` responses.\n\n**You MUST store the returned `id` in your database:**\n```javascript\nconst response = await fetch('/v1/orgs/{orgId}/plans/generate', {...});\nconst planId = response.id; // Store this in your database\nawait db.userPlans.create({ userId, planId });\n\n// Later retrieve: GET /v1/plans/{planId}\n```\n\n**Retrieval Pattern:**\n- Generated plans: `GET /v1/plans/{id}` with stored ID\n- Organization library: `GET /v1/orgs/{orgId}/plans`\n\n---\n\n### πŸ”„ Choose Your Endpoint\n\n| Need | Use | Speed | Result |\n|------|-----|-------|--------|\n| Browse library | `GET /orgs/{id}/plans` | <50ms | Filtered list |\n| Smart match | `POST /plans/recommend` | <100ms | Top 12 matches |\n| Custom program | `POST /plans/generate` | 5-8s | Unique plan |\n\n---\n\n### πŸ“‹ Quick Start\n\n1. **Fetch Metadata**: `GET /v1/plans/metadata` β†’ Get goal IDs and difficulties\n2. **Generate Program**: `POST /v1/orgs/{orgId}/plans/generate` β†’ **This endpoint**\n3. **Store Plan ID**: Save the returned `id` to your database/system\n4. **Retrieve Plan**: `GET /v1/plans/{id}` β†’ Use stored ID to access full details\n5. **Get Workouts**: `GET /v1/plans/{id}/workouts` β†’ Get workouts in program\n\n---\n\n### 🎯 Program Structure\n\n- **Duration**: 4-52 weeks of structured training\n- **Frequency**: 1-7 workouts per week\n- **Progressive**: Automatic intensity and volume progression\n- **Balanced**: Muscle group distribution across training cycle\n- **Complete**: Full workout details with exercises, sets, reps\n\n---\n\n### πŸ“¦ Workout Collection Sources\n\n| Source | Description | Use Case |\n|--------|-------------|----------|\n| `template` | Curated platform workout collections | **Recommended for variety** |\n| `team` | Your organization's custom workout collections | Brand consistency |\n\n**Default**: Uses both if omitted\n\n---\n\n### πŸ’‘ AI Personalization\n\n- **Goal Alignment**: Structures program based on fitness goals\n- **Difficulty Matching**: Adjusts complexity to user fitness level\n- **Age/Gender Adaptation**: Considers user demographics\n- **Duration Optimization**: Selects ideal program length within your range\n\n**Advanced Options:**\n- `userRequirements`: High-level context and guidelines for customer-specific training methodologies and program structure (e.g., \"Critical: select and use only workouts that are named and contain the word 'minimal'\", \"Progressive overload with 3-week cycles\"). Overrides default AI selection and structure behavior. Max 2000 characters.\n\n---\n\n### 🎯 What's Generated\n\n- **Duration**: 4-52 weeks of structured training\n- **Frequency**: 1-7 workouts per week\n- **Personalized**: Matched to age, fitness level, goals, equipment\n- **Progressive**: Automatic intensity progression across weeks\n- **Complete**: Full workout details with exercises\n\n**Duration Logic:**\n- Both min/max provided β†’ AI selects optimal in range\n- Only one value β†’ Uses as target\n- None β†’ Defaults to 8 weeks\n\n**User Profile:**\n- Age β†’ Appropriate intensity (16-24 Young, 25-34 Young Adult, 35-44 Early Middle Age, 45-54 Mid Life, 55-64 Late Middle Age, 65-74 Early Senior, 75+ Senior)\n- Fitness level β†’ Uses first level if multiple provided\n- Goals β†’ Structures program around objectives\n- Training days/week β†’ Determines frequency and volume\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### πŸ”— Related Endpoints\n\n- **Metadata**: `GET /v1/plans/metadata` - Get goal IDs and difficulties\n- **Metadata**: `GET /v1/workouts/equipment/metadata` - Get equipment category IDs\n- **Retrieve**: `GET /v1/plans/{id}` - Get generated plan details\n- **List**: `GET /v1/orgs/{orgId}/plans` - Browse organization library\n- **Recommend**: `POST /v1/orgs/{orgId}/plans/recommend` - Smart suggestions (faster)\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"67e2e9d0e23f010013e19dec","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Plan generation request with user profile and preferences.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGenerationRequestDto"},"examples":{"beginner-weight-loss-4weeks":{"summary":"Beginner Weight Loss - 4 Weeks","description":"Beginner program focused on weight loss with 3 workouts per week","value":{"endUserProfileDetails":{"age":28,"gender":"female","fitnessLevels":["beginner"],"goalIds":["63c92926f920a9005c4e619c"],"trainingDaysPerWeek":3},"workoutCollectionSources":["template"],"durationOptions":{"minWeeks":4,"maxWeeks":4},"workoutsPerWeek":3,"difficulty":"beginner"}},"advanced-strength-8weeks":{"summary":"Advanced Strength Building - 8 Weeks","description":"Advanced strength program with 5 workouts per week and equipment preferences","value":{"endUserProfileDetails":{"age":35,"gender":"male","fitnessLevels":["advanced"],"goalIds":["63c92926f920a9005c4e619d","63c92926f920a9005c4e61a0"],"trainingDaysPerWeek":5,"preferredEquipmentCategoryIds":["67deb3696a5e49797c122f55","67deb36a6a5e49797c122f56"]},"workoutCollectionSources":["template","team"],"durationOptions":{"minWeeks":6,"maxWeeks":8},"workoutsPerWeek":5,"difficulty":"advanced","userRequirements":"Progressive overload with 3-week cycles. Include deload weeks every 4th week. Focus on compound movements and strength progression."}},"intermediate-endurance-flexible":{"summary":"Intermediate Endurance - Flexible Duration","description":"Endurance-focused program with AI-selected optimal duration","value":{"endUserProfileDetails":{"age":42,"gender":"female","fitnessLevels":["intermediate"],"goalIds":["63c92926f920a9005c4e619e"],"trainingDaysPerWeek":4},"workoutCollectionSources":["template"],"durationOptions":{"minWeeks":8,"maxWeeks":12},"workoutsPerWeek":4,"difficulty":"intermediate"}},"custom-team-plan":{"summary":"Custom Team Workout Plan","description":"Use organization's workout collections for brand consistency","value":{"endUserProfileDetails":{"age":30,"fitnessLevels":["intermediate"],"trainingDaysPerWeek":4},"workoutCollectionSources":["team"],"durationOptions":{"minWeeks":8,"maxWeeks":12},"workoutsPerWeek":4}},"complete-all-parameters":{"summary":"Complete Example - All Parameters","description":"Real-world example with ALL available parameters filled out","value":{"endUserProfileDetails":{"age":32,"gender":"male","fitnessLevels":["intermediate"],"goalIds":["63c92926f920a9005c4e619c"],"trainingDaysPerWeek":4,"preferredEquipmentCategoryIds":["67deb36a6a5e49797c122f56","67deb3696a5e49797c122f55"],"endUserId":"64e3bca9d1b7e600141a9712"},"goalIds":["63c92926f920a9005c4e619d"],"difficulty":"intermediate","workoutsPerWeek":4,"workoutCollectionSources":["template","team"],"durationOptions":{"minWeeks":6,"maxWeeks":10},"userRequirements":"Progressive overload with 3-week cycles. Include deload weeks every 4th week. Focus on unilateral movements for balance. Critical: select and use only workouts that are named and contain the word \"minimal\"."}}}}}},"responses":{"200":{"description":"Successfully generated training program with progressive workout structure.","schema":{"example":{"id":"507f1f77bcf86cd799439017","name":"8-Week Strength Building Program","description":"Progressive strength program with balanced muscle group distribution","difficulty":"intermediate","goalIds":["63c92926f920a9005c4e619d"],"durationInWeeks":8,"workoutsPerWeek":3,"workouts":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","name":"Upper Body Strength","duration":2700,"difficulty":"intermediate","description":"Focus on chest, back, and arms"},{"id":"64f1a2b3c4d5e6f7a8b9c0d2","name":"Lower Body Power","duration":2400,"difficulty":"intermediate","description":"Legs, glutes, and core emphasis"},{"id":"64f1a2b3c4d5e6f7a8b9c0d3","name":"Full Body Conditioning","duration":3000,"difficulty":"intermediate","description":"Complete body workout with cardio elements"}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGenerationResponseDto"}}}},"400":{"description":"Bad Request - Invalid input parameters."},"401":{"description":"Unauthorized - Invalid API key."},"403":{"description":"Forbidden - API key required or insufficient permissions."},"404":{"description":"Not Found - Organization or other resources not found."},"500":{"description":"Internal Server Error - Failed to generate program."}},"tags":["ai-generation"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//plans/generate' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function generatePlan() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//plans/generate', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//plans/generate\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/plans/{planId}/adapt":{"post":{"operationId":"OrganizationPlanAdaptation_adaptPlan","summary":"Adapt an existing program based on user profile and data","description":"\n## Program Adaptation\n\nPersonalizes an existing training program by modifying the workout schedule based on:\n- User profile (age, fitness level, goals, equipment)\n- Last 60 days of wearable health data (body/sleep/physical scores)\n- Workout feedback and session history\n- User-provided guidance and constraints\n\n---\n\n### Key Behaviors\n\n| Scenario | Behavior |\n|----------|----------|\n| **Team-owned program** | Creates a personal copy, original unchanged |\n| **User-generated program** | Updates in place |\n| **Completed workouts** | Never modified, only future workouts adapted |\n\n---\n\n### What Gets Adapted\n\n- **Add workouts**: Insert new workouts from library\n- **Remove workouts**: Shorten program or accommodate constraints\n- **Replace workouts**: Substitute with better alternatives\n- **Reshuffle**: Reorder for better progression/recovery\n\n---\n\n### Adaptation Triggers\n\n| Data Source | Impact on Adaptation |\n|-------------|---------------------|\n| **Low sleep scores** | Remove intense workouts, add recovery |\n| **Declining physical scores** | Shorten program, easier alternatives |\n| **\"Too hard\" feedback** | Replace with lower difficulty |\n| **Low completion rate** | Remove workouts to reduce overwhelm |\n| **Injury in userGuidance** | Remove workouts targeting injured area |\n| **Beginner fitness level** | Easier workouts throughout |\n\n---\n\n### Response Details\n\n- `wasDuplicated`: true if program was copied from team program\n- `originalProgramId`: ID of original program if duplicated\n- `workouts[].action`: 'kept', 'replaced', or 'added'\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### Related Endpoints\n\n- Generate Program: `POST /v1/orgs/{orgId}/plans/generate`\n- Recommend Program: `POST /v1/orgs/{orgId}/plans/recommend`\n- Get Program: `GET /v1/plans/{id}`\n- List Programs: `GET /v1/orgs/{orgId}/plans`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"Organization/Team ID","example":"67e2e9d0e23f010013e19dec","schema":{"type":"string"}},{"name":"planId","required":true,"in":"path","description":"Plan ID to adapt","example":"67e2e9d0e23f010013e19def","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Program adaptation request with user profile and preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanAdaptationRequestDto"},"examples":{"basic-adaptation":{"summary":"Basic Adaptation - Intermediate User","description":"Adapt a program for an intermediate fitness level user","value":{"endUserProfileDetails":{"age":32,"gender":"female","fitnessLevels":["intermediate"],"trainingDaysPerWeek":4},"workoutSources":["template","team"]}},"injury-adaptation":{"summary":"Adaptation with Injury Guidance","description":"Adapt a program considering user injury","value":{"endUserProfileId":"64e3bca9d1b7e600141a9712","endUserProfileDetails":{"age":45,"gender":"male","fitnessLevels":["beginner"],"trainingDaysPerWeek":3},"workoutSources":["template"],"userGuidance":"I have a knee injury. Please remove high-impact workouts and focus on low-impact alternatives."}},"full-personalization":{"summary":"Full Personalization with User Data","description":"Adapt using 60-day wearable data and full user profile","value":{"endUserProfileId":"64e3bca9d1b7e600141a9712","endUserProfileDetails":{"age":28,"gender":"female","fitnessLevels":["advanced"],"goalIds":["63c92926f920a9005c4e619c"],"trainingDaysPerWeek":5,"preferredEquipmentCategoryIds":["67deb36a6a5e49797c122f56"]},"workoutSources":["template","team"],"userGuidance":"My sleep has been poor lately. Please reduce intensity and add more recovery-focused workouts."}},"shorten-program":{"summary":"Shorten Program","description":"User wants a shorter version of their program","value":{"endUserProfileDetails":{"age":35,"gender":"male","fitnessLevels":["intermediate"],"trainingDaysPerWeek":3},"workoutSources":["team"],"userGuidance":"I only have time for 3 workouts per week now instead of 5. Please remove workouts to fit my schedule."}}}}}},"responses":{"200":{"description":"Adapted program with personalized workout modifications","schema":{"example":{"id":"507f1f77bcf86cd799439020","name":"Adapted: 8-Week Strength Building Program","description":"Personalized strength program adapted for your fitness level and schedule","difficulty":"intermediate","durationInWeeks":8,"workoutsPerWeek":3,"totalWorkouts":24,"wasDuplicated":true,"originalProgramId":"507f1f77bcf86cd799439017","adaptationReasoning":"Program adapted to match your intermediate fitness level and 3-day training schedule. Removed 2 high-intensity workouts per week to accommodate recovery needs based on your sleep data. Replaced 3 advanced workouts with intermediate alternatives. Added 2 recovery-focused sessions to support your training progression.","workouts":[{"id":"64f1a2b3c4d5e6f7a8b9c0d1","name":"Upper Body Strength","duration":2700,"difficulty":"intermediate","description":"Focus on chest, back, and arms","position":0,"action":"kept"},{"id":"64f1a2b3c4d5e6f7a8b9c0d2","name":"Lower Body Power","duration":2400,"difficulty":"intermediate","description":"Legs, glutes, and core emphasis","position":1,"action":"kept"},{"id":"64f1a2b3c4d5e6f7a8b9c0d3","name":"Full Body Conditioning - Adapted","duration":3000,"difficulty":"intermediate","description":"Complete body workout with reduced intensity","position":2,"action":"replaced"},{"id":"64f1a2b3c4d5e6f7a8b9c0d4","name":"Recovery & Mobility","duration":1800,"difficulty":"beginner","description":"Gentle recovery session for active rest","position":3,"action":"added"}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanAdaptationResponseDto"}}}},"400":{"description":"Invalid request or program not found"},"401":{"description":"Unauthorized - Invalid API key"},"403":{"description":"Forbidden - Cannot adapt programs from other organizations"},"404":{"description":"Program or organization not found"}},"tags":["ai-adaptation"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//plans//adapt' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function adaptPlan() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//plans//adapt', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//plans//adapt\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/metadata":{"get":{"operationId":"OrganizationMetadataApi_getOrganizationMetadata","summary":"Get organization metadata","description":"\n## Organization Branding & Configuration\n\nRetrieves your organization's public metadata including branding, configuration, and client joining settings.\n\n---\n\n### What's Included\n\n**Branding:**\n- `name`, `handle`, `description`, `website`\n- `logoUrl` β€” single pre-derived 320x320 PNG variant served from CDN. There are no other size variants exposed today; resize client-side if you need smaller.\n- `watermarkUrl` β€” single pre-derived 320x320 PNG variant. Square, transparent background. Used in the embedded player and in rendered video exports.\n- `brandMainColor`, `brandSecondaryColor`, `brandTextColor` (hex strings). Any of these may be `null` if the org has not configured them.\n\n**Configuration:**\n- `clientsJoinSetting` β€” `OPEN` | `INVITE_ONLY` | `SUBSCRIPTION_REQUIRED`. For full join-flow context (e.g. paid join, available subscription products), call `GET /v1/orgs/{orgId}/join-options` instead.\n\n**Module Status (booleans, always present):**\n- `hasAssenseiModuleActive` β€” Asensei Assessment add-on (real-time AI form analysis on supported exercises). When `false`, AI assessment endpoints will not produce data for this org's content.\n- `hasWearableModuleActive` β€” ROOK Wearables add-on (Apple Health / Garmin / Fitbit / Oura sync). When `false`, end-user insights pillars that depend on wearables fall back to workout-derived data.\n- `hasWhiteLabelAppActive` β€” Org has a paid white-label consumer app build. Use this to gate \"open in app\" deeplinks and white-label-only UI.\n\n**Identifiers:**\n- `id` β€” pass to every `/v1/orgs/{organizationId}/...` endpoint.\n- `handle` β€” URL-friendly slug, may be `null`.\n\n---\n\n### Common Use Cases\n\n- **White-label mobile apps** - Fetch branding on app launch and on org switch.\n- **Custom web portals** - Apply organization colors/logo at the document root.\n- **Multi-tenant platforms** - Resolve organization context once per session.\n- **Onboarding flows** - Combine with `/join-options` to render the right CTA.\n\n---\n\n### Best Practices\n\n- **Cache metadata** - Treat as essentially-static. Refresh daily or on app restart; a 5-minute in-memory cache is also fine.\n- **Fallback colors** - Always have hard-coded fallbacks; any of the brand color fields may be `null`.\n- **Logo size** - Logo and watermark are served at a fixed 320x320 resolution; downscale in the client if you need smaller.\n- **Module gates** - Drive UI off the `has*ModuleActive` flags rather than trying to infer from feature responses.\n\n---\n\n### πŸ”— Related Endpoints\n\n- Join Options: `GET /v1/orgs/{orgId}/join-options`\n- Generate Workout: `POST /v1/orgs/{orgId}/workouts/generate`\n- List Workouts: `GET /v1/orgs/{orgId}/workouts`\n- List Plans: `GET /v1/orgs/{orgId}/plans`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved organization metadata with complete branding information.","schema":{"example":{"id":"63415bf67a9c7000126616c1","name":"DEMO - Brave Fitness Team","handle":"bravefitnessdemo","logoUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/t/63415bf67a9c7000126616c1/logo/i/logo-320x320.png","watermarkUrl":"https://hhcontent.s3.eu-central-1.amazonaws.com/t/63415bf67a9c7000126616c1/watermark/i/watermark-320x320.png","description":"This is a demo account for showcasing Hyperhuman's AI-powered video production platform made for the health & fitness industry.","website":"https://bogdanpred.wixsite.com/bravefitnessdemo","brandMainColor":"#eeeb3c","brandSecondaryColor":"#F3F8F8","brandTextColor":"#ffffff","clientsJoinSetting":"OPEN","hasAssenseiModuleActive":false,"hasWearableModuleActive":true,"hasWhiteLabelAppActive":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationMetadataResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified organization ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["organization"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//metadata' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationMetadata() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//metadata', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//metadata\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/join-options":{"get":{"operationId":"OrganizationJoinOptionsApi_getOrganizationJoinOptions","summary":"Get organization join options","description":"\n## User Onboarding Configuration\n\nRetrieves information about how users can join your organization, including join settings, subscription requirements, and available plans.\n\n---\n\n### πŸ“‹ What's Included\n\n**Join Settings:**\n- `clientsJoinSetting`: OPEN, INVITE_ONLY, or SUBSCRIPTION_REQUIRED\n- `canJoinDirectly`: Boolean flag for self-signup\n- `inviteOnlyMode`: Requires invitation to join\n- `requiresSubscription`: Payment required to access\n\n**Free Plans:**\n- `hasFreePlanWithAutoJoin`: Free access available\n- `freeJoinOptions`: List of free plans with auto-enrollment\n- `totalProductsAvailable`: Count of subscription products\n\n---\n\n### 🎯 Join Settings Explained\n\n| Setting | Description | User Flow |\n|---------|-------------|-----------|\n| **OPEN** | Anyone can join | Self-signup enabled |\n| **INVITE_ONLY** | Requires invitation | Admin must invite |\n| **SUBSCRIPTION_REQUIRED** | Payment required to join | User subscribes for access |\n\n---\n\n### πŸ’‘ Integration Patterns\n\n**Self-Signup Flow (OPEN):**\n```\n1. GET /v1/orgs/{orgId}/join-options β†’ Check if open\n2. POST /v1/orgs/{orgId}/endusers/invite β†’ Create user\n3. User receives email/access\n```\n\n**Invitation Flow (INVITE_ONLY):**\n```\n1. Admin invites via dashboard or API\n2. User receives invitation\n3. User accepts and creates account\n```\n\n**Subscription Required:**\n```\n1. GET /v1/orgs/{orgId}/join-options β†’ Check products\n2. Display subscription options to user\n3. User subscribes β†’ Access granted\n```\n\n---\n\n### πŸ”— Related Endpoints\n\n- Organization Metadata: `GET /v1/orgs/{orgId}/metadata`\n- Invite Users: `POST /v1/orgs/{orgId}/endusers/invite`\n- Paywall Products: `GET /v1/orgs/{orgId}/paywall/products`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved organization join options and configuration.","schema":{"example":{"clientsJoinSetting":"OPEN","canJoinDirectly":true,"requiresSubscription":false,"inviteOnlyMode":false,"hasFreePlanWithAutoJoin":false,"freeJoinOptions":[],"totalProductsAvailable":0}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationJoinOptionsResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified organization ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["organization"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//join-options' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationJoinOptions() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//join-options', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//join-options\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/plans/active/progress":{"get":{"operationId":"OrganizationEndUserPlansApi_getActivePlanProgress","summary":"Get plan progress for an end user","description":"\n## Plan progress\n\nReturns per-workout progress for the end user's active plan. Keys are position indices (as strings); values include completed, latestCompletionDate, workoutName, difficulty, duration, categories, workoutId, positionInPlan.\n\nWhen the end user has no active plan, the endpoint responds with `200 OK` and `{ \"data\": null }` (rather than 404), so callers can render a \"no active plan\" state without treating it as an error.\n\n---\n\n### Related endpoints\n\n- `GET .../plans/active` - Get active plan details\n- `POST .../plans/start` - Start a plan\n- `POST .../plans/{planId}/end` - End active plan\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The organization id (24-character hex string).","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"endUserId","required":true,"in":"path","description":"The user identifier. Can be email, externalUUID, or internal user ID.","example":"john.doe@acme.com","schema":{"type":"string"}}],"responses":{"200":{"description":"Plan progress for the end user, or `data: null` when there is no active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanProgressResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-plans"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/active/progress' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getActivePlanProgress() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/active/progress', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/active/progress\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/plans/active":{"get":{"operationId":"OrganizationEndUserPlansApi_getActivePlan","summary":"Get active plan for an end user","description":"\n## Active plan\n\nReturns the end user's active workout plan if any, with schedule (workoutsPerWeek, durationInWeeks, currentWeekNumber, daysSinceStart, completedWorkouts, totalWorkouts, completionPercentage).\n\n---\n\n### Related endpoints\n\n- `GET .../plans/active/progress` - Get per-workout progress\n- `POST .../plans/start` - Start a plan\n- `POST .../plans/{planId}/end` - End active plan\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The organization id (24-character hex string).","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"endUserId","required":true,"in":"path","description":"The user identifier. Can be email, externalUUID, or internal user ID.","example":"john.doe@acme.com","schema":{"type":"string"}}],"responses":{"200":{"description":"Active plan or null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivePlanResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-plans"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/active' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getActivePlan() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/active', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/active\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/plans/start":{"post":{"operationId":"OrganizationEndUserPlansApi_startPlan","summary":"Start a plan for an end user","description":"\n## Start plan\n\nStarts the given plan as the end user's active plan. Any existing active plan is deactivated.\n\n---\n\n### Related endpoints\n\n- `GET .../plans/active` - Get active plan details\n- `GET .../plans/active/progress` - Get plan progress\n- `POST .../plans/{planId}/end` - End active plan\n- `GET /v1/plans/{id}` - Plan catalog details\n- `GET /v1/plans/{id}/workouts` - Workouts in plan\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The organization id (24-character hex string).","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"endUserId","required":true,"in":"path","description":"The user identifier. Can be email, externalUUID, or internal user ID.","example":"john.doe@acme.com","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Plan ID to start as the active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartPlanBody"}}}},"responses":{"200":{"description":"Plan access record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-plans"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/start' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function startPlan() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/start', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//endusers//plans/start\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/plans/{planId}/end":{"post":{"operationId":"OrganizationEndUserPlansApi_endPlan","summary":"End an active plan for an end user","description":"\n## End plan\n\nEnds the specified plan for the end user. The plan must be the user's current active plan. Returns 404 if no active plan matches the given planId.\n\n---\n\n### Related endpoints\n\n- `GET .../plans/active` - Get active plan details\n- `GET .../plans/active/progress` - Get plan progress\n- `POST .../plans/start` - Start a plan\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The organization id (24-character hex string).","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"endUserId","required":true,"in":"path","description":"The user identifier. Can be email, externalUUID, or internal user ID.","example":"john.doe@acme.com","schema":{"type":"string"}},{"name":"planId","required":true,"in":"path","description":"The plan ID to end.","example":"60f1b3b3b3b3b3b3b3b3b3b3","schema":{"type":"string"}}],"responses":{"200":{"description":"Updated plan access record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanResponseDto"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-plans"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//endusers//plans//end' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function endPlan() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers//plans//end', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\"https://content.api.hyperhuman.cc/v1/orgs//endusers//plans//end\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers":{"get":{"operationId":"OrganizationEndUsersApi_getOrganizationEndUsers","summary":"Get organization end users","description":"Retrieves a paginated list of end users associated with the organization.\n\n`endUserId` is present only when the API key is for this organization and the end user has an active (non-suspended) team membership.\n\n### Pagination\nUse the standard `offset`/`limit` cursors. The response contains the canonical `links` envelope:\n- `links.next` β€” fully qualified URL for the next page (omitted on the last page)\n- `links.total` β€” total number of matching end users\n\nThe top-level `total` field is **deprecated** and kept only for backwards compatibility; new integrations should read `links.total` instead.","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier (UUID) of the organization.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}},{"name":"offset","required":false,"in":"query","description":"Offset for pagination. Defaults to 0.","schema":{"default":0,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page. Defaults to 20, Max 100.","schema":{"default":20,"type":"number"}},{"name":"status","required":false,"in":"query","description":"Filter clients by status: \"active\", \"suspended\", or \"all\"","schema":{"enum":["active","suspended","all"],"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort clients by \"name\", \"status\", or \"joined\" (default)","schema":{"enum":["name","status","joined"],"type":"string"}},{"name":"sortDirection","required":false,"in":"query","description":"Sort direction: \"asc\" (default) or \"desc\"","schema":{"enum":["asc","desc"],"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved list of end users for the organization.","schema":{"example":{"data":[{"email":"john.doe@acme.com","externalUUID":"ext-user-12345","firstName":"John","lastName":"Doe","status":"active","joinedDate":"2025-09-15T10:30:00Z","endUserId":"507f1f77bcf86cd799439011"},{"email":"jane.smith@acme.com","externalUUID":"ext-user-67890","firstName":"Jane","lastName":"Smith","status":"suspended","joinedDate":"2025-09-20T14:20:00Z"}],"links":{"next":"https://api.hyperhuman.club/v1/orgs/12ab3efd45c67c1234566cd1/endusers?limit=20&offset=20","total":142},"total":142}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUserProfileListResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The API key is not associated with the requested organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"The specified organization ID does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-management"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//endusers' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationEndUsers() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//endusers\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]},"delete":{"operationId":"OrganizationEndUsersApi_removeEndUser","summary":"Remove end user from organization","description":"\n## Permanently Remove User\n\nCompletely removes a user from your organization. This action is **irreversible** and will:\n\n- Delete all user data and progress\n- Remove access to organization content\n- Clear workout history and sessions\n- Cannot be undone\n\n---\n\n### ⚠️ Important Considerations\n\n**Before Removing:**\n- User will lose all progress and data\n- Consider suspending instead for temporary access removal\n- Backup any important user data first\n- Notify user if required by your policies\n\n**Use Cases:**\n- GDPR compliance (right to be forgotten)\n- Account closure requests\n- Data cleanup and maintenance\n- User requested permanent deletion\n\n---\n\n### πŸ”„ Alternative Actions\n\n**Temporary Removal:**\n- `PUT /v1/orgs/{orgId}/endusers/suspend` - Temporarily disable access\n- User data preserved, can be reactivated later\n- Better for temporary access issues\n\n**Permanent Removal:**\n- `DELETE /v1/orgs/{orgId}/endusers` - This endpoint\n- Complete data deletion, cannot be undone\n- Use for final account closure\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Verify user identity** - Double-check email/UUID before deletion \nβœ… **Consider suspension first** - Try suspend before permanent removal \nβœ… **Log deletion events** - Track for audit and compliance \nβœ… **Handle gracefully** - 404 is expected if user already removed \n❌ **Don't delete active users** - Consider suspending instead\n\n---\n\n### πŸ”— Related Endpoints\n\n- Find User: `GET /v1/orgs/{orgId}/endusers/find` - Locate user first\n- Suspend User: `PUT /v1/orgs/{orgId}/endusers/suspend` - Temporary removal\n- Reactivate User: `PUT /v1/orgs/{orgId}/endusers/reactivate` - Restore suspended user\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier (UUID) of the organization.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserIdentifierDto"}}}},"responses":{"200":{"description":"Successfully removed end user from organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The API key is not associated with the requested organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"End user not found in the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-management"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE 'https://content.api.hyperhuman.cc/v1/orgs//endusers' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function removeEndUser() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers', {\n method: 'DELETE',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.delete(\n \"https://content.api.hyperhuman.cc/v1/orgs//endusers\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/invite":{"post":{"operationId":"OrganizationEndUsersApi_inviteEndUsers","summary":"Invite end users to organization","description":"\n## Add Users to Your Organization\n\nSend invitations to one or more end users. Each user receives access to your organization's content and features.\n\n---\n\n### πŸ“‹ Identifier Options\n\n**Email Only:**\n- User invited via email address\n- Hyperhuman creates account on first login\n- Email must be valid and unique\n\n**Email + External UUID:**\n- Map to your existing user system\n- Track users across platforms\n- Sync user data between systems\n- **Recommended for integrations**\n\n---\n\n### 🎯 Typical User Lifecycle\n\n1. **Invite**: `POST /v1/orgs/{orgId}/endusers/invite` β†’ Add users\n2. **Verify**: `GET /v1/orgs/{orgId}/endusers/find?email=...` β†’ Check status\n3. **List**: `GET /v1/orgs/{orgId}/endusers` β†’ View all users\n4. **Manage**: Suspend/reactivate as needed\n5. **Remove**: `DELETE /v1/orgs/{orgId}/endusers` β†’ Permanent deletion\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Batch invitations** - Send up to 100 users at once for efficiency \nβœ… **Use externalUUID** - Map to your user IDs for sync \nβœ… **Validate emails** - Check format before sending \nβœ… **Handle failures** - Review failed array for issues \n❌ **Don't re-invite** - Check if user exists first\n\n---\n\n### πŸ” Error Handling\n\nCommon failure reasons:\n- `User already exists` - Email already in organization\n- `Invalid email format` - Email validation failed\n- `Duplicate in batch` - Same email appears twice\n- `Organization quota exceeded` - User limit reached\n\n---\n\n### πŸ”— Related Endpoints\n\n- Find User: `GET /v1/orgs/{orgId}/endusers/find`\n- List Users: `GET /v1/orgs/{orgId}/endusers`\n- Suspend User: `PUT /v1/orgs/{orgId}/endusers/suspend`\n- Remove User: `DELETE /v1/orgs/{orgId}/endusers`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"List of users to invite with optional external UUID mapping for integration with your user system.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteEndUsersDto"},"examples":{"single-email-only":{"summary":"Single User - Email Only","description":"Invite one user with just an email address","value":{"users":[{"email":"john.doe@acme.com"}]}},"batch-with-external-ids":{"summary":"Batch Invite - With External UUIDs","description":"Invite multiple users and map to your system IDs for synchronization","value":{"users":[{"email":"john.doe@acme.com","externalUUID":"user-12345"},{"email":"jane.smith@acme.com","externalUUID":"user-67890"},{"email":"bob.jones@acme.com","externalUUID":"user-11111"}]}},"large-batch":{"summary":"Large Batch - 10+ Users","description":"Efficiently invite many users at once (up to 100 per request)","value":{"users":[{"email":"user1@acme.com","externalUUID":"ext-user-1001"},{"email":"user2@acme.com","externalUUID":"ext-user-1002"},{"email":"user3@acme.com","externalUUID":"ext-user-1003"},{"email":"user4@acme.com","externalUUID":"ext-user-1004"},{"email":"user5@acme.com","externalUUID":"ext-user-1005"},{"email":"user6@acme.com","externalUUID":"ext-user-1006"},{"email":"user7@acme.com","externalUUID":"ext-user-1007"},{"email":"user8@acme.com","externalUUID":"ext-user-1008"},{"email":"user9@acme.com","externalUUID":"ext-user-1009"},{"email":"user10@acme.com","externalUUID":"ext-user-1010"}]}}}}}},"responses":{"200":{"description":"Invitation processing complete. Returns success count, any failures, and optionally invited with endUserId when the user already has an active team membership.","content":{"application/json":{"schema":{"type":"object","properties":{"successful":{"type":"number","description":"Number of successful invitations sent","example":12},"failed":{"type":"array","description":"List of failed invitations with error reasons","items":{"type":"object","properties":{"email":{"type":"string","example":"invalid@email"},"reason":{"type":"string","example":"Invalid email format"}}},"example":[{"email":"duplicate@acme.com","reason":"User already exists"},{"email":"bad-email","reason":"Invalid email format"}]},"invited":{"type":"array","description":"Successful invites; endUserId present only when the user already has an active team membership.","items":{"type":"object","properties":{"email":{"type":"string"},"endUserId":{"type":"string","description":"Internal user ID; present only for active members."}}}}},"example":{"successful":12,"failed":[{"email":"duplicate@acme.com","reason":"User already exists"}],"invited":[{"email":"user1@acme.com","endUserId":"507f1f77bcf86cd799439011"},{"email":"user2@acme.com"}]}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The API key is not associated with the requested organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-management"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/orgs//endusers/invite' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function inviteEndUsers() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers/invite', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/orgs//endusers/invite\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/suspend":{"put":{"operationId":"OrganizationEndUsersApi_suspendEndUser","summary":"Suspend end user in organization","description":"\n## Temporarily Suspend User Access\n\nSuspends a user's access to your organization content while preserving their data and progress. This is a **reversible action** that:\n\n- Blocks access to workouts and plans\n- Preserves user data and progress\n- Can be reactivated later\n- User cannot log in during suspension\n\n---\n\n### 🎯 When to Suspend\n\n**Temporary Access Issues:**\n- Payment/billing problems\n- Policy violations (temporary)\n- Account security concerns\n- User requested break\n\n**vs. Permanent Removal:**\n- Suspension: Temporary, data preserved\n- Deletion: Permanent, data lost\n- Choose suspension for reversible actions\n\n---\n\n### πŸ”„ User Experience During Suspension\n\n**What Users See:**\n- Cannot access organization content\n- Login blocked with suspension message\n- All data and progress preserved\n- Can be reactivated by admin\n\n**What Admins Can Do:**\n- View suspended users in user list\n- Reactivate anytime with reactivate endpoint\n- See suspension status in user details\n- Track suspension history\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Communicate with user** - Explain why and duration \nβœ… **Set clear policies** - Define suspension criteria \nβœ… **Monitor suspension duration** - Don't leave users suspended indefinitely \nβœ… **Use for temporary issues** - Permanent problems may need deletion \nβœ… **Document reasons** - Track why users were suspended\n\n---\n\n### πŸ”— Related Endpoints\n\n- Find User: `GET /v1/orgs/{orgId}/endusers/find` - Locate user first\n- Reactivate User: `PUT /v1/orgs/{orgId}/endusers/reactivate` - Restore access\n- Remove User: `DELETE /v1/orgs/{orgId}/endusers` - Permanent deletion\n- List Users: `GET /v1/orgs/{orgId}/endusers` - View all users (including suspended)\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier (UUID) of the organization.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserIdentifierDto"}}}},"responses":{"200":{"description":"Successfully suspended end user in organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The API key is not associated with the requested organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"End user not found in the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-management"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PUT 'https://content.api.hyperhuman.cc/v1/orgs//endusers/suspend' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function suspendEndUser() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers/suspend', {\n method: 'PUT',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.put(\n \"https://content.api.hyperhuman.cc/v1/orgs//endusers/suspend\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/reactivate":{"put":{"operationId":"OrganizationEndUsersApi_reactivateEndUser","summary":"Reactivate end user in organization","description":"\n## Restore Suspended User Access\n\nReactivates a previously suspended user, restoring full access to your organization content. This action:\n\n- Restores login access immediately\n- Preserves all user data and progress\n- Returns user to active status\n- Can be done anytime after suspension\n\n---\n\n### 🎯 When to Reactivate\n\n**Common Scenarios:**\n- Payment issues resolved\n- Policy violations addressed\n- Security concerns cleared\n- User requested restoration\n- Administrative error correction\n\n**Prerequisites:**\n- User must be currently suspended\n- Cannot reactivate already active users\n- Cannot reactivate permanently deleted users\n\n---\n\n### πŸ”„ User Experience After Reactivation\n\n**Immediate Access:**\n- User can log in immediately\n- Full access to organization content\n- All previous data and progress intact\n- No data loss from suspension period\n\n**Status Changes:**\n- User status changes from \"suspended\" to \"active\"\n- Appears in active user lists\n- Can participate in workouts and plans\n- Normal user functionality restored\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Verify suspension reason resolved** - Ensure original issue is fixed \nβœ… **Communicate with user** - Notify them of reactivation \nβœ… **Monitor user activity** - Ensure they can access content \nβœ… **Update user records** - Track reactivation for audit \nβœ… **Test user access** - Verify login and content access works\n\n---\n\n### πŸ”— Related Endpoints\n\n- Find User: `GET /v1/orgs/{orgId}/endusers/find` - Check current status\n- Suspend User: `PUT /v1/orgs/{orgId}/endusers/suspend` - Suspend if needed again\n- List Users: `GET /v1/orgs/{orgId}/endusers` - View all users\n- Remove User: `DELETE /v1/orgs/{orgId}/endusers` - Permanent deletion (if needed)\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier (UUID) of the organization.","example":"12ab3efd45c67c1234566cd1","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserIdentifierDto"}}}},"responses":{"200":{"description":"Successfully reactivated end user in organization.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The API key is not associated with the requested organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"End user not found in the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-management"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X PUT 'https://content.api.hyperhuman.cc/v1/orgs//endusers/reactivate' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function reactivateEndUser() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers/reactivate', {\n method: 'PUT',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.put(\n \"https://content.api.hyperhuman.cc/v1/orgs//endusers/reactivate\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/find":{"get":{"operationId":"OrganizationEndUsersApi_getEndUserById","summary":"Find end user by email or external UUID","description":"\n## Find Specific User\n\nRetrieve a single user from your organization by email or external UUID. Useful for checking if a user exists before inviting.\n\n---\n\n### πŸ“‹ Identifier Options\n\n**By Email:**\n```bash\nGET /v1/orgs/{orgId}/endusers/find?email=john.doe@acme.com\n```\n\n**By External UUID:**\n```bash\nGET /v1/orgs/{orgId}/endusers/find?externalUUID=ext-user-12345\n```\n\n**Required:** Must provide either `email` OR `externalUUID` (not both)\n\n---\n\n### 🎯 Use Cases\n\nβœ… **Pre-invite Check** - Verify user doesn't exist before inviting \nβœ… **User Lookup** - Find user details for support queries \nβœ… **Sync Validation** - Confirm external UUID mapping is correct \nβœ… **Duplicate Prevention** - Check before creating user in your system\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Email is case-insensitive** - john@acme.com = John@acme.com \nβœ… **Use external UUID for integrations** - More reliable than email \nβœ… **Handle 404 gracefully** - User not found is an expected case \nβœ… **Cache lookups** - Reduce API calls for frequently accessed users\n\n---\n\n### πŸ”— Related Endpoints\n\n- Invite Users: `POST /v1/orgs/{orgId}/endusers/invite` - Add new users\n- List Users: `GET /v1/orgs/{orgId}/endusers` - Browse all users\n- Suspend User: `PUT /v1/orgs/{orgId}/endusers/suspend` - Deactivate user\n- Remove User: `DELETE /v1/orgs/{orgId}/endusers` - Permanently delete\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"email","required":false,"in":"query","description":"Email address of the user to find (case-insensitive)","example":"john.doe@acme.com","schema":{"type":"string"}},{"name":"externalUUID","required":false,"in":"query","description":"External UUID of the user to find","example":"ext-user-12345","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved end user profile. endUserId is present only when the end user has an active (non-suspended) team membership.","schema":{"example":{"email":"john.doe@acme.com","externalUUID":"ext-user-12345","firstName":"John","lastName":"Doe","status":"active","joinedDate":"2025-09-15T10:30:00Z","endUserId":"507f1f77bcf86cd799439011"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUserProfileDto"}}}},"400":{"description":"Missing required identifier (email or externalUUID).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The API key is not associated with the requested organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"End user not found in the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-management"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//endusers/find' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getEndUserById() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers/find', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//endusers/find\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/insights/digest":{"get":{"operationId":"UserInsightsApi_getUserDailyDigest","summary":"Get daily AI-powered user insights digest","description":"\n## Daily Health & Fitness Digest\n\nReturns a personalized daily digest of insight pillars selected from: `health_pulse`, `training`, `recovery`, `movement`, `nutrition`, `body`. The exact set returned depends on which data sources the user has connected and on the current data completeness β€” typically 3-5 pillars per day.\n\nEach pillar in the digest is intentionally **summary-only**. Coaching signals such as readiness band, recommended intensity, risk triggers, form cue, why-explanations, and alternative actions are surfaced inside the `headline` and `action` strings, but **are not exposed as separate fields on `InsightPillarDto`**. To get the full coaching context for a single pillar, drill into `GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/pillars/{pillarType}`.\n\n---\n\n### Pillars Overview\n\n| Pillar | Description | Primary Data Source |\n|--------|-------------|---------------------|\n| **Health Pulse** | Overall health status and main driver | Rook wearables / workout adherence |\n| **Training** | Workout progress and next session | Workout sessions, AI assessments |\n| **Recovery** | Sleep and recovery readiness | Rook sleep score / workout intensity |\n| **Movement** | Daily activity and cardio | Rook activity / workout frequency |\n| **Nutrition** | Nutrition quality (when available) | Photo logs (coming soon) |\n| **Body** | Body metrics and momentum | Rook body score / workout streak |\n\n---\n\n### Status Indicators\n\n- **Green** (75-100): On track\n- **Yellow** (55-74): Watch it\n- **Red** (0-54): Priority action needed\n\n---\n\n### Data Completeness\n\nThe `dataCompleteness` field (0-1) indicates how much user data is available:\n- **0.8+**: Full wearable + workout data\n- **0.5-0.8**: Partial data (some wearables or workout history)\n- **<0.5**: Limited data (fallback insights provided)\n\n---\n\n### Fallback Behavior\n\nWhen data is missing:\n- Health Pulse calculates a \"Hyperhuman Pulse\" from workout adherence\n- Recovery uses workout intensity to estimate readiness\n- Nutrition shows a CTA to start tracking\n\n---\n\n### Enhanced Coaching Signals\n\nThe digest includes intelligent coaching signals embedded in pillar headlines:\n\n| Signal | Description | Pillars |\n|--------|-------------|---------|\n| **Readiness** | Push/Maintain/Recover recommendation based on recovery data | Health Pulse, Recovery |\n| **Risk Detection** | Fatigue warning when multiple triggers present | Training |\n| **Form Focus** | Primary technique cue from AI assessments | Training |\n| **Program Pacing** | On track/behind status for weekly goals | Training |\n\nThese signals adjust the `action` field to provide intensity-appropriate recommendations based on current readiness state.\n\n---\n\n### Use Cases\n\n- Daily digest screen in mobile app\n- Coach dashboard for client overview\n- Notification content generation\n- Personalized workout recommendations\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### Related Endpoints\n\n- Workout Sessions: `GET /v1/me/workouts/sessions`\n- Workout Feedback: `POST /v1/workouts/{id}/feedback`\n- AI Assessments: `GET /v1/me/workouts/measured-metrics`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier (UUID) of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"endUserId","required":true,"in":"path","description":"User identifier: email, externalUUID, or internal user ID.","example":"john.doe@acme.com","schema":{"type":"string"}},{"name":"date","required":false,"in":"query","description":"Date for the digest (ISO 8601, YYYY-MM-DD). Past dates within last 7 days and today supported; future or older dates return 400. Defaults to today.","example":"2026-01-10","schema":{"type":"string"}},{"name":"forceRefresh","required":false,"in":"query","description":"Force refresh, bypassing cache.","example":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successfully retrieved daily digest.","schema":{"example":{"userId":"63415bf67a9c7000126616c1","organizationId":"63415bf67a9c7000126616c1","date":"2026-01-10T00:00:00.000Z","pillars":[{"type":"health_pulse","status":"green","headline":"82 (+5 vs 7-day). Readiness: Push window today.","action":"Maintain your sleep routine","confidence":0.85,"score":82,"delta":5,"deltaDirection":"up","driver":"sleep"},{"type":"training","status":"green","headline":"4 workouts this week. Form: 78% (improving). On pace.","action":"Next: Full Body Strength at high intensity","confidence":0.8,"weeklyCompletions":4,"streak":5,"formScore":78,"formTrend":"improving"},{"type":"movement","status":"yellow","headline":"Activity below target the last 2 days.","action":"Add a 20-min walk this afternoon","confidence":0.7},{"type":"nutrition","status":"yellow","headline":"No meals logged today.","action":"Log your next meal to keep your streak","confidence":0.5,"isFallback":true}],"todaysFocus":"Complete: Full Body Strength at high intensity","dataCompleteness":0.75,"generatedAt":"2026-01-10T08:30:00.000Z"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserDigestResponse"}}}},"400":{"description":"Invalid date (e.g., future date, more than 7 days in past, or invalid format).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"User or organization not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-ai-insights"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//endusers//insights/digest' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getUserDailyDigest() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers//insights/digest', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//endusers//insights/digest\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/insights/pillars/{pillarType}":{"get":{"operationId":"UserInsightsApi_getPillarDetail","summary":"Get detailed view of a specific insight pillar","description":"\n## Pillar Detail\n\nReturns expanded information for a specific insight pillar, including all available metrics and recommendations.\n\n---\n\n### Available Pillar Types\n\n| Type | Details Included |\n|------|------------------|\n| `health_pulse` | Score, delta, driver, readiness band, recommended intensity |\n| `training` | Last workout, next session, form score, form cue, pacing status, risk level, why explanations, alternative actions |\n| `recovery` | Sleep score, main issue, intensity, readiness band, HRV band, why explanations |\n| `movement` | Activity level, suggested minutes, cardio trend |\n| `nutrition` | Nutrition score (when available), wins/watches |\n| `body` | Body score, weekly trend, streak, biggest lever |\n\n---\n\n### Enhanced Coaching Details\n\nWhen drilling into pillar details, you get actionable coaching context:\n\n**Readiness (Health Pulse and Recovery pillars):**\n- `readinessBand`: Training capacity recommendation (`push` | `maintain` | `recover`)\n- `readinessMessage`: Explanation of the recommendation\n- `recommendedIntensity`: Target workout intensity (`light` | `moderate` | `high`)\n- `hrvBand`: HRV relative to personal baseline (`low` | `normal` | `high`)\n\n**Risk Detection (Training pillar):**\n- `riskLevel`: Fatigue risk severity (`low` | `moderate` | `high`)\n- `riskTriggers`: Array of up to 3 contributing factors\n- `alternativeActions`: Safe workout alternatives when risk detected\n\n**Form Coaching (Training pillar):**\n- `formCue`: Primary technique focus for today\n- `formSuggestion`: Adjustment if form is declining\n- `repAccuracy`: Rep accuracy percentage from AI assessment\n\n**Program Pacing (Training pillar):**\n- `pacingStatus`: Weekly pacing status (`on_track` | `behind` | `ahead`)\n- `pacingMessage`: Weekly progress summary\n- `workoutsPlannedThisWeek` / `workoutsCompletedThisWeek`\n\n**Explanations:**\n- `why`: Array of up to 3 reasons explaining the recommendation\n\n---\n\n### Use Cases\n\n- Drill-down from digest view\n- Detailed pillar cards in UI\n- Coach insights for specific areas\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier (UUID) of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}},{"name":"endUserId","required":true,"in":"path","description":"User identifier: email, externalUUID, or internal user ID.","example":"john.doe@acme.com","schema":{"type":"string"}},{"name":"pillarType","required":true,"in":"path","description":"Type of pillar to get details for.","example":"training","schema":{"type":"string","enum":["health_pulse","training","recovery","movement","nutrition","body"]}}],"responses":{"200":{"description":"Successfully retrieved pillar details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PillarDetailResponse"}}}},"400":{"description":"Invalid pillar type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"User, organization, or pillar not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-ai-insights"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//endusers//insights/pillars/' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getPillarDetail() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//endusers//insights/pillars/', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//endusers//insights/pillars/\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/orgs/{organizationId}/stats":{"get":{"operationId":"OrganizationStatsApi_getOrganizationStats","summary":"Get organization API usage statistics","description":"\n## Organization API Usage Statistics\n\nRetrieves real-time API usage statistics for your organization including current hour requests, daily totals, and rate limits.\n\n---\n\n### πŸ“‹ What's Included\n\n**Current Usage:**\n- Current hour timestamp and request count\n- Total requests made today\n- Current date for reference\n\n**Rate Limits:**\n- Hourly rate limit from your subscription\n- Daily rate limit from your subscription\n\n**Organization Info:**\n- Organization ID and name\n- Response timestamp\n\n---\n\n### 🎯 Use Cases\n\nβœ… **API Monitoring** - Track real-time API usage \nβœ… **Rate Limit Management** - Monitor against your limits \nβœ… **Usage Analytics** - Understand API consumption patterns \nβœ… **Alerting Systems** - Set up usage-based notifications\n\n---\n\n### πŸ’‘ Best Practices\n\nβœ… **Cache responses** - Stats update every 5 minutes \nβœ… **Monitor trends** - Track usage patterns over time \nβœ… **Set up alerts** - Monitor approaching rate limits \nβœ… **Plan capacity** - Use data for subscription planning\n\n---\n\n### πŸ”— Related Endpoints\n\n- Organization Metadata: `GET /v1/orgs/{orgId}/metadata`\n- Organization Workouts: `GET /v1/orgs/{orgId}/workouts`\n- Organization Plans: `GET /v1/orgs/{orgId}/plans`\n ","parameters":[{"name":"organizationId","required":true,"in":"path","description":"The unique identifier of the organization.","example":"63415bf67a9c7000126616c1","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved organization API usage statistics.","schema":{"example":{"organizationId":"63415bf67a9c7000126616c1","organizationName":"My Fitness Company","currentStats":{"currentHour":"2023-11-06T14:00:00Z","currentHourRequests":45,"totalDayRequests":234,"currentDate":"2023-11-06"},"rateLimits":{"hourly":1000,"daily":15000},"timestamp":"2023-11-06T14:30:00Z"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationStatsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["organization"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/orgs//stats' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getOrganizationStats() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/orgs//stats', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/orgs//stats\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/chat/conversations":{"post":{"operationId":"ChatApi_startConversation","summary":"Start a new chat conversation","description":"\n## Start Conversation\n\nCreates a new conversation with the AI fitness coach and returns the assistant's response to the initial message.\n\n---\n\n### User Identification\n\nProvide at least one of `userEmail` or `userExternalUUID` in the request body to identify the end user.\n\n---\n\n### Organization ID\n\n- Use `\"default\"` to automatically resolve the organization from the API key\n- Or provide a valid 24-character hex organization id\n\n---\n\n### Response\n\nReturns the created conversation metadata and the AI assistant's first response message. The assistant message may include `metadata.contentPreview` (workouts, programs, exercises) or `metadata.pendingAction` when the AI proposes a state-changing action.\n\n---\n\n### Pending Actions\n\nWhen the AI proposes a state-changing action (e.g. log nutrition, add workouts, generate workout), the assistant message will include `metadata.pendingAction` with an `id`, `type`, `summary`, and `payload`. Use the Confirm Action endpoint to execute it.\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### Related Endpoints\n\n- `POST /v1/chat/conversations/{conversationId}/messages` - Send follow-up messages\n- `GET /v1/chat/conversations` - List user conversations\n- `POST /v1/chat/conversations/{conversationId}/actions/confirm` - Confirm a pending action\n ","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartConversationBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatConversationResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-ai-chat"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/chat/conversations' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function startConversation() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/chat/conversations', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/chat/conversations\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]},"get":{"operationId":"ChatApi_getConversations","summary":"Get user conversations","description":"\n## List Conversations\n\nReturns a paginated list of the end user's chat conversations, ordered by most recent activity.\n\n---\n\n### User Identification\n\nProvide at least one of `userEmail` or `userExternalUUID` as query parameters to identify the end user.\n\n---\n\n### Pagination\n\n| Parameter | Default | Max |\n|-----------|---------|-----|\n| `page` | 1 | - |\n| `limit` | 20 | 100 |\n\n---\n\n### Related Endpoints\n\n- `POST /v1/chat/conversations` - Start a new conversation\n- `GET /v1/chat/conversations/{conversationId}/messages` - Get messages in a conversation\n- `DELETE /v1/chat/conversations/{conversationId}` - Archive a conversation\n ","parameters":[{"name":"organizationId","required":true,"in":"query","description":"Organization ID - use \"default\" to use the user's default organization","example":"default","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":20,"type":"number"}},{"name":"userEmail","required":false,"in":"query","description":"User email address to identify the end user","example":"user@example.com","schema":{"type":"string"}},{"name":"userExternalUUID","required":false,"in":"query","description":"External unique identifier for the end user","example":"user-12345","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatConversationsResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-ai-chat"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/chat/conversations?organizationId=default' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getConversations() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/chat/conversations?organizationId=default', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/chat/conversations?organizationId=default\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/chat/conversations/{conversationId}/messages":{"get":{"operationId":"ChatApi_getConversationMessages","summary":"Get conversation messages","description":"\n## Get Messages\n\nReturns a paginated list of messages in a conversation, ordered chronologically.\n\n---\n\n### User Identification\n\nProvide at least one of `userEmail` or `userExternalUUID` as query parameters to identify the end user. The user must be the owner of the conversation.\n\n---\n\n### Message Structure\n\nEach message includes:\n- `role`: `\"user\"` or `\"assistant\"`\n- `content`: The message text\n- `status`: `\"pending\"`, `\"delivered\"`, or `\"failed\"`\n- `metadata`: Optional object containing `reasoning`, `topics`, `contentPreview`, `pendingAction`, or `confirmedResult`\n\n---\n\n### Pagination\n\n| Parameter | Default | Max |\n|-----------|---------|-----|\n| `page` | 1 | - |\n| `limit` | 50 | 100 |\n\n---\n\n### Related Endpoints\n\n- `POST /v1/chat/conversations/{conversationId}/messages` - Send a new message\n- `GET /v1/chat/conversations` - List conversations\n ","parameters":[{"name":"conversationId","required":true,"in":"path","schema":{"type":"string"}},{"name":"organizationId","required":true,"in":"query","description":"Organization ID - use \"default\" to use the user's default organization","example":"default","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"userEmail","required":false,"in":"query","description":"User email address to identify the end user","example":"user@example.com","schema":{"type":"string"}},{"name":"userExternalUUID","required":false,"in":"query","description":"External unique identifier for the end user","example":"user-12345","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatMessagesResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-ai-chat"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X GET 'https://content.api.hyperhuman.cc/v1/chat/conversations//messages?organizationId=default' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function getConversationMessages() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/chat/conversations//messages?organizationId=default', {\n method: 'GET',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.get(\"https://content.api.hyperhuman.cc/v1/chat/conversations//messages?organizationId=default\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]},"post":{"operationId":"ChatApi_sendMessage","summary":"Send message to conversation","description":"\n## Send Message\n\nSends a user message to an existing conversation and returns the AI coach's response.\n\n---\n\n### User Identification\n\nProvide at least one of `userEmail` or `userExternalUUID` in the request body to identify the end user. The user must be the owner of the conversation.\n\n---\n\n### Response\n\nReturns three objects:\n- `userMessage` - The saved user message\n- `assistantMessage` - The AI coach response\n- `conversation` - Updated conversation metadata (messageCount, lastMessageAt)\n\n---\n\n### AI Capabilities\n\nThe AI coach can:\n- List, search, and recommend workouts, programs, and exercises (returned in `metadata.contentPreview`)\n- Propose state-changing actions like logging nutrition, adding/assigning workouts and plans, adapting or generating workouts and programs (returned in `metadata.pendingAction`)\n- Provide personalized advice based on user profile, training history, and goals\n\n---\n\n### Rate Limit\n\nThis endpoint counts as 10x API calls toward your hourly and daily limits.\n\n---\n\n### Related Endpoints\n\n- `POST /v1/chat/conversations` - Start a new conversation\n- `POST /v1/chat/conversations/{conversationId}/actions/confirm` - Confirm a pending action\n- `GET /v1/chat/conversations/{conversationId}/messages` - Get message history\n ","parameters":[{"name":"conversationId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageBody"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Conversation not found or does not belong to the user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-ai-chat"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/chat/conversations//messages' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function sendMessage() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/chat/conversations//messages', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/chat/conversations//messages\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/chat/conversations/{conversationId}/actions/confirm":{"post":{"operationId":"ChatApi_confirmAction","summary":"Confirm a pending AI action","description":"\n## Confirm Action\n\nExecutes a pending action proposed by the AI coach after user confirmation.\n\n---\n\n### How It Works\n\n1. The AI proposes an action via `assistantMessage.metadata.pendingAction`\n2. Your client shows a confirmation UI with the action `summary`\n3. User confirms, and you call this endpoint with the `pendingActionId`\n4. The action is executed and the result is returned\n\n---\n\n### Supported Action Types\n\n| Type | Description | Response Field |\n|------|-------------|----------------|\n| `log_nutrition` | Log a meal or nutrition entry | `nutritionOverview` |\n| `add_workouts` | Add workouts to user's library | `message` |\n| `add_plans` | Add plans to user's library | `message` |\n| `assign_workouts` | Assign workouts to the user | `message` |\n| `assign_plans` | Assign plans to the user | `message` |\n| `adapt_workout` | Adapt a workout on the fly | `adaptedWorkout` |\n| `adapt_program` | Adapt a program on the fly | `adaptedProgram` |\n| `generate_workout` | Generate a new workout | `generatedWorkout` |\n| `generate_program` | Generate a new program | `generatedProgram` |\n\n---\n\n### Adapted/Generated Content\n\n`adaptedWorkout` and `generatedWorkout` use the same response format as `POST /v1/orgs/{orgId}/workouts/{id}/adapt` and `POST /v1/orgs/{orgId}/workouts/generate` respectively. Same applies to program equivalents. Clients can reuse the same types and rendering logic.\n\n---\n\n### Related Endpoints\n\n- `POST /v1/chat/conversations/{conversationId}/messages` - Send a message (may return pendingAction)\n- `POST /v1/chat/conversations` - Start a conversation (may return pendingAction)\n ","parameters":[{"name":"conversationId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmActionBody"}}}},"responses":{"200":{"description":"Action executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmActionResponseDto"}}}},"400":{"description":"Action expired or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Pending action not found or already used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-ai-chat"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X POST 'https://content.api.hyperhuman.cc/v1/chat/conversations//actions/confirm' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{}'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function confirmAction() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/chat/conversations//actions/confirm', {\n method: 'POST',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({}),\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.post(\n \"https://content.api.hyperhuman.cc/v1/chat/conversations//actions/confirm\",\n headers={**headers, \"Content-Type\": \"application/json\"},\n json={},\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/v1/chat/conversations/{conversationId}":{"delete":{"operationId":"ChatApi_archiveConversation","summary":"Archive conversation","description":"\n## Archive Conversation\n\nSoft-deletes a conversation by setting its status to `archived`. The conversation and its messages are retained in the database but will no longer appear in the conversations list.\n\n---\n\n### User Identification\n\nProvide at least one of `userEmail` or `userExternalUUID` as query parameters to identify the end user. The user must be the owner of the conversation.\n\n---\n\n### Related Endpoints\n\n- `GET /v1/chat/conversations` - List active conversations\n- `GET /v1/chat/conversations/{conversationId}/messages` - Get messages before archiving\n ","parameters":[{"name":"conversationId","required":true,"in":"path","schema":{"type":"string"}},{"name":"organizationId","required":true,"in":"query","description":"Organization ID - use \"default\" to use the user's default organization","example":"default","schema":{"type":"string"}},{"name":"userEmail","required":false,"in":"query","description":"User email address to identify the end user","example":"user@example.com","schema":{"type":"string"}},{"name":"userExternalUUID","required":false,"in":"query","description":"External unique identifier for the end user","example":"user-12345","schema":{"type":"string"}}],"responses":{"200":{"description":"Conversation archived successfully."},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication failed - API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key is not authorized for this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["endusers-ai-chat"],"security":[{"AccessToken":[]},{"X-Api-Key":["X-Api-Key"]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl -X DELETE 'https://content.api.hyperhuman.cc/v1/chat/conversations/?organizationId=default' \\\n -H 'X-Api-Key: YOUR_API_KEY'"},{"lang":"typescript","label":"TypeScript (fetch)","source":"async function archiveConversation() {\n const res = await fetch('https://content.api.hyperhuman.cc/v1/chat/conversations/?organizationId=default', {\n method: 'DELETE',\n headers: {\n 'X-Api-Key': process.env.HYPERHUMAN_API_KEY ?? '',\n },\n });\n if (!res.ok) {\n const err = await res.json().catch(() => ({}));\n throw new Error(err.error?.code ?? res.statusText);\n }\n return res.json();\n}"},{"lang":"python","label":"Python (requests)","source":"import os\nimport requests\n\nheaders = {\"X-Api-Key\": os.environ[\"HYPERHUMAN_API_KEY\"]}\nresponse = requests.delete(\"https://content.api.hyperhuman.cc/v1/chat/conversations/?organizationId=default\", headers=headers)\nresponse.raise_for_status()\nprint(response.json())"}]}}},"info":{"title":"Hyperhuman Content API","description":"\n\n> One API for delivery, personalization, and insights across your entire product.\n\nFitness content infrastructure for modern health, wellness, and fitness products: workout API, AI recommendations, AI generation, AI adaptation, and insights in one platform. Most teams ship Publish + Recommend in the first week and add the AI layers as their audience signals demand it.\n\n---\n\n## Quick Start\n\n**1. Get credentials** -> [team.hyperhuman.cc/settings?tab=integrations](https://team.hyperhuman.cc/settings?tab=integrations)\n\n**2. First request:**\n```bash\ncurl -X GET 'https://content.api.hyperhuman.cc/v1/workouts/metadata' \\\n -H 'X-Api-Key: YOUR_API_KEY'\n```\n\n**3. Generate a workout:**\n```bash\ncurl -X POST 'https://content.api.hyperhuman.cc/v1/orgs/{organizationId}/workouts/generate' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"endUserProfileDetails\": {\"age\": 28, \"fitnessLevels\": [\"beginner\"]},\n \"exerciseSources\": [\"premium_stock\"],\n \"durationOptions\": {\"minMinutes\": 20, \"maxMinutes\": 20},\n \"categoryId\": \"615aa3f0dbe7140012c59e94\"\n }'\n```\n\n---\n\n## For LLMs and AI agents\n\nIf you are a coding assistant integrating against this API, prefer these machine-readable artifacts over scraping this HTML page:\n\n| Artifact | URL | Use it for |\n|----------|-----|------------|\n| Compact LLM index (markdown) | [https://content.api.hyperhuman.cc/llms.txt](https://content.api.hyperhuman.cc/llms.txt) | Short overview + links to deeper docs. Drop into context windows. |\n| Full LLM bundle (markdown) | [https://content.api.hyperhuman.cc/llms-full.txt](https://content.api.hyperhuman.cc/llms-full.txt) | Auth, error envelope, pagination, locales, and per-endpoint summaries in one file. |\n| OpenAPI 3 spec (JSON) | [https://content.api.hyperhuman.cc/openapi.json](https://content.api.hyperhuman.cc/openapi.json) | Source of truth for tool/function calling. Stable `operationId`s of the form `Controller_method`. |\n| OpenAPI 3 spec (YAML) | [https://content.api.hyperhuman.cc/openapi.yaml](https://content.api.hyperhuman.cc/openapi.yaml) | Same content as `openapi.json`, friendlier for diffing and most CLI codegen tools. |\n| Agent integration guide | [https://content.api.hyperhuman.cc/AGENTS.md](https://content.api.hyperhuman.cc/AGENTS.md) | Conventions for generated client code (auth, errors, pagination, locales) plus **Β§11–12**: strict whitelisted query/body keys, public `/openapi.json` scope, id wording, and **repository** notes for API maintainers (DTOs, `parse-csv-ids`, OpenAPI `include` list). |\n| Custom player guide | [https://content.api.hyperhuman.cc/docs/guides/custom-player.md](https://content.api.hyperhuman.cc/docs/guides/custom-player.md) | Reference implementation for building a custom interactive workout player on top of `/playlist` and `/music`. |\n\n> Need a copy-paste prompt? Send the agent the URL of `/llms-full.txt` plus the prose: \"Use this Hyperhuman Content API. Authenticate with the `X-Api-Key` header. Every error response is `{ \"error\": { \"code\", \"message\" } }`. Pagination cursors are `offset` and `limit`.\"\n\n---\n\n## Five capabilities, one API\n\nFive product surfaces stack on the same library. Start where you are; add the AI layers as your product matures.\n\n| # | Capability | Primary endpoint | What it does | Latency band |\n|---|------------|------------------|--------------|--------------|\n| 1 | **Publish Content** | `GET /v1/orgs/{organizationId}/workouts`
`GET /v1/orgs/{organizationId}/plans` | List, filter, and play workouts and multi-week plans from your library. Your library becomes your product surface. | Fast |\n| 2 | **AI Recommend** | `POST /v1/orgs/{organizationId}/workouts/recommend`
`POST /v1/orgs/{organizationId}/plans/recommend` | Suggest the best next workout or plan from your library, ranked against goals and profile signals. | Sub-second |\n| 3 | **AI Generate** | `POST /v1/orgs/{organizationId}/workouts/generate`
`POST /v1/orgs/{organizationId}/plans/generate` | Create a brand-new workout or multi-week plan on the fly, scoped to the user's age, level, equipment, and time budget. | 2-8 seconds |\n| 4 | **AI Adapt** | `POST /v1/orgs/{organizationId}/workouts/{workoutId}/adapt`
`POST /v1/orgs/{organizationId}/plans/{planId}/adapt` | Evolve an existing workout or plan as the user progresses. Preserves the original goals; modifies intensity, duration, and exercise selection. Counts as 10x rate-limit weight. | 2-8 seconds |\n| 5 | **AI Insights** | `GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/digest?date=YYYY-MM-DD`
`GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/pillars/{pillarType}` | Daily digest plus per-pillar drill-downs (health pulse, training, recovery, movement, nutrition, body) for re-engagement loops. | Fast |\n\n> `{endUserId}` is the Hyperhuman end-user id (24-character hex DB id returned by the endusers endpoints), not the user's email. Treat all ids as opaque strings.\n\n---\n\n## Three delivery models\n\nThe same library and intelligence layer ship through three integration paths. Pick by team capacity and product surface.\n\n### 1. Embed & Go\n\nDrop Hyperhuman-hosted surfaces into a webview, landing page, or portal: a **single-workout or JSON player** on `team.hyperhuman.cc` (see **Embedded Player**), or a **full workouts or programs library grid** on the member web app with configurable discovery UI (see **Branded library embed**). Fastest path to live content; no custom player build required. Best for web apps, MVPs, corporate wellness portals, marketing pages.\n\n### 2. Stream Videos\n\nGet a pre-rendered, full-length workout **video** or **narrative audio** as a **single presigned HTTPS URL** in the response body. Best for VOD catalogs, CMS publishing, YouTube workflows, audio-first products.\n\n```bash\ncurl -X GET 'https://content.api.hyperhuman.cc/v1/workouts/{workoutId}/export/video/stream_url?locale=en-US' \\\n -H 'X-Api-Key: YOUR_API_KEY'\n```\n\n```bash\ncurl -X GET 'https://content.api.hyperhuman.cc/v1/workouts/{workoutId}/export/audio/stream_url?locale=en-US' \\\n -H 'X-Api-Key: YOUR_API_KEY'\n```\n\nReturns **`200`** with **`Content-Type: text/plain`**: a **single** presigned URL string (not JSON). The URL points to the full-workout **video** or **narrative audio** object stored for that locale; format and container (for example **MP4**, **HLS** `.m3u8`, or **M4A** audio) depend on the export that was generatedβ€”follow the URL. URLs are time-limited (on the order of **7 days**). Pre-rendered video/audio takes 2-5 minutes to produce after a workout is created or generated; until then the export endpoint returns `404`. If the requested locale has not been rendered, the endpoint also returns `404` - retry with `locale=en-US` or trigger a render for the missing locale.\n\n### 3. Build Your UX\n\nPower your own player UI with our structured playlist and pre-signed media URLs. Maximum control over UI, analytics, and offline behavior. Best for mobile apps, connected hardware, and premium coaching experiences. See the **Custom Interactive Workout Player** section below for the reference implementation.\n\n---\n\n## Embedded Player\n\nTwo drop-in iframes for the most common integration paths. The same player powers both - only the data source differs.\n\n### Pre-built Workout\n\nRenders any workout from your library by id.\n\n```html\n\n\n```\n\n#### Query Parameters\n\n| Param | Required | Type | Default | Description |\n|-------|----------|------|---------|-------------|\n| `organizationId` | yes | string | - | Organization id (24-character hex DB id) the workout belongs to. |\n| `apiKey` | yes | string | - | Your Content API key (`X-Api-Key` value). |\n| `locale` | no | string | `en-US` | BCP-47 locale. Falls back to English when unsupported. |\n| `segment` | no | string | first segment | Segment id to start playback from (e.g. resume from a specific exercise). |\n| `presentationStyle` | no | enum | workout default | One of `full`, `minimal`, `essential`, `noOverlays`. Overrides the workout's own `presentationStyle`. |\n| `muted` | no | boolean | `false` | Accept `1` or `true`. Pair with `autoplay=1` for unattended embeds. |\n| `autoplay` | no | boolean | `false` | Accept `1` or `true`. Browsers block sound autoplay without a user gesture - combine with `muted=1`. |\n| `brandLogoUrl` | no | string (URL) | org logo | Overrides the org logo shown in the player chrome. |\n| `brandWatermarkUrl` | no | string (URL) | org watermark | Overrides the bottom-right watermark. Square PNG with transparent background recommended. |\n| `brandMainColor` | no | hex string | org main color | Player accent color. URL-encode the `#` (`%23FF6600`). |\n| `brandSecondaryColor` | no | hex string | org secondary | Used for secondary accents. URL-encode the `#`. |\n| `brandTextColor` | no | hex string | org text color | Color of timer / next-exercise / outro text overlays. URL-encode the `#`. |\n\n> Tip: org-level branding (logo, watermark, colors) is exposed by `GET /v1/orgs/{organizationId}/metadata`. Pass overrides only when you need to differ from the org defaults (e.g. white-label per end-user).\n\n---\n\n### AI-Generated Workout\n\nFor workouts produced on the fly by your own backend or by `POST /v1/orgs/{organizationId}/workouts/generate`. The iframe announces readiness; your page replies with the JSON payload.\n\n```html\n\n\n\n```\n\n#### Query Parameters\n\n| Param | Required | Type | Default | Description |\n|-------|----------|------|---------|-------------|\n| `organizationId` | yes | string | - | Organization id (24-character hex DB id). |\n| `apiKey` | yes | string | - | Your Content API key. |\n| `locale` | no | string | `en-US` | BCP-47 locale. |\n| `segment` | no | string | first segment | Segment id to start playback from. |\n\n#### postMessage Protocol\n\n1. The iframe loads, validates credentials, then posts the literal string `'hyperhumanPlayerReadyForData'` to its parent.\n2. Your page replies with the workout JSON payload (shape below).\n3. Subsequent posts of the same shape replace the current workout (useful for \"play next\" flows).\n\n#### Workout JSON Payload Shape\n\n```json\n{\n \"name\": \"Quick Morning Burner\",\n \"totalDurationSeconds\": 600,\n \"difficulty\": \"intermediate\",\n \"categoryId\": \"615aa3f0dbe7140012c59e94\",\n \"initialSegmentId\": \"instance_1\",\n \"instances\": [\n {\n \"id\": \"instance_1\",\n \"kind\": \"single-exercise\",\n \"durationSeconds\": 45,\n \"pace\": \"medium\",\n \"weightLevel\": \"medium\",\n \"rpe\": 7,\n \"amrap\": false,\n \"skipIntro\": false,\n \"exercise\": {\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Bodyweight Squats\",\n \"thumbnailUrl\": \"https://images.hyperhuman.cc/squat-thumb.jpg\"\n }\n },\n {\n \"id\": \"instance_rest_1\",\n \"kind\": \"rest\",\n \"durationSeconds\": 30\n }\n ]\n}\n```\n\n| Field | Required | Notes |\n|-------|----------|-------|\n| `name` | yes | Workout title shown in the intro/outro. |\n| `instances[]` | yes | Ordered list of exercise + rest segments. |\n| `instances[].kind` | yes | `single-exercise` or `rest`. |\n| `instances[].exercise.id` | yes (for exercises) | Hyperhuman exercise id; the player fetches video/audio assets for this id via the Content API. |\n| `totalDurationSeconds` | recommended | Used for the progress bar. |\n| `initialSegmentId` | optional | Same effect as the `segment` query param. |\n\n#### Security Model\n\nThe receiver intentionally accepts `postMessage` from **any parent origin** so third-party customer pages can drive the player without per-tenant allow-list configuration. The trust boundary is **payload-shape validation** - the receiver only honors objects matching the schema above. Treat this channel as untrusted: never include API keys, access tokens, PII, or anything you wouldn't put in a URL fragment.\n\n---\n\n### Player Cast Controls (optional)\n\nBoth iframes accept playback control messages from any parent origin. Useful for casting, custom UI overlays, or remote control surfaces.\n\n```javascript\nplayerIframe.contentWindow.postMessage({\n type: 'CAST_CONTROL',\n action: 'play' // 'play' | 'pause' | 'next' | 'previous' | 'restart' | 'done'\n}, '*');\n```\n\nSame security model as the JSON receiver: payload-shape validated, origin-open. Do not transmit secrets.\n\n---\n\n## Branded library embed (workouts and programs)\n\nBranded, responsive **library pages**: a searchable grid of your team's workouts or multi-week programs, hosted on the **member web app** (not the Content API origin in `https://content.api.hyperhuman.cc`). Visitors browse and open workouts without you building a catalog UI. There is **no API key in the URL** β€” access and visibility follow your org's member-app and publishing settings.\n\nIn [Hyperhuman Teams](https://team.hyperhuman.cc), open **Share** on **Manage Content** (workouts or programs) and use the **Embed page** tab to copy a snippet and toggle options; the same query contract is documented here for hand-built URLs.\n\n### Base URL\n\nProduction host: `https://member.hyperhuman.cc`. Your team may use a different host in staging or white-label deployments β€” use the member app URL shown in Teams when copying the embed.\n\n### Paths\n\n| Surface | Path |\n|---------|------|\n| Workout library grid | `/workouts` |\n| Program library grid | `/plans` |\n\nAlways pass `orgId` (your organization id, same value as `{organizationId}` in Content API paths).\n\n### Query parameters\n\nOnly **non-default** options are serialized on the URL (short, readable links). Defaults match the Teams **Embed page** UI.\n\n| Param | Required | Type | Default | When it appears in the URL |\n|-------|----------|------|---------|----------------------------|\n| `orgId` | yes | string (24 hex chars) | - | Always. |\n| `showSearch` | no | boolean | `true` (search bar on) | Only as `showSearch=false` when the search bar is hidden. |\n| `showFilters` | no | boolean | `true` (filter chips on) | Only as `showFilters=false` when filters are hidden. |\n| `gridCols` | no | integer, one of 2, 3, or 4 | `3` | Only when not `3` (e.g. `gridCols=2` or `gridCols=4`). |\n| `playbackMode` | no | string | `overlay` | Only when `dedicated-page`. Default `overlay` opens playback in a lightbox over the embed; `dedicated-page` opens the workout in a **new browser tab** so the host page stays in place. |\n| `showDuration` | no | boolean | `true` (length badge on cards) | Only as `showDuration=false` when hidden. |\n| `showDifficulty` | no | boolean | `true` (difficulty badge on cards) | Only as `showDifficulty=false` when hidden. |\n\n### Iframe snippet\n\nThe Teams **Embed page** tab generates a container-filling iframe (your page controls the outer box size):\n\n```html\n\n```\n\nReplace `MEMBER_APP_URL_AND_QUERY` with the full `https://member.hyperhuman.cc/workouts?...` or `https://member.hyperhuman.cc/plans?...` URL from Teams or built from the table above.\n\n### Examples\n\n**Workouts grid** β€” search and filters off, 2 columns, open in new tab, length and difficulty badges off:\n\n```html\n\n```\n\n**Programs grid** β€” same options with 4 columns:\n\n```html\n\n```\n\n### API parity\n\nTo drive the same catalogs from your own UI, use the Content API:\n\n- `GET /v1/orgs/{organizationId}/workouts` β€” list and filter workouts (query params such as `offset`, `limit`, `q`, `sort`, `visibility`, `difficulty`, `categoryIds`, duration filters; no `page` β€” see [AGENTS.md](https://content.api.hyperhuman.cc/AGENTS.md) section 4).\n- `GET /v1/orgs/{organizationId}/plans` β€” list and filter plans (e.g. `difficulties`, `goalIds`, `durationInWeeks`, `workoutsPerWeek`).\n\n---\n\n## Custom Interactive Workout Player\n\nFor full UI control, build your own player on top of the public API. The contract is small:\n\n| Endpoint | Returns |\n|----------|---------|\n| `GET /v1/workouts/{workoutId}` | Workout metadata (name, duration, difficulty, `videoAudioMode`, `mixBgMusic`). |\n| `GET /v1/workouts/{workoutId}/playlist?locale={locale}` | Ordered segments with media assets and timing. Drives the player. |\n| `GET /v1/workouts/{workoutId}/music` | Shuffled, deduplicated background music playlist (pre-signed S3 URLs, 7-day expiration). Respects org/trainer music preferences and the workout's `mixBgMusic` flag. |\n\nThe full reference implementation - playlist manager, media controller, progress tracker, navigation handler, audio policy compliance - lives in the [Custom Player Guide](https://content.api.hyperhuman.cc/docs/guides/custom-player.md). It mirrors the Hyperhuman first-party players byte-for-byte and is the recommended starting point if you ship your own UX.\n\n### Audio Policy\n\nEach workout has a `videoAudioMode` (see `GET /v1/workouts/{workoutId}`) that controls which audio tracks the player must mix. Mirror this matrix exactly so your custom player matches the rendered MP4 export and the Hyperhuman first-party players byte-for-byte.\n\n| `videoAudioMode` | Voice instructions | Beeps / countdowns | Background music* |\n|-------------------|---------------------|--------------------|-------------------|\n| `full` (default) | yes | yes | yes |\n| `instructionsOnly` | yes | no | yes |\n| `beepsOnly` | no | yes | yes |\n| `none` | no | no | no |\n\n\\* Background music is additionally gated by the workout's `mixBgMusic` flag - if `mixBgMusic` is `false`, music never plays regardless of `videoAudioMode`.\n\n```javascript\n// Reference snippet - matches backend export pipeline 1:1.\nconst shouldIncludeVoiceInstructions = (mode) =>\n mode === undefined || mode === 'full' || mode === 'instructionsOnly';\n\nconst shouldIncludeBeeps = (mode) =>\n mode === undefined || mode === 'full' || mode === 'beepsOnly';\n\nconst shouldIncludeBackgroundMusic = (mode, mixBgMusic) =>\n mode !== 'none' && (mixBgMusic ?? true);\n```\n\n---\n\n## Localization\n\n**Supported locales (13):** `en-US`, `en-GB`, `en-AU`, `fr-FR`, `de-DE`, `es-ES`, `it-IT`, `pt-PT`, `he-IL`, `ro-RO`, `cs-CZ`, `fi-FI`, `nl-NL`.\n\n```bash\ncurl 'https://content.api.hyperhuman.cc/v1/workouts/{workoutId}?locale=fr-FR' \\\n -H 'X-Api-Key: YOUR_API_KEY'\n```\n\nLocalizes: workout titles and descriptions, exercise names, equipment, muscle groups, player metadata, and audio guidance (where enabled).\n\n#### Fallback Behavior\n\n| Endpoint family | Behavior when locale is unsupported |\n|-----------------|-------------------------------------|\n| Metadata, workout details, playlist (text + voice cues) | Falls back to English so playback never breaks. |\n| Pre-rendered video / audio exports (`/export/...`) | Returns `404` if no rendered asset exists in the requested locale. Re-request with `locale=en-US`, or trigger an export job for the missing locale. |\n\n---\n\n## Authentication\n\nAdd to all requests:\n\n```\nX-Api-Key: YOUR_API_KEY\n```\n\nGet your key: [team.hyperhuman.cc/settings?tab=integrations](https://team.hyperhuman.cc/settings?tab=integrations).\n\nA handful of end-user-scoped endpoints (`/me/...`) additionally accept a JWT `Authorization: Bearer ` header in place of, or in addition to, the API key. The OpenAPI spec marks these explicitly with `bearer` security.\n\n---\n\n## Complete API Workflows\n\n### Workflow 1: Browse and play pre-built content\n```\n1. GET /v1/workouts/metadata -> categories and filters\n2. GET /v1/orgs/{organizationId}/workouts -> browse the library\n3. GET /v1/workouts/{workoutId} -> workout details\n4. GET /v1/workouts/{workoutId}/playlist -> video segments\n5. (optional) GET /v1/workouts/{workoutId}/music -> background music\n6. (optional) POST /v1/workouts/{workoutId}/sessions/start -> track progress\n```\n\n### Workflow 2: AI-generated workouts\n```\n1. GET /v1/orgs/{organizationId}/metadata -> org settings\n2. POST /v1/orgs/{organizationId}/workouts/generate -> create custom workout\n3. GET /v1/workouts/{workoutId}/playlist -> get generated content\n4. (optional) GET /v1/workouts/{workoutId}/music -> background music\n5. POST /v1/workouts/{workoutId}/sessions/start -> begin tracking\n6. PATCH /v1/workouts/{workoutId}/sessions/{sessionId} -> update progress\n7. POST /v1/workouts/{workoutId}/sessions/end -> complete session\n8. POST /v1/workouts/{workoutId}/feedback -> collect user feedback\n```\n\n### Workflow 3: AI adaptation (evolve existing content)\n```\n1. GET /v1/orgs/{organizationId}/workouts -> pick a base workout\n2. POST /v1/orgs/{organizationId}/workouts/{workoutId}/adapt -> personalized variant\n3. GET /v1/workouts/{newWorkoutId}/playlist -> get the adapted content\n4. (then follow Workflow 2 from step 5 to track the session)\n```\n\n### Workflow 4: Multi-week training programs\n```\n1. GET /v1/plans/metadata -> plan goals and difficulties\n2. POST /v1/orgs/{organizationId}/plans/generate -> create multi-week plan\n3. GET /v1/plans/{planId} -> plan details\n4. GET /v1/plans/{planId}/workouts -> plan workouts\n5. For each workout: follow Workflow 2.\n```\n\n### Workflow 5: End-user governance (B2B lifecycle)\n```\n1. GET /v1/orgs/{organizationId}/endusers -> list users\n2. POST /v1/orgs/{organizationId}/endusers/invite -> add new users\n3. GET /v1/orgs/{organizationId}/endusers/find -> check user status\n4. PUT /v1/orgs/{organizationId}/endusers/suspend -> temporarily disable access\n5. PUT /v1/orgs/{organizationId}/endusers/reactivate -> restore access\n6. DELETE /v1/orgs/{organizationId}/endusers -> remove user permanently\n```\n\n### Workflow 6: Daily insights and re-engagement\n```\n1. GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/digest?date=2026-04-20\n -> 3-5 pillar summaries + todaysFocus + dataCompleteness\n2. GET /v1/orgs/{organizationId}/endusers/{endUserId}/insights/pillars/{pillarType}\n -> drill-down for any pillar (health_pulse, training, recovery, movement, nutrition, body)\n```\n\n---\n\n## Error Handling\n\n### Common HTTP Status Codes\n\n| Code | Meaning | Common Causes | How to Handle |\n|------|---------|----------------|---------------|\n| **200** | Success | Request completed successfully | Continue normal flow |\n| **201** | Created | Resource created (sessions, workouts) | Extract ID from response |\n| **400** | Bad Request | Invalid query/path parameters, malformed JSON body | Check request body and parameters |\n| **401** | Unauthorized | Missing, malformed or invalid API key (`X-Api-Key` header) | Verify the API key is sent on every request |\n| **403** | Forbidden | Valid API key, but not authorized for the requested organization or resource | Check that the API key belongs to the same org as the resource being accessed |\n| **404** | Not Found | Resource doesn't exist, was deleted, or the requested locale variant has not been rendered yet (export endpoints) | Verify IDs; for exports, retry without `locale` or with `locale=en-US` |\n| **409** | Conflict | Resource already exists (e.g. active session) or state transition not allowed | Reconcile against current state before retrying |\n| **422** | Unprocessable Entity | Body shape is valid JSON but fails business validation (`error.details` populated) | Inspect `error.details[]` for the offending fields |\n| **429** | Too Many Requests | Hourly or daily rate limit exceeded (see headers below) | Implement exponential backoff; respect `X-RateLimit-Reset` |\n| **500** | Internal Server Error | Server-side issue | Retry with exponential backoff |\n\n### Error Response Format\n\nEvery non-2xx response is wrapped in a single `error` envelope. The body is always JSON, even when the failing endpoint normally returns `text/plain` (e.g. stream URL endpoints).\n\n```json\n{\n \"error\": {\n \"code\": \"UnprocessableEntity\",\n \"message\": \"Validation failed\",\n \"target\": \"requestBody\",\n \"details\": [\n {\n \"code\": \"InvalidFormat\",\n \"message\": \"must be a positive number\",\n \"target\": \"durationOptions.minMinutes\"\n }\n ]\n }\n}\n```\n\n| Field | Type | Always present | Notes |\n|-------|------|----------------|-------|\n| `error.code` | string | yes | A stable machine-readable identifier from the closed enum below. Switch on this - never on `message`. |\n| `error.message` | string | yes | Human-readable English summary. Suitable for logs; not for end-user UI. |\n| `error.target` | string | no | The primary field/parameter related to the overall error (e.g. `requestBody`, `workoutId`). |\n| `error.details` | array | no | Field-level breakdown - populated for validation errors and entity-not-found errors. Each item has `code`, `message`, and optional `target`. |\n\n#### Stable error codes\n\n| HTTP status | `error.code` |\n|-------------|----------------|\n| 400 | `BadRequest` |\n| 401 | `Unauthorized` |\n| 403 | `Forbidden` |\n| 404 | `NotFound` |\n| 405 | `MethodNotAllowed` |\n| 408 | `RequestTimeout` |\n| 409 | `Conflict` |\n| 410 | `Gone` |\n| 413 | `PayloadTooLarge` |\n| 415 | `UnsupportedMediaType` |\n| 422 | `UnprocessableEntity` |\n| 500 | `InternalServerError` |\n| 501 | `NotImplemented` |\n| 502 | `BadGateway` |\n| 503 | `ServiceUnavailable` |\n| 504 | `GatewayTimeout` |\n\n> Treat the `error.code` enum as the contract. `error.message` wording can change between releases.\n\n### Best Practices\n\n**Do:**\n- Always check HTTP status codes\n- Implement exponential backoff for 429/500 errors\n- Log error details for debugging\n- Provide user-friendly error messages\n- Handle network timeouts gracefully\n\n**Don't:**\n- Ignore error responses\n- Retry immediately on all errors\n- Expose internal error details to users\n- Make requests without proper error handling\n\n### Retry Strategy\n\n```javascript\nconst retryWithBackoff = async (fn, maxRetries = 3) => {\n for (let i = 0; i < maxRetries; i++) {\n try {\n return await fn();\n } catch (error) {\n if (error.status === 429 || error.status >= 500) {\n const delay = Math.pow(2, i) * 1000;\n await new Promise(resolve => setTimeout(resolve, delay));\n continue;\n }\n throw error;\n }\n }\n throw new Error('Max retries exceeded');\n};\n```\n\n---\n\n## Rate Limiting\n\nEvery response carries:\n\n```\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 999\nX-RateLimit-Reset: 1640995200\n```\n\n- `X-RateLimit-Limit` - Maximum requests per window\n- `X-RateLimit-Remaining` - Requests remaining in current window\n- `X-RateLimit-Reset` - Unix timestamp when the window resets\n\n**Note:** AI and full-video endpoints (workout/plan generate, recommend, adapt, insights, chat, video generation, full video export) count as **10x** API calls toward your limits.\n\n**When rate limited (429):**\n1. Stop making requests immediately\n2. Wait until reset time (check `X-RateLimit-Reset`)\n3. Implement exponential backoff\n4. Consider upgrading your plan for higher limits\n\n**Best practices:**\n- Monitor remaining requests\n- Implement request queuing\n- Cache responses when possible\n- Use batch operations when available\n\n**Monitor usage:**\n- `GET /v1/orgs/{organizationId}/stats` - Real-time API usage statistics including current hour requests, daily totals, and rate limits.\n\n---\n\n## Hyperhuman product surfaces\n\nThe Content API is one surface in a wider platform. If a capability you need isn't in this API, it likely lives in one of these:\n\n- **Teams workspace** ([team.hyperhuman.cc](https://team.hyperhuman.cc)) - production hub for the Smart Library, AI Workout Builder, Content Autopilot, Social Publishing, and team analytics. This is where API keys are issued.\n- **Hyperhuman Club** ([hyperhuman.cc/club](https://hyperhuman.cc/club)) - white-label branded member app for iOS and Android. Plug-and-play health HQ that companies launch in weeks instead of months.\n- **Wix widget** ([hyperhuman.cc/wix](https://hyperhuman.cc/wix)) - embeddable workout library and player for Wix sites.\n- **Pricing** ([hyperhuman.cc/pricing](https://hyperhuman.cc/pricing)) - plan-dependent quotas and module availability.\n- **Book a demo** ([hyperhuman.cc/book-a-demo](https://hyperhuman.cc/book-a-demo)) - if you're scoping a custom integration.\n\n---\n\n## Resources\n\n- **OpenAPI spec (JSON):** [https://content.api.hyperhuman.cc/openapi.json](https://content.api.hyperhuman.cc/openapi.json)\n- **OpenAPI spec (YAML):** [https://content.api.hyperhuman.cc/openapi.yaml](https://content.api.hyperhuman.cc/openapi.yaml)\n- **Modern reference (Scalar):** [https://content.api.hyperhuman.cc/docs](https://content.api.hyperhuman.cc/docs)\n- **Classic explorer (Swagger UI):** [https://content.api.hyperhuman.cc/docs/api-explorer](https://content.api.hyperhuman.cc/docs/api-explorer)\n- **LLM bundle:** [https://content.api.hyperhuman.cc/llms-full.txt](https://content.api.hyperhuman.cc/llms-full.txt)\n- **Agent guide:** [https://content.api.hyperhuman.cc/AGENTS.md](https://content.api.hyperhuman.cc/AGENTS.md)\n- **Custom player guide:** [https://content.api.hyperhuman.cc/docs/guides/custom-player.md](https://content.api.hyperhuman.cc/docs/guides/custom-player.md)\n- **Support:** support@hyperhuman.cc\n- **Website:** [hyperhuman.cc](https://hyperhuman.cc)\n","version":"1.0","contact":{}},"tags":[{"name":"workouts"},{"name":"plans"},{"name":"library-exercises"},{"name":"exercise-groups"},{"name":"ai-generation"},{"name":"ai-recommendation"},{"name":"ai-adaptation"},{"name":"organization"},{"name":"social"},{"name":"content-autopilot"},{"name":"social-publish"},{"name":"endusers-ai-insights"},{"name":"endusers-ai-chat"},{"name":"endusers-plans"},{"name":"endusers-management"}],"servers":[{"url":"https://content.api.hyperhuman.cc"}],"components":{"securitySchemes":{"X-Api-Key":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Choose a plan that fits your expected API usage. Once activated, you'll receive your content key and organization ID in the [integrations tab](https://team.hyperhuman.cc/settings?tab=integrations)."}},"schemas":{"ApiErrorDetails":{"type":"object","properties":{"code":{"type":"string","description":"A specific error code related to this detail.","example":"InvalidFormat"},"message":{"type":"string","description":"A human-readable message explaining this specific error detail.","example":"The provided email address is not valid."},"target":{"type":"string","description":"The specific field or parameter that caused this error detail, if applicable.","example":"email"}},"required":["code","message"]},"ApiError":{"type":"object","properties":{"code":{"type":"string","description":"A general error code classifying the error.","example":"BadRequest"},"message":{"type":"string","description":"A human-readable message summarizing the overall error.","example":"The request is invalid."},"target":{"type":"string","description":"The primary field or parameter related to the overall error, if applicable.","example":"requestBody"},"details":{"description":"An array of specific error details, often related to validation failures on individual fields.","type":"array","items":{"$ref":"#/components/schemas/ApiErrorDetails"}}},"required":["code","message"]},"ErrorResponse":{"type":"object","properties":{"error":{"description":"Contains the details of the error that occurred.","allOf":[{"$ref":"#/components/schemas/ApiError"}]}},"required":["error"]},"TrainerRef":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the trainer.","example":"trainer-jane-doe"},"name":{"type":"string","description":"Display name of the trainer.","example":"Jane Doe"}},"required":["id","name"]},"WorkoutAudio":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the audio asset","example":"68b0557adbaf49d17ee429bb"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the audio was created","example":"2025-08-28T13:11:22.242Z"},"isStock":{"type":"boolean","description":"Whether this is a stock audio asset","example":false},"assetUri":{"type":"string","description":"Pre-signed URL to access the audio file","format":"url","example":"https://hhup-staging.s3.eu-central-1.amazonaws.com/a/..."},"scriptText":{"type":"string","description":"Script text for the audio","example":"Welcome to your workout!"},"type":{"type":"string","description":"Type of audio asset","example":"workoutIntro"},"locale":{"type":"string","description":"Locale/language of the audio","example":"en-US"},"duration":{"type":"number","description":"Duration of the audio in seconds","example":0.875},"status":{"type":"string","description":"Processing status of the audio","example":"generated"}},"required":["id","createdAt","isStock","assetUri","type","locale","duration","status"]},"VideoLinks":{"type":"object","properties":{"url":{"type":"string","description":"URL of the video resource (e.g., MP4, M3U8 playlist).","format":"url","example":"https://stream.hyperhuman.cc/video/workout-123/master.m3u8?token=..."},"poster":{"type":"object","description":"URL of a poster image to display before video playback.","format":"url","example":"https://assets.hyperhuman.cc/video/workout-123/poster.jpg"},"thumbnail":{"type":"object","description":"URL of a thumbnail image representing the video.","format":"url","example":"https://assets.hyperhuman.cc/video/workout-123/thumb.jpg"},"loop":{"type":"number","description":"Playback looping behavior hint. 0 = no loop, -1 = infinite loop, >0 = specific number of loops (if supported by player). Default is typically 0 or 1 depending on context.","example":-1,"default":0}},"required":["url"]},"ImageLinks":{"type":"object","properties":{"url":{"type":"string","description":"URL of the primary/original image.","format":"url","example":"https://assets.hyperhuman.cc/images/workout-cover-123.jpg"},"thumbnail":{"type":"object","description":"URL of a smaller (thumbnail) version of the image.","format":"url","example":"https://assets.hyperhuman.cc/images/workout-thumb-123.jpg"}},"required":["url"]},"Category":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the category.","example":"cat-hiit-123"},"name":{"type":"string","description":"Display name of the category. Localized based on locale query parameter.","example":"HIIT"}},"required":["id","name"]},"Equipment":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the equipment item.","example":"eq-dumbbell-abc"},"name":{"type":"string","description":"Display name of the equipment. Localized based on locale query parameter.","example":"Dumbbell"}},"required":["id","name"]},"MusicPlaylistLink":{"type":"object","properties":{"url":{"type":"string","description":"URL of the music playlist on an external platform (e.g., Spotify, Apple Music).","format":"url","example":"https://open.spotify.com/playlist/37i9dQZF1DX..."}},"required":["url"]},"MusicPlaylists":{"type":"object","properties":{"spotify":{"description":"Spotify music playlist","allOf":[{"$ref":"#/components/schemas/MusicPlaylistLink"}]},"youtube":{"description":"Youtube music playlist","allOf":[{"$ref":"#/components/schemas/MusicPlaylistLink"}]},"appleMusic":{"description":"Apple Music playlist","allOf":[{"$ref":"#/components/schemas/MusicPlaylistLink"}]},"amazonMusic":{"description":"Amazon Music playlist","allOf":[{"$ref":"#/components/schemas/MusicPlaylistLink"}]}}},"ShareLink":{"type":"object","properties":{"url":{"type":"string","description":"URL that can be shared to provide access or reference to the resource.","format":"url","example":"https://share.hyperhuman.cc/w/a1b2c3d4"}},"required":["url"]},"Organization":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the organization.","example":"org-fitness-first"},"name":{"type":"string","description":"Display name of the organization.","example":"Fitness First Gym"},"logo":{"description":"Links to the organization's logo images (if available).","allOf":[{"$ref":"#/components/schemas/ImageLinks"}]}},"required":["id","name"]},"MuscleGroupPercentage":{"type":"object","properties":{"muscleGroupId":{"type":"string","description":"Unique identifier of the muscle group","example":"507f1f77bcf86cd799439011"},"muscleGroupName":{"type":"string","description":"Localized name of the muscle group","example":"Chest"},"percentage":{"type":"number","description":"Percentage of workout focused on this muscle group","minimum":0,"maximum":100,"example":35.5}},"required":["muscleGroupId","muscleGroupName","percentage"]},"Workout":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the workout.","example":"12ab3efd45c67c1234566cd1"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the workout was created.","example":"2023-10-26T10:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the workout was last updated.","example":"2023-10-27T11:30:00.000Z"},"trainer":{"description":"Reference to the trainer associated with the workout.","allOf":[{"$ref":"#/components/schemas/TrainerRef"}]},"name":{"type":"string","description":"Display name of the workout. Localized based on locale query parameter.","example":"Full Body Blast"},"description":{"type":"string","description":"Detailed description of the workout, potentially including goals and target audience. Localized based on locale query parameter.","example":"A 30-minute high-intensity interval training session designed to improve cardiovascular fitness and strength."},"audioIntro":{"description":"Localized workout introduction audio. Selected based on locale query parameter and user preferences.","allOf":[{"$ref":"#/components/schemas/WorkoutAudio"}]},"audioOutro":{"description":"Localized workout outro audio. Selected based on locale query parameter and user preferences.","allOf":[{"$ref":"#/components/schemas/WorkoutAudio"}]},"duration":{"type":"number","description":"Estimated workout duration in seconds.","example":1800},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Raw difficulty enum value (beginner|intermediate|advanced). Clients should map to localized strings. Null if not specified.","example":"beginner"},"preview":{"description":"Links to preview video streams (e.g., HLS, MP4). Null if no preview is available.","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]},"images":{"description":"Links to workout images (thumbnail, cover, etc.). Null if no images are available.","allOf":[{"$ref":"#/components/schemas/ImageLinks"}]},"rating":{"type":"number","description":"Average user rating (e.g., 1-5). Null if not rated.","example":4.5},"visibility":{"type":"string","enum":["private","public"],"description":"Visibility level of the workout.","example":"public"},"locked":{"type":"boolean","description":"Indicates if the workout requires a subscription or specific entitlement to access.","example":false},"mixBgMusic":{"type":"boolean","description":"Whether to mix background music with workout audio. If true, background music will be played alongside exercise instructions.","example":true},"presentationStyle":{"type":"string","enum":["full","minimal","essential","noOverlays"],"description":"Video overlay presentation style. Controls which UI elements are shown during workout playback.","example":"full"},"skipWorkoutPreview":{"type":"boolean","description":"If true, skip workout preview/intro segment in interactive player","example":false},"skipWorkoutCompletionScreen":{"type":"boolean","description":"If true, skip workout completion/outro screen in interactive player","example":false},"videoAudioMode":{"type":"string","enum":["full","instructionsOnly","beepsOnly","none"],"description":"Audio mode for video export. Controls which audio components are included.","example":"full"},"categories":{"description":"List of categories associated with the workout (e.g., HIIT, Strength, Yoga). Category names are localized based on locale query parameter.","type":"array","items":{"$ref":"#/components/schemas/Category"}},"allowAssessment":{"type":"boolean","description":"Whether this workout supports AI assessment mode","example":false},"assessmentType":{"type":"string","enum":["mobility_baseline","glp1_muscle_guard","movement_assessment","overall_assessment","learning_tutorial","learning_practice"],"description":"Type of assessment supported (if allowAssessment is true)","example":"mobility_baseline","nullable":true},"equipment":{"description":"List of equipment required or recommended for the workout. Equipment names are localized based on locale query parameter.","type":"array","items":{"$ref":"#/components/schemas/Equipment"}},"musicPlaylists":{"description":"Links to suggested music playlists on various platforms (Spotify, Apple Music, etc.).","allOf":[{"$ref":"#/components/schemas/MusicPlaylists"}]},"shareLink":{"description":"A shareable link for the workout.","allOf":[{"$ref":"#/components/schemas/ShareLink"}]},"organization":{"description":"Reference to the organization that owns/published this workout, if applicable.","allOf":[{"$ref":"#/components/schemas/Organization"}]},"video":{"description":"Links to the full workout video streams (e.g., HLS, MP4). Use /export/video/stream_url for potentially temporary direct stream URLs.","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]},"muscleGroupPercentages":{"description":"Percentage distribution of muscle groups in this workout, sorted by highest percentage first","type":"array","items":{"$ref":"#/components/schemas/MuscleGroupPercentage"}}},"required":["id","createdAt","updatedAt","trainer","name","description","duration","visibility","locked","categories","equipment","shareLink","muscleGroupPercentages"]},"WorkoutResponse":{"type":"object","properties":{"data":{"description":"Contains the detailed workout object.","allOf":[{"$ref":"#/components/schemas/Workout"}]}},"required":["data"]},"PageLinks":{"type":"object","properties":{"next":{"type":"string","description":"URL of the next page. Missing if there is no next page.","example":"https://content.api.hyperhuman.cc/resource/next-page-link"},"total":{"type":"number","description":"Total number of items available across all pages.","example":100}}},"WorkoutListItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the workout.","example":"12ab3efd45c67c1234566cd1"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the workout was created.","example":"2023-10-26T10:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the workout was last updated.","example":"2023-10-27T11:30:00.000Z"},"trainer":{"description":"Reference to the trainer associated with the workout.","allOf":[{"$ref":"#/components/schemas/TrainerRef"}]},"name":{"type":"string","description":"Display name of the workout. Localized based on locale query parameter.","example":"Full Body Blast"},"description":{"type":"string","description":"Detailed description of the workout, potentially including goals and target audience. Localized based on locale query parameter.","example":"A 30-minute high-intensity interval training session designed to improve cardiovascular fitness and strength."},"audioIntro":{"description":"Localized workout introduction audio. Selected based on locale query parameter and user preferences.","allOf":[{"$ref":"#/components/schemas/WorkoutAudio"}]},"audioOutro":{"description":"Localized workout outro audio. Selected based on locale query parameter and user preferences.","allOf":[{"$ref":"#/components/schemas/WorkoutAudio"}]},"duration":{"type":"number","description":"Estimated workout duration in seconds.","example":1800},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Raw difficulty enum value (beginner|intermediate|advanced). Clients should map to localized strings. Null if not specified.","example":"beginner"},"preview":{"description":"Links to preview video streams (e.g., HLS, MP4). Null if no preview is available.","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]},"images":{"description":"Links to workout images (thumbnail, cover, etc.). Null if no images are available.","allOf":[{"$ref":"#/components/schemas/ImageLinks"}]},"rating":{"type":"number","description":"Average user rating (e.g., 1-5). Null if not rated.","example":4.5},"visibility":{"type":"string","enum":["private","public"],"description":"Visibility level of the workout.","example":"public"},"locked":{"type":"boolean","description":"Indicates if the workout requires a subscription or specific entitlement to access.","example":false},"mixBgMusic":{"type":"boolean","description":"Whether to mix background music with workout audio. If true, background music will be played alongside exercise instructions.","example":true},"presentationStyle":{"type":"string","enum":["full","minimal","essential","noOverlays"],"description":"Video overlay presentation style. Controls which UI elements are shown during workout playback.","example":"full"},"skipWorkoutPreview":{"type":"boolean","description":"If true, skip workout preview/intro segment in interactive player","example":false},"skipWorkoutCompletionScreen":{"type":"boolean","description":"If true, skip workout completion/outro screen in interactive player","example":false},"videoAudioMode":{"type":"string","enum":["full","instructionsOnly","beepsOnly","none"],"description":"Audio mode for video export. Controls which audio components are included.","example":"full"},"categories":{"description":"List of categories associated with the workout (e.g., HIIT, Strength, Yoga). Category names are localized based on locale query parameter.","type":"array","items":{"$ref":"#/components/schemas/Category"}},"allowAssessment":{"type":"boolean","description":"Whether this workout supports AI assessment mode","example":false},"assessmentType":{"type":"string","enum":["mobility_baseline","glp1_muscle_guard","movement_assessment","overall_assessment","learning_tutorial","learning_practice"],"description":"Type of assessment supported (if allowAssessment is true)","example":"mobility_baseline","nullable":true}},"required":["id","createdAt","updatedAt","trainer","name","description","duration","visibility","locked","categories"]},"WorkoutListResponse":{"type":"object","properties":{"links":{"description":"Pagination envelope. Use `links.next` to fetch the next page; `links.total` is the count across all pages and is omitted on endpoints where it is too expensive to compute.","allOf":[{"$ref":"#/components/schemas/PageLinks"}]},"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutListItem"}},"explanation":{"type":"string","description":"Explanation for how this list was filtered or sorted"}},"required":["links","data"]},"EndUserProfileDetailsDto":{"type":"object","properties":{"age":{"type":"number","description":"User age. Maps to age groups (16-24: Young, 25-34: Young Adult, 35-44: Early Middle Age, 45-54: Mid Life, 55-64: Late Middle Age, 65-74: Early Senior, 75+: Senior) for appropriate exercise intensity selection.","minimum":16,"maximum":99,"example":32},"gender":{"type":"string","enum":["male","female","other"],"description":"User gender. Influences coach gender matching preference (not guaranteed match).","example":"female"},"fitnessLevels":{"type":"array","description":"User fitness levels. Only the FIRST level is used for exercise difficulty selection. Provide only one for clarity. AI may adjust actual workout difficulty based on exercise availability and safety considerations.","example":["intermediate"],"items":{"type":"string","enum":["beginner","intermediate","advanced"]}},"goalIds":{"description":"Goal IDs the user is interested in. Currently accepted but not used in workout generation logic.","example":["63c92926f920a9005c4e619c"],"type":"array","items":{"type":"string"}},"trainingDaysPerWeek":{"type":"number","description":"Number of days per week the user wants to train. Currently accepted but not used in workout generation logic.","minimum":1,"maximum":7,"example":4},"preferredEquipmentCategoryIds":{"description":"Preferred equipment category IDs. Used as guidance (not strict filter). AI may include bodyweight exercises for safety. Use GET /v1/workouts/equipment/metadata to fetch available equipment categories.","example":["67deb36a6a5e49797c122f56","67deb3696a5e49797c122f55"],"type":"array","items":{"type":"string"}},"endUserId":{"type":"string","description":"End user profile ID for personalization. When provided, user context (workout history, digest, metrics) is used for AI workout generation and recommendations. Must belong to the same organization as the request.","example":"64e3bca9d1b7e600141a9712"}}},"WorkoutRecommendationRequestDto":{"type":"object","properties":{"endUserProfileDetails":{"description":"Detailed user profile information for personalized recommendations","allOf":[{"$ref":"#/components/schemas/EndUserProfileDetailsDto"}]},"locale":{"type":"string","description":"Preferred BCP-47 locale for recommendation text when the stack supports it.","example":"en-US"}}},"RecommendedWorkoutDto":{"type":"object","properties":{"id":{"type":"string","description":"Workout ID"},"name":{"type":"string","description":"Workout name"},"description":{"type":"string","description":"Workout description"},"duration":{"type":"number","description":"Workout duration in seconds"},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"]},"thumbnailUrl":{"type":"string","description":"URL to workout thumbnail image"},"recommendation":{"type":"string","description":"Reasoning for this recommendation"},"categories":{"description":"Workout categories","items":{"type":"array"},"type":"array"},"preview":{"description":"Preview video (playable URL when available). url is empty when only a thumbnail image exists.","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]}},"required":["id","name","description","duration","difficulty","thumbnailUrl","recommendation","categories"]},"WorkoutRecommendationResponseDto":{"type":"object","properties":{"workouts":{"description":"List of recommended workouts (max 12)","type":"array","items":{"$ref":"#/components/schemas/RecommendedWorkoutDto"}},"reasoning":{"type":"string","description":"Overall explanation for the recommendation strategy used"}},"required":["workouts","reasoning"]},"WorkoutDurationOptionsDto":{"type":"object","properties":{"minMinutes":{"type":"number","description":"Minimum workout duration in minutes","minimum":5,"example":5},"maxMinutes":{"type":"number","description":"Maximum workout duration in minutes","minimum":5,"example":30}}},"WorkoutGenerationRequestDto":{"type":"object","properties":{"endUserProfileDetails":{"description":"Detailed user profile information for personalized workout generation.","allOf":[{"$ref":"#/components/schemas/EndUserProfileDetailsDto"}]},"exerciseSources":{"type":"array","description":"Preferred source(s) of exercises. Use only `premium_stock` for consistent quality, or `team_exercises` for brand consistency. Avoid mixing `free_stock` with `premium_stock` for visual consistency.","example":["premium_stock"],"items":{"type":"string","enum":["premium_stock","free_stock","team_exercises"]}},"durationOptions":{"description":"Preferred workout duration range in minutes. You can specify minimum and maximum duration to generate workouts within a specific time range.","example":{"minMinutes":5,"maxMinutes":30},"allOf":[{"$ref":"#/components/schemas/WorkoutDurationOptionsDto"}]},"categoryId":{"type":"string","description":"Workout category ID to theme the workout. Use GET /v1/workouts/metadata to fetch available categories (HIIT, Strength, Mobility, Cardio, etc.).","example":"615aa3f0dbe7140012c59e94"},"muscleGroupIds":{"description":"Muscle group IDs to focus on during the workout. The workout will be generated with emphasis on exercises that target these muscle groups. Use the GET /v1/workouts/exercises/metadata endpoint to fetch the available muscle groups. Note that this is used for guidance, not as a strict filter - the workout will still include exercises for complementary muscle groups as needed.","example":["604b0129beaba770c284ff40","604b0165076fe2727354d73e"],"type":"array","items":{"type":"string"}},"excludeExerciseCollections":{"description":"Array of exercise collection names to exclude from workout generation. Exercises with matching collectionName (case-insensitive) will be filtered out. Use GET /v1/workouts/exercises/metadata to fetch the current list of available exercise collections with exercise counts.","example":["Free - Eclectic Home","Premium - Industrial"],"type":"array","items":{"type":"string"}},"userRequirements":{"type":"string","description":"High-level context, definitions, and guidelines for workout generation. Provides customer-specific grounding (e.g., \"intermediate osteoporosis strength training\", \"one-sided exercises, rep schemes\"). Used to inform exercise selection, intensity, and structure.","example":"Intermediate strength / stimulus, one-sided exercises, rep schemes. Focus on controlled movements suitable for osteoporosis patients.","maxLength":2000}}},"ApiExerciseDto":{"type":"object","properties":{"id":{"type":"string","description":"Exercise id (24-character hex DB id)"},"name":{"type":"string","description":"Name of the exercise"},"description":{"type":"string","description":"Description of the exercise"},"thumbnailUrl":{"type":"string","description":"Thumbnail URL for the exercise video"},"videoUri":{"type":"string","description":"Main video URI (e.g., signed S3 URL for MP4 or HLS master)"},"estimatedRepDuration":{"type":"number","description":"Estimated duration of one repetition in milliseconds"},"muscleGroups":{"description":"Primary muscle groups targeted","type":"array","items":{"type":"string"}},"equipment":{"description":"Equipment needed for this exercise","type":"array","items":{"type":"string"}},"collectionName":{"type":"string","description":"Collection name (free text)"},"coach":{"type":"string","enum":["male","female"],"description":"Coach gender"},"tags":{"description":"User-defined tags (up to 5)","type":"array","items":{"type":"string"}},"skillLevel":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Skill level"},"categories":{"type":"array","description":"Exercise categories (up to 3)","items":{"type":"string","enum":["strength","cardio","mobility","balance","endurance","flexibility","plyometrics","recovery","running"]}},"executionSide":{"type":"string","enum":["both","left","right","alternating"],"description":"Execution side"},"showcasedReps":{"type":"number","description":"Showcased number of reps"}},"required":["id","name"]},"ApiInstanceDto":{"type":"object","properties":{"id":{"type":"string","description":"Instance id (24-character hex DB id)"},"kind":{"type":"string","enum":["rest","single-exercise","multi-exercise","class","promo","educational"],"description":"Kind of instance (e.g., rest, singleExercise)"},"durationSeconds":{"type":"number","description":"Duration in seconds (for time-based exercises and rests). Check service implementation for actual unit and convert if necessary."},"reps":{"type":"number","description":"Number of repetitions (for reps-based exercises)"},"exercise":{"description":"Exercise details, if this instance is an exercise.","allOf":[{"$ref":"#/components/schemas/ApiExerciseDto"}]},"skipIntro":{"type":"boolean","description":"Whether to skip intro for the exercise video."},"pace":{"type":"string","enum":["slow","medium","fast"],"nullable":true,"description":"Pacing for time-based exercises."},"weightLevel":{"type":"string","enum":["light","medium","heavy"],"nullable":true,"description":"Weight level for reps-based exercises."},"rpe":{"type":"number","description":"Rate of Perceived Exertion (0-10). Target intensity for this exercise. When not provided, no specific RPE guidance.","minimum":0,"maximum":10},"amrap":{"type":"boolean","description":"As Many Reps As Possible (duration-based only)","default":false},"weight":{"type":"number","description":"Prescribed/target weight (0-1000). Unit in weightUnit.","minimum":0,"maximum":1000},"weightUnit":{"type":"string","enum":["metric","imperial"],"description":"Unit for weight: metric (kg) or imperial (lbs)."}},"required":["id","kind"]},"WorkoutGenerationResponseDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the generated workout."},"instances":{"description":"List of instances (exercises and rests) in the workout.","type":"array","items":{"$ref":"#/components/schemas/ApiInstanceDto"}},"totalDurationSeconds":{"type":"number","description":"Estimated total duration of the workout in seconds. Calculated if possible."},"difficulty":{"type":"string","description":"Overall difficulty of the workout, as determined or used by the generator."},"categoryId":{"type":"string","description":"The category ID used for generating the workout."}},"required":["name","instances"]},"AdaptationEndUserProfileDetailsDto":{"type":"object","properties":{"age":{"type":"number","description":"User age","minimum":16,"maximum":99,"example":32},"gender":{"type":"string","enum":["male","female","other"],"description":"User gender","example":"female"},"fitnessLevels":{"type":"array","description":"User fitness levels. First level is primary.","example":["intermediate"],"items":{"type":"string","enum":["beginner","intermediate","advanced"]}},"goalIds":{"description":"Goal IDs","example":["63c92926f920a9005c4e619c"],"type":"array","items":{"type":"string"}},"trainingDaysPerWeek":{"type":"number","description":"Training days per week","minimum":1,"maximum":7,"example":4},"preferredEquipmentCategoryIds":{"description":"Preferred equipment category IDs","type":"array","items":{"type":"string"}}}},"WorkoutAdaptationRequestDto":{"type":"object","properties":{"endUserProfileId":{"type":"string","description":"End user profile ID for fetching 60-day wearable data, workout feedback, and completed sessions","example":"64e3bca9d1b7e600141a9712"},"endUserProfileDetails":{"description":"User profile information for workout adaptation","allOf":[{"$ref":"#/components/schemas/AdaptationEndUserProfileDetailsDto"}]},"exerciseSources":{"type":"array","description":"Exercise sources for potential substitutions","example":["premium_stock","team_exercises"],"items":{"type":"string","enum":["premium_stock","free_stock","team_exercises"]}},"userGuidance":{"type":"string","description":"User free text for guidance/feedback/context/injury/environment/constraints","example":"I have a slight knee injury, avoid high-impact exercises. Working out at home with limited space.","maxLength":2000}},"required":["endUserProfileDetails","exerciseSources"]},"WorkoutAdaptationResponseDto":{"type":"object","properties":{"name":{"type":"string","description":"Adapted workout name"},"instances":{"description":"Adapted instances","type":"array","items":{"$ref":"#/components/schemas/ApiInstanceDto"}},"totalDurationSeconds":{"type":"number","description":"Total duration in seconds"},"difficulty":{"type":"string","description":"Adapted workout difficulty"},"categoryId":{"type":"string","description":"Original category ID (preserved)"},"adaptationReasoning":{"type":"string","description":"Explanation of adaptations made"}},"required":["name","instances","adaptationReasoning"]},"AutopilotTaskResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Task ID"},"organizationId":{"type":"string","description":"Organization ID"},"ownerId":{"type":"string","description":"Task owner ID"},"name":{"type":"string","description":"Task name"},"status":{"type":"string","enum":["active","draft"],"description":"Task status"},"scope":{"type":"string","enum":["ai_generate","create_similar","publish_existing"],"description":"Task scope"},"contentType":{"type":"string","enum":["workout","program"],"description":"Content type"},"sourceContentId":{"type":"string","description":"Source content ID (for create_similar)"},"existingContentId":{"type":"string","description":"Existing content ID (for publish_existing)"},"categoryIds":{"description":"Category IDs","type":"array","items":{"type":"string"}},"goalIds":{"description":"Goal IDs","type":"array","items":{"type":"string"}},"durationMin":{"type":"number","description":"Min duration"},"durationMax":{"type":"number","description":"Max duration"},"workoutsPerWeekMin":{"type":"number","description":"Min workouts per week"},"workoutsPerWeekMax":{"type":"number","description":"Max workouts per week"},"difficultyOptions":{"description":"Difficulty options","type":"array","items":{"type":"string"}},"includeFreeStock":{"type":"boolean","description":"Include free stock exercises"},"includePremiumStock":{"type":"boolean","description":"Include premium stock exercises"},"includeTeamContent":{"type":"boolean","description":"Include team exercises"},"repeatMode":{"type":"string","enum":["once","daily","weekly","biweekly","monthly"],"description":"Repeat schedule"},"repeatUntil":{"format":"date-time","type":"string","description":"Repeat until date"},"nextRunAt":{"type":"object","description":"Next scheduled execution","format":"date-time","nullable":true},"lastRunAt":{"type":"object","description":"Last execution time","format":"date-time","nullable":true},"assignToClientUserIds":{"description":"Client user IDs for content assignment","type":"array","items":{"type":"string"}},"promptGuidanceMode":{"type":"string","enum":["none","custom","ai_tuned","ai_driven"],"description":"Prompt guidance mode"},"customPromptGuidance":{"type":"string","description":"Custom prompt guidance text"},"createdAt":{"format":"date-time","type":"string","description":"Created at"},"updatedAt":{"format":"date-time","type":"string","description":"Updated at"}},"required":["id","organizationId","ownerId","name","status","scope","contentType","difficultyOptions","includeFreeStock","includePremiumStock","includeTeamContent","repeatMode","createdAt","updatedAt"]},"CreateAutopilotTaskDto":{"type":"object","properties":{"name":{"type":"string","description":"User-friendly task name (max 200 chars)","example":"Daily HIIT Generator"},"scope":{"type":"string","enum":["ai_generate","create_similar","publish_existing"],"description":"Task scope: ai_generate, create_similar, or publish_existing"},"contentType":{"type":"string","enum":["workout","program"],"description":"Content type to create: workout or program"},"sourceContentId":{"type":"string","description":"Source workout/program ID (required for create_similar scope)"},"existingContentId":{"type":"string","description":"Existing workout/program ID (required for publish_existing scope)"},"categoryIds":{"description":"Workout category IDs. One picked randomly per run when multiple.","type":"array","items":{"type":"string"}},"goalIds":{"description":"Program goal IDs. One picked randomly per run when multiple.","type":"array","items":{"type":"string"}},"durationMin":{"type":"number","description":"Min duration (minutes for workouts, weeks for programs)","minimum":1},"durationMax":{"type":"number","description":"Max duration (minutes for workouts, weeks for programs). Must be >= durationMin.","minimum":1},"workoutsPerWeekMin":{"type":"number","description":"Min workouts per week (programs only)","minimum":1,"maximum":7},"workoutsPerWeekMax":{"type":"number","description":"Max workouts per week (programs only). Must be >= workoutsPerWeekMin.","minimum":1,"maximum":7},"difficultyOptions":{"type":"array","description":"Difficulty options (1-3 values). One picked randomly per run when multiple.","example":["beginner","intermediate"],"items":{"type":"string","enum":["beginner","intermediate","advanced"]}},"includeFreeStock":{"type":"boolean","description":"Include free stock exercises","default":true},"includePremiumStock":{"type":"boolean","description":"Include premium stock exercises (requires premiumStock entitlement)","default":false},"includeTeamContent":{"type":"boolean","description":"Include team exercises","default":false},"repeatMode":{"type":"string","enum":["once","daily","weekly","biweekly","monthly"],"description":"Repeat schedule: once, daily, weekly, biweekly, monthly"},"repeatUntil":{"type":"string","description":"Repeat until date (ISO 8601). Omit for indefinite scheduling."},"nextRunAt":{"type":"string","description":"Initial scheduled execution date (ISO 8601). When omitted, computed on activation."},"assignToClientUserIds":{"description":"Client user IDs to assign created content to (max 100)","type":"array","items":{"type":"string"}},"promptGuidanceMode":{"type":"string","enum":["none","custom","ai_tuned","ai_driven"],"description":"Prompt guidance mode: none, custom, ai_tuned, ai_driven","default":"none"},"customPromptGuidance":{"type":"string","description":"Custom prompt guidance text (max 2000 chars). Used when promptGuidanceMode is custom.","maxLength":2000}},"required":["name","scope","contentType","difficultyOptions","repeatMode"]},"UpdateAutopilotTaskDto":{"type":"object","properties":{"name":{"type":"string","description":"Task name (max 200 chars)"},"categoryIds":{"description":"Workout category IDs","type":"array","items":{"type":"string"}},"goalIds":{"description":"Program goal IDs","type":"array","items":{"type":"string"}},"durationMin":{"type":"number","description":"Min duration"},"durationMax":{"type":"number","description":"Max duration"},"workoutsPerWeekMin":{"type":"number","description":"Min workouts per week (programs only)"},"workoutsPerWeekMax":{"type":"number","description":"Max workouts per week (programs only)"},"difficultyOptions":{"type":"array","description":"Difficulty options","items":{"type":"string","enum":["beginner","intermediate","advanced"]}},"includeFreeStock":{"type":"boolean","description":"Include free stock exercises"},"includePremiumStock":{"type":"boolean","description":"Include premium stock exercises"},"includeTeamContent":{"type":"boolean","description":"Include team exercises"},"repeatMode":{"type":"string","enum":["once","daily","weekly","biweekly","monthly"],"description":"Repeat schedule"},"repeatUntil":{"type":"string","description":"Repeat until date (ISO 8601)"},"nextRunAt":{"type":"string","description":"Next run date (ISO 8601). Use to reschedule an active task."},"assignToClientUserIds":{"description":"Client user IDs to assign content to","type":"array","items":{"type":"string"}},"promptGuidanceMode":{"type":"string","enum":["none","custom","ai_tuned","ai_driven"],"description":"Prompt guidance mode"},"customPromptGuidance":{"type":"string","description":"Custom prompt guidance text (max 2000 chars)","maxLength":2000}}},"ExportDropDto":{"type":"object","properties":{"channelPreset":{"type":"string","enum":["ig_reels","ig_stories","ig_carousel","tiktok","yt_shorts","fb_reels","yt_longform"],"description":"Channel preset; if omitted, uses drop channelPreset"},"aspectRatio":{"type":"string","enum":["9:16","1:1","16:9"],"description":"Aspect ratio override"},"duration":{"type":"number","enum":[15,30,60],"description":"Duration in seconds override"}}},"OrganizationConnectedPlatformsResponseDto":{"type":"object","properties":{"connectedPlatforms":{"type":"array","description":"Social platforms (instagram, tiktok, youtube, facebook) that have a connected account id stored for this organization","items":{"type":"string","enum":["instagram","tiktok","youtube","facebook"]}}},"required":["connectedPlatforms"]},"OrganizationSocialPublishTaskResponseDto":{"type":"object","properties":{"_id":{"type":"string","deprecated":true,"description":"Deprecated. Legacy internal id; use `id` instead. Will be removed in the next major Content API release."},"_teamId":{"type":"string","deprecated":true,"description":"Deprecated. Legacy internal team id; use `organizationId` instead. Will be removed in the next major Content API release."},"_ownerId":{"type":"string","deprecated":true,"description":"Deprecated. Legacy internal owner id; use `ownerId` instead. Will be removed in the next major Content API release."},"name":{"type":"string"},"status":{"type":"string","enum":["active","draft"]},"publishAssetType":{"type":"string","enum":["social_drop","workout_full_video"]},"sourceMode":{"type":"string","enum":["manual_fixed","random_ready","ai_insights","ai_pick"]},"dropId":{"type":"string"},"workoutId":{"type":"string"},"publishCopyPacks":{"type":"object","description":"workout_full_video: sanitized copy packs per channel (same shape as drop copyPacks)."},"workoutExportLocale":{"type":"string"},"coverOverridesByChannel":{"type":"object","description":"workout_full_video: S3 object keys for social/AI covers by channel preset and aspect ratio (same shape as Drop.coverOverridesByChannel). Not workout library thumbnails."},"readyDropPick":{"type":"string","enum":["random","latest"]},"allowedDropSourceTypes":{"type":"array","items":{"type":"string","enum":["exercise","exerciseCollection","workout","workoutCollection"]}},"primaryChannelPreset":{"type":"string","enum":["ig_reels","ig_stories","ig_carousel","tiktok","yt_shorts","fb_reels","yt_longform"]},"channelPresets":{"type":"array","items":{"type":"string","enum":["ig_reels","ig_stories","ig_carousel","tiktok","yt_shorts","fb_reels","yt_longform"]}},"exportAspectRatio":{"type":"string","enum":["9:16","1:1","16:9"]},"exportDurationSeconds":{"type":"number","enum":[15,30,60]},"repeatMode":{"type":"string","enum":["once","daily","weekly","biweekly","monthly"]},"repeatUntil":{"type":"object","nullable":true},"nextRunAt":{"type":"object"},"lastRunAt":{"type":"object"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"id":{"type":"string","description":"Automation ID. Use this for all subsequent /v1/orgs/{orgId}/social-publish/{taskId} calls."},"organizationId":{"type":"string","description":"Organization (team) ID that owns this automation."},"ownerId":{"type":"string","description":"User ID of the organization owner that the automation runs on behalf of."},"lastRunOutcome":{"type":"string","enum":["success","failed","skipped_limit","skipped_no_drop","skipped_no_workout_export","skipped_zernio_config"],"description":"Outcome of the most recent execution event for this automation"},"lastErrorSummary":{"type":"string","description":"Error or skip message from the most recent execution when it was not a success"},"lastExecutionAt":{"format":"date-time","type":"string","description":"Timestamp of the most recent execution event"}},"required":["name","status","publishAssetType","sourceMode","readyDropPick","allowedDropSourceTypes","primaryChannelPreset","channelPresets","repeatMode","createdAt","updatedAt","id","organizationId","ownerId"]},"OrganizationSocialPublishTaskListResponse":{"type":"object","properties":{"links":{"description":"Pagination envelope. Use `links.next` to fetch the next page; `links.total` is the count across all pages and is omitted on endpoints where it is too expensive to compute.","allOf":[{"$ref":"#/components/schemas/PageLinks"}]},"data":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationSocialPublishTaskResponseDto"}}},"required":["links","data"]},"CreateSocialDropPublishTaskDto":{"type":"object","properties":{"name":{"type":"string","description":"Automation name"},"publishAssetType":{"type":"string","enum":["social_drop","workout_full_video"],"description":"Defaults to social_drop. Use workout_full_video for full WorkoutExport video (not a social drop)."},"sourceMode":{"type":"string","enum":["manual_fixed","random_ready","ai_insights","ai_pick"],"description":"Required for social_drop automations. When publishAssetType is workout_full_video, omit to default to manual_fixed."},"dropId":{"type":"string","description":"Required when sourceMode is manual_fixed and publishAssetType is social_drop"},"workoutId":{"type":"string","description":"Required when publishAssetType is workout_full_video"},"publishCopyPacks":{"type":"object","description":"workout_full_video: copy packs per channel (same fields as drop copyPacks). The outbound publish payload uses copy for primaryChannelPreset; if hook and caption are both empty at run time, Gemini generates and the result is saved on the task."},"workoutExportLocale":{"type":"string","description":"Locale for choosing WorkoutExport variant when publishAssetType is workout_full_video"},"locale":{"type":"string","description":"Alias for workoutExportLocale when publishAssetType is workout_full_video. If both are set, workoutExportLocale wins."},"readyDropPick":{"type":"string","enum":["random","latest"],"description":"For random_ready / ai_insights: random among up to 80 most recently updated ready drops, or single latest by updatedAt. Ignored for manual_fixed.","default":"random"},"allowedDropSourceTypes":{"type":"array","description":"Pool of drop source types (exercise=clip/video, exerciseCollection=exercise groups, workout, workoutCollection=program). Omit or empty = all types.","items":{"type":"string","enum":["exercise","exerciseCollection","workout","workoutCollection"]}},"primaryChannelPreset":{"type":"string","enum":["ig_reels","ig_stories","ig_carousel","tiktok","yt_shorts","fb_reels","yt_longform"]},"channelPresets":{"type":"array","description":"Target channel presets for publishing; must include primary.","items":{"type":"string","enum":["ig_reels","ig_stories","ig_carousel","tiktok","yt_shorts","fb_reels","yt_longform"]}},"repeatMode":{"type":"string","enum":["once","daily","weekly","biweekly","monthly"]},"repeatUntil":{"type":"string","description":"Repeat until (ISO 8601)"},"nextRunAt":{"type":"string","description":"Next run (ISO 8601)"},"exportAspectRatio":{"type":"string","enum":["9:16","1:1","16:9"],"description":"Export variant aspect ratio override"},"exportDurationSeconds":{"type":"number","enum":[15,30,60],"description":"Export variant duration override (seconds)"}},"required":["name","primaryChannelPreset","channelPresets","repeatMode"]},"OrganizationPatchSocialPublishTaskDto":{"type":"object","properties":{"name":{"type":"string"},"publishAssetType":{"type":"string","enum":["social_drop","workout_full_video"]},"sourceMode":{"type":"string","enum":["manual_fixed","random_ready","ai_insights","ai_pick"]},"dropId":{"type":"object","nullable":true,"description":"Id of the drop, or null to clear (omit to leave unchanged)"},"workoutId":{"type":"object","nullable":true,"description":"Id of the workout, or null to clear (omit to leave unchanged)"},"publishCopyPacks":{"type":"object","description":"workout_full_video: merges into existing publishCopyPacks by channel key (same semantics as PATCH drop copyPacks)."},"workoutExportLocale":{"type":"object"},"locale":{"type":"object","description":"Alias for workoutExportLocale on workout_full_video tasks. If both are set in one request, workoutExportLocale wins."},"readyDropPick":{"type":"string","enum":["random","latest"]},"allowedDropSourceTypes":{"type":"array","items":{"type":"string","enum":["exercise","exerciseCollection","workout","workoutCollection"]}},"primaryChannelPreset":{"type":"string","enum":["ig_reels","ig_stories","ig_carousel","tiktok","yt_shorts","fb_reels","yt_longform"]},"channelPresets":{"type":"array","items":{"type":"string","enum":["ig_reels","ig_stories","ig_carousel","tiktok","yt_shorts","fb_reels","yt_longform"]}},"repeatMode":{"type":"string","enum":["once","daily","weekly","biweekly","monthly"]},"repeatUntil":{"type":"object","nullable":true,"description":"ISO 8601 end of recurrence, or null to clear"},"nextRunAt":{"type":"string"},"exportAspectRatio":{"type":"string","enum":["9:16","1:1","16:9"]},"exportDurationSeconds":{"type":"number","enum":[15,30,60]},"status":{"type":"string","enum":["active","draft"],"description":"Set to active to schedule runs (requires connected accounts for all channel preset platforms). Set to draft to pause and clear nextRunAt."}}},"WorkoutPlaylistResponse":{"type":"object","properties":{"data":{"description":"An ordered array of workout segments. Each object in the array has a single key indicating the segment type (e.g., 'intro', 'exercise', 'break') and the value is the corresponding segment object.","example":[{"intro":{"kind":"workout-intro","id":"intro","duration":5.2}},{"narrative":{"kind":"workout-narrative","id":"narrative_background","duration":1800}},{"exercise":{"kind":"exercise","id":"exercise_squats_1","exerciseId":"507f1f77bcf86cd799439011","duration":45,"name":"Bodyweight Squats"}},{"break":{"kind":"break","id":"break_1","duration":30}},{"exercise":{"kind":"exercise","id":"exercise_pushups_1","exerciseId":"507f1f77bcf86cd799439012","duration":45,"name":"Push-ups"}},{"outro":{"kind":"workout-outro","id":"outro","duration":45.5}}],"type":"array","items":{"type":"string"}},"presentationStyle":{"type":"string","enum":["full","minimal","essential","noOverlays"],"description":"Video overlay presentation style for this workout. Determines which UI elements the player should render. Null if not specified.","example":"full"},"links":{"type":"object","description":"Related links for the workout playlist (currently unused).","example":{}}},"required":["data","links"]},"WorkoutMusicTrack":{"type":"object","properties":{"id":{"type":"string","description":"Track ID","example":"track_123"},"name":{"type":"string","description":"Track name","example":"Upbeat Workout Mix"},"duration":{"type":"number","description":"Track duration in seconds","example":180},"url":{"type":"string","description":"Pre-signed S3 URL for the track","example":"https://s3.amazonaws.com/bucket/track.mp4a?signature=..."},"filename":{"type":"string","description":"Track filename","example":"upbeat-mix.mp4a"},"bpm":{"type":"number","description":"Track BPM (beats per minute)","example":128}},"required":["id","name","duration","url"]},"WorkoutMusicPlaylistResponse":{"type":"object","properties":{"tracks":{"description":"Ordered list of music tracks","type":"array","items":{"$ref":"#/components/schemas/WorkoutMusicTrack"}},"totalDuration":{"type":"number","description":"Total playlist duration in seconds","example":1800},"workoutDuration":{"type":"number","description":"Workout duration in seconds","example":1650}},"required":["tracks","totalDuration","workoutDuration"]},"WorkoutSession":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the workout session.","example":"12ab3efd45c67c1234566cd1"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the session was created.","example":"2023-10-28T10:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the session was last updated.","example":"2023-10-28T10:30:15.500Z"},"workoutId":{"type":"string","description":"ID of the workout associated with this session.","example":"12ab3efd45c67c1234566cd1"},"workoutSegmentId":{"type":"string","description":"ID of the current workout segment being played (from playlist). Use this to track which part of the workout the user is on.","example":"seg-exercise-2"},"status":{"type":"string","description":"Current status of the workout session.","enum":["started","completed"],"example":"started"},"duration":{"type":"number","description":"Total actual playback time in seconds (not including pauses). This is the duration the user has been actively engaged with the workout.","example":125.5,"minimum":0},"progress":{"type":"number","description":"Completion progress as a fraction (0.0 = not started, 1.0 = 100% complete). Calculated based on current segment position within the total workout.","example":0.75,"minimum":0,"maximum":1}},"required":["id","createdAt","updatedAt","workoutId","workoutSegmentId","status","duration","progress"]},"WorkoutSessionResponse":{"type":"object","properties":{"data":{"description":"Contains the detailed workout session object.","allOf":[{"$ref":"#/components/schemas/WorkoutSession"}]}},"required":["data"]},"PatchWorkoutSessionBody":{"type":"object","properties":{"workoutSegmentId":{"type":"string","description":"ID of the current workout segment.","example":"seg-exercise-squat-1"},"progressSeconds":{"type":"number","description":"Actual playback time in seconds. This is the primary method for tracking session duration accurately. Send this value on each PATCH to record how much time the user has actually spent playing the workout (excluding paused time). Duration is capped at 2x the expected workout duration.","example":125.5,"minimum":0},"state":{"type":"string","description":"[Deprecated] This field is accepted for backward compatibility but does not affect duration calculation. Duration is tracked via progressSeconds.","enum":["active","paused"],"example":"paused","deprecated":true}}},"EndWorkoutSessionBody":{"type":"object","properties":{"sessionId":{"type":"string","description":"The ID of the session to end.","example":"session-uuid-12345"},"progress":{"type":"number","description":"[Deprecated] This field is accepted but the actual progress is calculated from the last progressSeconds sent via PATCH.","example":100,"deprecated":true}},"required":["sessionId"]},"CompleteWorkoutSessionBody":{"type":"object","properties":{"sessionId":{"type":"string","description":"The ID of the specific workout session to mark as completed with 100% progress.","example":"session-uuid-12345"}},"required":["sessionId"]},"WorkoutFeedbackRatingOption":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this rating option","example":"507f1f77bcf86cd799439011"},"label":{"type":"string","description":"Human-readable label for this rating option","example":"Very Good"},"value":{"type":"number","description":"Numeric value representing this rating","example":4,"minimum":1,"maximum":5}},"required":["id","label","value"]},"WorkoutFeedbackDifficultyOption":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this difficulty option","example":"507f1f77bcf86cd799439012"},"label":{"type":"string","description":"Human-readable label for this difficulty level","example":"Challenging"},"value":{"type":"number","description":"Numeric value representing this difficulty level","example":4,"minimum":1,"maximum":5}},"required":["id","label","value"]},"WorkoutFeedbackOptions":{"type":"object","properties":{"rating":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutFeedbackRatingOption"}},"difficulty":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutFeedbackDifficultyOption"}}},"required":["rating","difficulty"]},"WorkoutFeedbackOptionsResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkoutFeedbackOptions"}},"required":["data"]},"ExerciseFeedbackData":{"type":"object","properties":{"instanceId":{"type":"string","description":"Instance ID from workout playlist segment","example":"64f1a2b3c4d5e6f7a8b9c0d1"},"weight":{"type":"number","description":"Weight used for this exercise (in the unit specified by weightUnit). Can be provided alone or together with reps.","minimum":0,"maximum":1000,"example":25.5},"reps":{"type":"number","description":"Number of reps completed. Can be provided alone or together with weight. Required for AMRAP/time-based exercises or rep-based exercises.","minimum":1,"maximum":100,"example":15}},"required":["instanceId"]},"SubmitWorkoutFeedbackBody":{"type":"object","properties":{"workoutSessionId":{"type":"string","description":"The ID of the completed workout session this feedback pertains to.","example":"12ab3efd45c67c1234566cd1"},"ratingId":{"type":"string","description":"Overall rating option ID. Refer to `GET /workouts/feedback/options` for possible values.","example":"rating-opt-5star"},"difficultyId":{"type":"string","description":"Perceived difficulty option ID. Refer to `GET /workouts/feedback/options` for possible values.","example":"difficulty-opt-moderate"},"comment":{"type":"string","description":"Optional free-text user comment about the workout.","example":"Great workout, but the music was a bit too loud.","maxLength":1000},"weightUnit":{"type":"string","enum":["metric","imperial"],"description":"Unit system for weight values. Required if exerciseData contains weight values.","example":"metric"},"exerciseData":{"description":"Exercise-specific data (weights and reps) in the same order as workout playlist (excluding rest segments).","type":"array","items":{"$ref":"#/components/schemas/ExerciseFeedbackData"}}},"required":["workoutSessionId"]},"ExerciseFeedbackDataResponse":{"type":"object","properties":{"instanceId":{"type":"string","description":"Instance ID from workout playlist identifying which exercise this feedback is for","example":"64f1a2b3c4d5e6f7a8b9c0d2"},"weight":{"type":"number","description":"Weight used for this exercise (in weightUnit specified in feedback)","example":25.5},"reps":{"type":"number","description":"Number of repetitions completed for this exercise","example":12,"minimum":0}},"required":["instanceId"]},"WorkoutFeedback":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this feedback record","example":"67d1a2b3c4e5f6789abc0d2"},"createdAt":{"format":"date-time","type":"string","description":"When this feedback was submitted","example":"2025-01-10T09:30:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"When this feedback was last updated","example":"2025-01-10T09:30:00.000Z"},"workoutId":{"type":"string","description":"ID of the workout this feedback is for","example":"12ab3efd45c67c1234566cd1"},"workoutSessionId":{"type":"string","description":"ID of the workout session this feedback is associated with","example":"67d1a2b3c4e5f6789abc0d1"},"rating":{"nullable":true,"description":"User rating of the workout experience","allOf":[{"$ref":"#/components/schemas/WorkoutFeedbackRatingOption"}]},"difficulty":{"nullable":true,"description":"User assessment of workout difficulty level","allOf":[{"$ref":"#/components/schemas/WorkoutFeedbackDifficultyOption"}]},"comment":{"type":"string","description":"Optional user comment or additional feedback","nullable":true,"example":"Great workout! Felt appropriately challenging."},"weightUnit":{"type":"string","enum":["metric","imperial"],"nullable":true,"description":"Unit system used for weight measurements","example":"metric"},"exerciseData":{"nullable":true,"description":"Detailed performance data for individual exercises","type":"array","items":{"$ref":"#/components/schemas/ExerciseFeedbackDataResponse"}}},"required":["id","createdAt","updatedAt","workoutId","workoutSessionId","rating","difficulty"]},"WorkoutFeedbackResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkoutFeedback"}},"required":["data"]},"MuscleGroup":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the muscle group.","example":"mg-legs-abc"},"name":{"type":"string","description":"Display name of the muscle group. Localized based on locale query parameter.","example":"Legs"}},"required":["id","name"]},"ExerciseBundleRefDto":{"type":"object","properties":{"id":{"type":"string","description":"Bundle ID"},"bundleIdentifier":{"type":"string","description":"Asensei bundle identifier"},"downloadUrl":{"type":"string","description":"Pre-signed download URL for bundle JSON content"},"displayName":{"type":"string","description":"Human-readable display name"}},"required":["id","bundleIdentifier","downloadUrl"]},"AudioDto":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"assetUri":{"type":"string"},"type":{"type":"string"},"locale":{"type":"string"},"scriptText":{"type":"string","description":"Verbatim transcript / script of the spoken instruction (the text the narrator reads in the `assetUri` clip). Useful for closed captions, accessibility, search indexing, and AI summarization. Optional: legacy or stock recordings without a stored script omit this field.","example":"Stand tall with your feet shoulder-width apart. Lower into a squat, keeping your chest up."}},"required":["id","createdAt","assetUri","type","locale"]},"VideoAssetListItem":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"trainer":{"description":"Creator reference for the workspace member who owns this asset in Hyperhuman Teams. The JSON field name remains `trainer` for API compatibility.","allOf":[{"$ref":"#/components/schemas/TrainerRef"}]},"name":{"type":"string"},"kind":{"type":"string","enum":["single-exercise","multi-exercise","class","promo","educational"],"description":"Video kind. See the VIDEO TYPE GUIDE on the list operation for product names and audio behavior."},"muscleGroups":{"type":"array","items":{"$ref":"#/components/schemas/MuscleGroup"}},"equipment":{"type":"array","items":{"$ref":"#/components/schemas/Equipment"}},"preview":{"description":"Preview video stream","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]},"collectionName":{"type":"string"},"coach":{"type":"string","enum":["male","female"]},"tags":{"type":"array","items":{"type":"string"}},"skillLevel":{"type":"string","enum":["beginner","intermediate","advanced"]},"categories":{"type":"array","items":{"type":"string","enum":["strength","cardio","mobility","balance","endurance","flexibility","plyometrics","recovery","running"]}},"executionSide":{"type":"string","enum":["both","left","right","alternating"]},"showcasedReps":{"type":"number"},"bundle":{"description":"Asensei movement bundle for this exercise","allOf":[{"$ref":"#/components/schemas/ExerciseBundleRefDto"}]},"playsInLoop":{"type":"boolean","description":"When true, preview playback is intended to loop (for example smart clips aligned with reps or duration)."},"organization":{"nullable":true,"description":"Workspace (organization) this exercise belongs to. `null` when the workspace cannot be resolved.","allOf":[{"$ref":"#/components/schemas/Organization"}]},"audioInstructions":{"description":"Locale-specific instruction audio tracks. Emitted only for `kind: single-exercise` (the smart-clip product type that strips original audio in favor of multilingual instructions). When `?locale=` is supplied, narrowed to matching locales via the standard locale chain (English fallback); when omitted, returns all available locales so catalog UIs can render a \"languages available\" indicator. Empty array for `single-exercise` rows that have not yet been narrated. Always empty for the other kinds (`multi-exercise`, `educational`, `promo`, `class`) which keep their original audio baked into the video. Currently populated by `GET /v1/orgs/{organizationId}/video-assets`; other endpoints that share this list-item shape do not yet emit this field.","type":"array","items":{"$ref":"#/components/schemas/AudioDto"}}},"required":["id","createdAt","trainer","name","kind","muscleGroups","equipment","playsInLoop","organization"]},"VideoAssetsListResponse":{"type":"object","properties":{"links":{"description":"Pagination envelope. Use `links.next` to fetch the next page; `links.total` is the count across all pages and is omitted on endpoints where it is too expensive to compute.","allOf":[{"$ref":"#/components/schemas/PageLinks"}]},"data":{"type":"array","items":{"$ref":"#/components/schemas/VideoAssetListItem"}},"explanation":{"type":"string","description":"Explanation for how this list was filtered or scoped."}},"required":["links","data"]},"TimeBasedConfig":{"type":"object","properties":{"kind":{"type":"string","enum":["timeBased"]},"duration":{"type":"number"},"pace":{"type":"string","enum":["slow","medium","fast"],"nullable":true},"weightLevel":{"type":"string","enum":["light","medium","heavy"],"nullable":true},"rpe":{"type":"number","description":"Rate of Perceived Exertion (0-10). Target intensity level for this exercise.","minimum":0,"maximum":10},"amrap":{"type":"boolean","description":"As Many Reps As Possible mode. Only applicable for time-based exercises."}},"required":["kind","duration"]},"RepsBasedConfig":{"type":"object","properties":{"kind":{"type":"string","enum":["repsBased"]},"reps":{"type":"number"},"weightLevel":{"type":"string","enum":["light","medium","heavy"],"nullable":true},"pace":{"type":"string","enum":["slow","medium","fast"],"nullable":true},"rpe":{"type":"number","description":"Rate of Perceived Exertion (0-10). Target intensity level for this exercise.","minimum":0,"maximum":10}},"required":["kind","reps"]},"SingleExerciseConfig":{"type":"object","properties":{"timeBasedConfig":{"description":"Time based configuration","allOf":[{"$ref":"#/components/schemas/TimeBasedConfig"}]},"repsBasedConfig":{"description":"Reps based configuration","allOf":[{"$ref":"#/components/schemas/RepsBasedConfig"}]}}},"GroupListItem":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"trainer":{"$ref":"#/components/schemas/TrainerRef"},"name":{"type":"string"},"kind":{"type":"string","enum":["circuit","sets"]},"preview":{"description":"Preview video stream","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]},"rounds":{"type":"number"},"roundBreakDuration":{"type":"number"},"exerciseBreakDuration":{"type":"number"},"exerciseConfig":{"$ref":"#/components/schemas/SingleExerciseConfig"}},"required":["id","createdAt","updatedAt","trainer","name","kind","rounds","roundBreakDuration","exerciseBreakDuration","exerciseConfig"]},"GroupListResponse":{"type":"object","properties":{"links":{"description":"Pagination envelope. Use `links.next` to fetch the next page; `links.total` is the count across all pages and is omitted on endpoints where it is too expensive to compute.","allOf":[{"$ref":"#/components/schemas/PageLinks"}]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GroupListItem"}},"explanation":{"type":"string","description":"Explanation for how this list was filtered or sorted"}},"required":["links","data"]},"Group":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"trainer":{"$ref":"#/components/schemas/TrainerRef"},"name":{"type":"string"},"kind":{"type":"string","enum":["circuit","sets"]},"preview":{"description":"Preview video stream","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]},"rounds":{"type":"number"},"roundBreakDuration":{"type":"number"},"exerciseBreakDuration":{"type":"number"},"exerciseConfig":{"$ref":"#/components/schemas/SingleExerciseConfig"},"organization":{"$ref":"#/components/schemas/Organization"}},"required":["id","createdAt","updatedAt","trainer","name","kind","rounds","roundBreakDuration","exerciseBreakDuration","exerciseConfig"]},"GroupResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Group"}},"required":["data"]},"GroupExerciseInstanceDto":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"trainer":{"description":"Creator reference for the workspace member who owns this asset in Hyperhuman Teams. The JSON field name remains `trainer` for API compatibility.","allOf":[{"$ref":"#/components/schemas/TrainerRef"}]},"name":{"type":"string"},"kind":{"type":"string","enum":["single-exercise","multi-exercise","class","promo","educational"],"description":"Video kind. See the VIDEO TYPE GUIDE on the list operation for product names and audio behavior."},"muscleGroups":{"type":"array","items":{"$ref":"#/components/schemas/MuscleGroup"}},"equipment":{"type":"array","items":{"$ref":"#/components/schemas/Equipment"}},"preview":{"description":"Preview video stream","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]},"collectionName":{"type":"string"},"coach":{"type":"string","enum":["male","female"]},"tags":{"type":"array","items":{"type":"string"}},"skillLevel":{"type":"string","enum":["beginner","intermediate","advanced"]},"categories":{"type":"array","items":{"type":"string","enum":["strength","cardio","mobility","balance","endurance","flexibility","plyometrics","recovery","running"]}},"executionSide":{"type":"string","enum":["both","left","right","alternating"]},"showcasedReps":{"type":"number"},"bundle":{"description":"Asensei movement bundle for this exercise","allOf":[{"$ref":"#/components/schemas/ExerciseBundleRefDto"}]},"playsInLoop":{"type":"boolean","description":"When true, preview playback is intended to loop (for example smart clips aligned with reps or duration)."},"organization":{"nullable":true,"description":"Workspace (organization) this exercise belongs to. `null` when the workspace cannot be resolved.","allOf":[{"$ref":"#/components/schemas/Organization"}]},"audioInstructions":{"description":"Locale-specific instruction audio tracks. Emitted only for `kind: single-exercise` (the smart-clip product type that strips original audio in favor of multilingual instructions). When `?locale=` is supplied, narrowed to matching locales via the standard locale chain (English fallback); when omitted, returns all available locales so catalog UIs can render a \"languages available\" indicator. Empty array for `single-exercise` rows that have not yet been narrated. Always empty for the other kinds (`multi-exercise`, `educational`, `promo`, `class`) which keep their original audio baked into the video. Currently populated by `GET /v1/orgs/{organizationId}/video-assets`; other endpoints that share this list-item shape do not yet emit this field.","type":"array","items":{"$ref":"#/components/schemas/AudioDto"}},"duration":{"type":"number","description":"Duration of this exercise in seconds.","example":30},"reps":{"type":"number","description":"Target reps for reps-based exercises. Null for time-based.","example":12},"pace":{"type":"string","enum":["slow","medium","fast"],"nullable":true,"description":"Recommended pace/tempo.","example":"medium"},"weightLevel":{"type":"string","enum":["light","medium","heavy"],"nullable":true,"description":"Recommended weight level for reps-based exercises.","example":"medium"},"rpe":{"type":"number","description":"Rate of Perceived Exertion (0-10). Target intensity level.","minimum":0,"maximum":10,"example":8},"amrap":{"type":"boolean","description":"As Many Reps As Possible mode. Only applicable for time-based exercises.","example":false},"weight":{"type":"number","description":"Prescribed/target weight (0-1000). Unit in weightUnit.","minimum":0,"maximum":1000},"weightUnit":{"type":"string","enum":["metric","imperial"],"nullable":true,"description":"Unit for weight: metric (kg) or imperial (lbs)."}},"required":["id","createdAt","trainer","name","kind","muscleGroups","equipment","playsInLoop","organization","duration"]},"GroupExercisesListResponse":{"type":"object","properties":{"links":{"description":"Pagination envelope. Use `links.next` to fetch the next page; `links.total` is the count across all pages and is omitted on endpoints where it is too expensive to compute.","allOf":[{"$ref":"#/components/schemas/PageLinks"}]},"data":{"type":"array","items":{"$ref":"#/components/schemas/GroupExerciseInstanceDto"}}},"required":["links","data"]},"Goal":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the goal.","example":"goal-strength-gain"},"name":{"type":"string","description":"Display name of the goal. Localized based on locale query parameter.","example":"Strength Gain"},"nameTranslations":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized goal names for different locales","example":{"en-US":"Weight Loss","de-DE":"Gewichtsverlust","fr-FR":"Perte de Poids"}}},"required":["id","name"]},"PlanListItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) for the workout plan.","example":"12ab3efd45c67c1234566cd1"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp when the plan was created.","example":"2023-10-26T10:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp when the plan was last updated.","example":"2023-10-27T11:30:00.000Z"},"trainer":{"description":"Reference to the trainer associated with the plan. Can be null.","allOf":[{"$ref":"#/components/schemas/TrainerRef"}]},"name":{"type":"string","description":"Display name of the workout plan. Localized based on locale query parameter.","example":"4-Week Strength Builder"},"description":{"type":"string","description":"Detailed description of the plan, including its purpose and target audience. Localized based on locale query parameter.","example":"A structured 4-week program designed to increase overall strength using compound lifts."},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Overall difficulty level of the plan.","example":"intermediate"},"visibility":{"type":"string","enum":["private","public","end-user-ai-generated"],"description":"Visibility level of the plan.","example":"public"},"durationInWeeks":{"type":"number","description":"Program duration in weeks (1-24). Use for filtering: ?durationInWeeks=8. Total workouts = durationInWeeks Γ— workoutsPerWeek","example":8,"minimum":1,"maximum":24},"workoutsPerWeek":{"type":"number","description":"Weekly workout frequency (1-7). Total workouts = durationInWeeks Γ— workoutsPerWeek","example":3,"minimum":1,"maximum":7},"adaptationReasoning":{"type":"string","description":"AI adaptation reasoning explanation (only present for AI-adapted programs)","example":"Program adapted to reduce intensity based on low sleep scores. Replaced 3 high-intensity workouts with recovery-focused alternatives."},"originalProgramId":{"type":"string","description":"Original program ID if this program was adapted from another (only present for AI-adapted programs)","example":"507f1f77bcf86cd799439016"},"preview":{"description":"Links to a preview video for the plan (if available).","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]},"goals":{"description":"List of primary goals this plan is designed for (e.g., Strength, Endurance, Weight Loss).","type":"array","items":{"$ref":"#/components/schemas/Goal"}}},"required":["id","createdAt","updatedAt","name","description","difficulty","visibility","goals"]},"PlanListResponse":{"type":"object","properties":{"links":{"description":"Pagination envelope. Use `links.next` to fetch the next page; `links.total` is the count across all pages and is omitted on endpoints where it is too expensive to compute.","allOf":[{"$ref":"#/components/schemas/PageLinks"}]},"data":{"description":"The array of plan list items for the current page.","type":"array","items":{"$ref":"#/components/schemas/PlanListItem"}},"explanation":{"type":"string","description":"Explanation for how this list was filtered or sorted"}},"required":["links","data"]},"PlanRecommendationRequestDto":{"type":"object","properties":{"endUserProfileDetails":{"description":"Detailed user profile information for personalized recommendations","allOf":[{"$ref":"#/components/schemas/EndUserProfileDetailsDto"}]},"goalIds":{"description":"Optional goal IDs at the root of the body (mobile clients). Merged with endUserProfileDetails.goalIds for library matching.","example":["63c92926f920a9005c4e61a0"],"type":"array","items":{"type":"string"}},"locale":{"type":"string","description":"Preferred BCP-47 locale for recommendation text when the stack supports it.","example":"en-US"}}},"RecommendedPlanDto":{"type":"object","properties":{"id":{"type":"string","description":"Plan ID"},"name":{"type":"string","description":"Plan name"},"description":{"type":"string","description":"Plan description"},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"]},"thumbnailUrl":{"type":"object","description":"URL to plan thumbnail image","nullable":true},"recommendation":{"type":"string","description":"Reasoning for this recommendation"},"goals":{"description":"Plan goals","items":{"type":"array"},"type":"array"},"preview":{"description":"Preview video (playable URL when available). url is empty when only a thumbnail image exists.","allOf":[{"$ref":"#/components/schemas/VideoLinks"}]}},"required":["id","name","description","difficulty","thumbnailUrl","recommendation","goals"]},"PlanRecommendationResponseDto":{"type":"object","properties":{"plans":{"description":"List of recommended plans (max 12)","type":"array","items":{"$ref":"#/components/schemas/RecommendedPlanDto"}},"reasoning":{"type":"string","description":"Overall explanation for the recommendation strategy used"}},"required":["plans","reasoning"]},"DurationOptionsDto":{"type":"object","properties":{"minWeeks":{"type":"number","description":"Minimum program duration in weeks","minimum":1,"maximum":24,"example":4},"maxWeeks":{"type":"number","description":"Maximum program duration in weeks","minimum":1,"maximum":24,"example":8}}},"PlanGenerationRequestDto":{"type":"object","properties":{"goalIds":{"description":"Array of goal IDs for the program","example":["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"],"type":"array","items":{"type":"string"}},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Difficulty level for the program","example":"intermediate"},"workoutsPerWeek":{"type":"number","description":"Number of workouts per week","minimum":1,"maximum":7,"example":3},"durationOptions":{"description":"Duration preferences for the program","allOf":[{"$ref":"#/components/schemas/DurationOptionsDto"}]},"endUserProfileDetails":{"description":"Detailed user profile information for personalized program generation","allOf":[{"$ref":"#/components/schemas/EndUserProfileDetailsDto"}]},"workoutCollectionSources":{"type":"array","description":"Sources of workout collections to use for plan generation. Defaults to both team and template if not specified.","example":["team","template"],"items":{"type":"string","enum":["team","template"]}},"userRequirements":{"type":"string","description":"High-level context, definitions, and guidelines for program generation. Provides customer-specific grounding for training methodologies, progression schemes, and program structure.","example":"Progressive overload with 3-week cycles. Include deload weeks every 4th week. Focus on unilateral movements for balance.","maxLength":2000}}},"ApiWorkoutDto":{"type":"object","properties":{"id":{"type":"string","description":"Workout ID","example":"507f1f77bcf86cd799439017"},"name":{"type":"string","description":"Workout name","example":"Upper Body Strength"},"duration":{"type":"number","description":"Workout duration in seconds","example":2700},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Workout difficulty level","example":"intermediate"},"description":{"type":"string","description":"Workout description"}},"required":["id","name","duration","difficulty"]},"PlanGenerationResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Generated program ID (if persisted)","example":"507f1f77bcf86cd799439017"},"name":{"type":"string","description":"Generated plan name","example":"8-Week Strength Building Program"},"description":{"type":"string","description":"Generated plan description","example":"A comprehensive 8-week program designed to build strength and muscle mass."},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Plan difficulty level","example":"intermediate"},"goalIds":{"description":"Array of goal IDs the plan addresses","example":["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"],"type":"array","items":{"type":"string"}},"workouts":{"description":"Array of workouts in the plan","type":"array","items":{"$ref":"#/components/schemas/ApiWorkoutDto"}},"durationInWeeks":{"type":"number","description":"Total number of weeks in the program","example":8},"workoutsPerWeek":{"type":"number","description":"Number of workouts per week","example":3}},"required":["name","description","difficulty","goalIds","workouts","durationInWeeks","workoutsPerWeek"]},"PlanAdaptationRequestDto":{"type":"object","properties":{"endUserProfileId":{"type":"string","description":"End user profile ID for fetching 60-day wearable data, workout feedback, and completed sessions","example":"64e3bca9d1b7e600141a9712"},"endUserProfileDetails":{"description":"User profile information for program adaptation","allOf":[{"$ref":"#/components/schemas/AdaptationEndUserProfileDetailsDto"}]},"workoutSources":{"type":"array","description":"Workout sources for additions/replacements","example":["template","team"],"items":{"type":"string","enum":["template","team"]}},"userGuidance":{"type":"string","description":"User free text for guidance/feedback/context/injury/environment/constraints","example":"I have a slight knee injury, avoid high-impact exercises. Reduce program intensity for recovery.","maxLength":2000}},"required":["endUserProfileDetails","workoutSources"]},"ApiAdaptedWorkoutDto":{"type":"object","properties":{"id":{"type":"string","description":"Workout ID","example":"507f1f77bcf86cd799439017"},"name":{"type":"string","description":"Workout name","example":"Upper Body Strength"},"duration":{"type":"number","description":"Workout duration in seconds","example":2700},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Workout difficulty"},"description":{"type":"string","description":"Workout description"},"position":{"type":"number","description":"Position in program (0-based)"},"action":{"type":"string","description":"Action taken","enum":["kept","replaced","added"]}},"required":["id","name"]},"PlanAdaptationResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Adapted program ID","example":"507f1f77bcf86cd799439017"},"name":{"type":"string","description":"Adapted program name","example":"Adapted: 8-Week Strength Program"},"description":{"type":"string","description":"Program description"},"workouts":{"description":"Workouts in adapted program","type":"array","items":{"$ref":"#/components/schemas/ApiAdaptedWorkoutDto"}},"totalWorkouts":{"type":"number","description":"Total number of workouts"},"durationInWeeks":{"type":"number","description":"Program duration in weeks"},"workoutsPerWeek":{"type":"number","description":"Workouts per week"},"difficulty":{"type":"string","enum":["beginner","intermediate","advanced"],"description":"Program difficulty"},"adaptationReasoning":{"type":"string","description":"Explanation of adaptations made"},"wasDuplicated":{"type":"boolean","description":"True if program was duplicated from team program"},"originalProgramId":{"type":"string","description":"Original program ID if duplicated"}},"required":["id","name","workouts","totalWorkouts","durationInWeeks","workoutsPerWeek","adaptationReasoning"]},"OrganizationMetadataResponse":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the organization","example":"12ab3efd45c67c1234566cd1"},"name":{"type":"string","description":"The name of the organization","example":"Hyperhuman LLC"},"handle":{"type":"object","description":"The organization handle (typically used in URLs)","example":"hyperhuman"},"logoUrl":{"type":"object","description":"URL to the organization logo","example":"https://assets.example.com/logos/hyperhuman-logo.png"},"watermarkUrl":{"type":"object","description":"URL to the brand watermark used in workout video exports and the embedded player. Square PNG with transparent background recommended.","example":"https://assets.example.com/logos/hyperhuman-watermark.png"},"description":{"type":"object","description":"The description of the organization","example":"A company dedicated to fitness and wellness solutions"},"website":{"type":"object","description":"The website URL of the organization","example":"https://hyperhuman.cc"},"brandMainColor":{"type":"object","description":"The primary brand color (hex format)","example":"#11CC88"},"brandSecondaryColor":{"type":"object","description":"The secondary brand color (hex format)","example":"#F3F8F8"},"brandTextColor":{"type":"object","description":"The text color that goes with the brand colors (hex format)","example":"#FFFFFF"},"clientsJoinSetting":{"type":"string","description":"Setting that controls how clients can join the organization","enum":["OPEN","INVITE_ONLY","SUBSCRIPTION_REQUIRED"],"example":"OPEN","default":"OPEN"},"hasAssenseiModuleActive":{"type":"boolean","description":"Whether the organization has the Asensei Assessment module active (AI form analysis)","example":false},"hasWearableModuleActive":{"type":"boolean","description":"Whether the organization has the ROOK Wearables module active (health data sync)","example":false},"hasWhiteLabelAppActive":{"type":"boolean","description":"Whether the organization has a White-Label App active (custom branded consumer app)","example":false}},"required":["id","name","clientsJoinSetting","hasAssenseiModuleActive","hasWearableModuleActive","hasWhiteLabelAppActive"]},"TeamClientsJoinSetting":{"type":"string","enum":["OPEN","INVITE_ONLY","SUBSCRIPTION_REQUIRED"]},"FreeJoinOptionDto":{"type":"object","properties":{"id":{"type":"string","description":"Product unique identifier","example":"507f1f77bcf86cd799439011"},"name":{"type":"string","description":"Product name/title","example":"Club Free Plan"},"description":{"type":"string","description":"Product description","example":"Free access with basic features"},"hasAutoJoin":{"type":"boolean","description":"Whether this product includes auto-join capability","example":true},"stripeProductId":{"type":"string","description":"Stripe product ID for payment processing","example":"prod_SMcyPrDHt0ROlQ"}},"required":["id","name","description","hasAutoJoin","stripeProductId"]},"OrganizationJoinOptionsResponse":{"type":"object","properties":{"clientsJoinSetting":{"description":"High-level team join setting that controls client access","example":"OPEN","$ref":"#/components/schemas/TeamClientsJoinSetting"},"canJoinDirectly":{"type":"boolean","description":"Whether users can join directly without any requirements (OPEN setting)","example":true},"requiresSubscription":{"type":"boolean","description":"Whether the team requires a subscription to join (SUBSCRIPTION_REQUIRED setting)","example":false},"inviteOnlyMode":{"type":"boolean","description":"Whether the team only allows invited users to join (INVITE_ONLY setting)","example":false},"hasFreePlanWithAutoJoin":{"type":"boolean","description":"Whether the team offers any free plans with auto-join capability","example":true},"freeJoinOptions":{"description":"Available free products that include auto-join capability","type":"array","items":{"$ref":"#/components/schemas/FreeJoinOptionDto"}},"totalProductsAvailable":{"type":"number","description":"Total number of subscription products available (including paid)","example":3}},"required":["clientsJoinSetting","canJoinDirectly","requiresSubscription","inviteOnlyMode","hasFreePlanWithAutoJoin","freeJoinOptions"]},"PlanProgressResponseDto":{"type":"object","properties":{"data":{"type":"object","nullable":true,"description":"A map where keys are position indices (as strings) and values contain completion status, latest completion date, and workout details. Returns `null` when the user has no active plan.","additionalProperties":{"type":"object","properties":{"completed":{"type":"boolean"},"latestCompletionDate":{"type":"string","format":"date-time"},"workoutName":{"type":"string"},"difficulty":{"type":"string"},"duration":{"type":"number"},"categories":{"type":"array","items":{"type":"string"}},"workoutId":{"type":"string"},"positionInPlan":{"type":"number"}}},"example":{"0":{"completed":true,"latestCompletionDate":"2023-07-22T15:30:45.123Z","workoutName":"Full Body HIIT","difficulty":"intermediate","duration":1800000,"categories":["Strength","HIIT","Full Body"],"workoutId":"60f1b3b3b3b3b3b3b3b3b3b3","positionInPlan":0},"1":{"completed":false,"latestCompletionDate":null,"workoutName":"Lower Body Strength","difficulty":"advanced","duration":2400000,"categories":["Strength","Lower Body"],"workoutId":"60f1b3b3b3b3b3b3b3b3b3b4","positionInPlan":1},"2":{"completed":false,"latestCompletionDate":null,"workoutName":"Full Body HIIT","difficulty":"intermediate","duration":1800000,"categories":["Strength","HIIT","Full Body"],"workoutId":"60f1b3b3b3b3b3b3b3b3b3b3","positionInPlan":2}}}},"required":["data"]},"ActivePlanResponseDto":{"type":"object","properties":{"data":{"type":"object","description":"The active workout collection access object or null if no active plan","nullable":true}},"required":["data"]},"StartPlanBody":{"type":"object","properties":{"planId":{"type":"string","description":"The plan ID to start as the active plan.","example":"60f1b3b3b3b3b3b3b3b3b3b3"}},"required":["planId"]},"PlanResponseDto":{"type":"object","properties":{"data":{"type":"object","description":"The workout collection access object"}},"required":["data"]},"EndUserProfileDto":{"type":"object","properties":{"email":{"type":"string","description":"User email address"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"externalUUID":{"type":"string","description":"External unique identifier provided by the API client"},"joinedDate":{"format":"date-time","type":"string","description":"When the user joined the team"},"status":{"type":"string","description":"User membership status","enum":["active","suspended"]},"endUserId":{"type":"string","description":"Internal user ID. Present only when the API key is for this organization and the end user has an active (non-suspended) team membership. Use in enduser-scoped endpoints (e.g. plans, insights).","example":"507f1f77bcf86cd799439011"}},"required":["email","joinedDate","status"]},"EndUserProfileListResponse":{"type":"object","properties":{"links":{"description":"Pagination envelope. Use `links.next` to fetch the next page; `links.total` is the count across all pages and is omitted on endpoints where it is too expensive to compute.","allOf":[{"$ref":"#/components/schemas/PageLinks"}]},"data":{"type":"array","items":{"$ref":"#/components/schemas/EndUserProfileDto"}},"total":{"type":"number","deprecated":true,"description":"Deprecated. Use `links.total` instead. Kept for one minor version for backwards compatibility."}},"required":["links","data","total"]},"EndUserInviteItem":{"type":"object","properties":{"email":{"type":"string","description":"Email address of the user to invite"},"externalUUID":{"type":"string","description":"External unique identifier for this user"},"firstName":{"type":"string","description":"First name of the user"},"lastName":{"type":"string","description":"Last name of the user"}},"required":["email"]},"InviteEndUsersDto":{"type":"object","properties":{"users":{"description":"List of users to invite","type":"array","items":{"$ref":"#/components/schemas/EndUserInviteItem"}}},"required":["users"]},"UserIdentifierDto":{"type":"object","properties":{"email":{"type":"string","description":"Email address of the user"},"externalUUID":{"type":"string","description":"External UUID of the user"}}},"InsightPillarDto":{"type":"object","properties":{"type":{"type":"string","description":"The type of insight pillar.","enum":["health_pulse","training","recovery","movement","nutrition","body"],"example":"health_pulse"},"status":{"type":"string","description":"Status indicator for this pillar.","enum":["green","yellow","red"],"example":"green"},"headline":{"type":"string","description":"Headline summarizing the pillar insight (1-2 lines). Does not include pillar type prefix.","example":"82 (+5 vs 7-day). Driver: Sleep."},"action":{"type":"string","description":"Recommended action for this pillar.","example":"Maintain your sleep routine"},"confidence":{"type":"number","description":"Confidence score for this pillar (0-1).","example":0.85},"score":{"type":"number","description":"Score value if applicable (0-100).","example":82},"delta":{"type":"number","description":"Change from baseline/average.","example":5},"deltaDirection":{"type":"string","description":"Direction of change.","enum":["up","down","stable"],"example":"up"},"driver":{"type":"string","description":"Primary driver for health pulse pillar.","enum":["sleep","exercise","body","nutrition","adherence"],"example":"sleep"},"weeklyCompletions":{"type":"number","description":"Number of workouts completed this week.","example":4},"streak":{"type":"number","description":"Current workout streak in days.","example":5},"formScore":{"type":"number","description":"Average form score from AI assessments.","example":78},"formTrend":{"type":"string","description":"Form score trend.","enum":["improving","declining","stable","insufficient-data"],"example":"improving"},"recentCoachingFocus":{"type":"string","description":"Most common coaching feedback.","example":"Keep your knees aligned with your toes"},"isFallback":{"type":"boolean","description":"Indicates if this pillar used fallback data.","example":false},"nutritionScore":{"type":"number","description":"Nutrition score (0-100) for nutrition pillar.","example":72},"caloriesConsumedKcal":{"type":"number","description":"Calories consumed (kcal) for nutrition pillar.","example":1850},"personalBests":{"type":"array","description":"Personal best metrics for this pillar (90-day window).","items":{"type":"object","properties":{"metric":{"type":"string"},"value":{"type":"number"},"label":{"type":"string"}}}},"streaks":{"type":"array","description":"Streaks for this pillar (90-day window).","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"},"label":{"type":"string"}}}},"milestones":{"type":"array","description":"Milestones for this pillar (90-day window).","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"},"label":{"type":"string"}}}}},"required":["type","status","headline","action","confidence"]},"UserDigestResponse":{"type":"object","properties":{"userId":{"type":"string","description":"User ID the digest is for.","example":"63415bf67a9c7000126616c1"},"organizationId":{"type":"string","description":"Organization ID.","example":"63415bf67a9c7000126616c1"},"date":{"format":"date-time","type":"string","description":"Date the digest is for.","example":"2026-01-10T00:00:00.000Z"},"pillars":{"description":"Array of insight pillars (3-5 items).","type":"array","items":{"$ref":"#/components/schemas/InsightPillarDto"}},"todaysFocus":{"type":"string","description":"The single most important action for today.","example":"Complete: Full Body Strength Workout"},"dataCompleteness":{"type":"number","description":"Data completeness score (0-1). Higher means more data sources available.","example":0.75},"generatedAt":{"format":"date-time","type":"string","description":"Timestamp when the digest was generated.","example":"2026-01-10T08:30:00.000Z"}},"required":["userId","organizationId","date","pillars","todaysFocus","dataCompleteness","generatedAt"]},"PillarDetailResponse":{"type":"object","properties":{"type":{"type":"string","description":"The type of insight pillar.","enum":["health_pulse","training","recovery","movement","nutrition","body"],"example":"health_pulse"},"status":{"type":"string","description":"Status indicator for this pillar.","enum":["green","yellow","red"],"example":"green"},"headline":{"type":"string","description":"Headline summarizing the pillar insight (1-2 lines). Does not include pillar type prefix.","example":"82 (+5 vs 7-day). Driver: Sleep."},"action":{"type":"string","description":"Recommended action for this pillar.","example":"Maintain your sleep routine"},"confidence":{"type":"number","description":"Confidence score for this pillar (0-1).","example":0.85},"score":{"type":"number","description":"Score value if applicable (0-100).","example":82},"delta":{"type":"number","description":"Change from baseline/average.","example":5},"deltaDirection":{"type":"string","description":"Direction of change.","enum":["up","down","stable"],"example":"up"},"driver":{"type":"string","description":"Primary driver for health pulse pillar.","enum":["sleep","exercise","body","nutrition","adherence"],"example":"sleep"},"weeklyCompletions":{"type":"number","description":"Number of workouts completed this week.","example":4},"streak":{"type":"number","description":"Current workout streak in days.","example":5},"formScore":{"type":"number","description":"Average form score from AI assessments.","example":78},"formTrend":{"type":"string","description":"Form score trend.","enum":["improving","declining","stable","insufficient-data"],"example":"improving"},"recentCoachingFocus":{"type":"string","description":"Most common coaching feedback.","example":"Keep your knees aligned with your toes"},"isFallback":{"type":"boolean","description":"Indicates if this pillar used fallback data.","example":false},"nutritionScore":{"type":"number","description":"Nutrition score (0-100) for nutrition pillar.","example":72},"caloriesConsumedKcal":{"type":"number","description":"Calories consumed (kcal) for nutrition pillar.","example":1850},"personalBests":{"type":"array","description":"Personal best metrics for this pillar (90-day window).","items":{"type":"object","properties":{"metric":{"type":"string"},"value":{"type":"number"},"label":{"type":"string"}}}},"streaks":{"type":"array","description":"Streaks for this pillar (90-day window).","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"},"label":{"type":"string"}}}},"milestones":{"type":"array","description":"Milestones for this pillar (90-day window).","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"number"},"label":{"type":"string"}}}},"lastWorkout":{"type":"object","description":"Last workout information for training pillar."},"nextSession":{"type":"object","description":"Next scheduled session for training pillar."},"bestLever":{"type":"string","description":"Best training lever for training pillar.","enum":["strength","cardio","mobility"]},"sleepScore":{"type":"number","description":"Sleep score for recovery pillar.","example":75},"mainIssue":{"type":"string","description":"Main issue identified for recovery pillar.","example":"Sleep efficiency"},"yesterdayIntensity":{"type":"string","description":"Yesterday's workout intensity for recovery pillar.","enum":["low","moderate","high"]},"activityLevel":{"type":"string","description":"Activity level for movement pillar.","enum":["low","moderate","high"]},"suggestedMinutes":{"type":"number","description":"Suggested movement minutes for movement pillar.","example":20},"cardioTrend":{"type":"string","description":"Cardio trend for movement pillar.","enum":["improving","declining","stable","insufficient-data"]},"bodyScore":{"type":"number","description":"Body score for body pillar.","example":72},"weeklyTrend":{"type":"string","description":"Weekly trend for body pillar.","enum":["improving","declining","stable","insufficient-data"]},"streakDays":{"type":"number","description":"Streak days for body/momentum pillar.","example":7},"biggestLever":{"type":"string","description":"Biggest lever for improvement.","enum":["sleep","nutrition","movement"]},"proteinG":{"type":"number","description":"Protein (g) for nutrition pillar.","example":120},"carbsG":{"type":"number","description":"Carbohydrates (g) for nutrition pillar.","example":200},"fatG":{"type":"number","description":"Fat (g) for nutrition pillar.","example":65},"mealsLoggedToday":{"type":"number","description":"Number of meals/entries logged today for nutrition pillar.","example":6},"nutritionMeals":{"type":"array","description":"Per-entry nutrition breakdown for the day (up to 20 entries).","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"caloriesKcal":{"type":"number"},"proteinG":{"type":"number"},"carbsG":{"type":"number"},"fatG":{"type":"number"}}}},"nutritionWin":{"type":"string","description":"Positive nutrition behavior identified for nutrition pillar.","example":"Good protein intake (195g)"},"nutritionWatch":{"type":"string","description":"Area to improve for nutrition pillar.","example":"High calorie day – confirm aligned with goal"},"readinessBand":{"type":"string","description":"Readiness band indicating training capacity for today.","enum":["push","maintain","recover"],"example":"maintain"},"readinessMessage":{"type":"string","description":"Short message explaining the readiness recommendation.","example":"Sleep down vs baseline - keep intensity moderate."},"recommendedIntensity":{"type":"string","description":"Recommended workout intensity based on readiness.","enum":["light","moderate","high"],"example":"moderate"},"hrvBand":{"type":"string","description":"HRV status relative to personal baseline.","enum":["low","normal","high"],"example":"normal"},"riskLevel":{"type":"string","description":"Risk level for burnout/overreaching.","enum":["low","moderate","high"],"example":"moderate"},"riskTriggers":{"description":"Factors that triggered the risk flag (max 3).","example":["Sleep trend declining","RPE consistently high"],"type":"array","items":{"type":"string"}},"formCue":{"type":"string","description":"Primary form cue to focus on today.","example":"Keep knees tracking over toes"},"formSuggestion":{"type":"string","description":"Suggested adjustment if form is declining.","example":"Slow tempo + lighter load today"},"repAccuracy":{"type":"number","description":"Average rep accuracy from AI assessments.","example":82},"pacingStatus":{"type":"string","description":"Program pacing status for the current week.","enum":["on_track","behind","ahead"],"example":"on_track"},"pacingMessage":{"type":"string","description":"Short message about program pacing.","example":"3/4 workouts this week. On pace."},"workoutsPlannedThisWeek":{"type":"number","description":"Planned workouts per week based on user profile.","example":4},"workoutsCompletedThisWeek":{"type":"number","description":"Workouts completed this week.","example":3},"currentWeek":{"type":"number","description":"Current week number in the program (1-based).","example":2},"totalWeeks":{"type":"number","description":"Total weeks in the program.","example":8},"why":{"description":"Reasons explaining the recommendation (max 3).","example":["HRV below baseline","Sleep score declining","High intensity yesterday"],"type":"array","items":{"type":"string"}},"alternativeActions":{"description":"Safe alternative actions (max 2).","example":["Do planned workout at moderate intensity","Swap to Mobility + Zone 2"],"type":"array","items":{"type":"string"}}},"required":["type","status","headline","action","confidence"]},"CurrentApiStatsDto":{"type":"object","properties":{"currentHour":{"type":"string","description":"Current hour timestamp (ISO 8601 format)","example":"2023-11-06T14:00:00Z"},"currentHourRequests":{"type":"number","description":"Number of requests made in the current hour","example":45},"totalDayRequests":{"type":"number","description":"Total number of requests made today","example":234},"currentDate":{"type":"string","description":"Current date (YYYY-MM-DD format)","example":"2023-11-06"}},"required":["currentHour","currentHourRequests","totalDayRequests","currentDate"]},"RateLimitsDto":{"type":"object","properties":{"hourly":{"type":"object","description":"Hourly rate limit from subscription entitlement","example":1000,"nullable":true},"daily":{"type":"object","description":"Daily rate limit from subscription entitlement","example":15000,"nullable":true}}},"OrganizationStatsResponse":{"type":"object","properties":{"organizationId":{"type":"string","description":"The unique identifier of the organization","example":"63415bf67a9c7000126616c1"},"organizationName":{"type":"string","description":"The name of the organization","example":"My Fitness Company"},"currentStats":{"description":"Current API usage statistics","allOf":[{"$ref":"#/components/schemas/CurrentApiStatsDto"}]},"rateLimits":{"description":"Rate limits from subscription entitlement","allOf":[{"$ref":"#/components/schemas/RateLimitsDto"}]},"timestamp":{"type":"string","description":"Response timestamp (ISO 8601 format)","example":"2023-11-06T14:30:00Z"}},"required":["organizationId","organizationName","currentStats","rateLimits","timestamp"]},"StartConversationBody":{"type":"object","properties":{"organizationId":{"type":"string","description":"Organization ID - use \"default\" to use the user's default organization","example":"default"},"initialMessage":{"type":"string","description":"Initial message to start the conversation","example":"What exercises should I do for chest?","minLength":1,"maxLength":2000},"userEmail":{"type":"string","description":"User email address to identify the end user","example":"user@example.com"},"userExternalUUID":{"type":"string","description":"External unique identifier for the end user","example":"user-12345"}},"required":["organizationId","initialMessage"]},"ChatConversationDto":{"type":"object","properties":{"id":{"type":"string","description":"Conversation ID"},"title":{"type":"string","description":"Conversation title"},"messageCount":{"type":"number","description":"Number of messages in conversation"},"lastMessageAt":{"format":"date-time","type":"string","description":"Last message timestamp"},"createdAt":{"format":"date-time","type":"string","description":"Conversation creation timestamp"}},"required":["id","messageCount","createdAt"]},"ChatMessageDto":{"type":"object","properties":{"id":{"type":"string","description":"Message ID"},"role":{"type":"string","description":"Message role","enum":["user","assistant"]},"content":{"type":"string","description":"Message content"},"createdAt":{"format":"date-time","type":"string","description":"Message creation timestamp"},"metadata":{"type":"object","description":"Message metadata (reasoning, topics, nutritionLogged, contentPreview, pendingAction, confirmedResult)"},"status":{"type":"string","description":"Message delivery status","enum":["pending","delivered","failed"]}},"required":["id","role","content","createdAt","status"]},"ChatConversationResponse":{"type":"object","properties":{"conversation":{"$ref":"#/components/schemas/ChatConversationDto"},"response":{"$ref":"#/components/schemas/ChatMessageDto"}},"required":["conversation","response"]},"PaginationDto":{"type":"object","properties":{"page":{"type":"number","description":"Current page number"},"limit":{"type":"number","description":"Items per page"},"total":{"type":"number","description":"Total number of items"},"totalPages":{"type":"number","description":"Total number of pages"}},"required":["page","limit","total","totalPages"]},"ChatConversationsResponse":{"type":"object","properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ChatConversationDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["conversations","pagination"]},"ChatMessagesResponse":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessageDto"}},"pagination":{"$ref":"#/components/schemas/PaginationDto"}},"required":["messages","pagination"]},"SendMessageBody":{"type":"object","properties":{"organizationId":{"type":"string","description":"Organization ID - use \"default\" to use the user's default organization","example":"default"},"content":{"type":"string","description":"Message content","example":"What exercises should I do for chest?","minLength":1,"maxLength":2000},"userEmail":{"type":"string","description":"User email address to identify the end user","example":"user@example.com"},"userExternalUUID":{"type":"string","description":"External unique identifier for the end user","example":"user-12345"}},"required":["organizationId","content"]},"SendMessageResponse":{"type":"object","properties":{"userMessage":{"description":"The user message that was sent","allOf":[{"$ref":"#/components/schemas/ChatMessageDto"}]},"assistantMessage":{"description":"The AI assistant response","allOf":[{"$ref":"#/components/schemas/ChatMessageDto"}]},"conversation":{"description":"Updated conversation information","allOf":[{"$ref":"#/components/schemas/ChatConversationDto"}]}},"required":["userMessage","assistantMessage","conversation"]},"ConfirmActionBody":{"type":"object","properties":{"pendingActionId":{"type":"string","description":"Pending action ID from assistantMessage.metadata.pendingAction.id","example":"507f1f77bcf86cd799439011"},"organizationId":{"type":"string","description":"Organization ID - use \"default\" to use the user's default organization","example":"default"},"userEmail":{"type":"string","description":"User email address to identify the end user","example":"user@example.com"},"userExternalUUID":{"type":"string","description":"External unique identifier for the end user","example":"user-12345"}},"required":["pendingActionId","organizationId"]},"NutritionOverviewLoggedDto":{"type":"object","properties":{"caloriesKcal":{"type":"number"},"proteinG":{"type":"number"},"carbsG":{"type":"number"},"fatG":{"type":"number"}},"required":["caloriesKcal","proteinG","carbsG","fatG"]},"NutritionOverviewDayTotalsDto":{"type":"object","properties":{"caloriesConsumedKcal":{"type":"number"},"proteinG":{"type":"number"},"carbsG":{"type":"number"},"fatG":{"type":"number"}},"required":["caloriesConsumedKcal","proteinG","carbsG","fatG"]},"NutritionOverviewDto":{"type":"object","properties":{"logged":{"$ref":"#/components/schemas/NutritionOverviewLoggedDto"},"dayTotals":{"$ref":"#/components/schemas/NutritionOverviewDayTotalsDto"},"nutritionScore":{"type":"object","nullable":true}},"required":["logged","dayTotals","nutritionScore"]},"ConfirmActionResponseDto":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"string"},"nutritionOverview":{"description":"Present when action was log_nutrition and success is true","allOf":[{"$ref":"#/components/schemas/NutritionOverviewDto"}]},"instructionForReply":{"type":"string","description":"Instruction for displaying the nutrition reply (log_nutrition only)"},"adaptedWorkout":{"description":"On-the-fly adapted workout (adapt_workout). Render and store locally.","allOf":[{"$ref":"#/components/schemas/WorkoutAdaptationResponseDto"}]},"generatedWorkout":{"description":"On-the-fly generated workout (generate_workout). Render and store locally.","allOf":[{"$ref":"#/components/schemas/WorkoutGenerationResponseDto"}]},"adaptedProgram":{"description":"On-the-fly adapted program (adapt_program). Render and store locally.","allOf":[{"$ref":"#/components/schemas/PlanAdaptationResponseDto"}]},"generatedProgram":{"description":"On-the-fly generated program (generate_program). Same shape as POST /v1/orgs/{orgId}/plans/generate. Render and store locally.","allOf":[{"$ref":"#/components/schemas/PlanGenerationResponseDto"}]}},"required":["success"]}}}}