Find a product by name, to reuse it

inventory.product.search

GET/api/v1/households/{household_id}/queries/inventory.product.search

Query
Rigel runs it

Products whose name contains the text, ignoring case and a plural "s": exact matches first, then names starting with it, then the rest, each with its category, staple flag and how many items we have. Use it before creating a product so the household keeps one "black beans", not three.

Parameters#

Find a product by name, to reuse it: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`text`querystringrequired	Part of the name to look for. 1 to 120 characters
`limit`queryintegeroptional	How many to return, 1–50. Defaults to 10. 1 to 50Default `10`

Response#

200 The answer.

Find a product by name, to reuse it: response fields
Field	Description
`items`array of objectsrequired
`items[].id`stringrequired	A product ID, such as prd_01JC0000000000000000000000.
`items[].name`stringrequired	No description.
`items[].category`string or nullrequired	Its category's name, or null.
`items[].is_staple`booleanrequired	No description.
`items[].is_tracked`booleanrequired	No description.
`items[].default_location_id`string or nullrequired	Where it usually goes.
`items[].item_count`integerrequired	How many inventory items of it we have.

Errors#

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

Find a product by name, to reuse it: 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.

Search products for flour

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.product.search?text=flour' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/inventory.product.search?text=flour 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_01M6V9CSBBH62CFTHETSGKN841

{
  "items": [
    {
      "id": "prd_01M6V9CSAG72MC7ERJ4GCZ0X7A",
      "name": "Flour",
      "category": "Baking",
      "is_staple": true,
      "is_tracked": true,
      "default_location_id": "loc_01M6V9CSA910340EZNX67RFMV0",
      "item_count": 1
    }
  ]
}

For Rigel#

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