Households

A household is a group of users who share part of their libraries. Sharing is opt-in per resource — joining a household does not expose everything you own.

Creating and joining

curl -X POST https://api.flambe.dev/api/households \
  -H "Authorization: Bearer $FLAMBE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Kitchen" }'

The creator becomes the owner. Members are owner, admin or member.

Invite by email for someone who may not have an account yet, or by user id for an existing user:

curl -X POST "https://api.flambe.dev/api/households/$HOUSEHOLD_ID/invites" \
  -H "Authorization: Bearer $FLAMBE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "recipient_email": "partner@example.com", "role": "member" }'

The invite carries a token. The recipient redeems it — authenticated, so the invite binds to whoever accepts:

curl -X POST "https://api.flambe.dev/api/households/invites/$TOKEN/accept" \
  -H "Authorization: Bearer $RECIPIENT_TOKEN"

GET /api/households/me lists the households the caller belongs to.

Sharing a resource

Nothing is shared until you grant it. Recipes, collections, meal plans and grocery lists can each be shared, as viewer or editor:

curl -X POST "https://api.flambe.dev/api/households/$HOUSEHOLD_ID/library/recipe" \
  -H "Authorization: Bearer $FLAMBE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "resource_id": "9b8a7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d", "role": "viewer" }'

GET /api/households/{id}/library returns everything shared into the household by anyone. Shared recipes also appear in the member's own GET /api/recipes, which is why a library can contain recipes the caller does not own.

Driving a share picker

Two endpoints exist specifically for a checkbox UI:

• GET /api/households/{id}/library/my-resources/{resourceType} — the caller's own resources of that type, each annotated with whether it is currently shared.
• PUT /api/households/{id}/library/{resourceType}/bulk — sets the complete set of grants in one call.

curl -X PUT "https://api.flambe.dev/api/households/$HOUSEHOLD_ID/library/recipe/bulk" \
  -H "Authorization: Bearer $FLAMBE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "grants": [{ "resource_id": "9b8a7c6d-...", "role": "editor" }] }'

{ "granted": 1, "revoked": 3 }

Defaults

GET and PUT /api/households/{id}/sharing/preferences hold the caller's per-household defaults — for example, whether newly created recipes are shared automatically. Read these before presenting a share dialog so the UI reflects what will actually happen.

Leaving and removing

When a member leaves or is removed, the resources they shared stop being visible to everyone else. Syncing clients see those ids in revoked_ids — see Syncing.

Copies, not references

POST /api/recipes/{id}/save-copy takes an independent copy of a shared recipe into the caller's own library. It keeps working after the original is un-shared, and it does not track later edits to the original. Use it when someone wants to keep a recipe permanently; rely on the share when they want to see updates.

Leaving a single resource

A member who wants out of one shared collection or grocery list, without leaving the household, can use POST /api/collections/{id}/leave or POST /api/grocery-lists/{id}/leave. The owner's copy is untouched. Owners cannot leave their own resource — they delete it instead.