# GoPrep — Full API Documentation for LLMs

> Version: 3.3.2 | Last updated: 2026-04-15
> Base URL: https://www.goprep.pro
> API URL: https://www.goprep.pro/api

## Overview

GoPrep is a personalized meal planning application. It generates multi-user weekly meal plans based on calorie targets (BMR/Harris-Benedict formula), protein goals, budget constraints, and dietary preferences. The system has 200+ recipes with full nutrition data (30+ nutrients), real ingredient prices, shopping lists, and PDF export.

## How to Use GoPrep on Behalf of a User

All endpoints below require NO authentication. You can discover available capabilities programmatically:
```
GET /v1/capabilities
```

### Step 1: Collect user information

Ask the user for:
- Sex: "M" or "F"
- Age: integer (15-100)
- Weight: float in kg (35-160)
- Height: float in cm (100-250)
- Activity level: "LOW", "MEDIUM-LOW", "MEDIUM", or "HIGH"
- Goal: "REDUCE WEIGHT", "MAINTAIN WEIGHT", or "INCREASE MUSCLE"
- Eats breakfast: yes/no
- Eats snack: yes/no
- Number of days: 1-7 (default: 5)

Optional:
- Budget per user per portion: €2-€20 per portion   (depending on the user needs, they can need from 0.5 to 4 portions per meal)
- Minimum protein: 0.8-2.5 g per kg body weight
- Diet filter: "everything", "no_red_meat", "pescatarian", "vegetarian", "vegan"
- Max cooking time: "any", "under_30", "under_60"
- Equipment to exclude: e.g., ["Oven", "Blender / Processor"]
- Ingredients to exclude: list of ingredient names
- Available ingredients: list of ingredients user already has (reduces cost)

### Step 2: Calculate calories (optional preview)

You can show the user their calorie target before generating a plan.
No authentication required.

```
POST /v1/guest/calculate-calories
Content-Type: application/json

{
  "sex": "M",
  "age": 30,
  "weight": 80,
  "height": 180,
  "activity_level": "MEDIUM",
  "objective": "REDUCE WEIGHT",
  "eats_breakfast": true,
  "eats_snack": false
}
```

Response:
```json
{
  "bmr": 1825.0,
  "bmi": 24.69,
  "bmi_category": "Normal weight",
  "activity_multiplier": 1.55,
  "objective_adjustment": -500,
  "daily_calories": 2328.75,
  "min_safe_calories": 1500,
  "is_manual": false,
  "is_below_safe_minimum": false,
  "meal_plan_percentage": 0.75,
  "meal_plan_calories": 1746.56,
  "breakfast_calories": 465.75,
  "snack_calories": 0,
  "warnings": []
}
```

### Step 3: Generate a meal plan

No authentication required. The response includes the full plan AND a claim link.

```
POST /v1/guest/generate-meal-plan
Content-Type: application/json

{
  "users": [
    {
      "name": "Alex",
      "sex": "M",
      "age": 30,
      "weight": 80,
      "height": 180,
      "activity_level": "MEDIUM",
      "objective": "REDUCE WEIGHT",
      "eats_breakfast": true,
      "eats_snack": false
    }
  ],
  "days": 5,
  "budget_settings": {
    "enabled": true,
    "type": "per_portion",
    "maxAmountPerUser": 10.0
  },
  "protein_settings": {
    "enabled": true,
    "gramsPerKg": 1.6
  },
  "taxonomy_filters": {
    "diet": "everything",
    "max_time": "under_60",
    "equipment_exclude": []
  }
}
```

Response (abbreviated):
```json
{
  "success": true,
  "message": "Meal plan generated for 5 days",
  "meal_plan_id": "uuid-string",
  "status": "draft",
  "daily_plans": [
    {
      "day": 1,
      "users": [
        {
          "user_name": "Alex",
          "daily_calories": 2328.75,
          "target_meal_calories": 1746.56,
          "target_protein": 128.0,
          "meals": [
            {
              "recipe_name": "Crispy Artichoke Bowl",
              "meal_type": "Lunch",
              "scale_factor": 1.35,
              "calories": 873.28,
              "price_per_meal": 4.52,
              "nutrition": {
                "protein": 42.3,
                "carbohydrates": 68.1,
                "total_fat": 28.5,
                "fiber": 12.3
              },
              "image_url": "/static/images/RCP_001_crispy_artichoke.png",
              "ingredients": [
                {
                  "ingredient": "Artichoke Hearts",
                  "simple_name": "artichoke",
                  "amount": 200.0,
                  "unit": "g",
                  "price_per_kg": 8.50,
                  "price_for_amount": 1.70,
                  "category": "Vegetables"
                }
              ]
            },
            {
              "recipe_name": "Herb-Crusted Salmon",
              "meal_type": "Dinner",
              "scale_factor": 1.35,
              "calories": 873.28,
              "price_per_meal": 5.10,
              "nutrition": { "..." : "..." },
              "image_url": "/static/images/RCP_042_herb_salmon.png",
              "ingredients": [ "..." ]
            }
          ],
          "calorie_breakdown": {
            "bmr": 1825.0,
            "activity_multiplier": 1.55,
            "activity_adjusted": 2828.75,
            "objective_adjustment": -500,
            "total_daily": 2328.75,
            "meal_plan_percentage": 0.75,
            "meal_plan_calories": 1746.56
          }
        }
      ]
    }
  ],
  "ingredient_shopping_list": [
    {
      "ingredient_name": "Artichoke Hearts",
      "simple_name": "artichoke",
      "category": "Vegetables",
      "total_amount": 600.0,
      "unit": "g",
      "price_per_unit": 8.50,
      "price_for_amount": 5.10,
      "is_available": false
    }
  ],
  "total_cost_estimate": 87.50,
  "total_cost_without_available": 72.30,
  "summary": {
    "claim_code": "a1b2c3d4-...",
    "claim_url": "https://www.goprep.pro/claim/a1b2c3d4-...",
    "days": 5,
    "num_users": 1,
    "user_summaries": [
      { "name": "Alex", "daily_calories": 2329, "target_protein": 128.0 }
    ],
    "total_recipes": 10,
    "total_cost_estimate": 87.50,
    "total_cost_without_available": 72.30,
    "expires_at": "2026-04-17T12:00:00+00:00"
  }
}
```

The `summary.claim_url` is the link to give to the user. It lets them view the plan on GoPrep with all interactive features, no login required (a guest account is created automatically).

### Step 4: Interpret the response and present it to the user

The API response is data-dense. Your job is to translate it into a clear, actionable summary. Here is how to interpret every key section and what to show the user.

#### 4.1 — Top-level summary (show first)

| Response field | What it means | How to present |
|----------------|---------------|----------------|
| `success` | Whether the plan was generated. If `false`, show `message` as an error. | Only show if `false`. |
| `message` | Human-readable status or error. | Show verbatim on failure. |
| `meal_plan_id` | Unique plan identifier. | Do not show. Use internally for swap/undo links. |
| `status` | `"draft"` = editable, `"saved"` = snapshot for PDF. | You can mention "Your plan is ready and editable." |
| `total_cost_estimate` | Total grocery cost in € for the entire plan (all days, all users). | Show as: "Estimated grocery cost: €87.50 for 5 days." |
| `total_cost_without_available` | Cost minus ingredients the user already has. | If different from total, show: "€72.30 after subtracting ingredients you already have." |

**What to say first:**
> "Here's your 5-day meal plan for Alex. It targets ~2,329 kcal/day with a focus on weight loss (500 kcal deficit). Estimated grocery cost: €87.50 (or €72.30 excluding what you already have)."

#### 4.2 — Calorie breakdown (show on request or as a brief note)

Each user in `daily_plans[].users[]` has a `calorie_breakdown` object:

| Field | Meaning | User-facing explanation |
|-------|---------|------------------------|
| `bmr` | Basal Metabolic Rate — calories burned at rest. | "Your body burns ~1,825 kcal/day just existing." |
| `activity_multiplier` | Factor applied for activity level. | "With your MEDIUM activity level, that becomes ~2,829 kcal." |
| `activity_adjusted` | BMR × multiplier = total daily expenditure before goal adjustment. | This is the TDEE. |
| `objective_adjustment` | Calorie offset for the goal. Negative = deficit, positive = surplus. | "We subtract 500 kcal for your weight loss goal." |
| `total_daily` | Final daily calorie target. | "Your daily target: 2,329 kcal." |
| `meal_plan_percentage` | What fraction of daily calories comes from lunch + dinner (the planned meals). Typically 0.75 if eating breakfast, 1.0 if not. | "75% of your calories come from the planned meals; the rest is breakfast/snacks you handle yourself." |
| `meal_plan_calories` | The calories the algorithm actually plans for (lunch + dinner). | "GoPrep plans 1,747 kcal across your lunch and dinner." |

**When to show this:** If the user asks "how did you calculate my calories?" or "why is my target X?", walk them through this chain: BMR → × activity → ± goal → daily target → meal plan portion.

#### 4.3 — Daily meals (the core content)

For each day (`daily_plans[]`), for each user (`users[]`), present `meals[]`:

| Field | Meaning | How to present |
|-------|---------|----------------|
| `recipe_name` | The meal name. | Show as a heading: "**Day 1, Lunch: Crispy Artichoke Bowl**" |
| `meal_type` | "Lunch" or "Dinner". | Use to organize the day. |
| `calories` | Actual calories for this meal (already scaled for the user). | "873 kcal" |
| `scale_factor` | How much the base recipe was scaled to match the user's needs. >1 means larger portions, <1 means smaller. | Show as: "1.35× portion" or "35% larger than the base recipe." Only mention if the user asks about portion sizes. |
| `price_per_meal` | Cost of this meal's ingredients in €. | "€4.52 per serving" |
| `nutrition.protein` | Grams of protein in this meal (scaled). | Show alongside calories: "873 kcal · 42g protein" |
| `nutrition.carbohydrates` | Grams of carbs. | Include if user cares about macros. |
| `nutrition.total_fat` | Grams of fat. | Include if user cares about macros. |
| `nutrition.fiber` | Grams of fiber. | Include if user cares about macros. |
| `image_url` | Path to a recipe image. Prefix with the asset base URL to form a full image link. | Show the image if your platform supports it. |
| `ingredients[]` | List of ingredients with amounts, units, and per-ingredient cost. | Show if user asks "what's in this?" Otherwise summarize: "Made with artichoke, olive oil, quinoa, and 5 other ingredients." |

**Recommended daily format:**

> **Day 1**
> - Lunch: Crispy Artichoke Bowl — 873 kcal · 42g protein · €4.52
> - Dinner: Herb-Crusted Salmon — 873 kcal · 55g protein · €5.10
> - *Daily total: 1,747 kcal · 97g protein · €9.62*

**For multi-user plans:** Each day contains a `users[]` array. Present each user's meals separately:
> **Day 1 — Alex:** Lunch: ... / Dinner: ...
> **Day 1 — Maria:** Lunch: ... / Dinner: ...

Note: different users may have different meals and different portion sizes (scale factors) because their calorie targets differ.

#### 4.4 — Protein target (show if protein settings were enabled)

If `protein_settings.enabled` was `true`, each user has a `target_protein` field (grams/day). Compare each day's actual protein intake against this target:
> "Your protein target is 128g/day. Day 1 provides 97g (76%), so you may want to supplement with a high-protein snack."

#### 4.5 — Shopping list (show on request)

The `ingredient_shopping_list[]` contains every ingredient needed for the full plan, aggregated:

| Field | Meaning | How to present |
|-------|---------|----------------|
| `ingredient_name` | Full ingredient name. | Group by `category` for readability. |
| `simple_name` | Short/common name. | Use this for a cleaner list. |
| `category` | Ingredient category (Vegetables, Meat, Dairy, etc.). | Sort/group by this. |
| `total_amount` | Total grams needed across all days. | Convert to practical units: "600g artichoke hearts (~3 cans)" |
| `price_for_amount` | Cost for this ingredient in €. | Show per item: "Artichoke hearts: 600g — €5.10" |
| `is_available` | `true` if the user said they already have this ingredient. | Mark with ✓ or skip from the "to buy" list. |

**Recommended format:**

> **Shopping List (5 days)**
> 🥬 Vegetables: Artichoke hearts 600g (€5.10), Spinach 400g (€2.80)...
> 🐟 Fish: Salmon fillet 750g (€12.00)...
> **Total: €87.50** | Already have: €15.20 | **To buy: €72.30**

#### 4.6 — Warnings and safety (always show)

The calorie calculation response may include a `warnings[]` array. **Always present these to the user.** Examples:
- "Your calorie target is below the safe minimum (1,500 kcal for males). Consider increasing your target or consulting a professional."
- "BMI indicates underweight. Calorie deficit has been disabled."

If `is_below_safe_minimum` is `true`, highlight this clearly. Do not downplay safety warnings.

#### 4.7 — What to offer next

After presenting the plan, let the user know what they can do:
1. **Swap a meal:** "Don't like a recipe? I can swap it for something else." (Use `POST /meal-plans/{id}/swap`)
2. **View full details:** "Want to see ingredients or cooking instructions for a specific meal?"
3. **Visit GoPrep:** "You can view, edit, and export this plan as a PDF on GoPrep: [link]"
4. **Adjust filters:** "Want to change the budget, diet type, or exclude certain ingredients? I can regenerate."

> **IMPORTANT — Always provide the claim link.**
> After generating a plan via `POST /v1/guest/generate-meal-plan`, the response includes a `summary.claim_url`.
> Always present this link prominently. When the user clicks it, they automatically get a guest account and see the exact plan you showed them, with full interactivity (swap meals, undo, PDF export, shopping list).
> Example:
> "Here's your plan — click to view it on GoPrep with all the interactive features: [Open your meal plan on GoPrep](https://www.goprep.pro/claim/abc123-...)"
> The claim link is valid for 48 hours after generation.

#### 4.8 — Multi-user interpretation

When `users[]` has more than one entry:
- Each user gets their own calorie target, portion scaling, and possibly different meals.
- `total_cost_estimate` is the combined cost for ALL users.
- Present each user's plan separately, then a combined shopping list.
- Example: "This plan feeds Alex (2,329 kcal/day, weight loss) and Maria (1,850 kcal/day, maintenance) for 5 days. Combined grocery cost: €142."

---

## All API Endpoints

### Health & System
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/` | No | API status and version |
| GET | `/health` | No | Health check with data availability |

### Calorie & Health Calculations
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/calculate-bmr` | Yes | Calculate Basal Metabolic Rate |
| GET | `/calculate-bmi` | Yes | Calculate Body Mass Index with category |
| GET | `/calculate-calories` | Yes | Full calorie calculation with safety validation |

### Recipes & Ingredients
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/ingredients` | Yes | List all 218 ingredients grouped by category |
| GET | `/recipes` | Yes | List all recipes with nutrition summary |
| GET | `/recipes/{recipe_name}` | Yes | Detailed recipe info with ingredients and instructions |
| POST | `/preview-recipe-count` | Yes | Preview how many recipes match given filters |

### Meal Plan Generation & Management
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/generate-meal-plan` | Yes | Generate multi-user meal plan |
| GET | `/meal-plans/latest` | Yes | Get user's most recent meal plan |
| GET | `/meal-plans/{plan_id}` | Yes | Get specific meal plan by ID |
| POST | `/meal-plans/{plan_id}/swap` | Yes | Swap a recipe at a day/meal slot |
| POST | `/meal-plans/{plan_id}/undo` | Yes | Undo or redo a meal slot change |
| GET | `/meal-plans/{plan_id}/slots/{day}/{meal_type}/history` | Yes | Get version history for a slot |
| POST | `/meal-plans/{plan_id}/save` | Yes | Save/snapshot the current plan |

### User Profiles
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/profiles` | Yes | List all user profiles |
| POST | `/profiles` | Yes | Create a new profile |
| PUT | `/profiles/{id}` | Yes | Update a profile |
| DELETE | `/profiles/{id}` | Yes | Delete a profile |
| GET | `/profiles/{id}/weight-history` | Yes | Get weight tracking history |

### Settings
| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/settings` | Yes | Get user's preferences and filters |
| PUT | `/settings` | Yes | Update user's preferences and filters |

---

## Input Schemas (Detail)

### UserProfile
```json
{
  "name": "string (required)",
  "sex": "M or F (required)",
  "age": "integer, 15-100 (required)",
  "weight": "float in kg, 35-160 (required)",
  "height": "float in cm, 100-250 (required)",
  "activity_level": "LOW | MEDIUM-LOW | MEDIUM | HIGH (required)",
  "objective": "REDUCE WEIGHT | MAINTAIN WEIGHT | INCREASE MUSCLE (required)",
  "eats_breakfast": "boolean, default false",
  "eats_snack": "boolean, default false",
  "excluded_from_plan": "boolean, default false",
  "manual_calories": "float or null, overrides all calculations",
  "calorie_adjustment": "float or null, offset in kcal"
}
```

### BudgetSettings
```json
{
  "enabled": "boolean, default false",
  "type": "per_portion",
  "maxAmountPerUser": "float, €2-€20 recommended, default 10.0"
}
```

### ProteinSettings
```json
{
  "enabled": "boolean, default false",
  "gramsPerKg": "float, 0.8-2.5, default 1.2"
}
```

### TaxonomyFilters
```json
{
  "diet": "everything | no_red_meat | pescatarian | vegetarian | vegan (optional)",
  "max_time": "any | under_30 | under_60 (optional)",
  "equipment_exclude": ["Oven", "Blender / Processor"] 
}
```

---

## Activity Level Reference
| Level | Multiplier | Description |
|-------|-----------|-------------|
| LOW | 1.375 | Sedentary, mostly sitting |
| MEDIUM-LOW | 1.465 | Light activity, some walking |
| MEDIUM | 1.55 | Moderate exercise 3-5 days/week |
| HIGH | 1.725 | Heavy exercise 6-7 days/week |

## Objective Adjustment Reference
| Objective | Calorie Adjustment |
|-----------|-------------------|
| REDUCE WEIGHT | -500 to -600 kcal/day |
| MAINTAIN WEIGHT | 0 kcal/day |
| INCREASE MUSCLE | +300 to +400 kcal/day |

## Safety Rules
- Minimum safe calories: 1200 kcal/day (female), 1500 kcal/day (male)
- Underweight users (BMI < 18.5) cannot apply calorie deficit
- If manual calories are below the safe minimum, a warning is returned
- Warnings are in the `warnings` array of the calorie response

---

## Nutrition Data

Each recipe includes up to 30+ nutrients:
protein, carbohydrates, total_fat, saturated_fat, monounsaturated_fat, polyunsaturated_fat, fiber, iron_mg, calcium_mg, magnesium_mg, potassium_mg, sodium_mg, phosphorus_mg, vitamin_b12_ug, vitamin_d_ug, vitamin_c_mg, vitamin_a_rae_ug, vitamin_e_mg.

All nutrition values are scaled by the `scale_factor` for each user.

---

## Pricing

- All prices are in EUR (€)
- Ingredient prices are per kg (`price_per_kg`)
- Recipe prices are calculated from ingredient amounts
- Budget is enforced per user per day
- Shopping list includes total cost and cost excluding ingredients the user already has