---
name: nutrition-chat
description: Ask an AI assistant questions about a user's Eat My Words diet history and goals, with multi-turn conversation support.
---

# nutrition-chat

Send a message to the Eat My Words nutrition assistant. The assistant has access
to the user's food logs, goals, and recent history, so it can answer open-ended
questions ("what should I eat for dinner to hit my protein goal?", "how has my
sugar intake trended this week?") that go beyond a single day's totals.

## When to use

- The user asks an open-ended or analytical question about their diet that needs reasoning over history.
- A simple totals lookup (`daily-summary.md`) isn't enough.

Prefer `daily-summary.md` for plain "how many X today" questions — it's free and
faster. This endpoint uses AI and **counts against the user's monthly budget**.

## Endpoint

```
POST https://words.my/api/v1/chat/
```

Headers:

| Header | Value |
| --- | --- |
| `Authorization` | `Api-Key <USER_KEY>` |
| `Content-Type` | `application/json` |

Body:

```json
{
  "message": "What should I eat for dinner to hit my protein goal?",
  "chat_id": 87
}
```

| Field | Required | Notes |
| --- | --- | --- |
| `message` | yes | The user's question or instruction for the assistant. |
| `chat_id` | no | Omit on the first call. The response returns a `chat_id`; pass it back on every later call to continue the same conversation with full context. |

## Response

Success (HTTP 200):

```json
{
  "reply": "You're at 95 g of protein with a 120 g goal...",
  "chat_id": 87,
  "usage": {
    "month": "2026-05",
    "estimated_cost_usd": 0.83,
    "budget_usd": 2.0,
    "remaining_usd": 1.17,
    "over_budget": false
  }
}
```

Show `reply` to the user verbatim (it's already conversational). **Store
`chat_id`** and send it on the next turn to keep the conversation going. The
`usage` block reports the user's current-month AI spend against their budget.

## Multi-turn conversations

1. First call: send `message` only → receive `reply` and a new `chat_id`.
2. Every following call: send `message` **and** the saved `chat_id`.
3. To start a fresh, unrelated conversation, omit `chat_id` again.

## Budget

Each call costs AI credits. When the user reaches their monthly budget the
endpoint returns **HTTP 429** and stops responding until the next calendar month.
Read the remaining budget any time from `GET /api/v1/chat/usage/`, or from the
`usage` block on each successful reply.

## Errors

| Status | Cause | Recovery |
| --- | --- | --- |
| 401 / 403 | Missing or invalid `Authorization` header | Ask the user to create an API key at their profile. |
| 400 | Body is not valid JSON, or `message` missing | Fix the request body. |
| 404 | `chat_id` doesn't belong to this user / doesn't exist | Drop `chat_id` and start a new conversation. |
| 429 | Monthly AI budget reached | Stop; tell the user the budget resets next month. |
| 502 | Transient AI outage | Retry once after a short delay; surface the error if it persists. |

## Example — curl

```bash
curl -sS https://words.my/api/v1/chat/ \
  -H "Authorization: Api-Key $EMW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "How am I doing on protein today?"}'
```

## Related endpoints

- `GET /api/v1/chat/usage/` — current-month AI usage and remaining budget.
- `GET /api/v1/daily-summary/` — free, non-AI totals for a day (see `daily-summary.md`).