Mark an item as gone or replaced

maintenance.asset.retire

POST/api/v1/households/{household_id}/commands/maintenance.asset.retire

Command
Rigel runs it
Applies offline

The item is gone or has been replaced. It keeps its history. Its active maintenance tasks are turned off with the reason "Retired" and their open Tasks-app tasks are closed. replaced_by_asset_id links the replacement, which must be another item at the same property. Errors: already_retired.

Parameters#

Mark an item as gone or replaced: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`Idempotency-Key`headerstringoptional	The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Mark an item as gone or replaced: request body fields
Field	Description
`asset_id`stringrequired	A asset ID, such as ast_01JC0000000000000000000000.
`retired_on`string (date)optional	When it was retired, YYYY-MM-DD. Defaults to today.
`replaced_by_asset_id`stringoptional	The item that replaced it, at the same property.

Response#

200 The command was applied.

Mark an item as gone or replaced: response fields
Field	Description
`result`objectrequired	What the command returned, such as the IDs it created.
`version`integerrequired	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.

Mark an item as gone or replaced: 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`	`asset_not_found`	A replacement that isn't there.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	`already_retired`	Already retired.
`409`	`replacement_is_self`	Can't replace itself.
`409`	`different_property`	A replacement at another property.
`409`	`idempotency_key_reused`	The 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.

Retires today with its tasks turned off and the replacement linked

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "replaced_by_asset_id": "ast_01JC0000000000000000000002"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    asset_id: "ast_01JC0000000000000000000001",
    replaced_by_asset_id: "ast_01JC0000000000000000000002",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "asset_id": "ast_01JC0000000000000000000001",
  "replaced_by_asset_id": "ast_01JC0000000000000000000002"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0P92HR5R97PEKQ9XC

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

Today is the household's local date, not UTC's

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    asset_id: "ast_01JC0000000000000000000001",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "asset_id": "ast_01JC0000000000000000000001"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R05JTW5TDSPY8T0Q03

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

A given date

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "retired_on": "2024-02-29"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    asset_id: "ast_01JC0000000000000000000001",
    retired_on: "2024-02-29",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "asset_id": "ast_01JC0000000000000000000001",
  "retired_on": "2024-02-29"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0EAG3NVGC7V0N1MS8

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

Already retired

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    asset_id: "ast_01JC0000000000000000000001",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "asset_id": "ast_01JC0000000000000000000001"
}

Response, 409

HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0Z9A5GDPPE7QZGNYS

{
  "error": {
    "code": "already_retired",
    "message": "That item is already retired. No changes were applied.",
    "details": {
      "retired_on": "2024-01-01"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0Z9A5GDPPE7QZGNYS"
  }
}

Can't replace itself

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "replaced_by_asset_id": "ast_01JC0000000000000000000001"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    asset_id: "ast_01JC0000000000000000000001",
    replaced_by_asset_id: "ast_01JC0000000000000000000001",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "asset_id": "ast_01JC0000000000000000000001",
  "replaced_by_asset_id": "ast_01JC0000000000000000000001"
}

Response, 409

HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0WR11N94TQHA2EV91

{
  "error": {
    "code": "replacement_is_self",
    "message": "An item can't replace itself. No changes were applied.",
    "details": {},
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0WR11N94TQHA2EV91"
  }
}

A replacement at another property

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "replaced_by_asset_id": "ast_01JC0000000000000000000002"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    asset_id: "ast_01JC0000000000000000000001",
    replaced_by_asset_id: "ast_01JC0000000000000000000002",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "asset_id": "ast_01JC0000000000000000000001",
  "replaced_by_asset_id": "ast_01JC0000000000000000000002"
}

Response, 409

HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0XZK16PMARXSF64QM

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

A replacement that isn't there

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "replaced_by_asset_id": "ast_01JC0000000000000000000002"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    asset_id: "ast_01JC0000000000000000000001",
    replaced_by_asset_id: "ast_01JC0000000000000000000002",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.asset.retire HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "asset_id": "ast_01JC0000000000000000000001",
  "replaced_by_asset_id": "ast_01JC0000000000000000000002"
}

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0M533QGW13C2AVXMX

{
  "error": {
    "code": "asset_not_found",
    "message": "That item isn't in the house records any more. No changes were applied.",
    "details": {
      "asset_id": "ast_01JC0000000000000000000002"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0M533QGW13C2AVXMX"
  }
}

Retire an item that was replaced

The old item keeps its history. Its tasks are turned off.

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/maintenance.asset.retire' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CSZPAVQM3C71JD41MP75' \
  -d '{
  "asset_id": "ast_01M6V9CSVPKQEST2JSGBYP0KJQ",
  "retired_on": "2026-10-18",
  "replaced_by_asset_id": "ast_01M6V9CSVR6DNGA62713A0QSFA"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/maintenance.asset.retire", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CSZPAVQM3C71JD41MP75",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    asset_id: "ast_01M6V9CSVPKQEST2JSGBYP0KJQ",
    retired_on: "2026-10-18",
    replaced_by_asset_id: "ast_01M6V9CSVR6DNGA62713A0QSFA",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/maintenance.asset.retire HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CSZPAVQM3C71JD41MP75

{
  "asset_id": "ast_01M6V9CSVPKQEST2JSGBYP0KJQ",
  "retired_on": "2026-10-18",
  "replaced_by_asset_id": "ast_01M6V9CSVR6DNGA62713A0QSFA"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSZPZHJXGAJ99AT65BQH

{
  "result": {},
  "version": 226
}

For Rigel#

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