One contractor visit

maintenance.visit.get

GET/api/v1/households/{household_id}/queries/maintenance.visit.get

Query
Rigel runs it

One visit: when (the arrival window, or the day it happened), who, what for, its status, summary and notes, the items and problems it concerns, the active maintenance tasks of those items (what marking it done can check off), the tasks it already checked off, and its quotes and invoices. Fails with visit_not_found.

Parameters#

One contractor visit: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`visit_id`querystringrequired	The visit.

Response#

200 The answer.

One contractor visit: response fields
Field	Description
`id`stringrequired	A visit ID, such as vst_01JC0000000000000000000000.
`address`string or nullrequired	The web route that opens it.
`title`stringrequired	What it is for.
`status`one of: scheduled, done, cancelledrequired	Where the visit stands.
`starts_at`string (date-time) or nullrequired	When they are due, start of the window.
`ends_at`string (date-time) or nullrequired	End of the arrival window.
`visited_on`string or nullrequired	When the work happened, YYYY-MM-DD.
`summary`string or nullrequired	What was done.
`notes`string or nullrequired	Notes about the visit.
`date`string or nullrequired	The visit's date: when it happened or when its window starts, YYYY-MM-DD.
`property_id`stringrequired	A property ID, such as prp_01JC0000000000000000000000.
`contractor_id`string or nullrequired	Who is coming or came.
`contractor_name`string or nullrequired	Who is coming or came.
`contractor_phone`string or nullrequired	Their phone number, to call about the visit.
`project_id`string or nullrequired	The project it is for.
`project_title`string or nullrequired	The project it is for.
`assets`array of objectsrequired	Items it concerns.
`assets[].id`stringrequired	A asset ID, such as ast_01JC0000000000000000000000.
`assets[].address`string or nullrequired	No description.
`assets[].name`stringrequired	The item's name.
`issues`array of objectsrequired	Problems it looked at.
`issues[].id`stringrequired	A issue ID, such as iss_01JC0000000000000000000000.
`issues[].address`string or nullrequired	No description.
`issues[].title`stringrequired	The problem.
`issues[].severity`one of: low, medium, high, urgentrequired	How bad it is: low (cosmetic or minor), medium (needs fixing), high (getting worse or costly), urgent (safety, water or no heat).
`issues[].status`one of: open, monitoring, resolvedrequired	open (needs work), monitoring (watching a symptom), resolved (fixed or no longer a problem).
`open_tasks`array of objectsrequired	Active maintenance tasks of its items, soonest due first: what marking the visit done can check off.
`open_tasks[].id`stringrequired	The task's ID (mtk_…).
`open_tasks[].address`string or nullrequired	The web route that opens the task, when it has one.
`open_tasks[].title`stringrequired	The task's title.
`open_tasks[].importance`one of: essential, recommended, optionalrequired	How much it matters.
`open_tasks[].status`one of: active, offrequired	Whether the task is on or turned off.
`open_tasks[].next_due_on`string or nullrequired	When it is next due, YYYY-MM-DD, or null (a usage task with no date).
`open_tasks[].due_group`one of: overdue, due_soon, this_season, later, null or nullrequired	Overdue, due_soon (within 2 weeks), this_season or later; null for optional and turned-off tasks.
`open_tasks[].due_in_words`string or nullrequired	"Due in 5 days", "Overdue since Oct 3", "Open until Nov 15" or "Check"; null when off.
`open_tasks[].asset_name`string or nullrequired	The item it is for.
`completed_tasks`array of objectsrequired	Maintenance tasks this visit checked off.
`completed_tasks[].task_id`stringrequired	A maintenance task ID, such as mtk_01JC0000000000000000000000.
`completed_tasks[].address`string or nullrequired	No description.
`completed_tasks[].title`stringrequired	The task it checked off.
`completed_tasks[].done_on`stringrequired	YYYY-MM-DD.
`invoices`array of objectsrequired	Quotes and invoices for the visit.
`invoices[].id`stringrequired	A invoice ID, such as ivc_01JC0000000000000000000000.
`invoices[].kind`one of: quote, invoicerequired	No description.
`invoices[].number`string or nullrequired	No description.
`invoices[].currency`stringrequired	An ISO 4217 currency code, such as USD. pattern ^[A-Z]{3}$
`invoices[].total`integer or nullrequired	In minor units; null when the paper gave none.

Errors#

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

One contractor visit: 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.

Open a visit

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.visit.get?visit_id=vst_01M6V9CSYWPZZCJP1Q0PBTS1SF' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.visit.get?visit_id=vst_01M6V9CSYWPZZCJP1Q0PBTS1SF 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_01M6V9CT20529KPQJ431KY9TTY

{
  "id": "vst_01M6V9CSYWPZZCJP1Q0PBTS1SF",
  "address": "/maintenance/visits/vst_01M6V9CSYWPZZCJP1Q0PBTS1SF",
  "title": "Furnace inspection and tune-up",
  "status": "scheduled",
  "starts_at": "2026-11-19T15:00:00.000Z",
  "ends_at": "2026-11-19T17:00:00.000Z",
  "visited_on": null,
  "summary": null,
  "notes": "Ask about the igniter. Ben will be home.",
  "date": "2026-11-19",
  "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
  "contractor_id": "ctr_01M6V9CSWEFJH8CRZCXNAH8109",
  "contractor_name": "Smith Heating & Air",
  "contractor_phone": "555-0142",
  "project_id": null,
  "project_title": null,
  "assets": [
    {
      "id": "ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
      "address": "/maintenance/assets/ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
      "name": "Basement furnace"
    }
  ],
  "issues": [],
  "open_tasks": [
    {
      "id": "mtk_01M6V9CSWSHKH0MYE1RMRRDC58",
      "address": "/maintenance/tasks/mtk_01M6V9CSWSHKH0MYE1RMRRDC58",
      "title": "Annual furnace inspection",
      "importance": "essential",
      "status": "active",
      "next_due_on": "2026-11-19",
      "due_group": "due_soon",
      "due_in_words": "Due in 12 days",
      "asset_name": "Basement furnace"
    },
    {
      "id": "mtk_01M6V9CSWM1GKX8MAYQFYBAM3S",
      "address": "/maintenance/tasks/mtk_01M6V9CSWM1GKX8MAYQFYBAM3S",
      "title": "Replace the furnace filter",
      "importance": "essential",
      "status": "active",
      "next_due_on": "2027-02-06",
      "due_group": "later",
      "due_in_words": "Due Feb 6, 2027",
      "asset_name": "Basement furnace"
    }
  ],
  "completed_tasks": [],
  "invoices": []
}

Open a visit that happened

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.visit.get?visit_id=vst_01M6V9CSYM7MF5MW4XZSAPDX0R' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.visit.get?visit_id=vst_01M6V9CSYM7MF5MW4XZSAPDX0R 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_01M6V9CT24ZCWG49DT4ZTZ676J

{
  "id": "vst_01M6V9CSYM7MF5MW4XZSAPDX0R",
  "address": "/maintenance/visits/vst_01M6V9CSYM7MF5MW4XZSAPDX0R",
  "title": "Fix the kitchen sink drip",
  "status": "done",
  "starts_at": null,
  "ends_at": null,
  "visited_on": "2026-09-18",
  "summary": "Tightened the supply line nut and replaced the rubber washer. Dry since.",
  "notes": null,
  "date": "2026-09-18",
  "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
  "contractor_id": "ctr_01M6V9CSWHPNYAY4A5FBX3R14F",
  "contractor_name": "Riverbend Plumbing & Drain",
  "contractor_phone": "555-0178",
  "project_id": null,
  "project_title": null,
  "assets": [],
  "issues": [
    {
      "id": "iss_01M6V9CSYKEZQVSA56BB6PYXRV",
      "address": "/maintenance/issues/iss_01M6V9CSYKEZQVSA56BB6PYXRV",
      "title": "Slow drip under the kitchen sink",
      "severity": "medium",
      "status": "resolved"
    }
  ],
  "open_tasks": [],
  "completed_tasks": [],
  "invoices": [
    {
      "id": "ivc_01M6V9CSYRAE8F77HCCX98XB0M",
      "kind": "invoice",
      "number": "RB-3071",
      "currency": "USD",
      "total": 14500
    }
  ]
}

For Rigel#

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