Household API

All household endpoints require authentication. Creating or joining a household requires the Family subscription tier.

POST /household

Create a new household. The current user becomes the owner.

Auth required: Yes (Family tier)

Request body:

{
  "household": {
    "name": "The Does"
  }
}

Response (201):

{
  "household": {
    "id": 1,
    "name": "The Does",
    "invite_code": "ABC123",
    "is_owner": true,
    "members_count": 1,
    "created_at": "2026-05-26T10:00:00Z"
  }
}

Errors:

Status	Cause
403	Not on Family tier
422	Already in a household

curl -X POST http://localhost:3000/api/v1/household \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"household":{"name":"The Does"}}'

---

GET /household

Get the current user's household.

Auth required: Yes

Response (200):

{
  "household": {
    "id": 1,
    "name": "The Does",
    "invite_code": "ABC123",
    "is_owner": true,
    "members_count": 3,
    "created_at": "2026-05-26T10:00:00Z"
  }
}

Errors:

Status	Cause
404	User is not in a household

curl http://localhost:3000/api/v1/household \
  -H "Authorization: Bearer <token>"

---

PATCH /household

Update the household name. Owner only.

Auth required: Yes (owner)

Request body:

{
  "household": {
    "name": "Doe Family"
  }
}

Response (200):

{
  "household": { ... }
}

Errors:

Status	Cause
403	Not the household owner

curl -X PATCH http://localhost:3000/api/v1/household \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"household":{"name":"Doe Family"}}'

---

DELETE /household

Delete the household. Owner only. Removes all members and unassigns all household tasks.

Auth required: Yes (owner)

Response: 204 No Content

curl -X DELETE http://localhost:3000/api/v1/household \
  -H "Authorization: Bearer <token>"

---

POST /household/join

Join an existing household using an invite code.

Auth required: Yes (Family tier)

Request body:

{
  "invite_code": "ABC123"
}

Response (200):

{
  "household": { ... }
}

Errors:

Status	Cause
403	Not on Family tier
404	Invalid invite code
422	Already in a household, or code blank

curl -X POST http://localhost:3000/api/v1/household/join \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"invite_code":"ABC123"}'

---

DELETE /household/leave

Leave the current household.

Auth required: Yes

If the owner leaves and other members exist, ownership transfers to another member. If no other members exist, the household is deleted.

Response: 204 No Content

Errors:

Status	Cause
404	Not in a household
422	Failed to leave

curl -X DELETE http://localhost:3000/api/v1/household/leave \
  -H "Authorization: Bearer <token>"

---

POST /household/regenerate_code

Generate a new invite code, invalidating the previous one. Owner only.

Auth required: Yes (owner)

Response (200):

{
  "household": {
    "id": 1,
    "name": "The Does",
    "invite_code": "XYZ789",
    "is_owner": true,
    "members_count": 3,
    "created_at": "2026-05-26T10:00:00Z"
  }
}

curl -X POST http://localhost:3000/api/v1/household/regenerate_code \
  -H "Authorization: Bearer <token>"

---

GET /household/members

List all members of the current household.

Auth required: Yes

Response (200):

{
  "members": [
    { "id": 1, "name": "Jane Doe", "email": "jane@example.com", "is_owner": true },
    { "id": 2, "name": "John Doe", "email": "john@example.com", "is_owner": false }
  ]
}

curl http://localhost:3000/api/v1/household/members \
  -H "Authorization: Bearer <token>"

---

DELETE /household/members/:id

Remove a member from the household. Owner only. Cannot remove yourself (use leave instead).

Auth required: Yes (owner)

Unassigns any tasks assigned to the removed member within the household.

Response: 204 No Content

Errors:

Status	Cause
403	Not the household owner
422	Trying to remove yourself

curl -X DELETE http://localhost:3000/api/v1/household/members/2 \
  -H "Authorization: Bearer <token>"