# Invite Protocol (Frontend <-> Backend)

This document defines the invite code contract for authenticated users.

Protocol verification status:

- Backend route source: `backend/src/v1/invite/router.py`
- Backend service source: `backend/src/v1/invite/service.py`
- Backend schema source: `backend/src/v1/invite/schemas.py`
- Frontend mapping source: `apps/lib/features/settings/data/apis/invite_api.dart`

## Compatibility strategy

- Additive evolution only.
- Existing response fields are stable and must remain backward-compatible.

## Route

### GET /api/v1/invite/me

Get the current user's invite code information.

**Authorization**: Requires authenticated session. User identity from JWT `sub`.

**Response (200)**:

```json
{
  "code": "ABC123XYZ",
  "used_count": 5
}
```

Field rules:

- `code`: string, unique invite code assigned to the user
- `used_count`: integer `>= 0`, number of times this code has been used

## Error contract linkage

- RFC7807 + extension `code`, optional `params`.
- Shared registry: `docs/protocols/common/http-error-codes.md`.
- Error codes for this feature:
  - `INVITE_CODE_NOT_FOUND` (404): Invite code not found for current user

## Data model linkage

- Invite codes are stored in `invite_codes` table.
- See `docs/protocols/common/user-points-chat-data-protocol.md` for `profiles.referred_by` field.