The places things are kept, as a tree

inventory.location.list

GET/api/v1/households/{household_id}/queries/inventory.location.list

Query
Rigel runs it

Every location in page order, each after its parent, with its environment, how many items are in it (and in the locations inside it), and when it was last checked as a whole.

Parameters#

The places things are kept, as a tree: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.

Response#

200 The answer.

The places things are kept, as a tree: response fields
Field	Description
`items`array of objectsrequired
`items[].id`stringrequired	A storage location ID, such as loc_01JC0000000000000000000000.
`items[].name`stringrequired	No description.
`items[].path`stringrequired	Its place from the top: "Kitchen pantry › Middle shelf".
`items[].parent_location_id`string or nullrequired	A storage location ID, such as loc_01JC0000000000000000000000.
`items[].depth`integerrequired	0 for a top-level location.
`items[].environment`one 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[].item_count`integerrequired	Items directly in it.
`items[].total_item_count`integerrequired	Items in it and in every location inside it.
`items[].confirmed_at`string (date-time) or nullrequired	When the whole location was last checked, or null if never.
`items[].seen_ago`string or nullrequired	How long ago that was, in words.

Errors#

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

The places things are kept, as a tree: 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.

List the places things are kept

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.location.list' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.location.list", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.location.list 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_01M6V9CSB857VREKH3RGRWR493

{
  "items": [
    {
      "id": "loc_01M6V9CSA7ZW2X97W1ARAE39NH",
      "name": "Kitchen pantry",
      "path": "Kitchen pantry",
      "parent_location_id": null,
      "depth": 0,
      "environment": "room",
      "item_count": 0,
      "total_item_count": 4,
      "confirmed_at": null,
      "seen_ago": null
    },
    {
      "id": "loc_01M6V9CSA910340EZNX67RFMV0",
      "name": "Middle shelf",
      "path": "Kitchen pantry › Middle shelf",
      "parent_location_id": "loc_01M6V9CSA7ZW2X97W1ARAE39NH",
      "depth": 1,
      "environment": "room",
      "item_count": 4,
      "total_item_count": 4,
      "confirmed_at": null,
      "seen_ago": null
    },
    {
      "id": "loc_01M6V9CSAACDPHW4NW889QQ2VV",
      "name": "Kitchen fridge",
      "path": "Kitchen fridge",
      "parent_location_id": null,
      "depth": 0,
      "environment": "cold",
      "item_count": 3,
      "total_item_count": 3,
      "confirmed_at": null,
      "seen_ago": null
    },
    {
      "id": "loc_01M6V9CSABVCCJRZ4RWVFW77D6",
      "name": "Chest freezer",
      "path": "Chest freezer",
      "parent_location_id": null,
      "depth": 0,
      "environment": "frozen",
      "item_count": 1,
      "total_item_count": 1,
      "confirmed_at": null,
      "seen_ago": null
    },
    {
      "id": "loc_01M6V9CSADPBG11HW38FMRV1ZQ",
      "name": "Basement closet",
      "path": "Basement closet",
      "parent_location_id": null,
      "depth": 0,
      "environment": "room",
      "item_count": 1,
      "total_item_count": 1,
      "confirmed_at": null,
      "seen_ago": null
    }
  ]
}

For Rigel#

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