Move an item to another place

inventory.item.move

POST/api/v1/households/{household_id}/commands/inventory.item.move

Command
Rigel runs it
Applies offline

Records that the item is now in another location. If the new place keeps things differently (frozen, cold or room) and no expires_on is given, an estimated use-by date is cleared because it was for the old place; a date from the label or a person is kept. Pass expires_on with expires_source to set a new date, such as an estimate for thawing in the fridge. A product with no usual place gets this one. Does not change when the item was last seen. Errors: item_not_found, location_not_found.

Parameters#

Move an item to another place: 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.

Move an item to another place: request body fields
Field	Description
`item_id`stringrequired	The item that moved.
`location_id`stringrequired	Where it is now.
`expires_on`string (date) or nulloptional	A new use-by date for where it is now, YYYY-MM-DD, such as a thawing date; null for none. Give it together with expires_source. Leave both out to keep the date, except that an estimated date is cleared when the new place keeps things differently (frozen, cold or room).
`expires_source`one of: label, person, estimated, null or nulloptional	Where expires_on came from. Give it together with expires_on; null clears both.

Response#

200 The command was applied.

Move an item to another place: 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.

Move an item to another place: 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`	`item_not_found`	The item doesn't exist in this household. An unknown item.
`404`	`location_not_found`	The location doesn't exist in this household. An unknown location.
`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.

Moving to another environment clears an estimated date, keeps the confirmation, and fills the product's usual place

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000A",
    location_id: "loc_01JC000000000000000000000B",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B"
}

Response, 200

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

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

Moving to another environment keeps a label date

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000A",
    location_id: "loc_01JC000000000000000000000B",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B"
}

Response, 200

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

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

Moving to another environment keeps a date a person gave

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000A"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000A",
    location_id: "loc_01JC000000000000000000000A",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000A"
}

Response, 200

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

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

Moving within the same environment keeps an estimated date

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000D"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000A",
    location_id: "loc_01JC000000000000000000000D",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000D"
}

Response, 200

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

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

An explicit new date replaces the old one

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B",
  "expires_on": "2025-11-08",
  "expires_source": "estimated"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000A",
    location_id: "loc_01JC000000000000000000000B",
    expires_on: "2025-11-08",
    expires_source: "estimated",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B",
  "expires_on": "2025-11-08",
  "expires_source": "estimated"
}

Response, 200

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

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

An explicit new date replaces a label date too

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B",
  "expires_on": "2025-11-20",
  "expires_source": "person"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000A",
    location_id: "loc_01JC000000000000000000000B",
    expires_on: "2025-11-20",
    expires_source: "person",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B",
  "expires_on": "2025-11-20",
  "expires_source": "person"
}

Response, 200

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

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

An explicit null date clears the expiry

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B",
  "expires_on": null,
  "expires_source": null
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000A",
    location_id: "loc_01JC000000000000000000000B",
    expires_on: null,
    expires_source: null,
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000B",
  "expires_on": null,
  "expires_source": null
}

Response, 200

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

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

An unknown item

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000Z",
  "location_id": "loc_01JC000000000000000000000B"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000Z",
    location_id: "loc_01JC000000000000000000000B",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000Z",
  "location_id": "loc_01JC000000000000000000000B"
}

Response, 404

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

{
  "error": {
    "code": "item_not_found",
    "message": "That item isn't in the inventory any more. No changes were applied.",
    "details": {
      "item_id": "inv_01JC000000000000000000000Z"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0MTNHHF71P7ZR2G5M"
  }
}

An unknown location

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000Z"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01JC000000000000000000000A",
    location_id: "loc_01JC000000000000000000000Z",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "location_id": "loc_01JC000000000000000000000Z"
}

Response, 404

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

{
  "error": {
    "code": "location_not_found",
    "message": "That place isn't in the inventory any more. No changes were applied.",
    "details": {
      "location_id": "loc_01JC000000000000000000000Z"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0SR2AY3YJ0S759KFF"
  }
}

Move something to thaw

Moving between environments gives the item a new date to match: here, a fridge date a couple of days out.

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/inventory.item.move' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CSCH0ZW7ZTT8SN92V00S' \
  -d '{
  "item_id": "inv_01M6V9CSB2QRQDPSG49EFX353W",
  "location_id": "loc_01M6V9CSAACDPHW4NW889QQ2VV"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/inventory.item.move", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CSCH0ZW7ZTT8SN92V00S",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01M6V9CSB2QRQDPSG49EFX353W",
    location_id: "loc_01M6V9CSAACDPHW4NW889QQ2VV",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/inventory.item.move HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CSCH0ZW7ZTT8SN92V00S

{
  "item_id": "inv_01M6V9CSB2QRQDPSG49EFX353W",
  "location_id": "loc_01M6V9CSAACDPHW4NW889QQ2VV"
}

Response, 200

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

{
  "result": {},
  "version": 43
}

For Rigel#

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