Household / Family

The Family tier enables household sharing, where multiple users can collaborate on tasks within a shared household.

Creating a Household

Family-tier users can create a household with a name. The creator becomes the owner and receives an auto-generated invite code.

POST /api/v1/household

A user can only belong to one household at a time.

Joining a Household

Other Family-tier users join by entering the invite code:

POST /api/v1/household/join

The code is case-insensitive and stripped of whitespace.

Invite Codes

Each household has a unique invite code. The owner can regenerate it at any time (invalidating the old one):

POST /api/v1/household/regenerate_code

Shared Tasks

Tasks can be shared with the household by assigning them to another member:

• When creating or editing a task, set assigned_to_id to a household member's ID
• The task automatically gets a household_id, making it visible to all members
• Tasks assigned to yourself remain personal (no household_id)

Members see shared tasks in their task list alongside personal tasks. The is_mine flag in the task JSON helps the UI distinguish ownership.

Family Visibility Toggle

Each user has a family_visibility setting (updated via PATCH /api/v1/auth/settings):

• On: The user sees all household tasks (their own + assigned to them + all other household tasks)
• Off: The user only sees tasks they created or tasks assigned to them

This gives household members control over how much they see.

Member Management

The household owner can:

• View all members: GET /api/v1/household/members
• Remove a member: DELETE /api/v1/household/members/:id

When a member is removed, their assigned tasks in the household are unassigned.

Leaving a Household

Any member can leave voluntarily:

DELETE /api/v1/household/leave

If the owner leaves:

• If other members exist, ownership transfers to the next member
• If no other members exist, the household is deleted

Shared AI Pool

Family households share an AI usage pool (200 tasks/month for the household). When the pool is depleted, each member gets a small daily emergency allocation to avoid complete lockout. Usage details are returned in the AI usage endpoint.

Deleting a Household

Only the owner can delete the household. This removes all members and unassigns all household tasks:

DELETE /api/v1/household