Households

The household itself: create it, read it, change its settings.6 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 the server is down for maintenance, 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.
503The server is down for maintenance (#4693). Retry-After says when to try again; problem type maintenance. Every call under /api answers this while maintenance mode is on, the version floor included.
application/problem+jsonProblemDetails
Headers
Retry-After
— Seconds to wait when a rate limit answered or the server is down for maintenance, 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). 403 with code country_not_supported, in every mode and with or without a code, when country is not one Bryti serves (NO, US, CA, AU, NZ, CH) — the caller is put on the waitlist with the country, and the problem carries it as country (#4993). The country Cloudflare places the request in decides first: from a country Bryti does not serve the answer is the same 403 naming that country, whatever country says, with decidedBy ip (picked when the country in the body decided); from another served country the household is created and a country_mismatch security event is written (#5124). The household speaks preferredLanguage when it is given, else the first language in Accept-Language Bryti speaks (nb, nn, en), else English when the header names only others (ADR-593 (#4969)).

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
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 the server is down for maintenance, 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.
503The server is down for maintenance (#4693). Retry-After says when to try again; problem type maintenance. Every call under /api answers this while maintenance mode is on, the version floor included.
application/problem+jsonProblemDetails
Headers
Retry-After
— Seconds to wait when a rate limit answered or the server is down for maintenance, 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,
  "freezesPrep": false,
  "currency": "NOK",
  "weekStartsOn": "Monday",
  "saveGeneratedRecipes": false
}
GET/api/v1/households/{householdId}

Get the household with its settings and sharing choices

Parameters

NameInTypeRequiredDescription
householdIdpathstring (uuid)Required—

Responses

200OK
application/jsonHouseholdResponse
401No session, or the session is no longer valid.
application/problem+jsonProblemDetails
404Not Found
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 the server is down for maintenance, 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.
503The server is down for maintenance (#4693). Retry-After says when to try again; problem type maintenance. Every call under /api answers this while maintenance mode is on, the version floor included.
application/problem+jsonProblemDetails
Headers
Retry-After
— Seconds to wait when a rate limit answered or the server is down for maintenance, 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,
  "freezesPrep": false,
  "currency": "NOK",
  "weekStartsOn": "Monday",
  "saveGeneratedRecipes": false
}
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 / weekStartsOn. weekStartsOn (Monday or Sunday, #5103) only changes the day the apps draw the week from; a plan is still the ISO week. 403 with code country_not_supported (and the country) for a move to a country Bryti does not serve: nothing in the body is saved and the household keeps its country (#5103).

Parameters

NameInTypeRequiredDescription
householdIdpathstring (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
403Forbidden
application/problem+jsonProblemDetails
404Not Found
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 the server is down for maintenance, 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.
503The server is down for maintenance (#4693). Retry-After says when to try again; problem type maintenance. Every call under /api answers this while maintenance mode is on, the version floor included.
application/problem+jsonProblemDetails
Headers
Retry-After
— Seconds to wait when a rate limit answered or the server is down for maintenance, 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,
  "freezesPrep": false,
  "currency": "NOK",
  "weekStartsOn": "Monday",
  "saveGeneratedRecipes": false
}
GET/api/v1/households/{householdId}/activity/last

Say when the household was last changed, in the app or by an assistant

Any member. lastWriteAt is the newest of two things: a member's write in the app (any POST, PUT, PATCH or DELETE under this household that answered 2xx, stamped at most once a minute) and a change a member's own assistant made over MCP. source says which, app or assistant; both are null when nobody has changed anything since the household was made. Reads never count. The review household's nightly reset waits until this is two hours old (#5021).

Parameters

NameInTypeRequiredDescription
householdIdpathstring (uuid)Required—

Responses

200OK
application/jsonHouseholdLastActivityResponse
401No session, or the session is no longer valid.
application/problem+jsonProblemDetails
404Not Found
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 the server is down for maintenance, 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.
503The server is down for maintenance (#4693). Retry-After says when to try again; problem type maintenance. Every call under /api answers this while maintenance mode is on, the version floor included.
application/problem+jsonProblemDetails
Headers
Retry-After
— Seconds to wait when a rate limit answered or the server is down for maintenance, 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/activity/last"

Example response

200application/json
{
  "lastWriteAt": "2026-09-07T16:30:00Z",
  "source": "string"
}
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

NameInTypeRequiredDescription
householdIdpathstring (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
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 the server is down for maintenance, 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.
503The server is down for maintenance (#4693). Retry-After says when to try again; problem type maintenance. Every call under /api answers this while maintenance mode is on, the version floor included.
application/problem+jsonProblemDetails
Headers
Retry-After
— Seconds to wait when a rate limit answered or the server is down for maintenance, 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

PropertyTypeRequired
skippedStepsOnboardingStep[] | null—
defaultDinnerTimestring | null—

CompleteOnboardingResponse

PropertyTypeRequired
onboardingCompletedAtstring (date-time)Required
alreadyCompletedbooleanRequired
conversationIdstring (uuid) | nullRequired

CountryProfileResponse

PropertyTypeRequired
filledbooleanRequired
priceCatalogbooleanRequired
storeFinderbooleanRequired
seasonsbooleanRequired
holidaysbooleanRequired
dietaryAdvicebooleanRequired
paymentsOpenbooleanRequired
vippsbooleanRequired
storesFromReceiptsbooleanRequired
cheapPerPortionnumber (double) | nullRequired
offmapRequired
publicLinksstring[]Required
localeDefaultsmapRequired
nutritionSourcestring | nullRequired
defaultMeasurementSystemstringRequired

CreateHouseholdRequest

PropertyTypeRequired
namestringRequired
timeZoneIdstringRequired
defaultDinnerTimestringRequired
preferredLanguagestring | null—
inviteCodestring | null—
countrystring | null—
sourcestring | null—

HouseholdLastActivityResponse

PropertyTypeRequired
lastWriteAtstring (date-time) | nullRequired
sourcestring | nullRequired

HouseholdResponse

PropertyTypeRequired
idstring (uuid)Required
namestringRequired
timeZoneIdstringRequired
defaultDinnerTimestringRequired
preferredLanguagestringRequired
countrystringRequired
preferOwnRecipesbooleanRequired
prefersLeftoverDinnersbooleanRequired
measurementSystemstringRequired
dryGoodsMeasurestringRequired
addressstring | nullRequired
loyaltyProgramsstring[]Required
createdAtstring (date-time)Required
updatedAtstring (date-time)Required
shareReceiptPricesboolean—
onboardingCompletedAtstring (date-time) | null—
shareUnitWeightsboolean—
tailorServingToTastesboolean—
showSoftServingAdviceboolean—
babyEatsSeparatelyWhenNeededboolean—
maxNewDishesPerWeekinteger (int32)—
alwaysNewDishesboolean—
pantryWeightstring—
useStarterLibraryboolean—
showChildTasksboolean—
madeAgainLiftboolean—
freezesPrepboolean—
currencystring—
countryProfileCountryProfileResponse | null—
lunchboxWeekdayPortionsinteger (int32) | null—
weekStartsOnstring—
saveGeneratedRecipesboolean—

OnboardingStep

Type

Values

PantryPeopleAllergiesRules

ProblemDetails

PropertyTypeRequired
typestring | null—
titlestring | null—
statusinteger (int32) | null—
detailstring | null—
instancestring | null—
codestring | null—

TimeZonesResponse

PropertyTypeRequired
idsstring[]Required

UpdateHouseholdRequest

PropertyTypeRequired
namestring | null—
timeZoneIdstring | null—
defaultDinnerTimestring | null—
preferredLanguagestring | null—
countrystring | null—
preferOwnRecipesboolean | null—
prefersLeftoverDinnersboolean | null—
lunchboxWeekdayPortionsinteger (int32) | null—
maxNewDishesPerWeekinteger (int32) | null—
alwaysNewDishesboolean | null—
pantryWeightstring | null—
addressstring | null—
loyaltyProgramsstring[] | null—
measurementSystemstring | null—
dryGoodsMeasurestring | null—
shareReceiptPricesboolean | null—
shareUnitWeightsboolean | null—
tailorServingToTastesboolean | null—
showSoftServingAdviceboolean | null—
babyEatsSeparatelyWhenNeededboolean | null—
useStarterLibraryboolean | null—
showChildTasksboolean | null—
madeAgainLiftboolean | null—
freezesPrepboolean | null—
currencystring | null—
weekStartsOnstring | null—
saveGeneratedRecipesboolean | null—