Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.onvy.health/llms.txt

Use this file to discover all available pages before exploring further.

health-api exposes two AI surfaces on top of a user’s harmonized health data:
  • chat completions for conversational AI with ONVY context injection
  • ai_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 nameBuilt fromGeneration
MealSummaryA meal description or photo plus meal_time, portion_multiplierCustomer-triggered via POST /users/{user_id}/ai/summaries with type=meal, or via POST /users/{user_id}/nutrition/meals
WorkoutSummaryA completed workout activity for the userSystem-generated when activity data lands
MindfulsessionSummaryA mindfulness session for the userSystem-generated
SleepSummarySleep records for the userSystem-generated
DailySummaryThe full set of daily signals for one daySystem-generated
DailyNutritionSummaryDaily nutrition aggregatesSystem-generated
WeeklySummaryWeekly aggregate signalsSystem-generated
WeeklyActivitySummaryWeekly activity aggregatesSystem-generated
WeeklyNutritionSummaryWeekly nutrition aggregatesSystem-generated
TrendSummaryMulti-week or multi-month signalsSystem-generated
ImpactSummaryHabit and behavior impact analysisSystem-generated
System-generated summaries are produced asynchronously when the underlying data becomes available. You consume them through the same list and detail routes regardless of who triggered the generation.

​
Read AI summaries

curl -sS "$BASE_URL/users/$USER_ID/ai/summaries?name=MealSummary&limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Filter by 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
    }
  }'
You can submit either a 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:
  • messages
  • model
  • temperature
  • max_tokens
  • stream
  • exclude_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.