Skip to content
Rigel docs
Open Rigel

One maintenance task in full

maintenance.task.get

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

  • Query
  • Rigel runs it

The task with its rule in words, next due date, last done, guidance, cost estimates, handling, parts, source and every completion, newest first. Fails with task_not_found.

Parameters#

One maintenance task in full: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

task_idquerystringrequired

The task.

Response#

200 The answer.

One maintenance task in full: response fields
FieldDescription
idstringrequired

A maintenance task ID, such as mtk_01JC0000000000000000000000.

titlestringrequired

What to do.

property_idstringrequired

A property ID, such as prp_01JC0000000000000000000000.

asset_idstring or nullrequired

The item it's for, or null.

location_idstring or nullrequired

The place it's for, or null.

subject_namestring or nullrequired

The name of the item or place it's for; null for a whole-home task.

importanceone of: essential, recommended, optionalrequired

essential (skipping it risks damage, safety, a voided warranty or an expensive repair; stays visible when overdue), recommended (meaningfully extends life or efficiency, and people actually do it), optional (nice to do; only on the asset page, never comes due).

statusone of: active, offrequired

off means turned off: kept, but never comes due.

off_reasonstring or nullrequired

Why it was turned off.

due_groupone of: overdue, due_soon, this_season, later, null or nullrequired

Where it goes in the list; null for tasks that aren't listed (turned off, optional, finished).

next_due_onstring or nullrequired

YYYY-MM-DD. For a seasonal task, the day its window opens. Null for a usage task without a date, a finished one-time task, or a task turned off.

due_in_wordsstringrequired

When it's due, for people: "Overdue since Oct 3", "Due in 5 days", "Check".

timing_in_wordsstringrequired

The rule for people: "Every 3 months", "Every year on Sep 15".

timing_kindone of: anchored, interval, seasonal, usage, oncerequired

How the task repeats: anchored (on a fixed day, such as every September 15, kept when done late; for warranties, certificates and habits like batteries at the clock change), interval (counted from when it was last done, such as every 3 months), seasonal (once in a window of the year, such as before the first frost), usage (when a reading or a check says so, such as every 100 hours), once (done for good once checked off).

last_done_onstring or nullrequired

The most recent completion, YYYY-MM-DD, or null if it was never done.

scheduled_onstring or nullrequired

The day someone planned to do it, if any.

handled_byone of: diy, hire, service, null or nullrequired

How the household handles it: diy (does it themselves), hire (calls someone), service (covered by a service plan).

handlingstring or nullrequired

The handling as a short tag: DIY, Hire or Service; null if unset.

handling_notestring or nullrequired

The household's plan for it.

contractor_idstring or nullrequired

A contractor ID, such as ctr_01JC0000000000000000000000.

contractor_namestring or nullrequired

The contractor who handles it.

summarystring or nullrequired

What it is.

whystring or nullrequired

What goes wrong if it's skipped.

timingobjectrequired

The task's rule, as stored.

timing.kindone of: anchored, interval, seasonal, usage, oncerequired

How the task repeats: anchored (on a fixed day, such as every September 15, kept when done late; for warranties, certificates and habits like batteries at the clock change), interval (counted from when it was last done, such as every 3 months), seasonal (once in a window of the year, such as before the first frost), usage (when a reading or a check says so, such as every 100 hours), once (done for good once checked off).

timing.interval_countinteger or nullrequired

For interval and anchored tasks: how many units between times.

timing.interval_unitone of: day, week, month, year, null or nullrequired

The unit of the interval: day, week, month or year.

timing.anchor_month_daystring or nullrequired

For anchored tasks: the anchor day, MM-DD.

timing.season_startstring or nullrequired

For seasonal tasks: when the window opens, MM-DD.

timing.season_endstring or nullrequired

For seasonal tasks: when the window closes, MM-DD. May be earlier in the year than the start.

timing.season_reasoningstring or nullrequired

Why the window is where it is.

timing.usage_rulestring or nullrequired

For usage tasks: when it's due, in words.

diy_stepsstring or nullrequired

Markdown steps for doing it yourself.

hire_guidancestring or nullrequired

Markdown: who to hire and what to ask for.

costobject or nullrequired

Cost ranges in minor units; null when there's no estimate.

cost.currencystringrequired

ISO 4217 code.

cost.diy_mininteger or nullrequiredNo description.
cost.diy_maxinteger or nullrequiredNo description.
cost.hire_mininteger or nullrequiredNo description.
cost.hire_maxinteger or nullrequiredNo description.
cost.basisstring or nullrequired

Where the estimate comes from.

assignee_person_idstring or nullrequired

Who usually does it.

assignee_namestring or nullrequiredNo description.
house_notesstring or nullrequiredNo description.
originone of: manufacturer, general, homeownerrequired

Where the task came from: manufacturer (the manual or maker), general (general guidance for this kind of thing), homeowner (someone in the household asked for it).

sourceobject or nullrequired

Where the task came from; null when none was recorded.

source.file_idstring or nullrequiredNo description.
source.urlstring or nullrequiredNo description.
source.said_by_person_idstring or nullrequiredNo description.
source.locatorstring or nullrequiredNo description.
source.excerptstring or nullrequiredNo description.
partsarray of objectsrequired

Parts and supplies it uses.

parts[].idstringrequired

A part ID, such as prt_01JC0000000000000000000000.

parts[].namestringrequiredNo description.
parts[].part_numberstring or nullrequiredNo description.
parts[].product_idstring or nullrequired

The inventory product it is, when linked: ask inventory.product.have whether there's a spare.

parts[].product_namestring or nullrequired

That product's name in the household's words.

completionsarray of objectsrequired

Every time it was done, newest first.

completions[].idstringrequired

A maintenance task completion ID, such as mtc_01JC0000000000000000000000.

completions[].done_onstringrequired

The day it was done, YYYY-MM-DD.

completions[].notestring or nullrequiredNo description.
completions[].costinteger or nullrequired

What it cost, in minor units of currency.

completions[].currencystring or nullrequiredNo description.
completions[].done_by_person_idstring or nullrequiredNo description.
completions[].done_by_namestring or nullrequired

Who did it: the household member or the contractor.

completions[].photo_file_idstring or nullrequiredNo description.
completions[].visit_idstring or nullrequired

The visit it was done during.

Errors#

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

One maintenance task in full: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404not_foundThe 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 maintenance task

Request, curl
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.task.get?task_id=mtk_01M6V9CSWM1GKX8MAYQFYBAM3S' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.task.get?task_id=mtk_01M6V9CSWM1GKX8MAYQFYBAM3S", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();
Request, HTTP
GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.task.get?task_id=mtk_01M6V9CSWM1GKX8MAYQFYBAM3S 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_01M6V9CT0VW97CH9CQ7XGFEYMN

{
  "id": "mtk_01M6V9CSWM1GKX8MAYQFYBAM3S",
  "title": "Replace the furnace filter",
  "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
  "asset_id": "ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
  "location_id": null,
  "subject_name": "Basement furnace",
  "importance": "essential",
  "status": "active",
  "off_reason": null,
  "due_group": "later",
  "next_due_on": "2027-02-06",
  "due_in_words": "Due Feb 6, 2027",
  "timing_in_words": "Every 3 months",
  "timing_kind": "interval",
  "last_done_on": "2026-11-06",
  "scheduled_on": null,
  "handled_by": "diy",
  "handling": "DIY",
  "handling_note": null,
  "contractor_id": null,
  "contractor_name": null,
  "summary": "Swap the 16x25x1 filter. The arrow points toward the furnace.",
  "why": "A clogged filter strains the blower and cuts airflow.",
  "timing": {
    "kind": "interval",
    "interval_count": 3,
    "interval_unit": "month",
    "anchor_month_day": null,
    "season_start": null,
    "season_end": null,
    "season_reasoning": null,
    "usage_rule": null
  },
  "diy_steps": "Switch the furnace off. Slide out the old filter, slide in the new one, and write the date on the frame.",
  "hire_guidance": null,
  "cost": {
    "currency": "USD",
    "diy_min": 1500,
    "diy_max": 3000,
    "hire_min": null,
    "hire_max": null,
    "basis": "A 4-pack lasts a year"
  },
  "assignee_person_id": "per_01M6V9CS744BQQH188FS6CXY9W",
  "assignee_name": "Ben Okafor",
  "house_notes": null,
  "origin": "manufacturer",
  "source": null,
  "parts": [
    {
      "id": "prt_01M6V9CSWCCK3TQDA78RGRZ2E2",
      "name": "Furnace filter 16x25x1",
      "part_number": "AF-1625-M11",
      "product_id": "prd_01M6V9CSWCK03ABGA7BSJA03Q1",
      "product_name": "Furnace filter 16x25x1"
    }
  ],
  "completions": [
    {
      "id": "mtc_01M6V9CSXX7N0X2QKSSW370DHG",
      "done_on": "2026-11-06",
      "note": "Bought a 4-pack. The old filter was grey.",
      "cost": 2499,
      "currency": "USD",
      "done_by_person_id": "per_01M6V9CS744BQQH188FS6CXY9W",
      "done_by_name": null,
      "photo_file_id": null,
      "visit_id": null
    },
    {
      "id": "mtc_01M6V9CSWM2KQTDJAY4PFXSQJB",
      "done_on": "2026-08-19",
      "note": null,
      "cost": null,
      "currency": null,
      "done_by_person_id": null,
      "done_by_name": null,
      "photo_file_id": null,
      "visit_id": null
    }
  ]
}

For Rigel#

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

Rigel is in early access, and sign-up is by invitation. Open Rigel