> ## 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.

# AI capabilities

> Use ONVY chat completions and AI summaries on top of harmonized health context.

`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 `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                                                                                                             |

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

```bash theme={null}
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`:

```bash theme={null}
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.

<Tip>
  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.
</Tip>