Save what reading a label found

maintenance.identification.record

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

Command
Rigel runs it
Applies offline

Saves one reading of an item's label or photo, with its evidence. The likeliest model (manufacturer and model_number) is linked only if the item has no model yet, and then the item becomes identified (unless Rigel is looking it up, which settles that when it finishes); the serial is filled only if the item has none; the item moves to category_key only while it is "Not identified yet". Nothing the household already entered is overwritten. alternatives are other model numbers the reading could be, likeliest first, kept for "that's the wrong model".

Parameters#

Save what reading a label found: 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.

Save what reading a label found: request body fields
Field	Description
`asset_id`stringrequired	A asset ID, such as ast_01JC0000000000000000000000.
`evidence`objectrequired	What was read: the label photo, with the text read from it.
`evidence.file_id`stringoptional	A photo, manual or invoice already uploaded to the household's files.
`evidence.url`string (uri)optional	A web address. at most 2,000 characters
`evidence.said_by_person_id`stringoptional	Who said it, when the source is something a person said.
`evidence.locator`stringoptional	Where in the source: "p. 14", "rating plate". at most 200 characters
`evidence.excerpt`stringoptional	The exact text the value was read from. at most 2,000 characters
`manufacturer`stringoptional	The maker as printed on the label, such as Carrier. Case is kept. at most 120 characters
`model_number`stringoptional	The complete model number exactly as printed, with every suffix and letter case. Never shorten it. at most 120 characters
`serial`stringoptional	The serial number exactly as printed on the label. at most 120 characters
`category_key`stringoptional	The curated category key this looks like, such as furnace. A key Rigel doesn't know is kept but not used.
`alternatives`array of stringsoptional	Other model numbers the reading could be, likeliest first. at most 10 items

Response#

200 The command was applied.

Save what reading a label found: response fields
Field	Description
`result`objectrequired	What the command returned, such as the IDs it created.
`result.identification_id`stringrequired	The saved reading.
`result.model_id`string or nullrequired	The model the item was linked to by this reading, if it was.
`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.

Save what reading a label found: 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`	An item that isn't there.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`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.

Links the model, fills the serial, moves the category and keeps the alternatives (with a file)

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "file_id": "fil_01JC0000000000000000000001",
    "locator": "rating plate",
    "excerpt": "MODEL 59TP6B080M1714 SER 1234"
  },
  "manufacturer": "Carrier",
  "model_number": "59TP6B080M1714",
  "serial": "1234",
  "category_key": "furnace",
  "alternatives": [
    "59TP6B080M1715",
    "59TP6B060M1714"
  ]
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record", {
  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",
    evidence: {
      file_id: "fil_01JC0000000000000000000001",
      locator: "rating plate",
      excerpt: "MODEL 59TP6B080M1714 SER 1234",
    },
    manufacturer: "Carrier",
    model_number: "59TP6B080M1714",
    serial: "1234",
    category_key: "furnace",
    alternatives: [
      "59TP6B080M1715",
      "59TP6B060M1714",
    ],
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "file_id": "fil_01JC0000000000000000000001",
    "locator": "rating plate",
    "excerpt": "MODEL 59TP6B080M1714 SER 1234"
  },
  "manufacturer": "Carrier",
  "model_number": "59TP6B080M1714",
  "serial": "1234",
  "category_key": "furnace",
  "alternatives": [
    "59TP6B080M1715",
    "59TP6B060M1714"
  ]
}

Response, 200

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

{
  "result": {
    "identification_id": "idn_01JC4N0000VGW1STJ6TGXRB7FY",
    "model_id": "eqm_01JC4N0000JVP6PWJ6S8P7WZ6B"
  },
  "version": 1
}

An item that already has a model, serial and category keeps them; the reading is only recorded

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "excerpt": "MODEL 99ZZ"
  },
  "manufacturer": "Lennox",
  "model_number": "99ZZ",
  "serial": "NEW",
  "category_key": "boiler"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record", {
  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",
    evidence: {
      excerpt: "MODEL 99ZZ",
    },
    manufacturer: "Lennox",
    model_number: "99ZZ",
    serial: "NEW",
    category_key: "boiler",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "excerpt": "MODEL 99ZZ"
  },
  "manufacturer": "Lennox",
  "model_number": "99ZZ",
  "serial": "NEW",
  "category_key": "boiler"
}

Response, 200

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

{
  "result": {
    "identification_id": "idn_01JC4N0000VGW1STJ6TGXRB7FY",
    "model_id": null
  },
  "version": 1
}

An existing model is found, not made

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "locator": "label"
  },
  "manufacturer": "Carrier",
  "model_number": "59TP"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record", {
  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",
    evidence: {
      locator: "label",
    },
    manufacturer: "Carrier",
    model_number: "59TP",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "locator": "label"
  },
  "manufacturer": "Carrier",
  "model_number": "59TP"
}

Response, 200

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

{
  "result": {
    "identification_id": "idn_01JC4N0000VGW1STJ6TGXRB7FY",
    "model_id": "eqm_01JC0000000000000000000001"
  },
  "version": 1
}

A category alone moves an unidentified item without linking a model

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "locator": "photo"
  },
  "category_key": "furnace"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record", {
  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",
    evidence: {
      locator: "photo",
    },
    category_key: "furnace",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "locator": "photo"
  },
  "category_key": "furnace"
}

Response, 200

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

{
  "result": {
    "identification_id": "idn_01JC4N0000VGW1STJ6TGXRB7FY",
    "model_id": null
  },
  "version": 1
}

A category key Rigel doesn't know is kept in the reading and not used

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "locator": "photo"
  },
  "category_key": "spaceship"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record", {
  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",
    evidence: {
      locator: "photo",
    },
    category_key: "spaceship",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "locator": "photo"
  },
  "category_key": "spaceship"
}

Response, 200

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

{
  "result": {
    "identification_id": "idn_01JC4N0000VGW1STJ6TGXRB7FY",
    "model_id": null
  },
  "version": 1
}

An unreadable label still records the reading

Request, curl

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

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record", {
  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",
    evidence: {
      locator: "blurry photo",
    },
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "locator": "blurry photo"
  }
}

Response, 200

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

{
  "result": {
    "identification_id": "idn_01JC4N0000VGW1STJ6TGXRB7FY",
    "model_id": null
  },
  "version": 1
}

While researching, linking the model leaves the status for the job to settle

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "file_id": "fil_01JC0000000000000000000001",
    "locator": "rating plate",
    "excerpt": "MODEL 59TP6B080M1714 SER 1234"
  },
  "manufacturer": "Carrier",
  "model_number": "59TP6B080M1714",
  "serial": "1234",
  "category_key": "furnace",
  "alternatives": [
    "59TP6B080M1715",
    "59TP6B060M1714"
  ]
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record", {
  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",
    evidence: {
      file_id: "fil_01JC0000000000000000000001",
      locator: "rating plate",
      excerpt: "MODEL 59TP6B080M1714 SER 1234",
    },
    manufacturer: "Carrier",
    model_number: "59TP6B080M1714",
    serial: "1234",
    category_key: "furnace",
    alternatives: [
      "59TP6B080M1715",
      "59TP6B060M1714",
    ],
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "file_id": "fil_01JC0000000000000000000001",
    "locator": "rating plate",
    "excerpt": "MODEL 59TP6B080M1714 SER 1234"
  },
  "manufacturer": "Carrier",
  "model_number": "59TP6B080M1714",
  "serial": "1234",
  "category_key": "furnace",
  "alternatives": [
    "59TP6B080M1715",
    "59TP6B060M1714"
  ]
}

Response, 200

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

{
  "result": {
    "identification_id": "idn_01JC4N0000VGW1STJ6TGXRB7FY",
    "model_id": "eqm_01JC4N0000JVP6PWJ6S8P7WZ6B"
  },
  "version": 1
}

An item that isn't there

Request, curl

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

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/maintenance.identification.record", {
  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",
    evidence: {
      locator: "label",
    },
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "asset_id": "ast_01JC0000000000000000000001",
  "evidence": {
    "locator": "label"
  }
}

Response, 404

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

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

For Rigel#

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