Find messages

chat.message.search

GET/api/v1/households/{household_id}/queries/chat.message.search

Query
Rigel runs it

Messages whose text has every word of the search, each as the start of a word, ignoring case and accents, newest first, with a snippet, the topic and a link. Threads and archived topics are searched too; deleted messages aren't.

Parameters#

Find messages: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`text`querystringrequired	The words to find. 1 to 200 characters
`conversation_id`querystringoptional	Only in this topic (and its threads).
`person_id`querystringoptional	Only messages this person wrote.
`limit`queryintegeroptional	Up to how many matches, 1–50, 20 by default. 1 to 50Default `20`
`cursor`querystringoptional	The next_cursor of the previous answer, with the same filters. pattern ^(\d+)\.(msg_[0-9A-HJKMNP-TV-Z]{26})$

Response#

200 The answer.

Find messages: response fields
Field	Description
`items`array of objectsrequired
`items[].message_id`stringrequired	A message ID, such as msg_01JC0000000000000000000000.
`items[].conversation_id`stringrequired	A conversation ID, such as cnv_01JC0000000000000000000000.
`items[].conversation_title`stringrequired	No description.
`items[].thread_root_message_id`string or nullrequired	A message ID, such as msg_01JC0000000000000000000000.
`items[].author_name`stringrequired	No description.
`items[].sent_at`string (date-time)required	No description.
`items[].snippet`stringrequired	Plain text around the first match.
`items[].address`stringrequired	The web route that opens the message.
`next_cursor`string or nullrequired	Send as cursor for more; null when there are no more.

Errors#

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

Find messages: 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.

Search the conversations for soccer

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.search?text=soccer' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.search?text=soccer", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/chat.message.search?text=soccer 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_01M6V9CSNRBK58RF8J8EYKPPPF

{
  "items": [
    {
      "message_id": "msg_01M6V9CSMTRMX2BPZ3MJTKGREF",
      "conversation_id": "cnv_00000000000000000000000000",
      "conversation_title": "Family",
      "thread_root_message_id": null,
      "author_name": "Ada Okafor",
      "sent_at": "2026-11-07T15:17:52.410Z",
      "snippet": "@Ben can you pick Theo up from soccer on Tuesday at 5? I have a late meeting.",
      "address": "/chat/message/msg_01M6V9CSMTRMX2BPZ3MJTKGREF"
    }
  ],
  "next_cursor": null
}

For Rigel#

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