Foods

Nutrition sources, with their nutrient values. A material product points at one through material.food_id.

catalog:readcatalog:writehttps://public-api.nutrasoft.ca/v1

Links toNutrientsnutrients[].nutrient_id

Linked fromProductsmaterial.food_id

The Food object

idinteger
is_globalboolean
True for a NutraSoft-supplied reference food shared by every account, which you can read but not change.
namestringnullable
name_frstringnullable
nutrientsarray of objectsnullable
Nutrient values, on GET /foods/{food_id} only: null elsewhere means not loaded, while an empty array means none.
ShowHide 5 fields of nutrients
- labelstringnullable
- namestringnullable
- nutrient_idinteger
- uomstringnullable
  The unit value is expressed in.
- valuenumbernullable
sourcestringnullable
Where the nutrition data came from, e.g. a reference database.
suggested_yield_descriptionstringnullable
suggested_yield_pctnumbernullable

Operations

List foods

get/foodscatalog:read

Nutrition sources, yours plus the NutraSoft reference set, marked is_global. nutrients is null here: retrieve a food for its values.

Query parameters

searchstringnullable
Free-text match on id, name or French name.
sortstringnullable
Comma-separated field:direction pairs, e.g. id:desc. Sortable: id, name, name_fr. id is always added last, so paging is stable.
limitinteger
Rows to return. Maximum 200.
- >= 1
- <= 200
- default 50
offsetinteger
Rows to skip. Maximum 10000: to read further, narrow the filters or page with updated_since.
- >= 0
- <= 10000
- default 0

Returns

200 A page of Food objects in data, with pagination.

Errors

400 401 403 429 500 503

GET /foods

curl "https://public-api.nutrasoft.ca/v1/foods?limit=50" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": [
    {
      "id": 123,
      "is_global": false,
      "name": "Sample name",
      "name_fr": "string",
      "nutrients": [
        {
          "label": "string",
          "name": "Sample name",
          "nutrient_id": 123,
          "uom": "string",
          "value": 12.5
        }
      ],
      "source": "string",
      "suggested_yield_description": "string",
      "suggested_yield_pct": 12.5
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "has_more": false
  },
  "order": "id:asc"
}

Retrieve a food

get/foods/{food_id}catalog:read

Includes the food's nutrient values.

Path parameters

food_idintegerrequired
The food's id.
- > 0

Returns

200 One Food object in data.

Errors

400 401 403 404 429 500 503

GET /foods/{food_id}

curl "https://public-api.nutrasoft.ca/v1/foods/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "is_global": false,
    "name": "Sample name",
    "name_fr": "string",
    "nutrients": [
      {
        "label": "string",
        "name": "Sample name",
        "nutrient_id": 123,
        "uom": "string",
        "value": 12.5
      }
    ],
    "source": "string",
    "suggested_yield_description": "string",
    "suggested_yield_pct": 12.5
  }
}

Create a food

post/foodscatalog:write

Creates a nutrition source with no nutrient values: they cannot be written in v1. Not idempotent: a retry creates a second food.

Request body

namestringrequired
English name.
- min 1 chars
- max 254 chars
name_frstringrequired
French name.
- min 1 chars
- max 254 chars
sourcestringnullable
Where the nutrition data came from, e.g. a reference database.
- max 100 chars
suggested_yield_descriptionstringnullable
- max 100 chars
suggested_yield_pctnumber
Percentage of the raw weight left after preparation.
- >= 0
- <= 100
- default 0

Returns

201 One Food object in data.

Errors

400 401 403 409 429 500 503

POST /foods

curl -X POST "https://public-api.nutrasoft.ca/v1/foods" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sample name",
  "name_fr": "string"
}'

Response201

{
  "data": {
    "id": 123,
    "is_global": false,
    "name": "Sample name",
    "name_fr": "string",
    "nutrients": [
      {
        "label": "string",
        "name": "Sample name",
        "nutrient_id": 123,
        "uom": "string",
        "value": 12.5
      }
    ],
    "source": "string",
    "suggested_yield_description": "string",
    "suggested_yield_pct": 12.5
  }
}

Update a food

patch/foods/{food_id}catalog:write

Omitted fields and nutrient values are left unchanged. Shared reference foods are read-only (403).

Path parameters

food_idintegerrequired
The food's id.
- > 0

Request body

namestringnullable
- min 1 chars
- max 254 chars
name_frstringnullable
- min 1 chars
- max 254 chars
sourcestringnullable
- max 100 chars
suggested_yield_descriptionstringnullable
- max 100 chars
suggested_yield_pctnumbernullable
- >= 0
- <= 100

Returns

200 One Food object in data.

Errors

400 401 403 404 409 429 500 503

PATCH /foods/{food_id}

curl -X PATCH "https://public-api.nutrasoft.ca/v1/foods/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sample name"
}'

Response200

{
  "data": {
    "id": 123,
    "is_global": false,
    "name": "Sample name",
    "name_fr": "string",
    "nutrients": [
      {
        "label": "string",
        "name": "Sample name",
        "nutrient_id": 123,
        "uom": "string",
        "value": 12.5
      }
    ],
    "source": "string",
    "suggested_yield_description": "string",
    "suggested_yield_pct": 12.5
  }
}

Delete a food

delete/foods/{food_id}catalog:write

Deletes one of your foods and its nutrient values. Refused with 409 while a product uses it as its nutrition source.

Path parameters

food_idintegerrequired
The food's id.
- > 0

Returns

200 One Food object in data.

Errors

400 401 403 404 409 429 500 503

DELETE /foods/{food_id}

curl -X DELETE "https://public-api.nutrasoft.ca/v1/foods/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "is_global": false,
    "name": "Sample name",
    "name_fr": "string",
    "nutrients": [
      {
        "label": "string",
        "name": "Sample name",
        "nutrient_id": 123,
        "uom": "string",
        "value": 12.5
      }
    ],
    "source": "string",
    "suggested_yield_description": "string",
    "suggested_yield_pct": 12.5
  }
}