---
title: "Save a food"
method: POST
path: "/foods"
tags: ["Foods"]
---

# Save a food

`POST /foods`

## Request

- Base URL: `https://app.splot.health/v1`
- URL: `https://app.splot.health/v1/foods`
- Auth: HTTP bearer

Saves a food or recipe to your foods, or changes one you saved.

## Request body

- FoodInput
  - `name` string, required: The food's name.
  - `brand` string, nullable: The brand, for a packaged product.
  - `barcode` string, nullable: The barcode: 8 to 14 digits.
  - `data` object, required: Nutrition, portions and recipe details.
    - `base` 'g' | 'ml' | 'serving': The unit nutrition is given in.
    - `nutrition` object: Nutrients for `basisAmount` of the base unit, such as per 100 g. A nutrient left out is unknown, not zero.
      - `basisAmount` number, required: How much of the base unit the values are for.
      - `values` object, required: kcal, and grams of protein, carbs, fat, saturated fat, sugars, fibre and salt. Carbs exclude fibre, as EU labels give them; subtract fibre from a US label's total carbohydrate.
        - `kcal` number
        - `protein` number
        - `carbs` number
        - `fat` number
        - `saturatedFat` number
        - `sugars` number
        - `fibre` number
        - `salt` number
    - `measures` object[]: Other portions by name, each `{ "label", "size" }` in the base unit, such as a tablespoon of 15 g.
      - `label` string, required
      - `size` number, required
    - `defaultPortion` object: The usual portion, as `{ "amount", "unit" }`.
      - `amount` number, required
      - `unit` string, required
    - `composition` string: Ingredients as printed on the label.
    - `note` string: Anything else worth knowing.
    - `images` union[]: Photos, as public links or saved Splot photos.
      - union
        - object
          - `url` string, uri, required
        - object
          - `path` string, required
    - `recipe` object: For a recipe: its `servings`, optional `minutes`, `steps`, and optional `weight`: the whole recipe's weight once made, in grams. With a weight the recipe is stored per 100 g; without one, a `g` measure is estimated from the ingredients when all of them have a weight in grams.
      - `servings` number, required
      - `minutes` number
      - `steps` string[], required
      - `weight` number
    - `source` object: Where the values come from, such as `{ "origin": "label" }`, or `estimate` with a `description`.
      - `origin` 'label' | 'restaurant' | 'manual' | 'estimate' | 'ingredients'
      - `by` 'chatgpt'
      - `place` string
      - `description` string
      - `edited` boolean
      - `library` 'splot' | 'off' | 'mine' | 'composition'
      - `key` string
    - `ingredients` object[]: For a recipe: its foods, each with a `portion`.
      - `food` object
        - `library` 'off' | 'splot' | 'mine' | 'composition', required
        - `key` string, required
        - `version` integer
      - `newFood` object
        - `name` string, required
        - `brand` string, nullable
        - `barcode` string, nullable
        - `data` object, required
          - `base` 'g' | 'ml' | 'serving'
          - `nutrition` object
            - `basisAmount` number, required
            - `values` object, required
              - …
          - `measures` object[]
            - `label` string, required
            - `size` number, required
          - `defaultPortion` object
            - `amount` number, required
            - `unit` string, required
          - `composition` string
          - `note` string
          - `images` union[]
            - union
              - …
          - `recipe` object
            - `servings` number, required
            - `minutes` number
            - `steps` string[], required
            - `weight` number
          - `source` object
            - `origin` 'label' | 'restaurant' | 'manual' | 'estimate' | 'ingredients'
            - `by` 'chatgpt'
            - `place` string
            - `description` string
            - `edited` boolean
            - `library` 'splot' | 'off' | 'mine' | 'composition'
            - `key` string
          - `ingredients` object[]
            - `food` object
              - …
            - `newFood` object
              - …
            - `portion` object
              - …
        - `copyFrom` object
          - `library` 'off' | 'splot' | 'mine' | 'composition', required
          - `key` string, required
      - `portion` object
        - `amount` number, required
        - `unit` string, required
  - `copyFrom` object: The food this one was changed from, as `{ "library", "key" }`, so where it came from is kept.
    - `library` 'off' | 'splot' | 'mine' | 'composition', required
    - `key` string, required
  - `id` string, uuid: To change a food you saved before, its key. Leave out to save a new one.

## Response `201`

The saved food.

- Food
  - `library` 'off' | 'splot' | 'mine' | 'composition', required: The library the food lives in.
  - `key` string, required: Its key in that library. Send `library` and `key` as `food` to log it.
  - `version` integer, required: Foods change over time; meals and recipes keep the version they were saved with.
  - `name` string, required: The food's name.
  - `brand` string, nullable, required: The brand, for packaged products.
  - `barcode` string, nullable, required: The barcode, for packaged products.
  - `data` object, required: Nutrition, portions and recipe details.
    - `base` 'g' | 'ml' | 'serving': The unit nutrition is given in.
    - `nutrition` object: Nutrients for `basisAmount` of the base unit, such as per 100 g. A nutrient left out is unknown, not zero.
      - `basisAmount` number, required: How much of the base unit the values are for.
      - `values` object, required: kcal, and grams of protein, carbs, fat, saturated fat, sugars, fibre and salt. Carbs exclude fibre, as EU labels give them; subtract fibre from a US label's total carbohydrate.
        - `kcal` number
        - `protein` number
        - `carbs` number
        - `fat` number
        - `saturatedFat` number
        - `sugars` number
        - `fibre` number
        - `salt` number
    - `measures` object[]: Other portions by name, each `{ "label", "size" }` in the base unit, such as a tablespoon of 15 g.
      - `label` string, required
      - `size` number, required
    - `defaultPortion` object: The usual portion, as `{ "amount", "unit" }`.
      - `amount` number, required
      - `unit` string, required
    - `composition` string: Ingredients as printed on the label.
    - `note` string: Anything else worth knowing.
    - `images` union[]: Photos, as public links or saved Splot photos.
      - union
        - object
          - `url` string, uri, required
        - object
          - `path` string, required
    - `recipe` object: For a recipe: its `servings`, optional `minutes`, `steps`, and optional `weight`: the whole recipe's weight once made, in grams. With a weight the recipe is stored per 100 g; without one, a `g` measure is estimated from the ingredients when all of them have a weight in grams.
      - `servings` number, required
      - `minutes` number
      - `steps` string[], required
      - `weight` number
    - `source` object: Where the values come from, such as `{ "origin": "label" }`, or `estimate` with a `description`.
      - `origin` 'label' | 'restaurant' | 'manual' | 'estimate' | 'ingredients'
      - `by` 'chatgpt'
      - `place` string
      - `description` string
      - `edited` boolean
      - `library` 'splot' | 'off' | 'mine' | 'composition'
      - `key` string
    - `ingredients` object[]: For a recipe: its foods, each with a `portion`.
      - `food` Food, required (recursive)
      - `portion` object: The usual portion, as `{ "amount", "unit" }`.
        - `amount` number, required
        - `unit` string, required
    - `thumbnail` string: Optional public Storage path for a small food image. Read-only; omit when saving a food.
  - `common` object: For a common food such as Apple, which form this is (raw, baked, dried) and its other forms.
    - `id` string, required: The common food's id, such as `apple`.
    - `name` string, required: The common food's name.
    - `names` object: Its name in each language, by language code, such as `{"en": "Apple", "pl": "Jabłko"}`.
    - `form` string, required: The id of the form this food is.
    - `forms` object[], required: Every form, in order, each a composition food: send `library` `composition` and its `key` to log it.
      - `id` string, required
      - `name` string, required
      - `key` string, required
      - `version` integer, required
      - `food` object
    - `varieties` object[]: Its varieties, each with its parent, as a tree: Red, then Crimson Seedless under it. Send one as a meal item's `variety`.
      - `id` string, required
      - `name` string, required
      - `names` object
      - `parent` string, nullable, required
    - `plural` string, nullable: The food's plural, such as `apples`.
    - `plurals` object: Its plural in each language.
    - `portionNames` object: Each portion label in `data.measures` named in other languages, such as `{"cup": {"pl": "szklanka"}}`. Send the label itself as a meal item's `unit`.

## Other responses

- `400`: The body or query is invalid; `issues` says which fields. Or the body is not valid JSON.
- `401`: The key is missing, revoked or expired.
- `403`: The key's permission doesn't allow this request, or you haven't yet agreed to how Splot handles health information.
- `404`: The food to change, or an ingredient, doesn't exist.
- `409`: The barcode is already in the catalogue. The body's `food` is the one to use.
- `429`: Too many requests. Wait for `Retry-After` seconds.

---

[API](https://skmtc.dev/splot/apis/splot-api.md) · [All operations](https://skmtc.dev/splot/apis/splot-api/llms.txt) · [OpenAPI document](https://skmtc.dev/splot/apis/splot-api/revisions/02f2a6340fe9?raw)