Set the picture behind a place's icon

dashboard.app_picture.set

POST/api/v1/households/{household_id}/commands/dashboard.app_picture.set

Command
Rigel runs it
Waits for the server

Uses an image from the household's files as the picture behind the icon of Today or an app, in the shell's tiles, switcher and sidebar. Use it when someone sends a photo and asks for it, and from the picture job when it has made one. The hint, what the picture should look like, is kept for the next time it's remade; leave it out to keep the one there, or send null to clear it. Fails with file_not_found if there's no such file.

Parameters#

Set the picture behind a place's icon: 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.

Set the picture behind a place's icon: request body fields
Field	Description
`place`one of: today, meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, maintenancerequired	Where the picture is shown: today (the home screen) or an app's ID, such as meals or inventory.
`file_id`stringrequired	An image in the household's files.
`hint`string or nulloptional	What it should look like, kept for remaking it; null clears it. 1 to 200 characters

Response#

200 The command was applied.

Set the picture behind a place's icon: response fields
Field	Description
`result`objectrequired	What the command returned, such as the IDs it created.
`result.picture_id`stringrequired	The place's picture record.
`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.

Set the picture behind a place's icon: 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`	`file_not_found`	A file 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.

A first picture for a place

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "place": "meals",
  "file_id": "fil_01JC000000000000000000000A"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    place: "meals",
    file_id: "fil_01JC000000000000000000000A",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "place": "meals",
  "file_id": "fil_01JC000000000000000000000A"
}

Response, 200

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

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

A hint is kept with it

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "place": "today",
  "file_id": "fil_01JC000000000000000000000A",
  "hint": "autumn colors"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    place: "today",
    file_id: "fil_01JC000000000000000000000A",
    hint: "autumn colors",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "place": "today",
  "file_id": "fil_01JC000000000000000000000A",
  "hint": "autumn colors"
}

Response, 200

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

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

A new picture replaces the old one, brings the style up to date and keeps the hint

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "place": "meals",
  "file_id": "fil_01JC000000000000000000000B"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    place: "meals",
    file_id: "fil_01JC000000000000000000000B",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "place": "meals",
  "file_id": "fil_01JC000000000000000000000B"
}

Response, 200

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

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

Null clears the hint

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "place": "meals",
  "file_id": "fil_01JC000000000000000000000A",
  "hint": null
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    place: "meals",
    file_id: "fil_01JC000000000000000000000A",
    hint: null,
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "place": "meals",
  "file_id": "fil_01JC000000000000000000000A",
  "hint": null
}

Response, 200

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

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

A picture whose file was lost gets a new one

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "place": "chat",
  "file_id": "fil_01JC000000000000000000000B"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    place: "chat",
    file_id: "fil_01JC000000000000000000000B",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "place": "chat",
  "file_id": "fil_01JC000000000000000000000B"
}

Response, 200

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

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

A file that isn't there

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "place": "meals",
  "file_id": "fil_01JC000000000000000000000A"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/dashboard.app_picture.set", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    place: "meals",
    file_id: "fil_01JC000000000000000000000A",
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "place": "meals",
  "file_id": "fil_01JC000000000000000000000A"
}

Response, 404

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

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

For Rigel#

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