Give an item its picture

inventory.item.set_photo

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

Command
Rigel runs it
Applies offline

Sets the item's picture to an uploaded image, or to just a crop of it (the part of a shelf photo that shows this item). Without a crop the whole image is used. A null file_id removes the picture. Errors: item_not_found, file_not_found.

Parameters#

Give an item its picture: 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.

Give an item its picture: request body fields
Field	Description
`item_id`stringrequired	The item to give a picture.
`file_id`string or nullrequired	The uploaded image. Null removes the picture and its crop.
`crop`objectoptional	Where the item is in the photo, as fractions of the image; the picture shows just that part. Leave out for the whole image.
`crop.x`numberrequired	Left edge of the item in the photo, as a fraction of the image width (0 to 1). 0 to 1
`crop.y`numberrequired	Top edge of the item in the photo, as a fraction of the image height (0 to 1). 0 to 1
`crop.width`numberrequired	Width of the item in the photo, as a fraction of the image width (more than 0). 0 to 1greater than 0
`crop.height`numberrequired	Height of the item in the photo, as a fraction of the image height (more than 0). 0 to 1greater than 0

Response#

200 The command was applied.

Give an item its picture: 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.

Give an item its picture: 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. Clearing the photo of an unknown item.
`404`	`file_not_found`	The file doesn't exist in this household. An unknown file.
`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.

A photo with a crop

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "file_id": "fil_01JC000000000000000000000A",
  "crop": {
    "x": 0.1,
    "y": 0.2,
    "width": 0.3,
    "height": 0.4
  }
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo", {
  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",
    file_id: "fil_01JC000000000000000000000A",
    crop: {
      x: 0.1,
      y: 0.2,
      width: 0.3,
      height: 0.4,
    },
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "file_id": "fil_01JC000000000000000000000A",
  "crop": {
    "x": 0.1,
    "y": 0.2,
    "width": 0.3,
    "height": 0.4
  }
}

Response, 200

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

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

A photo without a crop clears an earlier crop

Request, curl

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

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo", {
  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",
    file_id: "fil_01JC000000000000000000000A",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "file_id": "fil_01JC000000000000000000000A"
}

Response, 200

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

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

A crop that fills the image to the edge

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "item_id": "inv_01JC000000000000000000000A",
  "file_id": "fil_01JC000000000000000000000A",
  "crop": {
    "x": 0.5,
    "y": 0.5,
    "width": 0.5,
    "height": 0.5
  }
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo", {
  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",
    file_id: "fil_01JC000000000000000000000A",
    crop: {
      x: 0.5,
      y: 0.5,
      width: 0.5,
      height: 0.5,
    },
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "file_id": "fil_01JC000000000000000000000A",
  "crop": {
    "x": 0.5,
    "y": 0.5,
    "width": 0.5,
    "height": 0.5
  }
}

Response, 200

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

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

Null clears the photo and its crop

Request, curl

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

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo", {
  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",
    file_id: null,
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "file_id": null
}

Response, 200

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

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

An unknown file

Request, curl

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

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo", {
  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",
    file_id: "fil_01JC000000000000000000000Z",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000A",
  "file_id": "fil_01JC000000000000000000000Z"
}

Response, 404

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

{
  "error": {
    "code": "file_not_found",
    "message": "That file isn't there any more. No changes were applied.",
    "details": {
      "file_id": "fil_01JC000000000000000000000Z"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0W8DJAQK2CPSG44X4"
  }
}

An unknown item

Request, curl

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

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo", {
  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",
    file_id: "fil_01JC000000000000000000000A",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000Z",
  "file_id": "fil_01JC000000000000000000000A"
}

Response, 404

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

{
  "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_01K9D9S2R0SBQ0EM3XVYM15AEQ"
  }
}

Clearing the photo of an unknown item

Request, curl

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

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.item.set_photo", {
  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",
    file_id: null,
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01JC000000000000000000000Z",
  "file_id": null
}

Response, 404

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

{
  "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_01K9D9S2R0WY32322G66KY87MD"
  }
}

Give an item a photo

crop picks the part of the picture that shows this item, as fractions of its width and height.

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/inventory.item.set_photo' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CSCPN1CZB6KKGZSKTZ67' \
  -d '{
  "item_id": "inv_01M6V9CSAPM8JH7W1W1YEBHPRS",
  "file_id": "fil_01M6V9CS96RRJQEBVXVCKMMR0T",
  "crop": {
    "x": 0.04,
    "y": 0.08,
    "width": 0.2,
    "height": 0.35
  }
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/inventory.item.set_photo", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CSCPN1CZB6KKGZSKTZ67",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    item_id: "inv_01M6V9CSAPM8JH7W1W1YEBHPRS",
    file_id: "fil_01M6V9CS96RRJQEBVXVCKMMR0T",
    crop: {
      x: 0.04,
      y: 0.08,
      width: 0.2,
      height: 0.35,
    },
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "item_id": "inv_01M6V9CSAPM8JH7W1W1YEBHPRS",
  "file_id": "fil_01M6V9CS96RRJQEBVXVCKMMR0T",
  "crop": {
    "x": 0.04,
    "y": 0.08,
    "width": 0.2,
    "height": 0.35
  }
}

Response, 200

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

{
  "result": {},
  "version": 46
}

For Rigel#

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