{"openapi":"3.1.0","info":{"title":"Workout Exercise API","version":"2.0.0","description":"Exercise database with animated stickers for WhatsApp (WebP) and Telegram (WEBM). 101 exercises covering chest, back, shoulders, legs, biceps, triceps, core, and power movements. Optimized for AI agent consumption with field filtering, pagination, and workout generation."},"servers":[{"url":"https://exercise-api.uranusim.workers.dev","description":"Production"}],"paths":{"/exercises":{"get":{"operationId":"listExercises","summary":"List all exercises","x-agent-hint":"Returns all exercises. Use ?fields= to reduce token usage. Use ?limit=&offset= to paginate. For filtered results, use /exercises/search instead.","description":"Returns all exercises with sticker URLs and Telegram file IDs. Supports field filtering and pagination.","parameters":[{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to return (e.g. 'name,muscles,stickerUrl'). Omit to return all fields. Reduces token usage for AI agents.","example":"name,muscles,difficulty,stickerUrl"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1},"description":"Maximum number of results to return."},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0},"description":"Number of results to skip (for pagination)."}],"responses":{"200":{"description":"Array of exercises (or paginated object when limit/offset used)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Exercise"}}}}}}}},"/exercise/{id}":{"get":{"operationId":"getExercise","summary":"Get exercise by ID","x-agent-hint":"Use when you already know the exercise ID. Use ?fields= to reduce token usage.","description":"Returns a single exercise by its numeric ID (0-100).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":0,"maximum":100},"description":"Exercise ID"},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to return (e.g. 'name,muscles,stickerUrl'). Omit to return all fields. Reduces token usage for AI agents.","example":"name,muscles,difficulty,stickerUrl"}],"responses":{"200":{"description":"Exercise object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Exercise"}}}},"400":{"description":"Invalid ID"},"404":{"description":"Exercise not found"}}}},"/exercises/meta":{"get":{"operationId":"getExerciseMeta","summary":"Get valid filter values","x-agent-hint":"Call this FIRST to discover valid muscle names, equipment types, and difficulty levels before filtering. Avoids trial-and-error with search params.","description":"Returns all valid enum values for muscles, equipment, and difficulties. Use this to discover valid filter values before calling search, random, or workout endpoints.","responses":{"200":{"description":"Available filter values","content":{"application/json":{"schema":{"type":"object","properties":{"muscles":{"type":"array","items":{"type":"string"}},"equipment":{"type":"array","items":{"type":"string"}},"difficulties":{"type":"array","items":{"type":"string"}},"count":{"type":"integer","description":"Total number of exercises"}}},"example":{"muscles":["Back","Biceps","Chest","Core","Forearms","Legs","Shoulders","Triceps"],"equipment":["Barbell","Bench","Cable Machine","Dumbbells"],"difficulties":["Advanced","Beginner","Intermediate"],"count":101}}}}}}},"/exercises/random":{"get":{"operationId":"getRandomExercises","summary":"Get random exercises","x-agent-hint":"Use when the user wants exercise suggestions or a quick pick. Supports all search filters plus count.","description":"Returns N random exercises matching optional filters. Use for suggestions, quick picks, or varied recommendations.","parameters":[{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":1},"description":"Number of random exercises to return (max 20)."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search by exercise name or functional use (case-insensitive substring match)."},{"name":"muscle","in":"query","schema":{"type":"string"},"description":"Filter by target muscle."},{"name":"equipment","in":"query","schema":{"type":"string"},"description":"Filter by equipment type."},{"name":"difficulty","in":"query","schema":{"type":"string","enum":["Beginner","Intermediate","Advanced"]},"description":"Filter by difficulty."},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to return (e.g. 'name,muscles,stickerUrl'). Omit to return all fields. Reduces token usage for AI agents.","example":"name,muscles,difficulty,stickerUrl"}],"responses":{"200":{"description":"Random exercise results","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"exercises":{"type":"array","items":{"$ref":"#/components/schemas/Exercise"}}}}}}}}}},"/exercises/workout":{"get":{"operationId":"generateWorkout","summary":"Generate a workout","x-agent-hint":"Use when the user wants a complete workout plan. Distributes exercises evenly across requested muscle groups. Requires muscles param.","description":"Generates a balanced workout by distributing exercises across requested muscle groups. Avoids duplicates and mixes equipment types.","parameters":[{"name":"muscles","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated muscle groups (e.g. 'chest,triceps,shoulders')."},{"name":"count","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":6},"description":"Total number of exercises in the workout (max 30)."},{"name":"difficulty","in":"query","schema":{"type":"string","enum":["Beginner","Intermediate","Advanced"]},"description":"Filter by difficulty."},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to return (e.g. 'name,muscles,stickerUrl'). Omit to return all fields. Reduces token usage for AI agents.","example":"name,muscles,difficulty,stickerUrl"}],"responses":{"200":{"description":"Generated workout","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"muscles":{"type":"array","items":{"type":"string"}},"difficulty":{"type":"string"},"exercises":{"type":"array","items":{"$ref":"#/components/schemas/Exercise"}}}}}}},"400":{"description":"Missing muscles param"}}}},"/exercises/search":{"get":{"operationId":"searchExercises","summary":"Search exercises","x-agent-hint":"Use for filtered queries when the user asks for exercises by muscle, equipment, difficulty, or keyword. Supports field filtering and pagination.","description":"Filter exercises by name/functional use, target muscle, equipment, or difficulty. All parameters are optional and combined with AND logic.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search by exercise name or functional use (case-insensitive substring match)."},{"name":"muscle","in":"query","schema":{"type":"string"},"description":"Filter by target muscle, e.g. 'chest', 'biceps', 'lats'."},{"name":"equipment","in":"query","schema":{"type":"string"},"description":"Filter by equipment, e.g. 'barbell', 'dumbbell', 'cable'."},{"name":"difficulty","in":"query","schema":{"type":"string","enum":["Beginner","Intermediate","Advanced"]},"description":"Filter by difficulty level."},{"name":"fields","in":"query","schema":{"type":"string"},"description":"Comma-separated list of fields to return (e.g. 'name,muscles,stickerUrl'). Omit to return all fields. Reduces token usage for AI agents.","example":"name,muscles,difficulty,stickerUrl"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1},"description":"Maximum number of results to return."},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0},"description":"Number of results to skip (for pagination)."}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Total matching results before pagination"},"count":{"type":"integer","description":"Number of results returned"},"exercises":{"type":"array","items":{"$ref":"#/components/schemas/Exercise"}}}}}}}}}}},"components":{"schemas":{"Exercise":{"type":"object","properties":{"id":{"type":"integer","description":"Unique exercise ID (0-based)"},"name":{"type":"string","description":"Exercise name, e.g. 'Barbell Bench Press'"},"equipment":{"type":"array","items":{"type":"string"},"description":"Equipment needed, e.g. ['Barbell', 'Bench']"},"muscles":{"type":"array","items":{"type":"string"},"description":"Target muscles, e.g. ['Chest', 'Triceps']"},"difficulty":{"type":"string","enum":["Beginner","Intermediate","Advanced"]},"functionalUse":{"type":"string","description":"Brief functional purpose"},"instructions":{"type":"string","description":"How to perform the exercise"},"stickerUrl":{"type":"string","nullable":true,"description":"Full URL to animated WebP sticker (512x512, transparent). Can be used directly as WhatsApp Cloud API sticker link.","example":"https://exercise-api.uranusim.workers.dev/stickers/barbell-bench-press.webp"},"spriteClasses":{"type":"object","nullable":true,"description":"CSS class names for sprite sheet animation","properties":{"batch":{"type":"string","description":"Batch CSS class, e.g. 'sprite-batch1'"},"exercise":{"type":"string","description":"Exercise CSS class, e.g. 'exercise-barbell-bench-press'"}}},"telegramSticker":{"type":"object","nullable":true,"description":"Telegram sticker info for sending via Bot API sendSticker","properties":{"fileId":{"type":"string","description":"Telegram file_id to pass to sendSticker API"},"pack":{"type":"string","description":"Sticker pack name on Telegram"}}}}}}}}