# MacroMunch Full Read/Write API (`https://macromunch.ai`)

> MacroMunch is an AI-powered nutrition, meal planning, and macro tracking platform for iOS, Android, and Web. Every user can mint a personal API key (`mm_live_...`) with **full READ and WRITE access to everything in their MacroMunch account** — meals, photo uploads, AI vision/text macro analysis, daily & cycle macro goals, user profile settings, meal plans, favorites, common foods, run-rate analytics, AI coaching, and WebSocket/RPC commands.

## Getting Your API Key

Users can view, copy, or regenerate their personal API key (`mm_live_...`) in two ways:
1. **iOS / Mobile App**: Open **MacroMunch** → **Settings** → **API KEY & WEBHOOK**.
2. **Web**: Sign in at **https://macromunch.ai/api-key** (or **https://macromunch.ai/webtoken**), or click **API KEY** on **https://macros.xeb.ai**.

## Authentication

Every endpoint on `https://macromunch.ai` accepts your personal API key via any of:
- HTTP Bearer header (recommended):
  ```http
  Authorization: Bearer mm_live_<YOUR_API_KEY>
  ```
- X-API-Key header:
  ```http
  X-API-Key: mm_live_<YOUR_API_KEY>
  ```
- Query parameter (useful for `<img src>` or WebSocket upgrades):
  ```
  ?token=mm_live_<YOUR_API_KEY>
  ```

---

## 1. Meals, Photo Uploads & AI Analysis (WRITE)

### `POST /api/webhook/meal` (aliases: `POST /api/meals`, `POST /api/v1/meals`, `POST /api/webhooks/meal`)

Universal meal logging endpoint. Supports **three modes**:
1. **Pre-computed macros** (`description` + `calories`/`protein`/`carbs`/`fat`, or `food_items[]`), with optional base64 `image`/`images`.
2. **Photo upload + AI vision analysis**: Send base64 `image` or `images` (up to 5 photos) without macro numbers (or set `"analyze": true`). MacroMunch saves the photo(s) to the user's day and runs AI vision macro estimation synchronously (or in the background if `"async_process": true`).
3. **Text description + AI analysis**: Send `description` / `notes` without macro numbers (or set `"analyze": true`). MacroMunch runs AI text macro estimation and logs the resulting food items and macros.

#### Option A: Log a Meal with Estimated Macros or Itemized `food_items`
```json
{
  "description": "Steak and eggs breakfast",
  "meal_type": "breakfast",
  "date": "2026-10-15",
  "notes": "Post-workout breakfast",
  "reasoning": "6oz sirloin steak + 3 large whole eggs + 1 slice sourdough toast with butter.",
  "food_items": [
    {
      "name": "Top sirloin steak (6 oz cooked)",
      "calories": 340,
      "protein": 46,
      "carbs": 0,
      "fat": 16,
      "fiber": 0,
      "estimated_weight_grams": 170
    },
    {
      "name": "3 large whole eggs",
      "calories": 215,
      "protein": 18,
      "carbs": 1,
      "fat": 15,
      "fiber": 0,
      "estimated_weight_grams": 150
    }
  ]
}
```
Or a single-object summary:
```json
{
  "description": "Double protein shake with whole milk and banana",
  "calories": 510,
  "protein": 56,
  "carbs": 42,
  "fat": 11,
  "fiber": 3,
  "meal_type": "snack"
}
```

#### Option B: Upload Food Photo(s) for AI Macro Analysis
```json
{
  "image": "<BASE64_JPEG_OR_DATA_URL>",
  "notes": "Chicken katsu curry with half the rice eaten",
  "think_hard": false,
  "quantity_multiplier": 1.0,
  "date": "2026-10-15"
}
```
(For multi-angle photos of the same meal, pass `"images": ["<base64_1>", "<base64_2>"]`.)

#### Option C: Log Text Description for Server-Side AI Macro Analysis
```json
{
  "description": "2 slices of large pepperoni pizza and a Caesar side salad",
  "analyze": true,
  "think_hard": false
}
```

#### Field Reference (`POST /api/webhook/meal` / `POST /api/meals`)
- `description` (string; aliases: `text`, `name`, `title`): Meal description.
- `calories` (`cal`, `kcal`), `protein` (`protein_grams`, `p`), `carbs` (`carbs_grams`, `c`), `fat` (`fat_grams`, `f`), `fiber` (`fiber_grams`): Macro numbers. Optional when `food_items` is provided or when AI analysis runs.
- `food_items` (array; aliases: `items`, `foods`): Itemized foods (`name`, `calories`, `protein`, `carbs`, `fat`, optional `fiber`, optional `estimated_weight_grams`).
- `image` (string; aliases: `photo`, `image_base64`): Base64-encoded image (raw base64 or `data:image/jpeg;base64,...`).
- `images` (array of strings; alias: `photos`): Up to 5 base64-encoded photos of the meal.
- `analyze` (boolean, optional): Defaults to `true` when no macro numbers are provided, or `false` when macro numbers/items are provided. Set `true` to force AI analysis.
- `think_hard` (boolean, optional): Set `true` for Deep Analysis (`gemini-4-argon` high thinking + conditional web research for packaged/branded products).
- `quantity_multiplier` (number, optional; alias: `quantity`): Portion multiplier (`0 < q <= 100`, default `1.0`).
- `is_leftover` (boolean, optional): Set `true` to subtract leftover uneaten macros from the day's total.
- `async_process` (boolean, optional): Set `true` when `analyze: true` to queue analysis in the background and return immediately.
- `meal_type` (string, optional; alias: `meal`): `"breakfast"`, `"lunch"`, `"snack"`, or `"dinner"`.
  - Meal slot windows by local time: `breakfast` (`00:00–11:29`), `lunch` (`11:30–13:59`), `snack` (`14:00–15:59`), `dinner` (`16:00–23:59`).
  - If `meal_type` is explicitly specified without a timestamp, MacroMunch aligns the bundle timestamp to that meal slot so it is categorized under the requested meal.
- `local_datetime` (string, optional; aliases: `client_time`, `created_at`, `datetime`, `bundle_timestamp`): Client's local timestamp in ISO 8601 (`"2026-10-15T12:30:00"`) or RFC 3339 with offset (`"2026-10-15T12:30:00-07:00"`). Always pass the client's local time when known so the meal is recorded at the exact client time and meal slot.
- `time` (string, optional; alias: `local_time`): Client's local wall-clock time (`"HH:MM"` or `"HH:MM:SS"`, e.g. `"12:30"`).
- `date` (string, optional; aliases: `day`, `local_date`): `"YYYY-MM-DD"`. Defaults to the date of `local_datetime` or today in the user's timezone.
- `tz_offset` (integer, optional; alias: `utc_offset_minutes`): Minutes from UTC (e.g. `-420` for PDT, `-480` for PST). Defaults to the user's saved `tz_offset` in `goals.toml`.
- `photo_timestamp_utc` (integer or ISO string, optional; aliases: `timestamp_utc`, `timestamp`, `client_timestamp_utc`): Unix timestamp in seconds (or milliseconds).
- `idempotency_key` (string, optional; alias: `client_offline_id`): Deduplication key.

### Other Upload & Ephemeral Analysis Endpoints
- **`POST /api/upload`** (`multipart/form-data`): Fields `images` (file), `meal_type`, `date`, `details`, `tz_offset`, `is_leftover`, `precomputed_macros`.
- **`POST /api/analyze-image`**: Ephemeral macro estimation without logging a meal. Body: `{"image": "<base64>", "description": "optional text"}` (at least one of `image` or `description` required). Returns `{ "macros": { "name", "calories", "protein", "carbs", "fat", "fiber" }, "food_items": [...], "reasoning": "..." }`.
- **`POST /api/extract_macros`**: Extract macro targets from a screenshot or text (`{"text": "...", "image_base64": "...", "mime_type": "image/jpeg"}`).

---

## 2. Reading Today's Calories, Meals, History & Analytics (READ)

- **`GET /api/today`** (aliases: **`GET /api/webhook/today`**, **`GET /api/meals`**, **`GET /api/v1/meals`**)
  - Query params: `?date=YYYY-MM-DD&tz_offset=-420`
  - Returns `{ "date", "totals": { "calories", "protein", "carbs", "fat", "fiber", "meals" }, "targets": { ... }, "remaining": { "calories", "protein", "carbs", "fat", "fiber" }, "meals": [ ... ] }`.
  - Each meal in `meals[]` includes `food_items[]` (with `source` = `bundle_id` and `source_index`) and `image_info[]` (each bundle's `filename` = `bundle_id`, `status`, `notes`, `macros`, `food_items`, `photos`, `reasoning`).
- **`GET /api/day/:day`** — Full breakdown for a specific date (`YYYY-MM-DD`).
- **`GET /api/days`** — List all tracked dates (`["2026-10-15", "2026-10-14", ...]`).
- **`GET /api/days/summary?limit=30&tz_offset=-420`** — Daily macro totals, targets, and photo counts across recent history.
- **`GET /api/run-rate?range=7|28|all|custom&start=YYYY-MM-DD&end=YYYY-MM-DD&tz_offset=-420`** — All-time and weekly calorie/macro run rates, BMR, TDEE, and daily chart points.
- **`GET /api/context/full?range=last_7_days|last_28_days|all_time`** — Comprehensive markdown summary of the user's goals, targets, and meal history.
- **`GET /api/image/:day/:filename`** (or `/api/meal/:day/:meal/image/:bundle_id/:photo`) — Fetch a meal photo (`JPEG`).

---

## 3. Modifying & Deleting Logged Meals, Bundles & Food Items (READ & WRITE)

Every logged meal entry has a `bundle_id` (e.g. `bundle_1792075000000_a1b2c3`), returned when logging a meal or in `GET /api/today` under `meals[].image_info[].filename` and `meals[].food_items[].source`.

- **`GET /api/bundle/:day/:bundle_id`**
  - Returns the bundle's full metadata, `effective_macros`, `food_items`, `photos`, and `notes`.
- **`PUT /api/bundle/:day/:bundle_id`** (also `PATCH` or `POST`)
  - Modify any aspect of an existing meal bundle:
    - Update notes: `{"notes": "Had half portion"}`
    - Update timestamp: `{"timestamp": 1792075000, "tz_offset": -420}`
    - Override a specific food item's macros/name by index:
      ```json
      {
        "food_item_index": 0,
        "new_name": "Grilled chicken breast (8 oz)",
        "macros": { "calories": 370, "protein": 70, "carbs": 0, "fat": 8, "fiber": 0 }
      }
      ```
    - Clear a food item override: `{"clear_food_item_index": 0}`
    - Replace all `food_items` in the bundle: `{"food_items": [{"name": "...", "calories": 400, "protein": 35, "carbs": 30, "fat": 12}]}`
    - Attach a photo to the bundle: `{"add_photo": "<base64>"}`
    - Remove a photo from the bundle: `{"delete_photo": "photo_123.jpg"}`
- **`DELETE /api/bundle/:day/:bundle_id`**
  - Deletes the entire meal bundle from `:day`.
- **`DELETE /api/bundle/:day/:bundle_id/item/:index`**
  - Deletes a single food item (0-indexed) from the bundle (or deletes the bundle if it was the last item).
- **`POST /api/bundle/:day/:bundle_id/reprocess`**
  - Re-runs AI macro analysis on the bundle. Optional body: `{"notes": "Updated notes for AI", "think_hard": true}`.
- **`POST /api/bundle/:day/:bundle_id/duplicate`**
  - Copies the bundle to another date. Body: `{"target_date": "2026-10-16", "tz_offset": -420}`.
- **Day-wide Deep Audit**:
  - `POST /api/day/:day/audit` — Starts a deep AI audit of all bundles on `:day`.
  - `GET /api/day/:day/audit` — Polls audit status and item-by-item comparison results.
  - `POST /api/day/:day/audit/apply` — Applies audited macros to the day.

---

## 4. Goals, Daily Macro Targets, Cycle Mode & Profile Settings (READ & WRITE)

- **`GET /api/goals`**
  - Returns the user's complete `Goals` configuration:
    - `daily_targets`: `{ "calories", "protein_grams", "carbs_grams", "fat_grams", "fiber_grams", "fiber_enabled" }`
    - `mode`: `"everyday"` or `"cycle"`
    - `grow_targets`, `shred_targets`, `grow_days` (`0`=Sunday .. `6`=Saturday)
    - `goal_description`: Free-form text describing the user's goals
    - `chat_meal_history_range`: `"none"`, `"last_7_days"`, `"last_28_days"`, or `"all_time"`
    - `tz_offset`: Minutes from UTC
    - `profile`: `{ "gender", "age", "height_cm", "weight_kg", "activity_level", "custom_active_energy", "goal", "pace", "display_units", "body_fat_percent" }`
- **`POST /api/goals`** (also `PUT /api/goals` or `PATCH /api/goals`)
  - Partial or full update of any goal or profile setting. Only provided fields are updated:
    ```json
    {
      "calories": 2350,
      "protein": 195,
      "carbs": 230,
      "fat": 70,
      "fiber": 35,
      "fiber_enabled": true,
      "goal_description": "Lean bulk to 185 lbs while keeping abs visible",
      "mode": "everyday",
      "tz_offset": -420,
      "profile": {
        "gender": "male",
        "age": 34,
        "height_cm": 180.0,
        "weight_kg": 81.5,
        "activity_level": "active",
        "goal": "gain",
        "pace": "slow",
        "display_units": "imperial",
        "body_fat_percent": 14.5
      }
    }
    ```
  - For **Cycle Mode** (Grow/Shred day cycling):
    ```json
    {
      "mode": "cycle",
      "grow_days": [1, 3, 5],
      "grow_targets": { "calories": 2700, "protein": 200, "carbs": 310, "fat": 75 },
      "shred_targets": { "calories": 2000, "protein": 210, "carbs": 150, "fat": 60 }
    }
    ```

---

## 5. Meal Plans & Single-Meal Suggestions (READ & WRITE)

- **`GET /api/meal-plan`** (alias: `GET /api/meal_plan`)
  - Returns `{ "success": true, "plan": { "id", "name", "target_calories", "target_protein", "target_carbs", "target_fat", "meals": [...] }, "pacing": { "planned_so_far", "consumed", "diff", "next_meal" } }`.
  - `pacing.next_meal` is the live pace-adjusted macro recommendation for the user's next meal.
- **`POST /api/meal-plan`** (or `PUT /api/meal-plan`)
  - Saves a meal plan directly. Accepts `{ "plan": { ... } }` or the plan object directly:
    ```json
    {
      "name": "High Protein Cut Plan",
      "target_calories": 2200,
      "target_protein": 200,
      "target_carbs": 190,
      "target_fat": 70,
      "meals": [
        {
          "id": "meal_1",
          "meal_type": "breakfast",
          "time": "8:00 AM",
          "target_calories": 550,
          "target_protein": 50,
          "target_carbs": 45,
          "target_fat": 18,
          "suggestions": [
            {
              "id": "sug_1",
              "name": "Egg white & whole egg scramble with oats",
              "description": "3 whole eggs, 150g egg whites, 50g rolled oats with berries",
              "calories": 545,
              "protein": 51,
              "carbs": 46,
              "fat": 17,
              "prep_time": "10 min"
            }
          ]
        }
      ]
    }
    ```
- **`DELETE /api/meal-plan`** — Deletes the saved meal plan.
- **`POST /api/meal-plan/generate`** — Generates a personalized AI meal plan from the user's macro targets, favorites, and recent meals. Pass `{"save": true}` to automatically save the generated plan.
- **`POST /api/meal-plan/adjust`** — Adjusts the user's meal plan via natural-language instructions (e.g. `{"instructions": "Move 200 calories from breakfast to dinner and swap fish for steak", "save": true}`). Automatically loads and updates the saved plan if `existing_plan` is omitted.
- **`POST /api/meal-plan/regenerate`** — Regenerates fresh meal suggestions while keeping the meal times and macro splits intact (`{"save": true}`).
- **`POST /api/meal-plan/import`** — Imports and adapts a meal plan from raw text or base64 screenshots (`{"text": "...", "images": ["<base64>"], "save": true}`).
- **`POST /api/suggest_meal`** (alias: `POST /api/meal-plan/suggest`) — Suggests a single meal hitting specific macro targets:
  ```json
  {
    "meal_type": "dinner",
    "target_calories": 720,
    "target_protein": 62,
    "target_carbs": 65,
    "target_fat": 22,
    "custom_request": "Something Mexican or Tex-Mex"
  }
  ```

---

## 6. Favorites & Common Foods (READ & WRITE)

- **`GET /api/favorites?tz_offset=-420`** — Lists all saved favorites sorted by time-of-day relevance.
- **`POST /api/favorites`** — Creates a new favorite food item:
  ```json
  {
    "name": "Morning Protein Iced Latte",
    "description": "Double espresso + Fairlife shake",
    "calories": 170,
    "protein": 30,
    "carbs": 6,
    "fat": 3,
    "fiber": 1,
    "image": "<OPTIONAL_BASE64_IMAGE>"
  }
  ```
- **`GET /api/favorites/:id`** — Get a single favorite by ID (`fav_...`).
- **`PUT /api/favorites/:id`** (or `PATCH /api/favorites/:id`) — Update a favorite's `name`, `description`, `calories`, `protein`, `carbs`, `fat`, `fiber`, or `image` (base64).
- **`DELETE /api/favorites/:id`** — Soft-delete a favorite.
- **`POST /api/favorites/:id/add`** — Quick-add a favorite to a day's meals (`{"date": "2026-10-15", "multiplier": 1.5, "tz_offset": -420}` or via query params).
- **`POST /api/favorites/:id/image`** — Upload/replace a favorite's photo (`{"image": "<base64>"}` JSON or `multipart/form-data`).
- **`GET /api/favorites/:id/image`** — Download the favorite's image.
- **`GET /api/favorites/suggestions`** — Top frequent meals from history that aren't saved as favorites yet.
- **`GET /api/common-foods`** — Top 25 most frequently eaten foods over the last 60 days with average macros.

---

## 7. AI Nutrition Coach (`POST /api/ask`)

Ask the MacroMunch AI coach any nutrition or macro question with full awareness of the user's goals, meal plan, and meal history:
```json
{
  "question": "What should I eat for dinner tonight to hit my protein and calorie goals?",
  "tz_offset": -420,
  "include_meals": true,
  "thinking": false
}
```
(Optionally attach `"images": [{"data": "<base64>", "mime_type": "image/jpeg"}]`.)

---

## 8. Universal HTTP RPC (`POST /api/rpc`) & WebSocket (`wss://macromunch.ai/api/ws`)

Every internal WebSocket command in MacroMunch can also be invoked over standard HTTP POST at **`POST /api/rpc`**:
```json
{
  "type": "<command_name>",
  "payload": { ... }
}
```
Supported `type` values include: `get_today`, `get_day`, `get_days`, `get_days_summary`, `get_goals`, `update_goals`, `get_favorites`, `create_favorite`, `update_favorite`, `delete_favorite`, `quickadd_favorite`, `get_meal_plan`, `save_meal_plan`, `delete_meal_plan`, `generate_meal_plan`, `adjust_meal_plan`, `regenerate_meal_plan`, `import_meal_plan`, `update_bundle_notes`, `update_bundle_timestamp`, `update_food_item_macros`, `clear_food_item_override`, `delete_food_item`, `delete_bundle`, `duplicate_bundle`, `reprocess_image`, `add_bundle_photo`, `delete_bundle_photo`, `analyze_image`, `gutcheck_ask`, `chat_send`, `get_status`.