---
title: "Retrieve a food"
method: GET
path: "/foods/{library}/{key}"
tags: ["Foods"]
---

# Retrieve a food

`GET /foods/{library}/{key}`

## Request

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

Reads one food. A common food comes with every form, so you can offer Raw or Boiled.

## Query parameters

- `version` integer

## Response `200`

The 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`: No food with that key in that library.
- `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)