What is in a folder
documents.folder.list
GET/api/v1/households/{household_id}/queries/documents.folder.list
- Query
- Rigel runs it
The folders and documents directly inside a folder, or at the top level when folder_id is left out (where unfiled documents are too). Folders come with how many items each holds; documents newest change first. This is one folder's contents, not a search: use documents.document.search to find a document by what it says.
Parameters#
| Field | Description |
|---|---|
household_idpathstringrequired | The household's ID. |
folder_idquerystringoptional | The folder to list; leave out for the top level. |
Response#
200 The answer.
| Field | Description |
|---|---|
folderobject or nullrequired | The folder listed; null for the top level. |
folder.idstringrequired | A folder ID, such as fld_01JC0000000000000000000000. |
folder.namestringrequired | No description. |
folder.patharray of stringsrequired | Its name and the folders above it, from the top. |
foldersarray of objectsrequired | |
folders[].idstringrequired | A folder ID, such as fld_01JC0000000000000000000000. |
folders[].namestringrequired | No description. |
folders[].item_countintegerrequired | The folders and documents directly inside it. |
documentsarray of objectsrequired | |
documents[].idstringrequired | A document ID, such as doc_01JC0000000000000000000000. |
documents[].titlestringrequired | No description. |
documents[].kindone of: markdown, html, filerequired | No description. |
documents[].summarystring or nullrequired | No description. |
documents[].updated_atstring (date-time)required | No description. |
Errors#
Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.
| 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.
What is at the top level
Folders with how many items each holds, then unfiled documents.
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.folder.list' \
-H "Cookie: rigel_session=$RIGEL_SESSION"const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.folder.list", {
headers: {
Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
},
});
const data = await response.json();GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.folder.list HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTB2ZGB04B9Y3CQE49CH
{
"folder": null,
"folders": [
{
"id": "fld_01M6V9CT9X97T5BFYDED4FC8FW",
"name": "Family papers",
"item_count": 1
},
{
"id": "fld_01M6V9CT9VW92QWV5HRBAXVASH",
"name": "House",
"item_count": 3
}
],
"documents": [
{
"id": "doc_01M6V9CTAC5Y4Z9FTG59AEDPTH",
"title": "Pantry middle shelf",
"kind": "file",
"summary": "A photo of the pantry's middle shelf.",
"updated_at": "2026-11-07T15:17:53.102Z"
}
]
}What is in a folder
Its folders and documents, newest change first.
curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.folder.list?folder_id=fld_01M6V9CT9VW92QWV5HRBAXVASH' \
-H "Cookie: rigel_session=$RIGEL_SESSION"const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.folder.list?folder_id=fld_01M6V9CT9VW92QWV5HRBAXVASH", {
headers: {
Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
},
});
const data = await response.json();GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/documents.folder.list?folder_id=fld_01M6V9CT9VW92QWV5HRBAXVASH HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTB4ACX29CAN26XC0RBX
{
"folder": {
"id": "fld_01M6V9CT9VW92QWV5HRBAXVASH",
"name": "House",
"path": [
"House"
]
},
"folders": [
{
"id": "fld_01M6V9CT9WX6XJG5K82AEN92ZD",
"name": "Manuals",
"item_count": 0
}
],
"documents": [
{
"id": "doc_01M6V9CTA49AN0VKX4EC3Q8R0A",
"title": "Furnace notes",
"kind": "markdown",
"summary": "Where the furnace is, which filter it takes and who to call.",
"updated_at": "2026-11-07T15:17:53.121Z"
},
{
"id": "doc_01M6V9CTA8APRK3KGY0M9RKB4W",
"title": "Playroom plan",
"kind": "markdown",
"summary": null,
"updated_at": "2026-11-07T15:17:53.119Z"
}
]
}For Rigel#
Rigel's tool for this query is documents_folder_list. Rigel runs this on its own, then says what it did. The agent guide has the rest.