Mark some of my notifications read

notifications.notification.read

POST/api/v1/households/{household_id}/commands/notifications.notification.read

Command
Rigel runs it
Applies offline

Marks the listed notifications read. IDs that are gone, already read or someone else's are left alone, so this never fails because of them. Returns how many it marked.

Parameters#

Mark some of my notifications read: 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 some of my notifications read: request body fields
Field	Description
`notification_ids`array of stringsrequired	The notifications to mark read, 1–500. 1 to 500 items

Response#

200 The command was applied.

Mark some of my notifications read: response fields
Field	Description
`result`objectrequired	What the command returned, such as the IDs it created.
`result.marked`integerrequired	How many were unread and are now read.
`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 some of my notifications read: 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`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	`no_person`	An account that isn't linked to a person has no notifications.
`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.

Marks my unread notifications read, and leaves others', missing and already-read ones

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/notifications.notification.read' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "notification_ids": [
    "ntf_01JC000000000000000000000A",
    "ntf_01JC000000000000000000000B",
    "ntf_01JC000000000000000000000C",
    "ntf_01JC000000000000000000000D",
    "ntf_01JC000000000000000000000E",
    "ntf_01JC000000000000000000000A"
  ]
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/notifications.notification.read", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    notification_ids: [
      "ntf_01JC000000000000000000000A",
      "ntf_01JC000000000000000000000B",
      "ntf_01JC000000000000000000000C",
      "ntf_01JC000000000000000000000D",
      "ntf_01JC000000000000000000000E",
      "ntf_01JC000000000000000000000A",
    ],
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "notification_ids": [
    "ntf_01JC000000000000000000000A",
    "ntf_01JC000000000000000000000B",
    "ntf_01JC000000000000000000000C",
    "ntf_01JC000000000000000000000D",
    "ntf_01JC000000000000000000000E",
    "ntf_01JC000000000000000000000A"
  ]
}

Response, 200

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

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

IDs that are all gone change nothing and don't fail

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/notifications.notification.read' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "notification_ids": [
    "ntf_01JC000000000000000000000A"
  ]
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/notifications.notification.read", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    notification_ids: [
      "ntf_01JC000000000000000000000A",
    ],
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "notification_ids": [
    "ntf_01JC000000000000000000000A"
  ]
}

Response, 200

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

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

An account that isn't linked to a person has no notifications

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/notifications.notification.read' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "notification_ids": [
    "ntf_01JC000000000000000000000A"
  ]
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/notifications.notification.read", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    notification_ids: [
      "ntf_01JC000000000000000000000A",
    ],
  }),
});
const data = await response.json();

Request, HTTP

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

{
  "notification_ids": [
    "ntf_01JC000000000000000000000A"
  ]
}

Response, 409

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

{
  "error": {
    "code": "no_person",
    "message": "Only a member who signs in has notifications. No changes were applied.",
    "details": {},
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0YZECYZCV5MA74RAP"
  }
}

Mark notifications read

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/notifications.notification.read' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CST0XWXJFZH28PW9RYDZ' \
  -d '{
  "notification_ids": [
    "ntf_01M6V9CSSJ74CDDFEP3N4T0X8P"
  ]
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/notifications.notification.read", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CST0XWXJFZH28PW9RYDZ",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    notification_ids: [
      "ntf_01M6V9CSSJ74CDDFEP3N4T0X8P",
    ],
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/notifications.notification.read HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CST0XWXJFZH28PW9RYDZ

{
  "notification_ids": [
    "ntf_01M6V9CSSJ74CDDFEP3N4T0X8P"
  ]
}

Response, 200

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

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

For Rigel#

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