Get a household

households.get

GET/api/v1/households/{household_id}

Route

The household's settings and your role there.

Parameters#

Get a household: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.

Response#

200 The household.

Get a household: response fields
Field	Description
`id`stringrequired	The household's ID.
`name`stringrequired	What the household calls itself.
`time_zone`stringrequired	IANA time zone, such as America/New_York.
`role`one of: adminrequired	Your role there: admin (the only role for now).

Errors#

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

Get a household: errors
Status	Code	When
`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 household

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95 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_01M6V9CS6YB5Q24RZNZ5KWYQCZ

{
  "id": "hh_01M6V9CS6GGVFCY7NAS8ZTQV95",
  "name": "The Okafors",
  "time_zone": "America/Chicago",
  "role": "admin"
}

A household you're not in

Sam is signed in, but isn't a member. The API answers as it would for a household that doesn't exist.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01M6V9CS700A1RH663FWHX0E0B

{
  "error": {
    "code": "not_found",
    "message": "That household wasn't found.",
    "details": {},
    "recovery": "Check the ID. You can only reach households you're a member of.",
    "request_id": "req_01M6V9CS700A1RH663FWHX0E0B"
  }
}