The household's contractors

maintenance.contractor.list

GET/api/v1/households/{household_id}/queries/maintenance.contractor.list

Query
Rigel runs it

Contractors and service businesses the household uses, preferred ones first, optionally for one trade or matching text in the name, trade, phone, email or notes. Each has how many visits they've made and when they last came.

Parameters#

The household's contractors: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`trade`querystringoptional	Only this trade, such as "HVAC" or "plumbing", ignoring case.
`text`querystringoptional	Only contractors whose name, trade, phone, email or notes contain this text.
`limit`queryintegeroptional	How many to return, default 100. 1 to 500

Response#

200 The answer.

The household's contractors: response fields
Field	Description
`items`array of objectsrequired
`items[].id`stringrequired	A contractor ID, such as ctr_01JC0000000000000000000000.
`items[].address`string or nullrequired	The web route that opens it.
`items[].name`stringrequired	The business's name.
`items[].trade`string or nullrequired	What they do.
`items[].phone`string or nullrequired	Their phone number.
`items[].email`string or nullrequired	Their email address.
`items[].website`string or nullrequired	Their website.
`items[].is_preferred`booleanrequired	Whether the household prefers them.
`items[].visit_count`integerrequired	Visits they made (done).
`items[].last_visit_on`string or nullrequired	When they last came, YYYY-MM-DD.
`items[].next_visit_at`string (date-time) or nullrequired	When they are next due, if a visit is scheduled.
`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.

The household's contractors: 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 contractors

Request, curl

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

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.contractor.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_01M6V9CT1FDGY8T5Q0T8K5AYS9

{
  "items": [
    {
      "id": "ctr_01M6V9CSWEFJH8CRZCXNAH8109",
      "address": "/maintenance/people/ctr_01M6V9CSWEFJH8CRZCXNAH8109",
      "name": "Smith Heating & Air",
      "trade": "HVAC",
      "phone": "555-0142",
      "email": "pat@smithhvac.example.com",
      "website": "https://smithhvac.example.com",
      "is_preferred": true,
      "visit_count": 0,
      "last_visit_on": null,
      "next_visit_at": "2026-11-19T15:00:00.000Z"
    },
    {
      "id": "ctr_01M6V9CSWHPNYAY4A5FBX3R14F",
      "address": "/maintenance/people/ctr_01M6V9CSWHPNYAY4A5FBX3R14F",
      "name": "Riverbend Plumbing & Drain",
      "trade": "Plumbing",
      "phone": "555-0178",
      "email": "office@riverbendplumbing.example.com",
      "website": null,
      "is_preferred": false,
      "visit_count": 1,
      "last_visit_on": "2026-09-18",
      "next_visit_at": "2026-11-13T15:00:00.000Z"
    }
  ],
  "truncated": false
}

List the plumbers

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.contractor.list?trade=Plumbing' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.contractor.list?trade=Plumbing 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_01M6V9CT1G3K3H6KC0FT2EWSZ2

{
  "items": [
    {
      "id": "ctr_01M6V9CSWHPNYAY4A5FBX3R14F",
      "address": "/maintenance/people/ctr_01M6V9CSWHPNYAY4A5FBX3R14F",
      "name": "Riverbend Plumbing & Drain",
      "trade": "Plumbing",
      "phone": "555-0178",
      "email": "office@riverbendplumbing.example.com",
      "website": null,
      "is_preferred": false,
      "visit_count": 1,
      "last_visit_on": "2026-09-18",
      "next_visit_at": "2026-11-13T15:00:00.000Z"
    }
  ],
  "truncated": false
}

Search the contractors for Smith

Request, curl

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

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.contractor.list?text=smith 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_01M6V9CT1H1G0GSTJY3HJVQECA

{
  "items": [
    {
      "id": "ctr_01M6V9CSWEFJH8CRZCXNAH8109",
      "address": "/maintenance/people/ctr_01M6V9CSWEFJH8CRZCXNAH8109",
      "name": "Smith Heating & Air",
      "trade": "HVAC",
      "phone": "555-0142",
      "email": "pat@smithhvac.example.com",
      "website": "https://smithhvac.example.com",
      "is_preferred": true,
      "visit_count": 0,
      "last_visit_on": null,
      "next_visit_at": "2026-11-19T15:00:00.000Z"
    }
  ],
  "truncated": false
}

For Rigel#

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