Family Module

Project: Pet Feeder | page_id: 1727

Family Authentication Interface Documentation

Overview

• Base path: /api
• Documentation scope: family module interfaces in the authenticated routes
• Authentication method: request header X-Token
• Content-Type: application/json

Authentication Header

Unified Response Format

{
  "code": 200,
  "msg": "Operation successful",
  "data": {}
}

Response Field Description

Family Object Field Description

Family Detail Member Field Description

1. Get the Family List

• Path: /api/family/list
• Method: POST
• Authentication required: Yes

Request Body

No business parameters; an empty object can be passed:

{}

Success Response Example

{
  "code": 200,
  "msg": "Operation successful",
  "data": [
    {
      "id": "family_001",
      "name": "My Family",
      "ownerId": 1,
      "createdAt": "2026-05-09T10:00:00Z",
      "updatedAt": "2026-05-09T10:00:00Z"
    }
  ]
}

Response Parameter Description

Failure Response Example

{
  "code": 500,
  "msg": "Failed to get the family list",
  "data": null
}

2. Get Family Details

• Path: /api/family/detail
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "id": "family_001"
}

Success Response Example

{
  "code": 200,
  "msg": "Operation successful",
  "data": {
    "id": "family_001",
    "name": "My Family",
    "ownerId": 1,
    "members": [
      {
        "id": 1,
        "nickname": "Xiaoming",
        "phone": "13800138000",
        "role": "owner"
      }
    ],
    "createdAt": "2026-05-09T10:00:00Z"
  }
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "Parameter error",
  "data": null
}

{
  "code": 404,
  "msg": "Family does not exist",
  "data": null
}

3. Create a Family

• Path: /api/family/create
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "name": "My Family"
}

Success Response Example

{
  "code": 200,
  "msg": "Family created successfully",
  "data": {
    "id": "family_001",
    "name": "My Family",
    "ownerId": 1,
    "createdAt": "2026-05-09T10:00:00Z",
    "updatedAt": "2026-05-09T10:00:00Z"
  }
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "The family name cannot exceed 30 characters",
  "data": null
}

{
  "code": 400,
  "msg": "The family name can only contain Chinese characters, letters, digits, underscores and hyphens",
  "data": null
}

4. Change the Family Name

• Path: /api/family/updateName
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "familyId": "family_001",
  "name": "New family name"
}

Success Response Example

{
  "code": 200,
  "msg": "Family name changed successfully",
  "data": null
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "Family does not exist",
  "data": null
}

{
  "code": 400,
  "msg": "Only the family creator can change the family name",
  "data": null
}

5. Generate an Invitation Link

• Path: /api/family/invite
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "familyId": "family_001"
}

Success Response Example

{
  "code": 200,
  "msg": "Invitation link generated",
  "data": {
    "inviteCode": "a1b2c3d4",
    "inviteUrl": "https://example.com/invite/a1b2c3d4",
    "expireSeconds": 86400
  }
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "Family does not exist",
  "data": null
}

{
  "code": 400,
  "msg": "Only the family creator can invite members",
  "data": null
}

{
  "code": 400,
  "msg": "Operation failed, please try again",
  "data": null
}

{
  "code": 400,
  "msg": "Failed to generate the invitation code, please try again",
  "data": null
}

6. Join a Family with an Invitation Code

• Path: /api/family/join
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "inviteCode": "a1b2c3d4"
}

Success Response Example

{
  "code": 200,
  "msg": "Joined successfully",
  "data": {
    "familyId": "family_001",
    "familyName": "My Family"
  }
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "Parameter error",
  "data": null
}

{
  "code": 400,
  "msg": "You are already a member of this family",
  "data": null
}

7. Remove a Member

• Path: /api/family/removeMember
• Method: POST
• Authentication required: Yes

Request Body Parameters

Request Example

{
  "familyId": "family_001",
  "memberId": 2
}

Success Response Example

{
  "code": 200,
  "msg": "Member removed",
  "data": null
}

Response Parameter Description

Failure Response Example

{
  "code": 400,
  "msg": "Family does not exist",
  "data": null
}

{
  "code": 400,
  "msg": "Only the family creator can remove members",
  "data": null
}

{
  "code": 400,
  "msg": "You cannot remove yourself",
  "data": null
}

Appendix

Description

• family/list currently does not read the business request body; either an empty object or an empty body works.
• This document only covers the authenticated routes and does not include the public invitation page /invite/:code.

Failure Response Example

{
  "code": 400,
  "msg": "Family does not exist",
  "data": null
}

{
  "code": 400,
  "msg": "Only the family creator can remove members",
  "data": null
}

{
  "code": 400,
  "msg": "You cannot remove yourself",
  "data": null
}

Appendix

Description

• family/list currently does not read the business request body; either an empty object or an empty body works.
• This document only covers the authenticated routes and does not include the public invitation page /invite/:code.