health-api exposes two AI surfaces on top of a user’s harmonized health data:
chat completions for conversational AI with ONVY context injectionai_summaries for typed, persisted AI outputs that turn raw inputs (meals, workouts, sleep, daily and weekly trends) into structured analysis your product can read back later
If you cannot find a public endpoint for a specific health domain such as meals, sleep insight, or activity insight, this is usually because the analyzed result is delivered through ai_summaries rather than as a separate resource.
AI summaries
GET /users/{user_id}/ai/summaries and related routes manage persisted AI summaries. Each summary carries a name (the summary type), a period, structured data, and llm_output with a generated title, text, and optional followup_questions.
Summary types
Summary name | Built from | Generation |
|---|
MealSummary | A meal description or photo plus meal_time, portion_multiplier | Customer-triggered via POST /users/{user_id}/ai/summaries with type=meal, or via POST /users/{user_id}/nutrition/meals |
WorkoutSummary | A completed workout activity for the user | System-generated when activity data lands |
MindfulsessionSummary | A mindfulness session for the user | System-generated |
SleepSummary | Sleep records for the user | System-generated |
DailySummary | The full set of daily signals for one day | System-generated |
DailyNutritionSummary | Daily nutrition aggregates | System-generated |
WeeklySummary | Weekly aggregate signals | System-generated |
WeeklyActivitySummary | Weekly activity aggregates | System-generated |
WeeklyNutritionSummary | Weekly nutrition aggregates | System-generated |
TrendSummary | Multi-week or multi-month signals | System-generated |
ImpactSummary | Habit and behavior impact analysis | System-generated |
Read AI summaries
curl -sS "$BASE_URL/users/$USER_ID/ai/summaries?name=MealSummary&limit=20" \
-H "Authorization: Bearer $ACCESS_TOKEN"
name, start_date, end_date, and limit. Treat the returned page and next_page as opaque pagination tokens.
Create a meal summary
The current public create surface accepts type=meal:
curl -sS -X POST "$BASE_URL/users/$USER_ID/ai/summaries" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "meal",
"data": {
"description": "Grilled chicken breast with quinoa and steamed broccoli",
"meal_time": "2026-04-20T12:00:00Z",
"portion_multiplier": 1.5
}
}'
description or an image_base64. The response returns a MealSummary with data (calories, macros, glucose impact, healthiness score) and llm_output (title, text, follow-up questions).
Meal endpoint vs AI summary endpoint
POST /users/{user_id}/nutrition/meals is the higher-level meal flow. It stores the meal, runs nutrition analysis asynchronously, links the resulting MealSummary via summary_id, and emits a meals:updated webhook when analysis completes. Use the meals endpoint when you want a meal record in your timeline; use POST /users/{user_id}/ai/summaries when you only want the AI analysis.
User feedback on summaries
PATCH /users/{user_id}/ai/summaries/{summary_id} updates user_comment and user_rating (-1, 0, 1) without re-running generation. PUT regenerates the llm_output for the same summary identifier.
Chat completions
POST /users/{user_id}/chat/completions is an OpenAI-compatible chat surface that injects ONVY context for the user.
Request body highlights:
messagesmodeltemperaturemax_tokensstreamexclude_context
exclude_context lets you suppress parts of ONVY enrichment, for example knowledge, scores, workouts, facts, or all. Otherwise the call automatically uses the same harmonized health context that powers AI summaries: scores, workouts, facts, and knowledge matches for the user.
Completions are persisted. Use GET /users/{user_id}/chat/completions to list them, GET /users/{user_id}/chat/completions/{completion_id} to read one, and PATCH to update fields such as user feedback.
Webhook events for AI outputs
Subscribe to ai_summaries:* to react to summary generation, regeneration, and updates. meals:* events also signal when a meal’s summary_id becomes available after async analysis.
Standard data ingestion and user creation should land first. AI summaries become significantly more useful once facts, daily_records, and activity history exist for the user, because system-generated summaries depend on that underlying data.
