# The meal object

> What a meal holds, its items, and how its nutrition is added up.

A meal is an entry in your journal's timeline: what you ate, or plan to eat, at a moment on a day. Every meal endpoint returns meals in this shape.

```json
{
  "id": "6f1c2a8e-3b7d-4c5e-9a1f-2d8b7e4c9a10",
  "state": "logged",
  "category": "meals",
  "day": "2026-10-02",
  "eatenAt": "2026-10-02T06:30:00.000Z",
  "timezone": "Europe/Berlin",
  "name": "Breakfast",
  "notes": null,
  "images": [],
  "plannedVia": null,
  "loggedVia": "api",
  "nutrition": {
    "caloriesKcal": { "value": 80.85, "complete": true },
    "proteinG": { "value": 0.945, "complete": true },
    "carbsG": { "value": 8.625, "complete": true },
    "fatG": { "value": 4.635, "complete": true },
    "saturatedFatG": { "value": 1.59, "complete": true },
    "sugarsG": { "value": 8.445, "complete": true },
    "fibreG": { "value": null, "complete": false },
    "saltG": { "value": 0.0165, "complete": true }
  },
  "createdAt": "2026-10-02T06:31:12.000Z",
  "updatedAt": "2026-10-02T06:31:12.000Z",
  "items": [
    {
      "id": "0b9e4d2c-7a51-4f8e-b3c6-5d1a9e2f7c48",
      "position": 0,
      "quantity": 15,
      "unit": "g",
      "caloriesKcal": 80.85,
      "proteinG": 0.945,
      "carbsG": 8.625,
      "fatG": 4.635,
      "saturatedFatG": 1.59,
      "sugarsG": 8.445,
      "fibreG": null,
      "saltG": 0.0165,
      "food": { "library": "off", "key": "3017620422003", "version": 1, "name": "Nutella", "brand": "Ferrero", "barcode": "3017620422003", "data": { "base": "g", "nutrition": { "basisAmount": 100, "values": { "kcal": 539, "protein": 6.3, "carbs": 57.5, "fat": 30.9, "saturatedFat": 10.6, "sugars": 56.3, "salt": 0.11 } } } }
    }
  ]
}
```

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The meal's id. |
| `state` | string | `logged` for food eaten, `planned` for a meal planned ahead. One of `planned` or `logged`. |
| `category` | string | The kind of entry in the journal's timeline: `meals`. |
| `day` | date | The calendar day it belongs to, in its own timezone. |
| `eatenAt` | date-time | When it was eaten, or will be for a plan, in UTC. |
| `timezone` | string | The IANA timezone it was eaten in. |
| `name` | string or null | Its name, such as Breakfast. |
| `notes` | string or null | Its notes. |
| `images` | array | Photos: `{ "path" }` for photos saved in Splot, `{ "url" }` for links. |
| `plannedVia` | string or null | Where it was planned. One of `app`, `api`, `chatgpt`, `claude` or `assistant`. |
| `loggedVia` | string or null | Where it was logged. One of `app`, `api`, `chatgpt`, `claude` or `assistant`. |
| `nutrition` | object | The meal's totals, each `{ "value", "complete" }`. `complete` is false when an item, or an ingredient of a recipe item, lacks that nutrient. |
| `createdAt` | date-time | When it was created. |
| `updatedAt` | date-time | When it last changed. |
| `items` | array | What was eaten, in order. |

## Items

Each item is one food and the portion eaten. `quantity` and `unit` are the portion, in the food's base unit or one of its measures; both are `null` for an entry without a portion. The nutrient fields are that portion's amounts, and `food` is the [food](https://splot.health/docs/api/foods/object) as it was when the meal was saved, so later changes to a food never change past meals.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The item's id. |
| `position` | integer | Its place in the meal, from 0. |
| `quantity` | number or null | How much was eaten, in `unit`, or null for an entry without a portion. |
| `unit` | string or null | The food's base unit or one of its measures. |
| `caloriesKcal` | number or null | The portion's energy, in kcal. |
| `proteinG` | number or null | The portion's protein, in grams. |
| `carbsG` | number or null | The portion's carbs, in grams. |
| `fatG` | number or null | The portion's fat, in grams. |
| `saturatedFatG` | number or null | The portion's saturated fat, in grams. |
| `sugarsG` | number or null | The portion's sugars, in grams. |
| `fibreG` | number or null | The portion's fibre, in grams. |
| `saltG` | number or null | The portion's salt, in grams. |
| `food` | object | The food as it was when the meal was saved. |

## Nutrition

Splot works out every amount from the foods and portions; you never send totals. A meal's `nutrition` adds up its items. `complete` is `false` when any item lacks that nutrient, or is a recipe with an ingredient that lacks it, so the `value` covers only what lists it.