Find anything in the house records

maintenance.record.search

GET/api/v1/households/{household_id}/queries/maintenance.record.search

Query
Rigel runs it

Finds items, models, places, contractors and projects by text: names, model numbers (punctuation and spacing ignored), serial numbers, makers and trades. Best matches first, each with its kind and the web route that opens it. Use it to find the ID of 'the upstairs furnace' or whichever item has a model number.

Parameters#

Find anything in the house records: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`text`querystringrequired	What to look for: a name, model number, serial, place or contractor. 1 to 200 characters
`kinds`queryarray, each one of: asset, model, place, contractor, projectoptional	Only these kinds of record. Leave out for all.
`limit`queryintegeroptional	How many to return, default 20. 1 to 100

Response#

200 The answer.

Find anything in the house records: response fields
Field	Description
`items`array of objectsrequired
`items[].kind`one of: asset, model, place, contractor, projectrequired	What kind of record it is: asset, model, place, contractor or project.
`items[].id`stringrequired	The record's ID.
`items[].address`string or nullrequired	The web route that opens it, when it has one.
`items[].title`stringrequired	Its name.
`items[].detail`string or nullrequired	A line about it: where it is, its model, its trade.
`items[].matched`stringrequired	Which field matched, such as name, model_number or serial.
`truncated`booleanrequired	True when more matched than the limit allowed.

Errors#

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

Find anything in the house records: 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 the house records for the furnace

Items, models, places, contractors and projects.

Request, curl

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

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.record.search?text=furnace 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_01M6V9CT26PS4Q6XWKM2ZG03HN

{
  "items": [
    {
      "kind": "asset",
      "id": "ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
      "address": "/maintenance/assets/ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
      "title": "Basement furnace",
      "detail": "Hearthline FX96-080-1625 · Utility closet, Basement",
      "matched": "name"
    }
  ],
  "truncated": false
}

Search only some kinds of record

Repeat kinds for each kind to include.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.record.search?text=smith&kinds=contractor&kinds=asset' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.record.search?text=smith&kinds=contractor&kinds=asset", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.record.search?text=smith&kinds=contractor&kinds=asset 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_01M6V9CT28BW2WEWAF3D631NP6

{
  "items": [
    {
      "kind": "contractor",
      "id": "ctr_01M6V9CSWEFJH8CRZCXNAH8109",
      "address": "/maintenance/people/ctr_01M6V9CSWEFJH8CRZCXNAH8109",
      "title": "Smith Heating & Air",
      "detail": "HVAC",
      "matched": "name"
    }
  ],
  "truncated": false
}

For Rigel#

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