---
title: "Search foods"
method: GET
path: "/foods"
tags: ["Foods"]
---

# Search foods

`GET /foods`

## Request

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

Finds foods to log in one library, by name, brand or barcode.

## Query parameters

- `query` string
- `library` 'off' | 'splot' | 'mine' | 'composition'
- `limit` integer
- `offset` integer
- `locale` string
- `region` string

## Response `200`

A page of foods.

- FoodPage
  - `foods` Food[], required: The page of foods.
    - `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`.
  - `nextOffset` integer, nullable, required: The offset of the next page, or null on the last.

## 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.
- `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)