Skip to content
Rigel docs
Open Rigel

What to use soon

inventory.item.expiring

GET/api/v1/households/{household_id}/queries/inventory.item.expiring

  • Query
  • Rigel runs it

Items to use by within the next few days, including ones already past, soonest first. Dates that Rigel estimated (expires_source "estimated") are less certain than ones read off the label or given by a person, so treat them as a prompt to check rather than a fact.

Parameters#

What to use soon: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

within_daysqueryinteger or nulloptional

Include items to use by this many days from today, 0–60. Defaults to 7.

0 to 60Default 7

Response#

200 The answer.

What to use soon: response fields
FieldDescription
itemsarray of objectsrequired

Soonest first, then by name. Past dates come first.

items[].idstringrequired

A inventory item ID, such as inv_01JC0000000000000000000000.

items[].productobjectrequired
items[].product.idstringrequired

A product ID, such as prd_01JC0000000000000000000000.

items[].product.namestringrequired

What it is: "black beans".

items[].product.categorystring or nullrequired

The product's grouping, such as Canned, or null.

items[].product.is_staplebooleanrequired

Whether the household always keeps it in stock.

items[].product.is_trackedbooleanrequired

Whether the household tracks how much of it we have.

items[].locationobjectrequired
items[].location.idstringrequired

A storage location ID, such as loc_01JC0000000000000000000000.

items[].location.namestringrequired

The location's own name.

items[].location.pathstringrequired

Where it is from the top: "Kitchen pantry › Middle shelf".

items[].location.environmentone of: frozen, cold, roomrequired

How a location keeps things, which decides which shelf life applies: frozen (a freezer), cold (a fridge) or room (a pantry, cupboard or closet).

items[].brandstring or nullrequired

The brand, if recorded.

items[].variantstring or nullrequired

The kind, if recorded: "low sodium".

items[].sizestring or nullrequired

The package size in words: "15 oz each", or null.

items[].amountstringrequired

The amount in words: "2 cans", "about half", "some".

items[].quantitynumber or nullrequired

The number we have, in quantity_unit, or null when we don't know one.

items[].quantity_unitone 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

A unit. Mass: mg, g, kg, oz, lb. Volume (US sizes): ml, l, tsp, tbsp, fl_oz, cup, pint, quart, gallon. Items, for a count of something other than the thing itself (2 cloves of garlic, 1 can of beans): pinch, dash, clove, slice, stick, sprig, head, bunch, stalk, can, jar, bottle, box, bag, package, carton, roll. Leave it out or null for a plain count of the things themselves (3 eggs).

items[].levelone of: full, most, half, low, null or nullrequired

A rough amount when there's no number: full, most (mostly full), half (about half) or low. Leave both quantity and level out for "we have some".

items[].acquired_onstring or nullrequired

When we got it, YYYY-MM-DD, or null.

items[].opened_onstring or nullrequired

When it was opened, YYYY-MM-DD, or null.

items[].label_best_bystring or nullrequired

The date printed on the package, as read, or null.

items[].expires_onstring or nullrequired

When to use it by, YYYY-MM-DD, or null if it doesn't go bad.

items[].expires_sourceone of: label, person, estimated, null or nullrequired

Where expires_on came from: label (read off the package), person (someone told us) or estimated (Rigel worked it out from what it is, where it's kept and when it was bought, made or opened).

items[].expirystring or nullrequired

The date in words: "Use by Nov 9", "Past, Nov 2", or null.

items[].days_leftinteger or nullrequired

Days from today until expires_on, negative when it's past, or null without a date.

items[].confirmed_atstring (date-time)required

When this item's amount was last known to be true.

items[].seen_agostringrequired

How long ago that was, in words: "3 days ago".

items[].seen_onstringrequired

The day that was, in words: "Nov 6".

items[].pictureobject or nullrequired

A picture to show for the item, or null when there is none.

items[].picture.file_idstringrequired

The image file.

items[].picture.cropobject or nullrequired

The part of the image that shows the item, or null for all of it.

items[].picture.crop.xnumberrequired

Left edge, as a fraction of the image's width, 0–1.

items[].picture.crop.ynumberrequired

Top edge, as a fraction of the image's height, 0–1.

items[].picture.crop.widthnumberrequired

Width, as a fraction of the image's width, 0–1.

items[].picture.crop.heightnumberrequired

Height, as a fraction of the image's height, 0–1.

items[].picture.sourceone of: photo, iconrequired

photo: of this item. icon: the product's generated icon.

items[].notestring or nullrequired

A note about this item, as written.

todaystringrequired

Today in the household's time zone, YYYY-MM-DD.

Errors#

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

What to use soon: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404not_foundThe 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's about to expire

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.item.expiring' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.item.expiring", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.item.expiring 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_01M6V9CSC001K3PYGAASMYKQ4A

{
  "items": [
    {
      "id": "inv_01M6V9CSAWTFE7ARBQF4CXQ31Q",
      "product": {
        "id": "prd_01M6V9CSAWSAMCWTBQ2M7F80H9",
        "name": "Milk",
        "category": "Dairy",
        "is_staple": true,
        "is_tracked": true
      },
      "location": {
        "id": "loc_01M6V9CSAACDPHW4NW889QQ2VV",
        "name": "Kitchen fridge",
        "path": "Kitchen fridge",
        "environment": "cold"
      },
      "brand": null,
      "variant": null,
      "size": null,
      "amount": "1 gallon",
      "quantity": 1,
      "quantity_unit": "gallon",
      "level": null,
      "acquired_on": null,
      "opened_on": null,
      "label_best_by": null,
      "expires_on": "2026-11-10",
      "expires_source": "label",
      "expiry": "Use by Nov 10",
      "days_left": 3,
      "confirmed_at": "2026-11-07T15:17:52.093Z",
      "seen_ago": "just now",
      "seen_on": "Nov 7",
      "picture": null,
      "note": null
    },
    {
      "id": "inv_01M6V9CSB0YB2Y7WBZBMR3G5Z0",
      "product": {
        "id": "prd_01M6V9CSB0DQFW5YBZYYMJ0A77",
        "name": "Yogurt",
        "category": null,
        "is_staple": false,
        "is_tracked": true
      },
      "location": {
        "id": "loc_01M6V9CSAACDPHW4NW889QQ2VV",
        "name": "Kitchen fridge",
        "path": "Kitchen fridge",
        "environment": "cold"
      },
      "brand": null,
      "variant": null,
      "size": null,
      "amount": "about half",
      "quantity": null,
      "quantity_unit": null,
      "level": "half",
      "acquired_on": null,
      "opened_on": null,
      "label_best_by": null,
      "expires_on": "2026-11-13",
      "expires_source": "label",
      "expiry": "Use by Nov 13",
      "days_left": 6,
      "confirmed_at": "2026-11-07T15:17:52.096Z",
      "seen_ago": "just now",
      "seen_on": "Nov 7",
      "picture": null,
      "note": null
    }
  ],
  "today": "2026-11-07"
}

What expires within a week

within_days widens or narrows the window.

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.item.expiring?within_days=7' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.item.expiring?within_days=7", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.item.expiring?within_days=7 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_01M6V9CSC3924H6G4FD7Z617S4

{
  "items": [
    {
      "id": "inv_01M6V9CSAWTFE7ARBQF4CXQ31Q",
      "product": {
        "id": "prd_01M6V9CSAWSAMCWTBQ2M7F80H9",
        "name": "Milk",
        "category": "Dairy",
        "is_staple": true,
        "is_tracked": true
      },
      "location": {
        "id": "loc_01M6V9CSAACDPHW4NW889QQ2VV",
        "name": "Kitchen fridge",
        "path": "Kitchen fridge",
        "environment": "cold"
      },
      "brand": null,
      "variant": null,
      "size": null,
      "amount": "1 gallon",
      "quantity": 1,
      "quantity_unit": "gallon",
      "level": null,
      "acquired_on": null,
      "opened_on": null,
      "label_best_by": null,
      "expires_on": "2026-11-10",
      "expires_source": "label",
      "expiry": "Use by Nov 10",
      "days_left": 3,
      "confirmed_at": "2026-11-07T15:17:52.093Z",
      "seen_ago": "just now",
      "seen_on": "Nov 7",
      "picture": null,
      "note": null
    },
    {
      "id": "inv_01M6V9CSB0YB2Y7WBZBMR3G5Z0",
      "product": {
        "id": "prd_01M6V9CSB0DQFW5YBZYYMJ0A77",
        "name": "Yogurt",
        "category": null,
        "is_staple": false,
        "is_tracked": true
      },
      "location": {
        "id": "loc_01M6V9CSAACDPHW4NW889QQ2VV",
        "name": "Kitchen fridge",
        "path": "Kitchen fridge",
        "environment": "cold"
      },
      "brand": null,
      "variant": null,
      "size": null,
      "amount": "about half",
      "quantity": null,
      "quantity_unit": null,
      "level": "half",
      "acquired_on": null,
      "opened_on": null,
      "label_best_by": null,
      "expires_on": "2026-11-13",
      "expires_source": "label",
      "expiry": "Use by Nov 13",
      "days_left": 6,
      "confirmed_at": "2026-11-07T15:17:52.096Z",
      "seen_ago": "just now",
      "seen_on": "Nov 7",
      "picture": null,
      "note": null
    }
  ],
  "today": "2026-11-07"
}

For Rigel#

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

Rigel is in early access, and sign-up is by invitation. Open Rigel