# Create a meal

> Logs a meal you ate, or plans one ahead.

`POST /meals`

Needs the **Read and write** permission.

## Body

| Field | Type | Description |
| --- | --- | --- |
| `eatenAt` | date-time | Required. When it was eaten, or will be for a plan, with a UTC offset. |
| `timezone` | string | Required. The IANA timezone it is eaten in, such as `Europe/Berlin`. Up to 100 characters. |
| `items` | array | Required. What was eaten. 1 to 100 items. |
| `state` | string | Whether the meal was eaten or is planned ahead. One of `planned` or `logged`. Defaults to `logged`. |
| `images` | array | Photos: public links as `{ "url" }`, or saved Splot photos as `{ "path" }` from an earlier read. Up to 20 items. |
| `name` | string or null | A name, such as Breakfast. Up to 2,000 characters. |
| `notes` | string or null | Notes about the meal. Up to 2,000 characters. |

## Items

Each item is either a food that already exists or a new one, and a portion.

| Field | Type | Description |
| --- | --- | --- |
| `food` | object | A food that exists: its `library` and `key` from a food search. |
| `newFood` | object | A food that isn't in Splot yet, as saving a food takes it. It is saved to your foods first. |
| `quantity` | number or null | How much was eaten, in `unit`. Send it with `unit`, or leave both out. |
| `unit` | string or null | The food's base unit (`g`, `ml` or `serving`) or one of its measures. Up to 2,000 characters. |

Give either `food`, from [Search foods](https://splot.health/docs/api/foods/search), or `newFood`, in the shape [Save a food](https://splot.health/docs/api/foods/create) takes. Convert other units first, such as 1 oz to 28.35 g. A dish is one item: don't add a dish and its ingredients as separate items.

## Response

`201` with the new [meal](https://splot.health/docs/api/meals/object), including its id and its items' ids.

## Example

```sh
curl https://app.splot.health/v1/meals \
  -H "Authorization: Bearer $SPLOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eatenAt": "2026-10-02T12:40:00+02:00",
    "timezone": "Europe/Berlin",
    "name": "Lunch",
    "items": [
      { "food": { "library": "composition", "key": "c3f1a2b4-5d6e-4f70-8a91-b2c3d4e5f607" }, "quantity": 180, "unit": "g" },
      {
        "newFood": {
          "name": "Flat white",
          "data": { "base": "ml", "nutrition": { "basisAmount": 100, "values": { "kcal": 54, "protein": 3.1, "carbs": 4.6, "fat": 2.6 } } }
        },
        "quantity": 220,
        "unit": "ml"
      }
    ]
  }'
```