{"openapi":"3.0.0","paths":{"/v1/workouts/metadata":{"get":{"operationId":"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"]}]}},"/v1/workouts/equipment/metadata":{"get":{"operationId":"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"]}]}},"/v1/workouts/{workoutId}":{"get":{"operationId":"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,"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"]}]}},"/v1/workouts/{workoutId}/export/video/stream_url":{"get":{"operationId":"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** in MP4 format. This is a single video file containing the entire workout from start to finish, including all exercises, rest periods, audio narration, graphics, and timing overlays.\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 MP4 file with entire workout\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":"Pre-signed S3 URL to complete workout video (MP4 format), valid for 7 days.","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"]}]}},"/v1/workouts/{workoutId}/export/audio/stream_url":{"get":{"operationId":"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---\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":"Pre-signed S3 URL to complete audio file (M4A/AAC format), valid for 7 days.","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"]}]}},"/v1/workouts/exercises/metadata":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/workouts":{"get":{"operationId":"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- `page` - 1-indexed page number (default: 1)\n- `limit` - Items per page (default: 20, max: 100)\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":"Number of items per page. Defaults to 20, Max 100.","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":"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 category IDs (provide comma-separated values if multiple).","example":"cat-hiit-123,cat-strength-456","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"}},{"name":"page","required":false,"in":"query","description":"Page number for pagination (1-indexed). Defaults to 1.","example":1,"schema":{"type":"number"}}],"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"}],"pagination":{"page":1,"limit":20,"total":45,"pages":3}}},"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"]}]}},"/v1/orgs/{organizationId}/workouts/recommend":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/workouts/generate":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/workouts/{workoutId}/adapt":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/content-autopilot":{"get":{"operationId":"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"]}]},"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/content-autopilot/events":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}":{"get":{"operationId":"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"]}]},"patch":{"operationId":"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"]}]},"delete":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}/activate":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}/deactivate":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}/run-now":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/content-autopilot/{taskId}/events":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/drops":{"get":{"operationId":"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, 45, 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,45,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"]}]}},"/v1/orgs/{organizationId}/drops/{dropId}":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/drops/{dropId}/export":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/social-publish/connected-platforms":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/social-publish":{"get":{"operationId":"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"]}]},"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/social-publish/{taskId}":{"get":{"operationId":"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"]}]},"patch":{"operationId":"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"]}]},"delete":{"operationId":"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"]}]}},"/v1/workouts/{workoutId}/playlist":{"get":{"operationId":"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- Audio Stream: `GET /v1/workouts/{id}/export/audio-stream`\n ","parameters":[{"name":"workoutId","required":true,"in":"path","description":"The unique identifier (UUID or ObjectId) of the workout 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, including all segments, media links, and metadata necessary for playback.","schema":{"example":{"data":{"id":"12ab3efd45c67c1234566cd1","name":"Full Body HIIT Power","duration":1800,"segments":[{"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"}},{"kind":"exercise","id":"exercise_squats_1","exerciseId":"507f1f77bcf86cd799439011","duration":45,"name":"Bodyweight Squats","reps":12,"pace":"moderate","weightLevel":null,"rpe":null,"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"}]}},{"kind":"break","id":"break_1","duration":30,"audio":null,"video":null}]}}},"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":[]}]}},"/v1/workouts/{workoutId}/music":{"get":{"operationId":"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**: Shuffles tracks to cover workout duration + 10% buffer\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":[]}]}},"/v1/workouts/{workoutId}/sessions/start":{"post":{"operationId":"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"]}]}},"/v1/workouts/{workoutId}/sessions/{sessionId}":{"patch":{"operationId":"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"]}]},"get":{"operationId":"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"]}]}},"/v1/workouts/{workoutId}/sessions/end":{"post":{"operationId":"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"]}]}},"/v1/workouts/{workoutId}/sessions/complete":{"post":{"operationId":"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"]}]}},"/v1/workouts/{workoutId}/sessions/recent":{"get":{"operationId":"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"]}]}},"/v1/workouts/feedback/options":{"get":{"operationId":"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"]}]}},"/v1/workouts/{workoutId}/feedback":{"post":{"operationId":"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"]}]}},"/v1/plans/metadata":{"get":{"operationId":"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"]}]}},"/v1/plans/{planId}":{"get":{"operationId":"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"]}]}},"/v1/plans/{planId}/workouts":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/groups":{"get":{"operationId":"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":"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"]}]}},"/v1/orgs/{organizationId}/groups/{groupId}":{"get":{"operationId":"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"}}],"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"]}]}},"/v1/orgs/{organizationId}/groups/{groupId}/exercises":{"get":{"operationId":"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"}}],"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"]}]}},"/v1/orgs/{organizationId}/plans":{"get":{"operationId":"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- `page` - Page number (default: 1)\n- `limit` - Items per page (default: 20, max: 100)\n- `sort` - Sort by: createdAt, updatedAt, name, difficulty, durationInWeeks, workoutsPerWeek\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":"org-hyperhuman-llc","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of items per page. Defaults to 20, Max 100.","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":"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":"goal-weightloss-1,goal-endurance-2","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"}},{"name":"page","required":false,"in":"query","description":"Page number for pagination (1-indexed). Defaults to 1.","example":1,"schema":{"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"}}],"pagination":{"page":1,"limit":20,"total":45,"pages":3}}},"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"]}]}},"/v1/orgs/{organizationId}/plans/recommend":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/plans/generate":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/plans/{planId}/adapt":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/metadata":{"get":{"operationId":"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- Organization name and handle\n- Logo URLs (multiple sizes available)\n- Brand colors (primary, secondary, text)\n- Website URL\n- Description\n\n**Configuration:**\n- Client joining settings (OPEN, INVITE_ONLY, SUBSCRIPTION_REQUIRED)\n- Join mode flags\n- Subscription requirements\n\n**Module Status:**\n- Asensei Assessment module (AI form analysis for exercises)\n- ROOK Wearables module (health data sync from wearable devices)\n- White-Label App (custom branded consumer mobile app)\n\n**Identifiers:**\n- Organization ID (for API calls)\n- Unique handle (URL-friendly)\n\n---\n\n### šŸŽÆ Common Use Cases\n\nāœ… **White-label mobile apps** - Fetch branding on app launch \nāœ… **Custom web portals** - Apply organization colors/logo \nāœ… **Multi-tenant platforms** - Display correct organization context \nāœ… **Onboarding flows** - Check joining requirements\n\n---\n\n### šŸ’” Best Practices\n\nāœ… **Cache metadata** - Refresh daily or on app restart \nāœ… **Fallback colors** - Handle missing brand colors gracefully \nāœ… **Logo sizes** - Request appropriate size for your UI \nāœ… **Handle changes** - Organization settings can update\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","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"]}]}},"/v1/orgs/{organizationId}/join-options":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/plans/active/progress":{"get":{"operationId":"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\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 unique identifier (UUID) of the organization.","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.","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"]}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/plans/active":{"get":{"operationId":"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 unique identifier (UUID) of the organization.","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"]}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/plans/start":{"post":{"operationId":"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 unique identifier (UUID) of the organization.","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"]}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/plans/{planId}/end":{"post":{"operationId":"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 unique identifier (UUID) of the organization.","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"]}]}},"/v1/orgs/{organizationId}/endusers":{"get":{"operationId":"getOrganizationEndUsers","summary":"Get organization end users","description":"Retrieves a list of end users associated with the organization. endUserId is present only when the API key is for this organization and the end user has an active (non-suspended) team membership.","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"}],"total":2}},"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"]}]},"delete":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/endusers/invite":{"post":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/endusers/suspend":{"put":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/endusers/reactivate":{"put":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/endusers/find":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/insights/digest":{"get":{"operationId":"getUserDailyDigest","summary":"Get daily AI-powered user insights digest","description":"\n## Daily Health & Fitness Digest\n\nReturns a personalized daily digest with 3-5 insight pillars covering health, training, recovery, movement, nutrition, and body metrics.\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","readinessBand":"push"},{"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":"recovery","status":"yellow","headline":"Moderate (HRV 45ms). Readiness: Maintain.","action":"Keep today moderate intensity","confidence":0.7}],"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"]}]}},"/v1/orgs/{organizationId}/endusers/{endUserId}/insights/pillars/{pillarType}":{"get":{"operationId":"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"]}]}},"/v1/orgs/{organizationId}/stats":{"get":{"operationId":"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"]}]}},"/v1/chat/conversations":{"post":{"operationId":"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 MongoDB ObjectId for a specific organization\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"]}]},"get":{"operationId":"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"]}]}},"/v1/chat/conversations/{conversationId}/messages":{"get":{"operationId":"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"]}]},"post":{"operationId":"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"]}]}},"/v1/chat/conversations/{conversationId}/actions/confirm":{"post":{"operationId":"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"]}]}},"/v1/chat/conversations/{conversationId}":{"delete":{"operationId":"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"]}]}}},"info":{"title":"Hyperhuman Content API","description":"\n## The Fitness Content OS for Your Product\n\nRecommend, generate, and deliver personalized video & audioā€”then learn from every session.\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 Workout:**\n```bash\ncurl -X POST 'https://content.api.hyperhuman.cc/v1/orgs/{orgId}/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## šŸŽÆ Core Features\n\n| Feature | Endpoints | Use Case |\n|---------|-----------|----------|\n| **Workout Library** | `GET /v1/orgs/{organizationId}/workouts` | List organization workouts |\n| **Plan Library** | `GET /v1/orgs/{organizationId}/plans` | List organization training plans |\n| **AI Workout Generation** | `POST /v1/orgs/{orgId}/workouts/generate` | Create custom workouts on-the-fly |\n| **AI Plan Generation** | `POST /v1/orgs/{orgId}/plans/generate` | Generate multi-week programs |\n| **Video Playback** | `GET /v1/workouts/{id}/playlist` | Structured segments with HLS streams |\n| **Session Tracking** | `POST /v1/workouts/{id}/sessions/start` | Track user progress & completion |\n| **Exercise Collections** | `GET /v1/orgs/{orgId}/groups` | List org micro workouts (circuit/sets) |\n\n---\n\n## šŸ“¦ What You Get\n\n**Video Assets:**\n- HLS master playlists (adaptive streaming)\n- Pre-signed S3 URLs\n- Intro, exercise, and outro segments\n\n**Metadata:**\n- Exercise details (name, reps, duration, difficulty)\n- Equipment requirements\n- Muscle group targeting\n- Localized content (13 languages)\n\n**AI Personalization:**\n- User profile-based generation\n- Fitness level adaptation\n- Equipment availability filtering\n- Goal-based programming\n\n---\n\n## šŸŽ¬ Embedded Player\n\n### Pre-built Workout\n```html\n\n```\n\n### AI-Generated Workout\n```html\n\n\n\n```\n\n**Required Parameters:**\n- `organizationId` - Your org ID\n- `apiKey` - Your API key\n- `locale` (optional) - Default: `en-US`\n\n---\n\n## šŸŽ® Custom Interactive Workout Player Implementation\n\nHyperhuman provides two integration options for workout players:\n\n1. **Plug-and-play embedded player** - Ready-to-use iframe solution\n2. **Custom implementation** - Build your own player using our public API endpoints\n\n### API Endpoints\n\n#### 1. Get Workout Metadata\n```http\nGET /v1/workouts/{workoutId}\n```\n\nReturns basic workout information (name, duration, difficulty, etc.)\n\n#### 2. Get Workout Playlist\n```http\nGET /v1/workouts/{workoutId}/playlist?locale={locale}\n```\n\nReturns complete workout structure with media assets and timing.\n\n### Progress Bar Implementation\n\n#### Visual Design\nThe progress bar consists of:\n- **Visual indicators**: Rectangle bars representing each exercise\n- **Active state**: Filled rectangles (green) for completed exercises\n- **Inactive state**: Empty rectangles (white) for remaining exercises\n- **Text display**: Remaining time or completion status\n\n#### Logic Flow\n```javascript\n// Calculate progress state\nfunction getProgressState(playlist, currentSegmentIndex) {\n const exerciseCount = countExercises(playlist);\n const doneExerciseIndex = getCompletedExerciseIndex(playlist, currentSegmentIndex);\n\n return {\n exerciseCount,\n doneExerciseIndex, // -1 if none completed, 0-based index of last completed\n remainingTime: calculateRemainingTime(playlist, currentSegmentIndex)\n };\n}\n\nfunction countExercises(playlist) {\n return playlist.filter(segment =>\n segment.kind === 'exercise' || segment.kind === 'multi-exercise'\n ).length;\n}\n\nfunction getCompletedExerciseIndex(playlist, currentIndex) {\n let completedCount = 0;\n for (let i = 0; i < Math.min(currentIndex, playlist.length); i++) {\n const segment = playlist[i];\n if (segment.kind === 'exercise' || segment.kind === 'multi-exercise') {\n completedCount++;\n }\n }\n return completedCount - 1; // Convert to 0-based index\n}\n```\n\n#### Component Structure\n```jsx\nconst WorkoutProgress = ({ exerciseCount, doneExerciseIndex, remainingTime, finished }) => {\n return (\n
\n
\n {Array.from({ length: exerciseCount }, (_, index) => (\n \n ))}\n
\n
\n {finished ? 'Workout Complete' : formatTime(remainingTime)}\n
\n
\n );\n};\n```\n\n### Navigation Logic\n\n#### Segment Types\nThe workout playlist contains these segment types:\n- `workout-intro`: Introduction video/overview\n- `exercise`/`multi-exercise`: Main exercise segments with video/audio\n- `break`: Rest periods\n- `promo`/`educational`: Additional video content\n- `workout-outro`: Completion/summary\n\n#### Navigation Controls\n```javascript\nclass WorkoutController {\n constructor(playlist) {\n this.playlist = playlist;\n this.currentIndex = 0;\n this.listeners = [];\n }\n\n // Navigate to next segment\n next() {\n if (this.currentIndex < this.playlist.length - 1) {\n this.currentIndex++;\n this.notifyListeners('next', this.currentIndex);\n this.stopCurrentMedia();\n this.playCurrentSegment();\n }\n }\n\n // Navigate to previous segment\n previous() {\n if (this.currentIndex > 0) {\n this.currentIndex--;\n this.notifyListeners('previous', this.currentIndex);\n this.stopCurrentMedia();\n this.playCurrentSegment();\n }\n }\n\n // Jump to specific segment\n jumpToIndex(index) {\n if (index >= 0 && index < this.playlist.length) {\n this.currentIndex = index;\n this.notifyListeners('jump', this.currentIndex);\n this.stopCurrentMedia();\n this.playCurrentSegment();\n }\n }\n\n // Handle exercise completion\n onExerciseComplete() {\n // Auto-advance to next segment after exercise completion\n setTimeout(() => this.next(), 1000); // Small delay for UX\n }\n\n stopCurrentMedia() {\n // Stop any playing video/audio\n // Clear audio queues\n // Reset media players\n }\n\n playCurrentSegment() {\n const segment = this.playlist[this.currentIndex];\n switch (segment.kind) {\n case 'exercise':\n case 'multi-exercise':\n this.playExerciseSegment(segment);\n break;\n case 'break':\n this.playBreakSegment(segment);\n break;\n // Handle other segment types...\n }\n }\n}\n```\n\n#### UI Controls\n```jsx\nconst NavigationControls = ({ onPrevious, onNext, canGoPrevious, canGoNext }) => {\n return (\n
\n {canGoPrevious && (\n \n )}\n\n {canGoNext && (\n \n )}\n
\n );\n};\n```\n\n### Implementation Architecture\n\n#### Core Components\n1. **Playlist Manager**: Handles API calls and data transformation\n2. **Media Controller**: Manages video/audio playback\n3. **Progress Tracker**: Updates progress bar and timing\n4. **Navigation Handler**: Processes next/previous actions\n5. **UI Renderer**: Displays current segment and controls\n\n#### State Management\n```javascript\nconst WorkoutPlayerState = {\n // API Data\n workout: null,\n playlist: [],\n\n // Playback State\n currentSegmentIndex: 0,\n isPlaying: false,\n isPaused: false,\n\n // Progress Tracking\n exerciseCount: 0,\n completedExercises: 0,\n remainingTime: 0,\n\n // Media State\n currentVideo: null,\n currentAudio: null,\n audioQueue: []\n};\n```\n\n#### Integration Flow\n```javascript\nasync function initializeWorkoutPlayer(workoutId, apiKey, organizationId) {\n // 1. Fetch workout metadata\n const workout = await fetchWorkout(workoutId);\n\n // 2. Fetch detailed playlist\n const playlist = await fetchWorkoutPlaylist(workoutId);\n\n // 3. Initialize controller\n const controller = new WorkoutController(playlist);\n\n // 4. Setup media players\n const mediaController = new MediaController();\n\n // 5. Initialize progress tracking\n const progressTracker = new ProgressTracker(playlist);\n\n // 6. Render UI\n renderWorkoutPlayer(controller, mediaController, progressTracker);\n\n return { controller, mediaController, progressTracker };\n}\n```\n\n### Key Considerations\n\n#### Media Management\n- **Pre-signed URLs**: Video/audio URLs expire, handle refresh logic\n- **Audio Queuing**: Multiple audio tracks (instructions, background music)\n- **Video Synchronization**: Keep video and audio in sync during navigation\n\n#### Error Handling\n- Network failures during media loading\n- Invalid segment data\n- Unsupported locales fall back to English\n\n#### Performance\n- Lazy load media assets\n- Pre-buffer next segment\n- Clean up resources on navigation\n\n#### User Experience\n- Smooth transitions between segments\n- Visual feedback for loading states\n- Accessibility support (keyboard navigation, screen readers)\n\n### Testing Recommendations\n\n1. **Navigation Flow**: Test all next/previous scenarios\n2. **Progress Tracking**: Verify progress bar updates correctly\n3. **Media Playback**: Ensure smooth transitions and no audio gaps\n4. **Edge Cases**: Empty playlists, single exercises, network failures\n\nThis implementation provides the core functionality needed to build a custom workout player that matches Hyperhuman's user experience while giving you full control over the UI and behavior.\n\n---\n\n## šŸŒ Localization\n\n**Supported Locales (13):**\n`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**Example:**\n```bash\n# French workout\ncurl 'https://content.api.hyperhuman.cc/v1/workouts/{id}?locale=fr-FR' \\\n -H 'X-Api-Key: YOUR_KEY'\n```\n\nLocalizes: exercise names, equipment, muscle groups, audio instructions.\n\n---\n\n## šŸ“š Complete API Workflows\n\n### šŸƒā€ā™‚ļø Workflow 1: Browse & Play Pre-built Content\n```\n1. GET /v1/workouts/metadata ā†’ Get categories and filters\n2. GET /v1/workouts ā†’ Browse available workouts\n3. GET /v1/workouts/{id} ā†’ Get workout details\n4. GET /v1/workouts/{id}/playlist ā†’ Get video segments\n5. (Optional) POST /v1/workouts/{id}/sessions/start ā†’ Track progress\n```\n\n### šŸ¤– Workflow 2: AI-Generated Workouts\n```\n1. GET /v1/orgs/{orgId}/metadata ā†’ Get organization settings\n2. POST /v1/orgs/{orgId}/workouts/generate ā†’ Create custom workout\n3. GET /v1/workouts/{id}/playlist ā†’ Get generated content\n4. POST /v1/workouts/{id}/sessions/start ā†’ Begin tracking\n5. PATCH /v1/workouts/{id}/sessions/{sessionId} ā†’ Update progress\n6. POST /v1/workouts/{id}/sessions/end ā†’ Complete session\n7. POST /v1/workouts/{id}/feedback ā†’ Collect user feedback\n```\n\n### šŸ“‹ Workflow 3: Training Programs\n```\n1. GET /v1/plans/metadata ā†’ Get plan goals and difficulties\n2. POST /v1/orgs/{orgId}/plans/generate ā†’ Create multi-week program\n3. GET /v1/plans/{id} ā†’ Get plan details\n4. GET /v1/plans/{id}/workouts ā†’ Get plan workouts\n5. For each workout: Follow Workflow 2\n```\n\n### šŸ‘„ Workflow 4: User Management\n```\n1. GET /v1/orgs/{orgId}/endusers ā†’ List organization users\n2. POST /v1/orgs/{orgId}/endusers/invite ā†’ Add new users\n3. GET /v1/orgs/{orgId}/endusers/find ā†’ Check user status\n4. PUT /v1/orgs/{orgId}/endusers/suspend ā†’ Temporarily disable access\n5. PUT /v1/orgs/{orgId}/endusers/reactivate ā†’ Restore access\n6. DELETE /v1/orgs/{orgId}/endusers ā†’ Remove user permanently\n```\n\n### šŸ“Š Workflow 5: Session Analytics\n```\n1. POST /v1/workouts/{id}/sessions/start ā†’ Begin session\n2. PATCH /v1/workouts/{id}/sessions/{sessionId} ā†’ Track progress\n3. GET /v1/workouts/{id}/sessions/recent ā†’ Check last session\n4. GET /v1/workouts/{id}/sessions/{sessionId} ā†’ Get session details\n5. POST /v1/workouts/{id}/sessions/complete ā†’ Force completion\n6. POST /v1/workouts/{id}/feedback ā†’ Submit feedback\n```\n\n---\n\n## āš ļø Error Handling Guide\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 parameters, missing required fields | Check request body and parameters |\n| **401** | Unauthorized | Missing or invalid API key | Verify API key in headers |\n| **403** | Forbidden | API key not associated with organization | Check organization ID and API key match |\n| **404** | Not Found | Resource doesn't exist | Verify IDs and check if resource was deleted |\n| **409** | Conflict | Resource already exists (active session) | Handle existing resources appropriately |\n| **422** | Unprocessable Entity | Validation errors in request data | Check field validation rules |\n| **429** | Too Many Requests | Rate limit exceeded | Implement exponential backoff |\n| **500** | Internal Server Error | Server-side issue | Retry with exponential backoff |\n\n### Error Response Format\n```json\n{\n \"statusCode\": 400,\n \"message\": \"Validation failed\",\n \"error\": \"Bad Request\",\n \"details\": [\n {\n \"field\": \"durationOptions.minMinutes\",\n \"message\": \"must be a positive number\"\n }\n ]\n}\n```\n\n### Best Practices for Error Handling\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```javascript\n// Example retry logic\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; // Exponential backoff\n await new Promise(resolve => setTimeout(resolve, delay));\n continue;\n }\n throw error; // Don't retry client errors\n }\n }\n throw new Error('Max retries exceeded');\n};\n```\n\n---\n\n## šŸš¦ Rate Limiting\n\n### Rate Limit Headers\nAll responses include rate limiting information:\n\n```\nX-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 999\nX-RateLimit-Reset: 1640995200\n```\n\n### Rate Limit Handling\n\n**Headers Explained:**\n- `X-RateLimit-Limit` - Maximum requests per window\n- `X-RateLimit-Remaining` - Requests remaining in current window\n- `X-RateLimit-Reset` - Unix timestamp when limit resets\n\n**Note:** AI and full video streaming 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` - Get real-time API usage statistics including current hour requests, daily totals, and rate limits\n\n---\n\n## šŸ”‘ Authentication\n\nAdd to all requests:\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\n---\n\n## šŸ“š Resources\n\n- **OpenAPI Spec:** [/docs/api-explorer-json](https://content.api.hyperhuman.cc/docs/api-explorer-json)\n- **Support:** support@hyperhuman.cc\n- **Website:** [hyperhuman.cc](https://hyperhuman.cc)\n ","version":"1.0","contact":{"name":"Hyperhuman","url":"https://hyperhuman.cc","email":"support@hyperhuman.cc"}},"tags":[],"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: 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"]},"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":{"type":"object","description":"Pagination links"},"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"}]}}},"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 (MongoDB ObjectId)"},"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 (MongoDB ObjectId from the Instance entity)"},"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,45,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"]},"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}}},"OrganizationSocialPublishTaskResponseDto":{"type":"object","properties":{"_id":{"type":"string"},"_teamId":{"type":"string"},"_ownerId":{"type":"string"},"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,45,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"},"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":["_id","_teamId","_ownerId","name","status","publishAssetType","sourceMode","readyDropPick","allowedDropSourceTypes","primaryChannelPreset","channelPresets","repeatMode","createdAt","updatedAt"]},"OrganizationSocialPublishTaskListResponse":{"type":"object","properties":{"links":{"description":"Pagination links","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,45,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":"string"},"workoutId":{"type":"string"},"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,45,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"]},"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 links","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"]},"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"]},"GroupExerciseInstanceDto":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"trainer":{"$ref":"#/components/schemas/TrainerRef"},"name":{"type":"string"},"kind":{"type":"string","enum":["single-exercise","multi-exercise","class","promo","educational"]},"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"}]},"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","duration"]},"GroupExercisesListResponse":{"type":"object","properties":{"links":{"description":"Pagination links","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":{"type":"object","description":"Pagination links"},"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"}]}}},"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"},"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","description":"A map where keys are position indices (as strings) and values contain completion status, latest completion date, and workout details","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":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EndUserProfileDto"}},"total":{"type":"number"}},"required":["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"]}}}}