# Add an alternative meal

`POST https://api.coach-platform.com/api/public/nutrition-menus/{menuId}/meals/{mealId}/alternatives`

Add an alternative meal to one meal of a menu — the same "add alternative meal" the dashboard offers. Take mealId from the meals array of GET /nutrition-menus/{menuId}. The alternative carries its own foods and macros and does not change the menu totals. Returns the alternative including its id. Does not cascade: copies duplicated from this menu keep their own alternatives — repeat the call against the menuId of each copy to update them.

- Resource: Nutrition Menus
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/post-nutrition-menus-menu-id-meals-meal-id-alternatives
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `menuId` | string | Yes |   |
| `mealId` | string | Yes |   |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | string | No | Optional. Send a unique key (e.g. a UUID) to make this POST safe to retry. The same key within 24h returns the original result instead of creating a duplicate. |

## Request body

Content type: `application/json`. Required.

| Field | Type | Required | Description |
|---|---|---|---|
| `title` | string | Yes | Alternative name, e.g. "Omelette instead". |
| `foodItems` | object[] | No | Maximum items: `100`. |
| `foodItems[].name` | string | No | Food name, e.g. "Chicken breast". |
| `foodItems[].quantity` | number | No | Amount in the given unit, e.g. 150. |
| `foodItems[].unit` | string | No | Unit of the quantity, e.g. "g", "ml", "unit". |
| `foodItems[].unitWeight` | number | No | Grams in one unit. The app scales macros as quantity * unitWeight / 100 * the per-100g values, so send it whenever unit is not grams. Take it from the matching entry in the units array of GET /food-items. Defaults to 100. |
| `foodItems[].productCode` | number | No | Food database code, from GET /food-items. Send it to link the food to its catalog entry so replacements and portion data behave like they do in the dashboard. |
| `foodItems[].caloriesPer100g` | number | No |   |
| `foodItems[].proteinPer100g` | number | No |   |
| `foodItems[].carbsPer100g` | number | No |   |
| `foodItems[].fatPer100g` | number | No |   |
| `calories` | number | Yes | Total calories for the alternative. Required. |
| `protein` | number | Yes | Grams of protein. Required. |
| `carbs` | number | Yes | Grams of carbs. Required. |
| `fat` | number | Yes | Grams of fat. Required. |
| `notes` | string | No |   |
| `applyToAllSharedTrainees` | boolean | No | Required (true) to edit a menu shared by multiple trainees; the alternative is then added for all of them. Without it, a shared menu returns 409. |

## Responses

| Status | Description |
|---|---|
| `201` Created |  |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `404` Not Found |  |
| `409` Conflict |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 201 Created

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object | An alternative the trainee may eat instead of the meal it belongs to. Its macros do not count towards the menu totals. |
| `data.id` | string | Alternative id. Read-only; pass it to DELETE /nutrition-menus/{menuId}/meals/{mealId}/alternatives/{alternativeId}. Not stable: saving the menu from the dashboard gives every alternative a new id, so read it fresh rather than caching it. |
| `data.title` | string | Alternative name, e.g. "Omelette instead". |
| `data.foodItems` | object[] |   |
| `data.foodItems[].name` | string | Food name, e.g. "Chicken breast". |
| `data.foodItems[].quantity` | number | Amount in the given unit, e.g. 150. |
| `data.foodItems[].unit` | string | Unit of the quantity, e.g. "g", "ml", "unit". |
| `data.foodItems[].unitWeight` | number | Grams in one unit. The app scales macros as quantity * unitWeight / 100 * the per-100g values, so send it whenever unit is not grams. Take it from the matching entry in the units array of GET /food-items. Defaults to 100. |
| `data.foodItems[].productCode` | number | Food database code, from GET /food-items. Send it to link the food to its catalog entry so replacements and portion data behave like they do in the dashboard. |
| `data.foodItems[].caloriesPer100g` | number |   |
| `data.foodItems[].proteinPer100g` | number |   |
| `data.foodItems[].carbsPer100g` | number |   |
| `data.foodItems[].fatPer100g` | number |   |
| `data.calories` | number | Total calories for the alternative. |
| `data.protein` | number |   |
| `data.carbs` | number |   |
| `data.fat` | number |   |
| `data.notes` | string |   |
| `warnings` | object[] | Non-fatal problems with follow-up writes. The resource was created, but each listed field was not applied. |
| `warnings[].field` | string |   |
| `warnings[].message` | string |   |

Example:

```json
{
  "data": {
    "id": "<string>",
    "title": "<string>",
    "foodItems": [
      {
        "name": "<string>",
        "quantity": 123,
        "unit": "<string>",
        "unitWeight": 123,
        "productCode": 123,
        "caloriesPer100g": 123,
        "proteinPer100g": 123,
        "carbsPer100g": 123,
        "fatPer100g": 123
      }
    ],
    "calories": 123,
    "protein": 123,
    "carbs": 123,
    "fat": 123,
    "notes": "<string>"
  },
  "warnings": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ]
}
```

### Error responses 400, 401, 403, 404, 409, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request POST \
  --url 'https://api.coach-platform.com/api/public/nutrition-menus/<menuId>/meals/<mealId>/alternatives' \
  --header 'Authorization: Bearer cp_live_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "<string>",
  "calories": 123,
  "protein": 123,
  "carbs": 123,
  "fat": 123
}'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/nutrition-menus/<menuId>/meals/<mealId>/alternatives', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cp_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "<string>",
    "calories": 123,
    "protein": 123,
    "carbs": 123,
    "fat": 123
  }),
});

const data = await response.json();
```

## Related endpoints

- [Get a trainee's daily nutrition log](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-nutrition-log/index.md): `GET /api/public/trainees/{traineeId}/nutrition-log`. What a trainee actually ate on ONE day: the food log for that date, per-meal and per-day calorie/macro totals, and the times of day the food was logged.
- [List nutrition menus](https://www.coach-platform.com/docs/api/reference/get-nutrition-menus/index.md): `GET /api/public/nutrition-menus`. List nutrition menus.
- [Create a nutrition menu](https://www.coach-platform.com/docs/api/reference/post-nutrition-menus/index.md): `POST /api/public/nutrition-menus`. Create a nutrition menu.
- [Get a nutrition menu](https://www.coach-platform.com/docs/api/reference/get-nutrition-menus-menu-id/index.md): `GET /api/public/nutrition-menus/{menuId}`. Get a nutrition menu by id (with full meals breakdown).
- [Update a nutrition menu](https://www.coach-platform.com/docs/api/reference/patch-nutrition-menus-menu-id/index.md): `PATCH /api/public/nutrition-menus/{menuId}`. Partially update a nutrition menu.
- [Delete a nutrition menu](https://www.coach-platform.com/docs/api/reference/delete-nutrition-menus-menu-id/index.md): `DELETE /api/public/nutrition-menus/{menuId}`. Delete a nutrition menu permanently.
- [Get a trainee's active nutrition menu](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-active-nutrition-menu/index.md): `GET /api/public/trainees/{traineeId}/active-nutrition-menu`. Get a trainee's currently active nutrition menu (resolved via the active coaching period).
- [Remove an alternative meal](https://www.coach-platform.com/docs/api/reference/delete-nutrition-menus-menu-id-meals-meal-id-alternatives-alternative-id/index.md): `DELETE /api/public/nutrition-menus/{menuId}/meals/{mealId}/alternatives/{alternativeId}`. Remove one alternative meal from a meal.
- [Search the food database](https://www.coach-platform.com/docs/api/reference/get-food-items/index.md): `GET /api/public/food-items`. Search the food database the dashboard searches: the shared catalog plus the coach's own items.
- Previous: [Get a trainee's active nutrition menu](https://www.coach-platform.com/docs/api/reference/get-trainees-trainee-id-active-nutrition-menu/index.md): `GET /api/public/trainees/{traineeId}/active-nutrition-menu`. Get a trainee's currently active nutrition menu (resolved via the active coaching period).
- Next: [Remove an alternative meal](https://www.coach-platform.com/docs/api/reference/delete-nutrition-menus-menu-id-meals-meal-id-alternatives-alternative-id/index.md): `DELETE /api/public/nutrition-menus/{menuId}/meals/{mealId}/alternatives/{alternativeId}`. Remove one alternative meal from a meal.