My notifications

notifications.notification.list

GET/api/v1/households/{household_id}/queries/notifications.notification.list

Query
Rigel runs it

My notifications that are due, newest first, with how many of all of mine are unread. Scheduled ones appear when their time comes. Fails with no_person for someone who doesn't sign in.

Parameters#

My notifications: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`unread_only`queryboolean or stringoptional	Only unread notifications. Defaults to false.
`app`queryone of: meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, maintenanceoptional	Only notifications from this app.
`limit`queryintegeroptional	How many to return, 1–200. Defaults to 50. 1 to 200Default `50`
`cursor`querystringoptional	The next_cursor of the previous page, with the same filters. pattern ^(\d+)\.(ntf_[0-9A-HJKMNP-TV-Z]{26})$

Response#

200 The answer.

My notifications: response fields
Field	Description
`items`array of objectsrequired
`items[].id`stringrequired	A notification ID, such as ntf_01JC0000000000000000000000.
`items[].app`one of: meals, recipes, shopping, inventory, calendar, email, tasks, documents, chat, maintenance, null or nullrequired	The app that sent it, or null for the household or Rigel in general.
`items[].kind`stringrequired	What kind of notification it is, such as mention or reminder.
`items[].title`stringrequired	What it says.
`items[].body`string or nullrequired	More detail, if any.
`items[].record_id`string or nullrequired	The record it is about.
`items[].topic_id`string or nullrequired	The larger thing it belongs to.
`items[].address`string or nullrequired	The web route that opens the record, or null when there isn't one.
`items[].delivered_at`string (date-time)required	When it was delivered.
`items[].read_at`string (date-time) or nullrequired	When it was read, or null if it is unread.
`next_cursor`string or nullrequired	Send as cursor for the next page; null on the last page.
`unread_count`integerrequired	How many due notifications I haven't read, whatever the filters.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

My notifications: 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.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

See your notifications

Newest first, with how many are unread.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

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

{
  "items": [
    {
      "id": "ntf_01M6V9CSSMTA415FM404N9HKYH",
      "app": "meals",
      "kind": "message",
      "title": "Dinner is at 6:00 pm",
      "body": null,
      "record_id": null,
      "topic_id": "mel_01M6V9CSFSFH4859KG4NM47HF2",
      "address": null,
      "delivered_at": "2026-11-07T15:17:52.566Z",
      "read_at": null
    },
    {
      "id": "ntf_01M6V9CSSJ74CDDFEP3N4T0X8P",
      "app": "calendar",
      "kind": "reminder",
      "title": "Pick up Theo from soccer",
      "body": "Tuesday at 5:00 pm, Riverside Park. Ben is going.",
      "record_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "topic_id": null,
      "address": "/calendar?event=evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "delivered_at": "2026-11-07T15:17:52.563Z",
      "read_at": null
    }
  ],
  "next_cursor": null,
  "unread_count": 2
}

Only unread calendar notifications

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?unread_only=true&app=calendar' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?unread_only=true&app=calendar", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?unread_only=true&app=calendar HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

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

{
  "items": [
    {
      "id": "ntf_01M6V9CSSJ74CDDFEP3N4T0X8P",
      "app": "calendar",
      "kind": "reminder",
      "title": "Pick up Theo from soccer",
      "body": "Tuesday at 5:00 pm, Riverside Park. Ben is going.",
      "record_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "topic_id": null,
      "address": "/calendar?event=evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "delivered_at": "2026-11-07T15:17:52.563Z",
      "read_at": null
    }
  ],
  "next_cursor": null,
  "unread_count": 2
}

See one notification at a time

limit and cursor page through them.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?limit=1' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?limit=1", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?limit=1 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

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

{
  "items": [
    {
      "id": "ntf_01M6V9CSSMTA415FM404N9HKYH",
      "app": "meals",
      "kind": "message",
      "title": "Dinner is at 6:00 pm",
      "body": null,
      "record_id": null,
      "topic_id": "mel_01M6V9CSFSFH4859KG4NM47HF2",
      "address": null,
      "delivered_at": "2026-11-07T15:17:52.566Z",
      "read_at": null
    }
  ],
  "next_cursor": "1794064672566.ntf_01M6V9CSSMTA415FM404N9HKYH",
  "unread_count": 2
}

See the next notification

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?limit=1&cursor=1794064672566.ntf_01M6V9CSSMTA415FM404N9HKYH' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?limit=1&cursor=1794064672566.ntf_01M6V9CSSMTA415FM404N9HKYH", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/notifications.notification.list?limit=1&cursor=1794064672566.ntf_01M6V9CSSMTA415FM404N9HKYH HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

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

{
  "items": [
    {
      "id": "ntf_01M6V9CSSJ74CDDFEP3N4T0X8P",
      "app": "calendar",
      "kind": "reminder",
      "title": "Pick up Theo from soccer",
      "body": "Tuesday at 5:00 pm, Riverside Park. Ben is going.",
      "record_id": "evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "topic_id": null,
      "address": "/calendar?event=evt_01M6V9CSHPG77MMGGKHAEJQ484",
      "delivered_at": "2026-11-07T15:17:52.563Z",
      "read_at": null
    }
  ],
  "next_cursor": null,
  "unread_count": 2
}

For Rigel#

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