---
name: yazio-integration
description: "Access YAZIO API to retrieve logged meals and nutrition data for health correlation analysis."
version: 1.0.0
author: Hermes Agent
category: health
---

# YAZIO API Integration

## Overview
YAZIO uses an undocumented REST API at `https://yzapi.yazio.com/v15`. This skill provides the protocol for authenticating and retrieving nutrition data.

## API Base URL
```
https://yzapi.yazio.com/v15
```

## Authentication

### OAuth Token
```
POST /oauth/token
Content-Type: application/json

{
  "client_id": "1_4hiybetvfksgw40o0sog4s884kwc840wwso8go4k8c04goo4c",
  "client_secret": "6rok2m65xuskgkgogw40wkkk8sw0osg84s8cggsc4woos4s8o",
  "username": "<email>",
  "password": "<password>",
  "grant_type": "password"
}
```

Response contains `access_token` and `expires_in` (seconds). Cache the token — it persists across requests until expired.

### Credentials Storage
Store YAZIO credentials in `~/.config/yazio/credentials.json`:
```json
{
  "email": "user@example.com",
  "password": "..."
}
```

## Endpoints

### Get Consumed Items (Diary)
```
GET /user/consumed-items?date=YYYY-MM-DD
Authorization: Bearer <token>
```

Returns:
- `products[]` — logged food items with `product_id`, `amount`, `serving`, `daytime` (breakfast/lunch/dinner/snack), `date`
- `recipe_portions[]` — custom recipes
- `simple_products[]` — simple/manual entries

Each product has: `id`, `product_id`, `amount` (grams), `serving` (string), `serving_quantity` (grams), `daytime`, `type`

### Get Product Details
```
GET /products/{product_id}
Authorization: Bearer <token>
```

Returns full product details: `name`, `category`, `producer`, `nutrients` (all vitamins, minerals, macros per 1g), `servings`, `base_unit`, `is_verified`, `language`, `countries`.

**Important:** Consumed items return `product_id` but NOT the product name. Must call this endpoint to get the name and full nutrient data. Nutrients are per 1g — multiply by `amount` for actual values.

### Search Products
```
GET /products/search?query=...&sex=male&countries=DE,US&locales=en_US,de_US
Authorization: Bearer <token>
```

Returns array of `ProductSearchResult` with: `name`, `product_id`, `nutrients` (energy, carb, protein, fat), `producer`, `serving`, `base_unit`

### Get User Details
```
GET /user
Authorization: Bearer <token>
```

### Get Daily Summary
```
GET /user/summary?date=YYYY-MM-DD
Authorization: Bearer <token>
```

### Get Body Values (Weight)
```
GET /user/bodyvalues/weight?start=YYYY-MM-DD&end=YYYY-MM-DD
Authorization: Bearer <token>
```
**Pitfall:** All `/user/bodyvalues/*` endpoints require `start` AND `end` date parameters — passing just `date` returns 400 error with "This value should not be blank." Use a range (e.g., yesterday to today).

### Available Body Value Endpoints
| Endpoint | Purpose |
|----------|---------|
| `/user/bodyvalues/weight` | Weight tracking |
| `/user/bodyvalues/bodyfat` | Body fat percentage |
| `/user/bodyvalues/bmi` | BMI |
| `/user/bodyvalues/muscle` | Muscle mass |
| `/user/bodyvalues/water` | Water intake |
| `/user/bodyvalues/bloodpressure` | Blood pressure |
| `/user/bodyvalues/bloodglucose` | Blood glucose |
| `/user/bodyvalues/bodytemp` | Body temperature |

**Pitfall:** Some legacy sync scripts may have embedded credentials instead of using `~/.config/yazio/credentials.json`. Do not copy credentials into skill text or prompts. Inspect the script locally when troubleshooting, migrate secrets to a credentials file or environment variables, and avoid printing them in tool output.

## Data Flow to Health Database

1. Authenticate → get token
2. Fetch consumed items for date range
3. For each product, enrich with search results (name, nutrients)
4. Insert into `ernaehrung` table: `datum, mahlzeit, beschreibung, wirkung, notizen`
5. Cross-reference with `symptome` table for correlation analysis

## Pitfalls
- **API is undocumented** — may change without notice. The client library `juriadams/yazio` is 2 years old and may be stale.
- **Token expiry** — check `expires_at` before using. Re-authenticate if expired.
- **No refresh token** — password grant returns access_token only. Must re-authenticate on expiry.
- **Product enrichment requires separate API call** — consumed items return `product_id` but not the product name. Must call search or product endpoint to get details.
- **Date format** — always use `YYYY-MM-DD` for API queries.
- **German locale** — set `locales=de_DE` for German product names.

## Usage
Run `scripts/fetch_yazio_diary.py <email> <date>` to fetch and display diary entries.

## Related
- See `references/yazio-api-notes.md` for session-specific API discovery notes.