Memberships & invites

Who belongs to which household, and how they got in.8 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

POST/api/v1/invites/accept

Join a household with an invite code

Any signed-in user; no household membership needed. Safe to retry: a caller who already belongs to the household answers 200 with the existing membership and the code stays unused. 400 when the code is unknown, expired or already used. A code made for a named person links the new account to them, unless that person has since been claimed or removed — then the join is unlinked. Everyone in the household gets a «joined» push (#254).

Parameters

No parameters

Request body

application/jsonRequiredAcceptInviteRequest

Responses

200OK

application/jsonMembershipResponse

400Bad Request

application/problem+jsonProblemDetails

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.

Problem codes

The `code` in the problem body is what to branch on. `detail` is English, written for a log.

invite_not_usable: — That invitation has expired or was already used. Ask for a new one.

Example

curl -b "bryti_session=…" \
  -X POST \
  "https://bryti.app/api/v1/invites/accept" \
  -H "Content-Type: application/json" \
  -d '{"code":"string"}'

Example response

200application/json

{
  "householdId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "householdName": "string",
  "role": "Owner",
  "memberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

GET/api/v1/households/{householdId}/memberships

List the accounts in the household with their role and linked person

Parameters

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

Responses

200OK

application/jsonHouseholdMembershipResponse[]

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

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/memberships"

Example response

200application/json

[
  {
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "displayName": "string",
    "email": "string",
    "role": "Owner",
    "memberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
]

PATCH/api/v1/households/{householdId}/memberships/{userId}

Change an account's role in the household

Owner only. 400 when the change would leave the household without an owner.

Parameters

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

Request body

application/jsonRequiredChangeMembershipRoleRequest

Responses

204No Content

400The request could not be read as the route needs it: a body that is not the documented shape (a required field left out, a null where none is allowed, a value too long for its field), a parameter that does not parse, or a NUL character anywhere (#3540, #3541, #3543). Code validation_failed or value_too_long.

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/memberships/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{"role":"Owner"}'

DELETE/api/v1/households/{householdId}/memberships/{userId}

Leave the household, or remove another account from it

Any member may remove their own membership; removing someone else is owner only (403 otherwise). 400 when the account is the household's last owner. The linked person, if any, stays in the household.

Parameters

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

Responses

204No Content

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.

Problem codes

The `code` in the problem body is what to branch on. `detail` is English, written for a log.

owner_required_remove_member: — Only an owner can remove someone else from the household.

Example

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

PATCH/api/v1/households/{householdId}/memberships/{userId}/member

Link an account to the household person it belongs to, or unlink it

Any member may link their own account; linking someone else's is owner only (403 otherwise). memberId null unlinks. 400 when the person is not in this household. Planning uses the link to know who «you» are.

Parameters

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

Request body

application/jsonRequiredLinkMembershipMemberRequest

Responses

204No Content

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.

Problem codes

The `code` in the problem body is what to branch on. `detail` is English, written for a log.

owner_required_link_member: — Only an owner can connect someone else to a person in the household.

Example

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

GET/api/v1/households/{householdId}/invites

List the household's pending invites

Owner only. Only unused, unexpired invites are listed; the codes themselves are never returned.

Parameters

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

Responses

200OK

application/jsonInviteResponse[]

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

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/invites"

Example response

200application/json

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "role": "Owner",
    "expiresAt": "2026-09-07T16:30:00Z",
    "createdAt": "2026-09-07T16:30:00Z",
    "memberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "memberName": "string"
  }
]

POST/api/v1/households/{householdId}/invites

Create a single-use invite code for a role, optionally for a named person

Owner only. The code is returned exactly once, here — only its hash is stored — and expires after 7 days. 400 when the named person is not in this household, already has an account, or already has a pending invite.

Parameters

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

Request body

application/jsonRequiredCreateInviteRequest

Responses

200OK

application/jsonInviteCreatedResponse

400Bad Request

application/problem+jsonProblemDetails

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

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/invites" \
  -H "Content-Type: application/json" \
  -d '{"role":"Owner"}'

Example response

200application/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code": "string",
  "role": "Owner",
  "expiresAt": "2026-09-07T16:30:00Z",
  "memberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

DELETE/api/v1/households/{householdId}/invites/{inviteId}

Revoke an invite so its code can no longer be used

Owner only.

Parameters

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

Responses

204No Content

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 DELETE \
  "https://bryti.app/api/v1/households/3fa85f64-5717-4562-b3fc-2c963f66afa6/invites/3fa85f64-5717-4562-b3fc-2c963f66afa6"

Schemas

AcceptInviteRequest

Property	Type	Required
`code`	`string`	Required

ChangeMembershipRoleRequest

Property	Type	Required
`role`	`HouseholdRole`	Required

CreateInviteRequest

Property	Type	Required
`role`	`HouseholdRole`	Required
`memberId`	`string (uuid) \| null`	—

HouseholdMembershipResponse

Property	Type	Required
`userId`	`string (uuid)`	Required
`displayName`	`string`	Required
`email`	`string \| null`	Required
`role`	`HouseholdRole`	Required
`memberId`	`string (uuid) \| null`	Required

HouseholdRole

Type

Values

OwnerAdultJunior

InviteCreatedResponse

Property	Type	Required
`id`	`string (uuid)`	Required
`code`	`string`	Required
`role`	`HouseholdRole`	Required
`expiresAt`	`string (date-time)`	Required
`memberId`	`string (uuid) \| null`	Required

InviteResponse

Property	Type	Required
`id`	`string (uuid)`	Required
`role`	`HouseholdRole`	Required
`expiresAt`	`string (date-time)`	Required
`createdAt`	`string (date-time)`	Required
`memberId`	`string (uuid) \| null`	Required
`memberName`	`string \| null`	Required

LinkMembershipMemberRequest

Property	Type	Required
`memberId`	`string (uuid) \| null`	Required

MembershipResponse

Property	Type	Required
`householdId`	`string (uuid)`	Required
`householdName`	`string`	Required
`role`	`HouseholdRole`	Required
`memberId`	`string (uuid) \| null`	Required

ProblemDetails

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