A document's history

documents.version.list

GET/api/v1/households/{household_id}/queries/documents.version.list

Query
Rigel runs it

The saved earlier versions of a Markdown or HTML document, newest first: when, why, who, and how much text each change added and removed (comparing each version with the next newer one, the newest with the current text). Restore one with documents.version.restore. Uploaded files have no versions.

Parameters#

A document's history: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`document_id`querystringrequired	A document ID, such as doc_01JC0000000000000000000000.
`limit`queryintegeroptional	How many versions, 1–500. Defaults to 100. 1 to 500Default `100`

Response#

200 The answer.

A document's history: response fields
Field	Description
`items`array of objectsrequired
`items[].id`stringrequired	A document version ID, such as dcv_01JC0000000000000000000000.
`items[].created_at`string (date-time)required	When this version was saved.
`items[].reason`one of: rigel_write, editing, restore, importrequired	rigel_write (before Rigel changed it), editing (after a burst of editing), restore, or import.
`items[].title`stringrequired	The title at that point.
`items[].saved_by`object or nullrequired	Whose change it was; null for Rigel or an import.
`items[].saved_by.person_id`stringrequired	A person ID, such as per_01JC0000000000000000000000.
`items[].saved_by.name`stringrequired	No description.
`items[].chars_added`integerrequired	Characters the next change added to this text.
`items[].chars_removed`integerrequired	Characters the next change removed from this text.
`has_more`booleanrequired	True when older versions exist beyond limit.

Errors#

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

A document's history: 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.

A document's history

Each earlier version, newest first, with how much the next change added and removed.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.version.list?document_id=doc_01M6V9CTA8APRK3KGY0M9RKB4W' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.version.list?document_id=doc_01M6V9CTA8APRK3KGY0M9RKB4W 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_01M6V9CTAQ83WZRCY2W65KNACH

{
  "items": [
    {
      "id": "dcv_01M6V9CTAN41B1ZHSJSX09YY4P",
      "created_at": "2026-11-07T15:17:53.109Z",
      "reason": "rigel_write",
      "title": "Playroom plan",
      "saved_by": null,
      "chars_added": 79,
      "chars_removed": 0
    },
    {
      "id": "dcv_01M6V9CTAM33T4YK1TF4F53B8D",
      "created_at": "2026-11-07T15:17:53.108Z",
      "reason": "rigel_write",
      "title": "Playroom plan",
      "saved_by": null,
      "chars_added": 190,
      "chars_removed": 201
    }
  ],
  "has_more": false
}

For Rigel#

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