Invites¶

Manage household invitation codes. Invites allow household owners to share a code or QR image that other authenticated users can accept to join the household. All endpoints are prefixed with /api/v1/households/:hid/invites.

POST /households/:hid/invites¶

Generate a new invite code with an associated QR code image.

Path parameters¶

Response 201 Created¶

{
  "id": "clh4d5e6f0004qw08g1h2i3j4",
  "code": "ABCD-1234-EFGH",
  "qrDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "expiresAt": "2025-01-22T09:00:00.000Z"
}

Example¶

curl -X POST http://localhost:3000/api/v1/households/clh3a1b2c0001qw08k5m7n9p0/invites \
  -H "Authorization: Bearer <accessToken>"

GET /households/:hid/invites¶

List all active (non-expired, non-revoked) invites for a household.

Path parameters¶

Response 200 OK¶

[
  {
    "id": "clh4d5e6f0004qw08g1h2i3j4",
    "code": "ABCD-1234-EFGH",
    "qrDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expiresAt": "2025-01-22T09:00:00.000Z"
  }
]

Example¶

curl http://localhost:3000/api/v1/households/clh3a1b2c0001qw08k5m7n9p0/invites \
  -H "Authorization: Bearer <accessToken>"

DELETE /households/:hid/invites/:inviteId¶

Revoke an invite code so it can no longer be used.

Path parameters¶

Response 200 OK¶

{
  "message": "Invite revoked successfully"
}

Example¶

curl -X DELETE http://localhost:3000/api/v1/households/clh3a1b2c0001qw08k5m7n9p0/invites/clh4d5e6f0004qw08g1h2i3j4 \
  -H "Authorization: Bearer <accessToken>"

POST /households/:hid/invites/accept¶

Accept an invite code to join the household as a MEMBER.

Path parameters¶

Request body¶

{
  "code": "ABCD-1234-EFGH"
}

Response 200 OK¶

{
  "message": "Successfully joined household"
}

Errors¶

Example¶

curl -X POST http://localhost:3000/api/v1/households/clh3a1b2c0001qw08k5m7n9p0/invites/accept \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <accessToken>" \
  -d '{ "code": "ABCD-1234-EFGH" }'