Skip to content
Rigel docs
Open Rigel

Record a visit that already happened

maintenance.visit.record

POST/api/v1/households/{household_id}/commands/maintenance.visit.record

  • Command
  • Rigel runs it
  • Applies offline

Creates a visit that is already done, in one go, with the same effects as maintenance.visit.complete: each task in completes_task_ids is checked off on visited_on by the contractor, and each problem in resolves_issue_ids is resolved with the summary. Without property_id, the property comes from the linked items, problems or project. Everything linked must be at the same property (different_property).

Parameters#

Record a visit that already happened: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

Idempotency-Keyheaderstringoptional

The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Record a visit that already happened: request body fields
FieldDescription
property_idstringoptional

Which property. Leave it out when the household has one property (it's made on first use); with several, give it, or the command is rejected with property_required.

contractor_idstringoptional

Who came.

titlestringrequired

What the visit is for, such as Annual furnace service.

at most 200 characters
visited_onstring (date)required

The day the work happened.

summarystringoptional

What was done.

at most 20,000 characters
asset_idsarray of stringsoptional

The items the visit concerns.

at most 100 items
issue_idsarray of stringsoptional

The problems the visit looked at.

at most 100 items
project_idstringoptional

The project this visit is part of.

notesstringoptional

Anything else worth keeping.

at most 20,000 characters
completes_task_idsarray of stringsoptional

Maintenance tasks the work did. Each is checked off on the visit date, by the visit's contractor, and its next due date moves on.

at most 100 items
resolves_issue_idsarray of stringsoptional

Problems the work fixed. Each is marked resolved with the visit summary as how.

at most 100 items

Response#

200 The command was applied.

Record a visit that already happened: response fields
FieldDescription
resultobjectrequired

What the command returned, such as the IDs it created.

result.visit_idstringrequired

The new visit.

versionintegerrequired

The household version after the command.

Errors#

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

Record a visit that already happened: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404task_not_foundA task that isn't there.
404contractor_not_foundA contractor that isn't there.
404not_foundThe household doesn't exist, or you aren't a member of it.
409different_property
  • An item at another property.
  • A problem to resolve at another property.
409idempotency_key_reusedThe Idempotency-Key was already used for a different command.

Examples#

These are real. Each scenario is one of the command's test cases, run on a household when this site was built, and the response is what the API returned.

A visit that already happened

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "contractor_id": "ctr_01JC00000000000000000000K1",
  "title": "Furnace tune-up",
  "visited_on": "2025-10-20",
  "summary": "All good",
  "asset_ids": [
    "ast_01JC00000000000000000000A1"
  ],
  "project_id": "mpj_01JC00000000000000000000J1",
  "notes": "Paid cash"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    contractor_id: "ctr_01JC00000000000000000000K1",
    title: "Furnace tune-up",
    visited_on: "2025-10-20",
    summary: "All good",
    asset_ids: [
      "ast_01JC00000000000000000000A1",
    ],
    project_id: "mpj_01JC00000000000000000000J1",
    notes: "Paid cash",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "contractor_id": "ctr_01JC00000000000000000000K1",
  "title": "Furnace tune-up",
  "visited_on": "2025-10-20",
  "summary": "All good",
  "asset_ids": [
    "ast_01JC00000000000000000000A1"
  ],
  "project_id": "mpj_01JC00000000000000000000J1",
  "notes": "Paid cash"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0ATBM4T41M6SCR7AF

{
  "result": {
    "visit_id": "vst_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

Resolves problems in the same go

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "title": "Fixed the leak",
  "visited_on": "2025-11-03",
  "summary": "New trap",
  "issue_ids": [
    "iss_01JC00000000000000000000Q1"
  ],
  "resolves_issue_ids": [
    "iss_01JC00000000000000000000Q1",
    "iss_01JC00000000000000000000Q2"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    title: "Fixed the leak",
    visited_on: "2025-11-03",
    summary: "New trap",
    issue_ids: [
      "iss_01JC00000000000000000000Q1",
    ],
    resolves_issue_ids: [
      "iss_01JC00000000000000000000Q1",
      "iss_01JC00000000000000000000Q2",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "title": "Fixed the leak",
  "visited_on": "2025-11-03",
  "summary": "New trap",
  "issue_ids": [
    "iss_01JC00000000000000000000Q1"
  ],
  "resolves_issue_ids": [
    "iss_01JC00000000000000000000Q1",
    "iss_01JC00000000000000000000Q2"
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0196QWETPT1RN8BGR

{
  "result": {
    "visit_id": "vst_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

The property is made on first use

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "title": "Mowed",
  "visited_on": "2025-11-03"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    title: "Mowed",
    visited_on: "2025-11-03",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "title": "Mowed",
  "visited_on": "2025-11-03"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R038ZYDREWJR88NBFJ

{
  "result": {
    "visit_id": "vst_01JC4N0000JVP6PWJ6S8P7WZ6B"
  },
  "version": 1
}

Checks off a task in the same go

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "contractor_id": "ctr_01JC00000000000000000000K1",
  "title": "Filter",
  "visited_on": "2025-11-05",
  "completes_task_ids": [
    "mtk_01JC00000000000000000000T1"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    contractor_id: "ctr_01JC00000000000000000000K1",
    title: "Filter",
    visited_on: "2025-11-05",
    completes_task_ids: [
      "mtk_01JC00000000000000000000T1",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "contractor_id": "ctr_01JC00000000000000000000K1",
  "title": "Filter",
  "visited_on": "2025-11-05",
  "completes_task_ids": [
    "mtk_01JC00000000000000000000T1"
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0ZSVBKE8P9FZ5XW1W

{
  "result": {
    "visit_id": "vst_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

An item at another property

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "property_id": "prp_01JC00000000000000000000P1",
  "title": "x",
  "visited_on": "2025-11-03",
  "asset_ids": [
    "ast_01JC00000000000000000000A2"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    property_id: "prp_01JC00000000000000000000P1",
    title: "x",
    visited_on: "2025-11-03",
    asset_ids: [
      "ast_01JC00000000000000000000A2",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "property_id": "prp_01JC00000000000000000000P1",
  "title": "x",
  "visited_on": "2025-11-03",
  "asset_ids": [
    "ast_01JC00000000000000000000A2"
  ]
}
Response, 409
HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0RME6NMZ8Y55VJ2XQ

{
  "error": {
    "code": "different_property",
    "message": "That item is at a different property. No changes were applied.",
    "details": {
      "property_id": "prp_01JC00000000000000000000P2"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0RME6NMZ8Y55VJ2XQ"
  }
}

A problem to resolve at another property

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "property_id": "prp_01JC00000000000000000000P1",
  "title": "x",
  "visited_on": "2025-11-03",
  "resolves_issue_ids": [
    "iss_01JC00000000000000000000Q2"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    property_id: "prp_01JC00000000000000000000P1",
    title: "x",
    visited_on: "2025-11-03",
    resolves_issue_ids: [
      "iss_01JC00000000000000000000Q2",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "property_id": "prp_01JC00000000000000000000P1",
  "title": "x",
  "visited_on": "2025-11-03",
  "resolves_issue_ids": [
    "iss_01JC00000000000000000000Q2"
  ]
}
Response, 409
HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0ZMHRT703MNYXEDP8

{
  "error": {
    "code": "different_property",
    "message": "That problem is at a different property. No changes were applied.",
    "details": {
      "property_id": "prp_01JC00000000000000000000P2"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0ZMHRT703MNYXEDP8"
  }
}

A task that isn't there

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "property_id": "prp_01JC00000000000000000000P1",
  "title": "x",
  "visited_on": "2025-11-03",
  "completes_task_ids": [
    "mtk_01JC00000000000000000000TX"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    property_id: "prp_01JC00000000000000000000P1",
    title: "x",
    visited_on: "2025-11-03",
    completes_task_ids: [
      "mtk_01JC00000000000000000000TX",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "property_id": "prp_01JC00000000000000000000P1",
  "title": "x",
  "visited_on": "2025-11-03",
  "completes_task_ids": [
    "mtk_01JC00000000000000000000TX"
  ]
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0B0WMP2PJC21Z9EYX

{
  "error": {
    "code": "task_not_found",
    "message": "That maintenance task isn't there any more. No changes were applied.",
    "details": {
      "task_id": "mtk_01JC00000000000000000000TX"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0B0WMP2PJC21Z9EYX"
  }
}

A contractor that isn't there

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "property_id": "prp_01JC00000000000000000000P1",
  "title": "x",
  "visited_on": "2025-11-03",
  "contractor_id": "ctr_01JC00000000000000000000K1"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    property_id: "prp_01JC00000000000000000000P1",
    title: "x",
    visited_on: "2025-11-03",
    contractor_id: "ctr_01JC00000000000000000000K1",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "property_id": "prp_01JC00000000000000000000P1",
  "title": "x",
  "visited_on": "2025-11-03",
  "contractor_id": "ctr_01JC00000000000000000000K1"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0PQZDYCZRQ62EBEWF

{
  "error": {
    "code": "contractor_not_found",
    "message": "That contractor isn't there any more. No changes were applied.",
    "details": {
      "contractor_id": "ctr_01JC00000000000000000000K1"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0PQZDYCZRQ62EBEWF"
  }
}

Record a visit that already happened

resolves_issue_ids resolves each problem, with the visit's summary as how it was fixed.

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/maintenance.visit.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CSYM59Q0A9SXSP91YSEJ' \
  -d '{
  "contractor_id": "ctr_01M6V9CSWHPNYAY4A5FBX3R14F",
  "title": "Fix the kitchen sink drip",
  "visited_on": "2026-09-18",
  "summary": "Tightened the supply line nut and replaced the rubber washer. Dry since.",
  "issue_ids": [
    "iss_01M6V9CSYKEZQVSA56BB6PYXRV"
  ],
  "resolves_issue_ids": [
    "iss_01M6V9CSYKEZQVSA56BB6PYXRV"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/maintenance.visit.record", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CSYM59Q0A9SXSP91YSEJ",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    contractor_id: "ctr_01M6V9CSWHPNYAY4A5FBX3R14F",
    title: "Fix the kitchen sink drip",
    visited_on: "2026-09-18",
    summary: "Tightened the supply line nut and replaced the rubber washer. Dry since.",
    issue_ids: [
      "iss_01M6V9CSYKEZQVSA56BB6PYXRV",
    ],
    resolves_issue_ids: [
      "iss_01M6V9CSYKEZQVSA56BB6PYXRV",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/maintenance.visit.record HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CSYM59Q0A9SXSP91YSEJ

{
  "contractor_id": "ctr_01M6V9CSWHPNYAY4A5FBX3R14F",
  "title": "Fix the kitchen sink drip",
  "visited_on": "2026-09-18",
  "summary": "Tightened the supply line nut and replaced the rubber washer. Dry since.",
  "issue_ids": [
    "iss_01M6V9CSYKEZQVSA56BB6PYXRV"
  ],
  "resolves_issue_ids": [
    "iss_01M6V9CSYKEZQVSA56BB6PYXRV"
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSYMHHB78229TD0AD3NN

{
  "result": {
    "visit_id": "vst_01M6V9CSYM7MF5MW4XZSAPDX0R"
  },
  "version": 216
}

For Rigel#

Rigel's tool for this command is maintenance_visit_record. 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