Households

The household itself: create it, read it, change its settings.5 operations

Headers on every response

Every response on this page carries these headers.

X-Trace-Id: — The W3C trace id of this request — the same id in the log and in the traceId of a problem. Quote it when reporting.
Server-Timing: — Where the time went: total, db;dur=…;desc="N queries", and every step the handler named (ADR-163).
X-Diagnostics: — Only when the request asked with X-Diagnostics: 1 or ?diagnostics=1: the same breakdown as one JSON object, with the trace id (ADR-163).

Operations

GET/api/v1/time-zones

List the IANA time zones a household can be set to

Every id the server's own tz database knows — which is exactly what PATCH /households/{householdId} accepts as timeZoneId (ADR-228). Unsorted; the household's own zone first and the rest alphabetical is the client's job. Cached for a day (Cache-Control: private, max-age=86400).

Parameters

No parameters

Responses

200OK

application/jsonTimeZonesResponse

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

426The build named in X-App-Version is below its platform's version floor (ADR-070). Problem type app-version-unsupported; the only way forward is the store. Callers without the header are never turned away.

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  "https://bryti.app/api/v1/time-zones"

Example response

200application/json

{
  "ids": [
    "string"
  ]
}

POST/api/v1/households

Create a household and become its owner

Any signed-in user. The caller becomes the household's owner, and a subscription on the default plan is opened with it; a first-time creator is promised the plan's welcome credits — one bundle per user, however many households they create (ADR-024). 403 with code invite_required or invite_code_invalid when intake is invite-only and no valid inviteCode came along, and intake_paused when intake is paused — the caller is then put on the waitlist (ADR-025).

Parameters

No parameters

Request body

application/jsonRequiredCreateHouseholdRequest

Responses

201Created

application/jsonHouseholdResponse

400Bad Request

application/problem+jsonProblemDetails

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

403Forbidden

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  -X POST \
  "https://bryti.app/api/v1/households" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","timeZoneId":"string","defaultDinnerTime":"string"}'

Example response

201application/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "timeZoneId": "string",
  "defaultDinnerTime": "string",
  "preferredLanguage": "string",
  "country": "string",
  "preferOwnRecipes": false,
  "prefersLeftoverDinners": false,
  "measurementSystem": "string",
  "dryGoodsMeasure": "string",
  "address": "string",
  "loyaltyPrograms": [
    "string"
  ],
  "createdAt": "2026-09-07T16:30:00Z",
  "updatedAt": "2026-09-07T16:30:00Z",
  "shareReceiptPrices": true,
  "shareUnitWeights": false,
  "tailorServingToTastes": true,
  "showSoftServingAdvice": true,
  "babyEatsSeparatelyWhenNeeded": false,
  "maxNewDishesPerWeek": 7,
  "alwaysNewDishes": false,
  "pantryWeight": "Usual",
  "useStarterLibrary": true,
  "showChildTasks": false,
  "madeAgainLift": true
}

GET/api/v1/households/{householdId}

Get the household with its settings and sharing choices

Parameters

Name	In	Type	Required	Description
`householdId`	path	`string (uuid)`	Required	—

Responses

200OK

application/jsonHouseholdResponse

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

404Not Found

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  "https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6"

Example response

200application/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "timeZoneId": "string",
  "defaultDinnerTime": "string",
  "preferredLanguage": "string",
  "country": "string",
  "preferOwnRecipes": false,
  "prefersLeftoverDinners": false,
  "measurementSystem": "string",
  "dryGoodsMeasure": "string",
  "address": "string",
  "loyaltyPrograms": [
    "string"
  ],
  "createdAt": "2026-09-07T16:30:00Z",
  "updatedAt": "2026-09-07T16:30:00Z",
  "shareReceiptPrices": true,
  "shareUnitWeights": false,
  "tailorServingToTastes": true,
  "showSoftServingAdvice": true,
  "babyEatsSeparatelyWhenNeeded": false,
  "maxNewDishesPerWeek": 7,
  "alwaysNewDishes": false,
  "pantryWeight": "Usual",
  "useStarterLibrary": true,
  "showChildTasks": false,
  "madeAgainLift": true
}

PATCH/api/v1/households/{householdId}

Change one or more household settings, leaving the rest as they are

Owner only. Every field is «omit = leave it» (#689, #729, #754), so a settings screen may send just the field it changed. 400 for a blank name or an unknown measurementSystem / dryGoodsMeasure.

Parameters

Name	In	Type	Required	Description
`householdId`	path	`string (uuid)`	Required	—

Request body

application/jsonRequiredUpdateHouseholdRequest

Responses

200OK

application/jsonHouseholdResponse

400Bad Request

application/problem+jsonProblemDetails

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

404Not Found

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  -X PATCH \
  "https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

200application/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "timeZoneId": "string",
  "defaultDinnerTime": "string",
  "preferredLanguage": "string",
  "country": "string",
  "preferOwnRecipes": false,
  "prefersLeftoverDinners": false,
  "measurementSystem": "string",
  "dryGoodsMeasure": "string",
  "address": "string",
  "loyaltyPrograms": [
    "string"
  ],
  "createdAt": "2026-09-07T16:30:00Z",
  "updatedAt": "2026-09-07T16:30:00Z",
  "shareReceiptPrices": true,
  "shareUnitWeights": false,
  "tailorServingToTastes": true,
  "showSoftServingAdvice": true,
  "babyEatsSeparatelyWhenNeeded": false,
  "maxNewDishesPerWeek": 7,
  "alwaysNewDishes": false,
  "pantryWeight": "Usual",
  "useStarterLibrary": true,
  "showChildTasks": false,
  "madeAgainLift": true
}

POST/api/v1/households/{householdId}/onboarding/complete

Finish the guided setup and write its recap into the day's thread

Any member, Junior included — refusing whoever holds the phone would only strand the setup (#413, ADR-043). The recap goes into today's thread, the one Home shows, under the morning message — not into a conversation of its own (#3378); conversationId is that thread. Safe to retry: a second call answers 200 with the original stamp and alreadyCompleted true, writing nothing; the defaultDinnerTime in the body is honoured on the completing call only. The recap is written from the household's own tables, not generated, so it costs no credits.

Parameters

Name	In	Type	Required	Description
`householdId`	path	`string (uuid)`	Required	—

Request body

application/jsonRequiredCompleteOnboardingRequest

Responses

200OK

application/jsonCompleteOnboardingResponse

400Bad Request

application/problem+jsonProblemDetails

401No session, or the session is no longer valid.

application/problem+jsonProblemDetails

404Not Found

application/problem+jsonProblemDetails

409Conflict

application/problem+jsonProblemDetails

429Too many calls in the window; Retry-After says how long.

application/problem+jsonProblemDetails

Headers

Retry-After: — Seconds to wait when a rate limit answered, or an HTTP date when the household's AI is paused. Absent when the household's AI quota for the period is used up — that resets by itself.

Example

curl -b "bryti_session=…" \
  -X POST \
  "https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6/onboarding/complete" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response

200application/json

{
  "onboardingCompletedAt": "2026-09-07T16:30:00Z",
  "alreadyCompleted": false,
  "conversationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Schemas

CompleteOnboardingRequest

Property	Type	Required
`skippedSteps`	`OnboardingStep[] \| null`	—
`defaultDinnerTime`	`string \| null`	—

CompleteOnboardingResponse

Property	Type	Required
`onboardingCompletedAt`	`string (date-time)`	Required
`alreadyCompleted`	`boolean`	Required
`conversationId`	`string (uuid) \| null`	Required

CreateHouseholdRequest

Property	Type	Required
`name`	`string`	Required
`timeZoneId`	`string`	Required
`defaultDinnerTime`	`string`	Required
`preferredLanguage`	`string \| null`	—
`inviteCode`	`string \| null`	—

HouseholdResponse

Property	Type	Required
`id`	`string (uuid)`	Required
`name`	`string`	Required
`timeZoneId`	`string`	Required
`defaultDinnerTime`	`string`	Required
`preferredLanguage`	`string`	Required
`country`	`string`	Required
`preferOwnRecipes`	`boolean`	Required
`prefersLeftoverDinners`	`boolean`	Required
`measurementSystem`	`string`	Required
`dryGoodsMeasure`	`string`	Required
`address`	`string \| null`	Required
`loyaltyPrograms`	`string[]`	Required
`createdAt`	`string (date-time)`	Required
`updatedAt`	`string (date-time)`	Required
`shareReceiptPrices`	`boolean`	—
`onboardingCompletedAt`	`string (date-time) \| null`	—
`shareUnitWeights`	`boolean`	—
`tailorServingToTastes`	`boolean`	—
`showSoftServingAdvice`	`boolean`	—
`babyEatsSeparatelyWhenNeeded`	`boolean`	—
`maxNewDishesPerWeek`	`integer (int32)`	—
`alwaysNewDishes`	`boolean`	—
`pantryWeight`	`string`	—
`useStarterLibrary`	`boolean`	—
`showChildTasks`	`boolean`	—
`madeAgainLift`	`boolean`	—

OnboardingStep

Type

Values

PantryPeopleAllergiesRules

ProblemDetails

Property	Type	Required
`type`	`string \| null`	—
`title`	`string \| null`	—
`status`	`integer (int32) \| null`	—
`detail`	`string \| null`	—
`instance`	`string \| null`	—
`code`	`string \| null`	—

TimeZonesResponse

Property	Type	Required
`ids`	`string[]`	Required

UpdateHouseholdRequest

Property	Type	Required
`name`	`string \| null`	—
`timeZoneId`	`string \| null`	—
`defaultDinnerTime`	`string \| null`	—
`preferredLanguage`	`string \| null`	—
`country`	`string \| null`	—
`preferOwnRecipes`	`boolean \| null`	—
`prefersLeftoverDinners`	`boolean \| null`	—
`maxNewDishesPerWeek`	`integer (int32) \| null`	—
`alwaysNewDishes`	`boolean \| null`	—
`pantryWeight`	`string \| null`	—
`address`	`string \| null`	—
`loyaltyPrograms`	`string[] \| null`	—
`measurementSystem`	`string \| null`	—
`dryGoodsMeasure`	`string \| null`	—
`shareReceiptPrices`	`boolean \| null`	—
`shareUnitWeights`	`boolean \| null`	—
`tailorServingToTastes`	`boolean \| null`	—
`showSoftServingAdvice`	`boolean \| null`	—
`babyEatsSeparatelyWhenNeeded`	`boolean \| null`	—
`useStarterLibrary`	`boolean \| null`	—
`showChildTasks`	`boolean \| null`	—
`madeAgainLift`	`boolean \| null`	—