What to buy to cook a recipe

recipes.recipe.shopping_preview

GET/api/v1/households/{household_id}/queries/recipes.recipe.shopping_preview

Query
Rigel runs it

Each ingredient scaled to the servings, with whether its product is a staple, what inventory says we have, and whether it is already on the grocery list. ticked says whether to add it by default. Staples are in the check group. on_list is true when the product is on the list and not yet checked off; adding it again with shopping.item.add_many merges into that item and links the recipe.

Parameters#

What to buy to cook a recipe: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`recipe_id`querystringrequired	A recipe ID, such as rcp_01JC0000000000000000000000.
`servings`queryintegerrequired	How many servings to buy for, 1–1,000. 1 to 1,000

Response#

200 The answer.

What to buy to cook a recipe: response fields
Field	Description
`servings`integerrequired	The servings the amounts are for.
`items`array of objectsrequired
`items[].ingredient_id`stringrequired	A recipe ingredient ID, such as rci_01JC0000000000000000000000.
`items[].name`stringrequired	The ingredient as written.
`items[].product_id`string or nullrequired	The product it is linked to, or null.
`items[].quantity`number or nullrequired	The scaled amount, or null for 'to taste'.
`items[].quantity_max`number or nullrequired	The scaled top of a range, or null.
`items[].unit`one of: mg, g, kg, oz, lb, ml, l, tsp, tbsp, fl_oz, cup, pint, quart, gallon, pinch, dash, clove, slice, stick, sprig, head, bunch, stalk, can, jar, bottle, box, bag, package, carton, roll, null or nullrequired	The unit, or null for a plain count.
`items[].amount`string or nullrequired	The scaled amount for people, such as "2 tbsp", or null.
`items[].is_optional`booleanrequired	Whether it can be left out.
`items[].is_staple`booleanrequired	Whether its product is a household staple.
`items[].have`string or nullrequired	What inventory says we have, such as "2 in the pantry", or null.
`items[].on_list`booleanrequired	Whether it is already on the grocery list.
`items[].group`one of: buy, checkrequired	buy, or check for staples to check you have.
`items[].ticked`booleanrequired	Whether to add it by default: false for staples, things we have or have listed, and optional ones.
`items[].reason`string or nullrequired	Why it is not ticked: "On the list", what we have, "Optional", or null.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

What to buy to cook a recipe: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

What to buy for a recipe

Each ingredient is checked against what the household has: things to buy, and staples to check.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.shopping_preview?recipe_id=rcp_01M6V9CSD8VZYF11AC568Y7QPZ&servings=4' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.shopping_preview?recipe_id=rcp_01M6V9CSD8VZYF11AC568Y7QPZ&servings=4", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/recipes.recipe.shopping_preview?recipe_id=rcp_01M6V9CSD8VZYF11AC568Y7QPZ&servings=4 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSDZ2267B7DYYXM4TMTW

{
  "servings": 4,
  "items": [
    {
      "ingredient_id": "rci_01M6V9CSD8MJZZDY9C256CQPD0",
      "name": "olive oil",
      "product_id": "prd_01M6V9CSAT6M58YWZ1H4DFY9K2",
      "quantity": 2,
      "quantity_max": null,
      "unit": "tbsp",
      "amount": "2 tbsp",
      "is_optional": false,
      "is_staple": false,
      "have": "Have mostly full · Middle shelf",
      "on_list": false,
      "group": "buy",
      "ticked": false,
      "reason": "Have mostly full · Middle shelf"
    },
    {
      "ingredient_id": "rci_01M6V9CSD8HFZX76ACQ7929C3Z",
      "name": "garlic",
      "product_id": null,
      "quantity": 3,
      "quantity_max": 4,
      "unit": "clove",
      "amount": "3–4 cloves",
      "is_optional": false,
      "is_staple": false,
      "have": null,
      "on_list": false,
      "group": "buy",
      "ticked": true,
      "reason": null
    },
    {
      "ingredient_id": "rci_01M6V9CSD8J6BVN3AC4YDGRFCN",
      "name": "orzo",
      "product_id": "prd_01M6V9CSAQDSZHDQNXHXRCDA8Z",
      "quantity": 1,
      "quantity_max": null,
      "unit": "cup",
      "amount": "1 cup",
      "is_optional": false,
      "is_staple": false,
      "have": "Have 1 box · Middle shelf",
      "on_list": false,
      "group": "buy",
      "ticked": false,
      "reason": "Have 1 box · Middle shelf"
    },
    {
      "ingredient_id": "rci_01M6V9CSD8Q0HKRAACH243A5QR",
      "name": "crushed tomatoes",
      "product_id": null,
      "quantity": 1,
      "quantity_max": null,
      "unit": "can",
      "amount": "1 can",
      "is_optional": false,
      "is_staple": false,
      "have": null,
      "on_list": false,
      "group": "buy",
      "ticked": true,
      "reason": null
    },
    {
      "ingredient_id": "rci_01M6V9CSD8GKH358ACE12HS4ES",
      "name": "white beans",
      "product_id": null,
      "quantity": 1,
      "quantity_max": null,
      "unit": "can",
      "amount": "1 can",
      "is_optional": false,
      "is_staple": false,
      "have": null,
      "on_list": false,
      "group": "buy",
      "ticked": true,
      "reason": null
    },
    {
      "ingredient_id": "rci_01M6V9CSD8DPC2ZFAC3657BTP5",
      "name": "vegetable broth",
      "product_id": null,
      "quantity": 2,
      "quantity_max": null,
      "unit": "cup",
      "amount": "2 cups",
      "is_optional": false,
      "is_staple": false,
      "have": null,
      "on_list": false,
      "group": "buy",
      "ticked": true,
      "reason": null
    },
    {
      "ingredient_id": "rci_01M6V9CSD8Y6T0ADACG3WMTNWC",
      "name": "baby spinach",
      "product_id": null,
      "quantity": 2,
      "quantity_max": null,
      "unit": "cup",
      "amount": "2 cups",
      "is_optional": true,
      "is_staple": false,
      "have": null,
      "on_list": false,
      "group": "buy",
      "ticked": false,
      "reason": "Optional"
    }
  ]
}

For Rigel#

Rigel's tool for this query is recipes_recipe_shopping_preview. Rigel runs this on its own, then says what it did. The agent guide has the rest.