{"openapi":"3.0.3","info":{"title":"Helios Health API","version":"1.2.0","description":"Public health and authenticated Helios client endpoints. REST account endpoints require a signed-in session. Agents use the OAuth-protected MCP server; its tokens do not grant REST session access. REST uses /api/v1; breaking changes require a new major path. The current v1 API has no announced deprecation or retirement date. See the [versioning and deprecation policy](https://www.getheliosapp.com/docs/api/#versioning-and-deprecation-policy).","contact":{"name":"Helios Health support","email":"support@getheliosapp.com","url":"https://www.getheliosapp.com/support/"}},"servers":[{"url":"https://api.getheliosapp.com"}],"components":{"schemas":{"AccountAccess":{"type":"object","properties":{"allowed":{"type":"boolean"},"code":{"type":"string","enum":["beta","subscription","access_expired","account_suspended","account_deleting","access_unavailable"]},"serverTime":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"trialAvailable":{"type":"boolean","enum":[false]},"billing":{"type":"object","nullable":true,"properties":{"provider":{"type":"string","enum":["apple","web"]},"status":{"type":"string","enum":["active","canceled","grace","expired","refunded","revoked"]},"paidThrough":{"type":"string","nullable":true,"format":"date-time"},"graceThrough":{"type":"string","nullable":true,"format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"}},"required":["provider","status","paidThrough","graceThrough","cancelAtPeriodEnd"]}},"required":["allowed","code","serverTime","expiresAt","trialAvailable","billing"]},"Problem":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"type":"object","additionalProperties":{"nullable":true}}},"required":["code","message","requestId"]},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"apiVersion":{"type":"string"},"buildVersion":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}},"required":["status","apiVersion","buildVersion","timestamp"]},"TrainingNoteList":{"type":"object","properties":{"notes":{"type":"array","items":{"$ref":"#/components/schemas/TrainingNote"}}},"required":["notes"]},"TrainingNote":{"allOf":[{"$ref":"#/components/schemas/TrainingNotePayload"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":0,"exclusiveMinimum":true},"revision":{"$ref":"#/components/schemas/RevisionHash"}},"required":["id","version","revision"]}]},"RevisionHash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"TrainingNotePayload":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"detail":{"type":"string","maxLength":50000},"workoutPlanId":{"type":"string","nullable":true,"format":"uuid"},"exerciseId":{"type":"string","nullable":true,"format":"uuid"},"sessionId":{"type":"string","nullable":true,"format":"uuid"},"sessionExerciseId":{"type":"string","nullable":true,"format":"uuid"},"linkedNameSnapshot":{"type":"string","minLength":1,"maxLength":500},"capturedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["title","detail","workoutPlanId","exerciseId","linkedNameSnapshot","capturedAt","createdAt","updatedAt"]},"FoodLookupResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/FoodLookupResult"},"maxItems":50},"nextCursor":{"type":"string","nullable":true}},"required":["results","nextCursor"]},"FoodLookupResult":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":240},"name":{"type":"string","minLength":1,"maxLength":160},"brand":{"type":"string","nullable":true,"maxLength":120},"servingLabel":{"type":"string","minLength":1,"maxLength":80},"servingMassMilligrams":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"nutrients":{"$ref":"#/components/schemas/NutrientAmount"},"sourceName":{"type":"string","minLength":1,"maxLength":120},"sourceUrl":{"type":"string","nullable":true,"format":"uri"},"barcode":{"type":"string","nullable":true,"pattern":"^\\d{8,14}$"}},"required":["key","name","brand","servingLabel","servingMassMilligrams","nutrients","sourceName","sourceUrl","barcode"]},"NutrientAmount":{"type":"object","properties":{"energyMilliKcal":{"type":"integer","nullable":true,"minimum":0},"proteinMilligrams":{"type":"integer","nullable":true,"minimum":0},"carbohydrateMilligrams":{"type":"integer","nullable":true,"minimum":0},"fatMilligrams":{"type":"integer","nullable":true,"minimum":0}},"required":["energyMilliKcal","proteinMilligrams","carbohydrateMilligrams","fatMilligrams"]},"NutritionEstimateDraft":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"meal":{"$ref":"#/components/schemas/MealSnapshot"},"confidence":{"type":"string","enum":["low","medium","high"]},"assumptions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":240},"maxItems":10},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"url":{"type":"string","format":"uri"}},"required":["name","url"]},"minItems":1,"maxItems":10},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","meal","confidence","assumptions","sources","expiresAt"]},"MealSnapshot":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":160},"servingLabel":{"type":"string","minLength":1,"maxLength":80},"servingMassMilligrams":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"default":null},"nutrients":{"$ref":"#/components/schemas/NutrientAmount"},"source":{"type":"string","enum":["custom","plan","barcode","lookup","ai_estimate"]},"sourceReference":{"type":"string","nullable":true,"maxLength":500,"default":null},"savedMealId":{"type":"string","nullable":true,"format":"uuid","default":null},"savedMealRevision":{"type":"string","nullable":true,"pattern":"^[0-9a-f]{64}$","default":null}},"required":["name","servingLabel","nutrients","source"]},"NutritionEstimateRequest":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":500},"portion":{"type":"string","nullable":true,"maxLength":160,"default":null}},"required":["description"]},"TrainingNoteHistory":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["created","edited","archived"]},"revision":{"$ref":"#/components/schemas/RevisionHash"},"changedAt":{"type":"string","format":"date-time"}},"required":["kind","revision","changedAt"]}}},"required":["entries"]},"NotePhotoList":{"type":"object","properties":{"photos":{"type":"array","items":{"$ref":"#/components/schemas/NotePhoto"}}},"required":["photos"]},"NotePhoto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"noteId":{"type":"string","format":"uuid"},"contentType":{"type":"string","enum":["image/jpeg"]},"byteSize":{"type":"integer","minimum":0,"exclusiveMinimum":true},"width":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"height":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","noteId","contentType","byteSize","width","height","createdAt"]},"ExerciseLibrarySnapshot":{"type":"object","properties":{"version":{"type":"integer","minimum":0,"exclusiveMinimum":true},"exercises":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","minLength":1,"maxLength":250},"name":{"type":"string","minLength":1,"maxLength":200},"instructions":{"type":"string","maxLength":50000},"movementPattern":{"type":"string","maxLength":200},"muscles":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"role":{"type":"string","enum":["primary","secondary"]}},"required":["name","role"]},"maxItems":50},"equipment":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50}},"required":["id","slug","name","instructions","movementPattern","muscles","equipment"]}},"revision":{"$ref":"#/components/schemas/RevisionHash"}},"required":["version","exercises","revision"]},"SyncPullResponse":{"type":"object","properties":{"changes":{"type":"array","items":{"$ref":"#/components/schemas/SyncChange"}},"nextCursor":{"type":"string"},"hasMore":{"type":"boolean"}},"required":["changes","nextCursor","hasMore"]},"SyncChange":{"type":"object","properties":{"sequence":{"type":"integer","minimum":0},"operationId":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["profile","custom_exercise","workout_plan","workout_session","training_note","saved_meal","meal_plan","nutrition_day","scheduled_meal","food_entry"]},"entityId":{"type":"string","format":"uuid"},"operation":{"type":"string","enum":["create","update","archive","void","correct"]},"version":{"type":"integer","minimum":0,"exclusiveMinimum":true},"revision":{"$ref":"#/components/schemas/RevisionHash"},"parentRevision":{"allOf":[{"$ref":"#/components/schemas/RevisionHash"},{"nullable":true}]},"payload":{"type":"object","additionalProperties":{"nullable":true}},"changedAt":{"type":"string","format":"date-time"}},"required":["sequence","operationId","entityType","entityId","operation","version","revision","parentRevision","payload","changedAt"]},"SyncBootstrapResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SyncBootstrapItem"}},"checkpoint":{"type":"string","pattern":"^\\d+$"},"nextPageCursor":{"type":"string","format":"uuid"},"hasMore":{"type":"boolean"}},"required":["items","checkpoint","hasMore"]},"SyncBootstrapItem":{"type":"object","properties":{"operationId":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["profile","custom_exercise","workout_plan","workout_session","training_note","saved_meal","meal_plan","nutrition_day","scheduled_meal","food_entry"]},"entityId":{"type":"string","format":"uuid"},"operation":{"type":"string","enum":["create","update","archive","void","correct"]},"version":{"type":"integer","minimum":0,"exclusiveMinimum":true},"revision":{"$ref":"#/components/schemas/RevisionHash"},"parentRevision":{"allOf":[{"$ref":"#/components/schemas/RevisionHash"},{"nullable":true}]},"payload":{"type":"object","additionalProperties":{"nullable":true}},"changedAt":{"type":"string","format":"date-time"}},"required":["operationId","entityType","entityId","operation","version","revision","parentRevision","payload","changedAt"]},"SyncPushResponse":{"type":"object","properties":{"applied":{"type":"array","items":{"$ref":"#/components/schemas/SyncChange"}}},"required":["applied"]},"SyncConflictResponse":{"type":"object","properties":{"code":{"type":"string","enum":["version_conflict"]},"message":{"type":"string"},"requestId":{"type":"string"},"operationIndex":{"type":"integer","minimum":0},"operationId":{"type":"string","format":"uuid"},"current":{"$ref":"#/components/schemas/SyncChange"}},"required":["code","message","requestId","operationIndex"]},"SyncPushRequest":{"type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"operations":{"type":"array","items":{"$ref":"#/components/schemas/SyncPushOperation"},"minItems":1,"maxItems":500}},"required":["idempotencyKey","operations"]},"SyncPushOperation":{"type":"object","properties":{"operationId":{"type":"string","format":"uuid"},"entityType":{"type":"string","enum":["profile","custom_exercise","workout_plan","workout_session","training_note","saved_meal","meal_plan","nutrition_day","scheduled_meal","food_entry"]},"entityId":{"type":"string","format":"uuid"},"operation":{"type":"string","enum":["create","update","archive","void","correct"]},"expectedVersion":{"type":"integer","minimum":0},"expectedRevision":{"allOf":[{"$ref":"#/components/schemas/RevisionHash"},{"nullable":true}]},"payload":{"type":"object","additionalProperties":{"nullable":true}}},"required":["operationId","entityType","entityId","operation","payload"]}},"parameters":{},"securitySchemes":{"HeliosSession":{"type":"apiKey","in":"cookie","name":"__Secure-better-auth.session_token","description":"The session cookie supplied by Helios sign-in. MCP OAuth tokens cannot be used in its place."},"HeliosMcpOAuth":{"type":"oauth2","description":"OAuth 2.0 authorization code with PKCE for https://api.getheliosapp.com/mcp only. Request the minimum tool scopes. This scheme does not authenticate the REST session endpoints in this document.","flows":{"authorizationCode":{"authorizationUrl":"https://api.getheliosapp.com/api/auth/oauth2/authorize","tokenUrl":"https://api.getheliosapp.com/api/auth/oauth2/token","scopes":{"openid":"Identify the signed-in account.","email":"Read the account email and its verification status.","offline_access":"Refresh access after the current access token expires.","history:read":"Read completed workout history.","history:write":"Correct or void completed workout records with approval.","notes:read":"Read training notes.","notes:write":"Create, update, or delete training notes with approval.","nutrition:read":"Read nutrition records, targets, and saved meals.","nutrition:write":"Save nutrition records, targets, and meals with approval.","exercises:read":"Read the exercise library.","exercises:write":"Create or update custom exercises with approval.","workouts:read":"Read workout plans.","workouts:write":"Create, update, or delete workout plans with approval."}}}}}},"paths":{"/api/v1/account/access":{"get":{"operationId":"getAccountAccess","responses":{"200":{"description":"Current account access. No purchase starts from this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountAccess"}}}},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Access could not be checked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Current account access. No purchase starts from this response."}},"/health":{"get":{"operationId":"getHealth","responses":{"200":{"description":"API availability and version information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}},"headers":{"RateLimit-Policy":{"description":"Public discovery quota per client IP, when the quota store is available.","schema":{"type":"string","example":"\"public-api\";q=120;w=60"}},"RateLimit":{"description":"Remaining requests and seconds until the current window resets.","schema":{"type":"string","example":"\"public-api\";r=119;t=60"}}}},"429":{"description":"The public API quota was exceeded. Wait for Retry-After before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"headers":{"RateLimit-Policy":{"description":"Public discovery quota per client IP, when the quota store is available.","schema":{"type":"string","example":"\"public-api\";q=120;w=60"}},"RateLimit":{"description":"Remaining requests and seconds until the current window resets.","schema":{"type":"string","example":"\"public-api\";r=119;t=60"}},"Retry-After":{"description":"Seconds before retrying.","schema":{"type":"integer","minimum":1}}}}},"description":"API availability and version information","security":[]}},"/api/v1/analytics-preference":{"get":{"operationId":"getAnalyticsPreference","responses":{"200":{"description":"The authenticated user's optional analytics preference","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"revision":{"type":"integer","minimum":0},"updatedAt":{"type":"string","format":"date-time"}},"required":["enabled","revision","updatedAt"]}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The requested account does not match the authenticated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"The authenticated user's optional analytics preference"},"put":{"operationId":"updateAnalyticsPreference","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"expectedRevision":{"type":"integer","minimum":0}},"required":["enabled","expectedRevision"]}}}},"responses":{"200":{"description":"The updated analytics preference","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"revision":{"type":"integer","minimum":0},"updatedAt":{"type":"string","format":"date-time"}},"required":["enabled","revision","updatedAt"]}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The requested account does not match the authenticated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The preference revision is stale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"The updated analytics preference"}},"/api/v1/notes":{"get":{"operationId":"listTrainingNotes","responses":{"200":{"description":"Active training notes for the authenticated user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingNoteList"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Active training notes for the authenticated user"}},"/api/v1/nutrition/lookup":{"get":{"operationId":"lookupFood","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":160},"required":true,"name":"query","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"Normalized public food search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FoodLookupResponse"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Normalized public food search results"}},"/api/v1/nutrition/barcodes/{code}":{"get":{"operationId":"lookupFoodBarcode","parameters":[{"schema":{"type":"string","pattern":"^\\d{8,14}$"},"required":true,"name":"code","in":"path"}],"responses":{"200":{"description":"A normalized public food product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FoodLookupResult"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No product matched the barcode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"A normalized public food product"}},"/api/v1/nutrition/estimates":{"post":{"operationId":"estimateNutrition","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NutritionEstimateRequest"}}}},"responses":{"200":{"description":"A reviewable nutrition estimate draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NutritionEstimateDraft"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Nutrition estimation is not configured or is temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"A reviewable nutrition estimate draft"}},"/api/v1/notes/{noteId}/history":{"get":{"operationId":"listTrainingNoteHistory","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"noteId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Revision history for one training note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingNoteHistory"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The note was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Revision history for one training note"}},"/api/v1/notes/{noteId}/photos":{"get":{"operationId":"listNotePhotos","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"noteId","in":"path"}],"responses":{"200":{"description":"Private photo metadata for one note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotePhotoList"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The note or photo was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Photo storage is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Private photo metadata for one note"}},"/api/v1/notes/{noteId}/photos/{photoId}":{"put":{"operationId":"uploadNotePhoto","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"noteId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"photoId","in":"path"},{"schema":{"type":"string","enum":["image/jpeg"]},"required":true,"name":"content-type","in":"header"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":false,"name":"x-image-width","in":"header"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true},"required":false,"name":"x-image-height","in":"header"}],"requestBody":{"required":true,"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"The idempotent photo upload already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotePhoto"}}}},"201":{"description":"The photo was stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotePhoto"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The account does not permit uploads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The note or photo was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"The photo is empty or too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"The photo type is not supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Photo storage is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"The idempotent photo upload already exists"},"delete":{"operationId":"deleteNotePhoto","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"noteId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"photoId","in":"path"}],"responses":{"204":{"description":"The photo was deleted"},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The note or photo was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Photo storage is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"The photo was deleted"}},"/api/v1/notes/{noteId}/photos/{photoId}/content":{"get":{"operationId":"getNotePhotoContent","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"noteId","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"photoId","in":"path"}],"responses":{"200":{"description":"The private photo bytes","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"The note or photo was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"Photo storage is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"The private photo bytes"}},"/api/v1/history":{"get":{"operationId":"listWorkoutHistory","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Completed workout history for the authenticated user","content":{"application/json":{"schema":{"type":"object","properties":{"sessions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"workoutName":{"type":"string"},"status":{"type":"string","enum":["completed","voided"]},"startedAt":{"type":"string","format":"date-time"},"finishedAt":{"type":"string","nullable":true,"format":"date-time"},"exerciseCount":{"type":"integer","minimum":0},"completedSetCount":{"type":"integer","minimum":0}},"required":["id","workoutName","status","startedAt","finishedAt","exerciseCount","completedSetCount"]}},"hasMore":{"type":"boolean"}},"required":["sessions","hasMore"]}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Completed workout history for the authenticated user"}},"/api/v1/workout-plans":{"get":{"operationId":"listWorkoutPlans","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Active workout plans for the authenticated user","content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":0,"exclusiveMinimum":true},"revision":{"$ref":"#/components/schemas/RevisionHash"},"name":{"type":"string","minLength":1,"maxLength":500},"notes":{"type":"string","nullable":true,"maxLength":10000},"exercises":{"type":"array","items":{"type":"object","properties":{"exerciseDefinitionId":{"type":"string","format":"uuid","description":"Copy an active definition ID from list_exercises; do not use its name or a plan exercise ID."},"defaultRestSeconds":{"type":"integer","nullable":true,"minimum":0,"maximum":86400,"description":"Default rest in seconds; null means no default."},"notes":{"type":"string","nullable":true,"maxLength":10000},"id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":0},"exerciseNameSnapshot":{"type":"string","minLength":1,"maxLength":500},"sets":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["warmup","working","drop","cooldown","failure"]},"targetRepetitionsMin":{"type":"integer","nullable":true,"minimum":0,"maximum":10000,"description":"Minimum target repetitions; null means unset."},"targetRepetitionsMax":{"type":"integer","nullable":true,"minimum":0,"maximum":10000,"description":"Maximum target repetitions; null means unset."},"targetLoadGrams":{"type":"integer","nullable":true,"minimum":0,"maximum":2000000,"description":"Target load in whole grams; null means unset."},"targetRpe":{"type":"integer","nullable":true,"minimum":1,"maximum":10,"description":"Target rating of perceived exertion from 1 to 10; null means unset."},"restOverrideSeconds":{"type":"integer","nullable":true,"minimum":0,"maximum":86400,"description":"Set rest in seconds; null uses the exercise default."},"id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":0}},"required":["kind","targetRepetitionsMin","targetRepetitionsMax","targetLoadGrams","targetRpe","restOverrideSeconds","id","position"]}}},"required":["exerciseDefinitionId","defaultRestSeconds","notes","id","position","exerciseNameSnapshot","sets"]}},"archivedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","version","revision","name","notes","exercises","archivedAt","createdAt","updatedAt"]}},"hasMore":{"type":"boolean"}},"required":["plans","hasMore"]}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Active workout plans for the authenticated user"}},"/api/v1/exercises/library":{"get":{"operationId":"getExerciseLibrary","responses":{"200":{"description":"The current global exercise library","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExerciseLibrarySnapshot"}}}},"304":{"description":"The client already has the current exercise library"},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"The current global exercise library"}},"/api/v1/sync/pull":{"get":{"operationId":"pullSyncChanges","parameters":[{"schema":{"type":"string","default":"0"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Tenant changes after the supplied cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncPullResponse"}}}},"400":{"description":"The supplied cursor is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Tenant changes after the supplied cursor"}},"/api/v1/sync/bootstrap":{"get":{"operationId":"bootstrapSyncState","parameters":[{"schema":{"type":"string","pattern":"^\\d+$"},"required":false,"name":"checkpoint","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of current materialized state and its pull checkpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncBootstrapResponse"}}}},"400":{"description":"The supplied bootstrap checkpoint is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"A page of current materialized state and its pull checkpoint"}},"/api/v1/sync/push":{"post":{"operationId":"pushSyncChanges","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncPushRequest"}}}},"responses":{"200":{"description":"Applied tenant changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncPushResponse"}}}},"400":{"description":"The push request is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"An operation was based on a stale version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncConflictResponse"}}}},"422":{"description":"A sync operation is invalid or not yet supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"description":"Applied tenant changes"}}},"externalDocs":{"url":"https://www.getheliosapp.com/docs/api/","description":"Helios API, MCP, OAuth scopes, and rate limits"},"security":[{"HeliosSession":[]}]}