Maintenance tasks, grouped by when they're due

maintenance.task.list

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

Query
Rigel runs it

Active, non-optional tasks in four groups, in this order: Overdue, Due in the next 2 weeks, This season, Later (usage tasks without a date are in Later, shown as Check). Narrow it to a property, an item or a place. Optional tasks and tasks turned off are left out unless asked for; they come back in not_listed. Finished one-time tasks are only in history.

Parameters#

Maintenance tasks, grouped by when they're due: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`property_id`querystringoptional	Only this property's tasks.
`asset_id`querystringoptional	Only this item's tasks.
`location_id`querystringoptional	Only the tasks for this place (not for the items in it).
`include_optional`queryboolean or stringoptional	Also list optional tasks, which never come due. Defaults to false.
`include_off`queryboolean or stringoptional	Also list tasks that are turned off. Defaults to false.

Response#

200 The answer.

Maintenance tasks, grouped by when they're due: response fields
Field	Description
`today`stringrequired	The household's date, YYYY-MM-DD, that the groups are worked out against.
`groups`array of objectsrequired	All four groups, in order, empty ones included.
`groups[].group`one of: overdue, due_soon, this_season, laterrequired	overdue (the date has passed, or a seasonal window has closed), due_soon (due within 14 days or a seasonal window is open), this_season (due before the season ends), later.
`groups[].title`stringrequired	The group's heading.
`groups[].tasks`array of objectsrequired	Earliest due first.
`groups[].tasks[].id`stringrequired	A maintenance task ID, such as mtk_01JC0000000000000000000000.
`groups[].tasks[].title`stringrequired	What to do.
`groups[].tasks[].property_id`stringrequired	A property ID, such as prp_01JC0000000000000000000000.
`groups[].tasks[].asset_id`string or nullrequired	The item it's for, or null.
`groups[].tasks[].location_id`string or nullrequired	The place it's for, or null.
`groups[].tasks[].subject_name`string or nullrequired	The name of the item or place it's for; null for a whole-home task.
`groups[].tasks[].importance`one 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).
`groups[].tasks[].status`one of: active, offrequired	off means turned off: kept, but never comes due.
`groups[].tasks[].off_reason`string or nullrequired	Why it was turned off.
`groups[].tasks[].due_group`one 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).
`groups[].tasks[].next_due_on`string 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.
`groups[].tasks[].due_in_words`stringrequired	When it's due, for people: "Overdue since Oct 3", "Due in 5 days", "Check".
`groups[].tasks[].timing_in_words`stringrequired	The rule for people: "Every 3 months", "Every year on Sep 15".
`groups[].tasks[].timing_kind`one 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).
`groups[].tasks[].last_done_on`string or nullrequired	The most recent completion, YYYY-MM-DD, or null if it was never done.
`groups[].tasks[].scheduled_on`string or nullrequired	The day someone planned to do it, if any.
`groups[].tasks[].handled_by`one 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).
`groups[].tasks[].handling`string or nullrequired	The handling as a short tag: DIY, Hire or Service; null if unset.
`groups[].tasks[].handling_note`string or nullrequired	The household's plan for it.
`groups[].tasks[].contractor_id`string or nullrequired	A contractor ID, such as ctr_01JC0000000000000000000000.
`groups[].tasks[].contractor_name`string or nullrequired	The contractor who handles it.
`not_listed`array of objectsrequired	Optional and turned-off tasks, when asked for.
`not_listed[].id`stringrequired	A maintenance task ID, such as mtk_01JC0000000000000000000000.
`not_listed[].title`stringrequired	What to do.
`not_listed[].property_id`stringrequired	A property ID, such as prp_01JC0000000000000000000000.
`not_listed[].asset_id`string or nullrequired	The item it's for, or null.
`not_listed[].location_id`string or nullrequired	The place it's for, or null.
`not_listed[].subject_name`string or nullrequired	The name of the item or place it's for; null for a whole-home task.
`not_listed[].importance`one 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).
`not_listed[].status`one of: active, offrequired	off means turned off: kept, but never comes due.
`not_listed[].off_reason`string or nullrequired	Why it was turned off.
`not_listed[].due_group`one 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).
`not_listed[].next_due_on`string 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.
`not_listed[].due_in_words`stringrequired	When it's due, for people: "Overdue since Oct 3", "Due in 5 days", "Check".
`not_listed[].timing_in_words`stringrequired	The rule for people: "Every 3 months", "Every year on Sep 15".
`not_listed[].timing_kind`one 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).
`not_listed[].last_done_on`string or nullrequired	The most recent completion, YYYY-MM-DD, or null if it was never done.
`not_listed[].scheduled_on`string or nullrequired	The day someone planned to do it, if any.
`not_listed[].handled_by`one 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).
`not_listed[].handling`string or nullrequired	The handling as a short tag: DIY, Hire or Service; null if unset.
`not_listed[].handling_note`string or nullrequired	The household's plan for it.
`not_listed[].contractor_id`string or nullrequired	A contractor ID, such as ctr_01JC0000000000000000000000.
`not_listed[].contractor_name`string or nullrequired	The contractor who handles it.

Errors#

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

Maintenance tasks, grouped by when they're due: 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.

What maintenance is coming up

Request, curl

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

Request, TypeScript

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

Request, HTTP

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

{
  "today": "2026-11-07",
  "groups": [
    {
      "group": "overdue",
      "title": "Overdue",
      "tasks": [
        {
          "id": "mtk_01M6V9CSX5S6WYB5HV2YGMA0FD",
          "title": "Clean the dryer vent",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": "ast_01M6V9CSVKPYARY331YY06WH85",
          "location_id": null,
          "subject_name": "Dryer",
          "importance": "essential",
          "status": "active",
          "off_reason": null,
          "due_group": "overdue",
          "next_due_on": "2026-10-23",
          "due_in_words": "Overdue since Oct 23",
          "timing_in_words": "Every year",
          "timing_kind": "interval",
          "last_done_on": "2025-10-23",
          "scheduled_on": null,
          "handled_by": "diy",
          "handling": "DIY",
          "handling_note": null,
          "contractor_id": null,
          "contractor_name": null
        }
      ]
    },
    {
      "group": "due_soon",
      "title": "Due in the next 2 weeks",
      "tasks": [
        {
          "id": "mtk_01M6V9CSWXXCGQMAC702FF72JQ",
          "title": "Clean the gutters",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": null,
          "location_id": null,
          "subject_name": null,
          "importance": "recommended",
          "status": "active",
          "off_reason": null,
          "due_group": "due_soon",
          "next_due_on": "2026-10-25",
          "due_in_words": "Open until Dec 5",
          "timing_in_words": "Each year between Oct 25 and Dec 5",
          "timing_kind": "seasonal",
          "last_done_on": null,
          "scheduled_on": null,
          "handled_by": "diy",
          "handling": "DIY",
          "handling_note": null,
          "contractor_id": null,
          "contractor_name": null
        },
        {
          "id": "mtk_01M6V9CSWSHKH0MYE1RMRRDC58",
          "title": "Annual furnace inspection",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": "ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
          "location_id": null,
          "subject_name": "Basement furnace",
          "importance": "essential",
          "status": "active",
          "off_reason": null,
          "due_group": "due_soon",
          "next_due_on": "2026-11-19",
          "due_in_words": "Due in 12 days",
          "timing_in_words": "Every year",
          "timing_kind": "interval",
          "last_done_on": null,
          "scheduled_on": null,
          "handled_by": "hire",
          "handling": "Hire",
          "handling_note": null,
          "contractor_id": "ctr_01M6V9CSWEFJH8CRZCXNAH8109",
          "contractor_name": "Smith Heating & Air"
        }
      ]
    },
    {
      "group": "this_season",
      "title": "This season",
      "tasks": []
    },
    {
      "group": "later",
      "title": "Later",
      "tasks": [
        {
          "id": "mtk_01M6V9CSX1RN5MWBHS4SJAK8F3",
          "title": "Test the smoke alarms",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": "ast_01M6V9CSVNY4PN710B9NWNSNVT",
          "location_id": null,
          "subject_name": "Smoke alarms",
          "importance": "essential",
          "status": "active",
          "off_reason": null,
          "due_group": "later",
          "next_due_on": "2026-12-07",
          "due_in_words": "Due Dec 7",
          "timing_in_words": "Every month",
          "timing_kind": "interval",
          "last_done_on": "2026-11-07",
          "scheduled_on": null,
          "handled_by": "diy",
          "handling": "DIY",
          "handling_note": null,
          "contractor_id": null,
          "contractor_name": null
        },
        {
          "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
        },
        {
          "id": "mtk_01M6V9CSXBS5X8WTT5WMDY9GYD",
          "title": "Drain the outdoor faucets",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": null,
          "location_id": null,
          "subject_name": null,
          "importance": "recommended",
          "status": "active",
          "off_reason": null,
          "due_group": "later",
          "next_due_on": "2027-10-15",
          "due_in_words": "Opens Oct 15, 2027",
          "timing_in_words": "Each year between Oct 15 and Nov 15",
          "timing_kind": "seasonal",
          "last_done_on": null,
          "scheduled_on": null,
          "handled_by": "diy",
          "handling": "DIY",
          "handling_note": null,
          "contractor_id": null,
          "contractor_name": null
        }
      ]
    }
  ],
  "not_listed": []
}

Maintenance for one item

Request, curl

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

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.task.list?asset_id=ast_01M6V9CSVCMZFAP6ZN5WANZ6M8 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_01M6V9CT0RC410GE2GQF708GQ1

{
  "today": "2026-11-07",
  "groups": [
    {
      "group": "overdue",
      "title": "Overdue",
      "tasks": []
    },
    {
      "group": "due_soon",
      "title": "Due in the next 2 weeks",
      "tasks": [
        {
          "id": "mtk_01M6V9CSWSHKH0MYE1RMRRDC58",
          "title": "Annual furnace inspection",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": "ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
          "location_id": null,
          "subject_name": "Basement furnace",
          "importance": "essential",
          "status": "active",
          "off_reason": null,
          "due_group": "due_soon",
          "next_due_on": "2026-11-19",
          "due_in_words": "Due in 12 days",
          "timing_in_words": "Every year",
          "timing_kind": "interval",
          "last_done_on": null,
          "scheduled_on": null,
          "handled_by": "hire",
          "handling": "Hire",
          "handling_note": null,
          "contractor_id": "ctr_01M6V9CSWEFJH8CRZCXNAH8109",
          "contractor_name": "Smith Heating & Air"
        }
      ]
    },
    {
      "group": "this_season",
      "title": "This season",
      "tasks": []
    },
    {
      "group": "later",
      "title": "Later",
      "tasks": [
        {
          "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
        }
      ]
    }
  ],
  "not_listed": []
}

List optional and turned-off tasks too

They come back in the groups instead of not_listed.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.task.list?include_optional=true&include_off=true' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/maintenance.task.list?include_optional=true&include_off=true 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_01M6V9CT0T2ZX687Z7KX66SRX2

{
  "today": "2026-11-07",
  "groups": [
    {
      "group": "overdue",
      "title": "Overdue",
      "tasks": [
        {
          "id": "mtk_01M6V9CSX5S6WYB5HV2YGMA0FD",
          "title": "Clean the dryer vent",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": "ast_01M6V9CSVKPYARY331YY06WH85",
          "location_id": null,
          "subject_name": "Dryer",
          "importance": "essential",
          "status": "active",
          "off_reason": null,
          "due_group": "overdue",
          "next_due_on": "2026-10-23",
          "due_in_words": "Overdue since Oct 23",
          "timing_in_words": "Every year",
          "timing_kind": "interval",
          "last_done_on": "2025-10-23",
          "scheduled_on": null,
          "handled_by": "diy",
          "handling": "DIY",
          "handling_note": null,
          "contractor_id": null,
          "contractor_name": null
        }
      ]
    },
    {
      "group": "due_soon",
      "title": "Due in the next 2 weeks",
      "tasks": [
        {
          "id": "mtk_01M6V9CSWXXCGQMAC702FF72JQ",
          "title": "Clean the gutters",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": null,
          "location_id": null,
          "subject_name": null,
          "importance": "recommended",
          "status": "active",
          "off_reason": null,
          "due_group": "due_soon",
          "next_due_on": "2026-10-25",
          "due_in_words": "Open until Dec 5",
          "timing_in_words": "Each year between Oct 25 and Dec 5",
          "timing_kind": "seasonal",
          "last_done_on": null,
          "scheduled_on": null,
          "handled_by": "diy",
          "handling": "DIY",
          "handling_note": null,
          "contractor_id": null,
          "contractor_name": null
        },
        {
          "id": "mtk_01M6V9CSWSHKH0MYE1RMRRDC58",
          "title": "Annual furnace inspection",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": "ast_01M6V9CSVCMZFAP6ZN5WANZ6M8",
          "location_id": null,
          "subject_name": "Basement furnace",
          "importance": "essential",
          "status": "active",
          "off_reason": null,
          "due_group": "due_soon",
          "next_due_on": "2026-11-19",
          "due_in_words": "Due in 12 days",
          "timing_in_words": "Every year",
          "timing_kind": "interval",
          "last_done_on": null,
          "scheduled_on": null,
          "handled_by": "hire",
          "handling": "Hire",
          "handling_note": null,
          "contractor_id": "ctr_01M6V9CSWEFJH8CRZCXNAH8109",
          "contractor_name": "Smith Heating & Air"
        }
      ]
    },
    {
      "group": "this_season",
      "title": "This season",
      "tasks": []
    },
    {
      "group": "later",
      "title": "Later",
      "tasks": [
        {
          "id": "mtk_01M6V9CSX1RN5MWBHS4SJAK8F3",
          "title": "Test the smoke alarms",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": "ast_01M6V9CSVNY4PN710B9NWNSNVT",
          "location_id": null,
          "subject_name": "Smoke alarms",
          "importance": "essential",
          "status": "active",
          "off_reason": null,
          "due_group": "later",
          "next_due_on": "2026-12-07",
          "due_in_words": "Due Dec 7",
          "timing_in_words": "Every month",
          "timing_kind": "interval",
          "last_done_on": "2026-11-07",
          "scheduled_on": null,
          "handled_by": "diy",
          "handling": "DIY",
          "handling_note": null,
          "contractor_id": null,
          "contractor_name": null
        },
        {
          "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
        },
        {
          "id": "mtk_01M6V9CSXBS5X8WTT5WMDY9GYD",
          "title": "Drain the outdoor faucets",
          "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
          "asset_id": null,
          "location_id": null,
          "subject_name": null,
          "importance": "recommended",
          "status": "active",
          "off_reason": null,
          "due_group": "later",
          "next_due_on": "2027-10-15",
          "due_in_words": "Opens Oct 15, 2027",
          "timing_in_words": "Each year between Oct 15 and Nov 15",
          "timing_kind": "seasonal",
          "last_done_on": null,
          "scheduled_on": null,
          "handled_by": "diy",
          "handling": "DIY",
          "handling_note": null,
          "contractor_id": null,
          "contractor_name": null
        }
      ]
    }
  ],
  "not_listed": [
    {
      "id": "mtk_01M6V9CSX9NQR7S63YXVAJ5EQV",
      "title": "Run a descaling cycle",
      "property_id": "prp_01M6V9CSTXS6P4CG6RNTNT60FA",
      "asset_id": "ast_01M6V9CSVH77630WV0WA1X2DAK",
      "location_id": null,
      "subject_name": "Dishwasher",
      "importance": "optional",
      "status": "off",
      "off_reason": "The dishwasher has a self-cleaning filter.",
      "due_group": null,
      "next_due_on": null,
      "due_in_words": "Turned off",
      "timing_in_words": "Every 6 months",
      "timing_kind": "interval",
      "last_done_on": null,
      "scheduled_on": null,
      "handled_by": "diy",
      "handling": "DIY",
      "handling_note": null,
      "contractor_id": null,
      "contractor_name": null
    }
  ]
}

For Rigel#

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