Find documents by what they say

documents.document.search

GET/api/v1/households/{household_id}/queries/documents.document.search

Query
Rigel runs it

Finds documents with all of the words you give in their title, summary, text or extracted information, best matches first. The last word matches as a prefix, as you type. Each result has the folder path, kind, summary and a snippet where the words appear; use documents.document.read to read one. Filter to a folder (and the folders inside it) or to kinds.

Parameters#

Find documents by what they say: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`text`querystringrequired	The words to look for. 1 to 500 characters
`folder_id`querystringoptional	Only documents in this folder or the folders inside it.
`kinds`queryarray, each one of: markdown, html, fileoptional	Only these kinds of document: markdown, html, file. A list, or comma-separated. at most 3 items
`limit`queryintegeroptional	How many to return, 1–100. Defaults to 20. 1 to 100Default `20`
`cursor`querystringoptional	The next_cursor of the previous page, with the same filters. pattern ^(-?[0-9.]+(?:e[+-]?[0-9]+)?)~(doc_[0-9A-HJKMNP-TV-Z]{26})$

Response#

200 The answer.

Find documents by what they say: response fields
Field	Description
`items`array of objectsrequired
`items[].id`stringrequired	A document ID, such as doc_01JC0000000000000000000000.
`items[].title`stringrequired	No description.
`items[].kind`one of: markdown, html, filerequired	No description.
`items[].summary`string or nullrequired	No description.
`items[].folder_id`string or nullrequired	A folder ID, such as fld_01JC0000000000000000000000.
`items[].folder_path`array of stringsrequired	The names of the folders it is in, from the top level down; empty when it is unfiled.
`items[].snippet`string or nullrequired	A few words around the match in its text, summary or extracts; null when only the title matched.
`items[].updated_at`string (date-time)required	When it last changed.
`next_cursor`string or nullrequired	Send as cursor for the next page; null on the last page.

Errors#

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

Find documents by what they say: 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 documents for the filter

Request, curl

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

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.document.search?text=filter 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_01M6V9CTB5FG215YJ2H5V84ZH5

{
  "items": [
    {
      "id": "doc_01M6V9CTA49AN0VKX4EC3Q8R0A",
      "title": "Furnace notes",
      "kind": "markdown",
      "summary": "Where the furnace is, which filter it takes and who to call.",
      "folder_id": "fld_01M6V9CT9VW92QWV5HRBAXVASH",
      "folder_path": [
        "House"
      ],
      "snippet": "# Furnace notes\n\nThe furnace is in the utility closet in the basement.\n\n## The filter…",
      "updated_at": "2026-11-07T15:17:53.121Z"
    }
  ],
  "next_cursor": null
}

Search inside one folder

folder_id includes the folders inside it.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.document.search?text=color&folder_id=fld_01M6V9CT9VW92QWV5HRBAXVASH' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.document.search?text=color&folder_id=fld_01M6V9CT9VW92QWV5HRBAXVASH 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_01M6V9CTB8G98WECVASTYGJQ69

{
  "items": [
    {
      "id": "doc_01M6V9CTA8APRK3KGY0M9RKB4W",
      "title": "Playroom plan",
      "kind": "markdown",
      "summary": null,
      "folder_id": "fld_01M6V9CT9VW92QWV5HRBAXVASH",
      "folder_path": [
        "House"
      ],
      "snippet": "# Playroom plan\n\nPaint and shelves before the holidays.\n\n## Walls\n\nNia is choosing the color…",
      "updated_at": "2026-11-07T15:17:53.119Z"
    }
  ],
  "next_cursor": null
}

For Rigel#

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