A file's details

files.file.get

GET/api/v1/households/{household_id}/queries/files.file.get

Query
Rigel runs it

The file's name, kind, and the type and size of each copy, or null when there is no such file.

Parameters#

A file's details: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`file_id`querystringrequired	A file ID, such as fil_01JC0000000000000000000000.

Response#

200 The answer.

A file's details: response fields
Field	Description
`file`object or nullrequired	The file, or null when it doesn't exist.
`file.id`stringrequired	A file ID, such as fil_01JC0000000000000000000000.
`file.name`stringrequired	The file's name as uploaded, used for downloads.
`file.kind`one of: image, pdf, video, audio, otherrequired	What the file is: image, pdf, video, audio, or other (anything else, which is only ever offered as a download).
`file.original`object or nullrequired	The bytes as uploaded, or null until the original is stored.
`file.original.type`stringrequired	The original's media type, such as image/heic.
`file.original.size`integerrequired	The original's size in bytes.
`file.display`object or nullrequired	The image that stands for the file on screen, or null when it has none.
`file.display.type`stringrequired	The display copy's media type: image/jpeg, image/webp or image/png.
`file.display.size`integerrequired	The display copy's size in bytes.
`file.display.width`integerrequired	The display copy's width in pixels.
`file.display.height`integerrequired	The display copy's height in pixels.
`file.created_at`string (date-time)required	When the file was first stored.

Errors#

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

A file's details: 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.

Get a file's details

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/files.file.get?file_id=fil_01M6V9CS96RRJQEBVXVCKMMR0T' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/files.file.get?file_id=fil_01M6V9CS96RRJQEBVXVCKMMR0T", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/files.file.get?file_id=fil_01M6V9CS96RRJQEBVXVCKMMR0T 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_01M6V9CS9RX30EMT6B4SRF0FT9

{
  "file": {
    "id": "fil_01M6V9CS96RRJQEBVXVCKMMR0T",
    "name": "pantry-middle-shelf.png",
    "kind": "image",
    "original": {
      "type": "image/png",
      "size": 655
    },
    "display": {
      "type": "image/png",
      "size": 342,
      "width": 96,
      "height": 64
    },
    "created_at": "2026-11-07T15:17:52.045Z"
  }
}

Ask for a file that was removed

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/files.file.get?file_id=fil_01M6V9CSA07VXEA2WJV6NA8D4F' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/files.file.get?file_id=fil_01M6V9CSA07VXEA2WJV6NA8D4F", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/files.file.get?file_id=fil_01M6V9CSA07VXEA2WJV6NA8D4F 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_01M6V9CSA6W9F1Z77ENXHVF71H

{
  "file": null
}

For Rigel#

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