# List nutrition menus

`GET https://api.coach-platform.com/api/public/nutrition-menus`

List nutrition menus. Filter by traineeId.

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

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | No | Page number (1-based, default 1) Minimum: `1`. |
| `limit` | integer | No | Number of items to return (default 25, max 500) Minimum: `1`. Maximum: `500`. |
| `traineeId` | string | No |   |

## Responses

| Status | Description |
|---|---|
| `200` OK | Successful response |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 200 OK

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object[] |   |
| `data[].id` | string |   |
| `data[].coach` | string |   |
| `data[].escorts` | string[] |   |
| `data[].title` | string |   |
| `data[].description` | string |   |
| `data[].goal` | string |   |
| `data[].type` | string |   |
| `data[].totalCalories` | number |   |
| `data[].totalProtein` | number |   |
| `data[].totalCarbs` | number |   |
| `data[].totalFat` | number |   |
| `data[].meals` | object[] |   |
| `data[].meals[].id` | string | Meal id. Not stable: saving the menu from the dashboard rewrites every meal with a new id, so re-read this endpoint before each write instead of caching it. Ignored on create; resend it on PATCH to keep the meal and its alternatives instead of replacing it with a new one. |
| `data[].meals[].title` | string | Meal name, e.g. "Breakfast". |
| `data[].meals[].foodItems` | object[] |   |
| `data[].meals[].foodItems[].name` | string | Food name, e.g. "Chicken breast". |
| `data[].meals[].foodItems[].quantity` | number | Amount in the given unit, e.g. 150. |
| `data[].meals[].foodItems[].unit` | string | Unit of the quantity, e.g. "g", "ml", "unit". |
| `data[].meals[].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[].meals[].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[].meals[].foodItems[].caloriesPer100g` | number |   |
| `data[].meals[].foodItems[].proteinPer100g` | number |   |
| `data[].meals[].foodItems[].carbsPer100g` | number |   |
| `data[].meals[].foodItems[].fatPer100g` | number |   |
| `data[].meals[].calories` | number | Total calories for the meal. |
| `data[].meals[].protein` | number |   |
| `data[].meals[].carbs` | number |   |
| `data[].meals[].fat` | number |   |
| `data[].meals[].notes` | string |   |
| `data[].meals[].alternatives` | object[] | Alternatives the trainee may eat instead of this meal. Manage them one at a time with POST/DELETE /nutrition-menus/{menuId}/meals/{mealId}/alternatives, or send the whole array here. Maximum items: `20`. |
| `data[].meals[].alternatives[].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[].meals[].alternatives[].title` | string | Alternative name, e.g. "Omelette instead". |
| `data[].meals[].alternatives[].foodItems` | object[] |   |
| `data[].meals[].alternatives[].foodItems[].name` | string | Food name, e.g. "Chicken breast". |
| `data[].meals[].alternatives[].foodItems[].quantity` | number | Amount in the given unit, e.g. 150. |
| `data[].meals[].alternatives[].foodItems[].unit` | string | Unit of the quantity, e.g. "g", "ml", "unit". |
| `data[].meals[].alternatives[].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[].meals[].alternatives[].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[].meals[].alternatives[].foodItems[].caloriesPer100g` | number |   |
| `data[].meals[].alternatives[].foodItems[].proteinPer100g` | number |   |
| `data[].meals[].alternatives[].foodItems[].carbsPer100g` | number |   |
| `data[].meals[].alternatives[].foodItems[].fatPer100g` | number |   |
| `data[].meals[].alternatives[].calories` | number | Total calories for the alternative. |
| `data[].meals[].alternatives[].protein` | number |   |
| `data[].meals[].alternatives[].carbs` | number |   |
| `data[].meals[].alternatives[].fat` | number |   |
| `data[].meals[].alternatives[].notes` | string |   |
| `data[].createdAt` | string<date-time> |   |
| `pagination` | object |   |
| `pagination.page` | number |   |
| `pagination.limit` | number |   |
| `pagination.total` | number \| null | Total number of matching items. null when the underlying source cannot report an exact count for this page; use hasMore to keep paging. |
| `pagination.hasMore` | boolean |   |
| `pagination.truncated` | boolean | Present and true when the result set exceeded the in-memory scan cap and was truncated. Narrow your filters to page through all items. |

Example:

```json
{
  "data": [
    {
      "id": "<string>",
      "coach": "<string>",
      "escorts": [
        "<string>"
      ],
      "title": "<string>",
      "description": "<string>",
      "goal": "<string>",
      "type": "<string>",
      "totalCalories": 123,
      "totalProtein": 123,
      "totalCarbs": 123,
      "totalFat": 123,
      "meals": [
        {
          "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>",
          "alternatives": [
            {
              "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>"
            }
          ]
        }
      ],
      "createdAt": "<date-time>"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "hasMore": true,
    "truncated": true
  }
}
```

### Error responses 400, 401, 403, 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 GET \
  --url 'https://api.coach-platform.com/api/public/nutrition-menus' \
  --header 'Authorization: Bearer cp_live_...'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/nutrition-menus', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer cp_live_...',
  },
});

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.
- [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).
- [Add an alternative meal](https://www.coach-platform.com/docs/api/reference/post-nutrition-menus-menu-id-meals-meal-id-alternatives/index.md): `POST /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.
- [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 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.
- Next: [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.