# Quickstart

> Create a key, read your journal and log your first meal in a few minutes.

The Splot API is a JSON REST API over HTTPS. It follows the same rules as the app and connected assistants, so a meal saved through the API looks the same everywhere.

```text
https://app.splot.health/v1
```

The whole API is also described as an OpenAPI spec, for tools and AI assistants: [openapi.json](https://splot.health/openapi.json).

Splot adds endpoints and fields to `/v1` over time, so ignore any you don't use. A change that would break existing code comes as a new version beside this one, announced well before `/v1` stops working.

## Your journal

Your Splot journal is a timeline. Every meal you log or plan is an entry on it, placed at the moment it was eaten, or will be, and on that day in the timezone it was eaten in. The app shows the timeline day by day, and the API reads and writes the same entries.

- A logged meal is food you ate. A planned meal is one you mean to eat: it sits on the timeline beside eaten meals, and only eaten meals count toward the day's totals.
- Each meal holds items, one food and a portion each. Splot works out the nutrition from them.

## Create a key

In the app, open **Account → API Keys** and create a key with the **Read and write** permission. The key is shown once, so copy it straight away and keep it out of your code:

```sh
export SPLOT_API_KEY="splot_pat_…"
```

## Read your journal

[List meals](https://splot.health/docs/api/meals/list) returns your latest meals, newest first:

```sh
curl "https://app.splot.health/v1/meals?limit=3" \
  -H "Authorization: Bearer $SPLOT_API_KEY"
```

## Find a food

A meal is made of foods. [Search foods](https://splot.health/docs/api/foods/search) finds one to log, here a product from Open Food Facts by its barcode:

```sh
curl "https://app.splot.health/v1/foods?library=off&query=3017620422003" \
  -H "Authorization: Bearer $SPLOT_API_KEY"
```

Each result has a `library` and a `key`. Together they point at that food.

## Log a meal

[Create a meal](https://splot.health/docs/api/meals/create) with the food and the portion eaten:

```sh
curl https://app.splot.health/v1/meals \
  -H "Authorization: Bearer $SPLOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eatenAt": "2026-10-02T08:30:00+02:00",
    "timezone": "Europe/Berlin",
    "name": "Breakfast",
    "items": [
      { "food": { "library": "off", "key": "3017620422003" }, "quantity": 15, "unit": "g" }
    ]
  }'
```

Splot works out the nutrition from the food and the portion, and the meal appears in the app straight away.