Family Tree API

28 endpoints.

Method	Path	Summary
`GET`	`/api/communities/{communityId}/family-tree`	Get the whole family tree
`POST`	`/api/communities/{communityId}/family-tree/{husbandId}/spouses`	Add a wife
`DELETE`	`/api/communities/{communityId}/family-tree/{id}`	Delete a card and its descendants
`GET`	`/api/communities/{communityId}/family-tree/{id}`	Get one card
`PATCH`	`/api/communities/{communityId}/family-tree/{id}`	Edit a card
`GET`	`/api/communities/{communityId}/family-tree/{id}/delete-preview`	Preview a delete cascade
`DELETE`	`/api/communities/{communityId}/family-tree/{id}/edit-grant`	Revoke the edit grant on a card
`GET`	`/api/communities/{communityId}/family-tree/{id}/edit-grant`	Get the edit grant on a card
`POST`	`/api/communities/{communityId}/family-tree/{id}/edit-grant`	Grant one member edit access to an unlinked card
`POST`	`/api/communities/{communityId}/family-tree/{id}/father`	Insert a father above a card
`POST`	`/api/communities/{communityId}/family-tree/{id}/relatives/bulk`	Add several children and wives at once
`POST`	`/api/communities/{communityId}/family-tree/{parentId}/children`	Add a child
`POST`	`/api/communities/{communityId}/family-tree/{parentId}/reorder`	Reorder children
`GET`	`/api/communities/{communityId}/family-tree/branches`	List family branches (فخذ)
`POST`	`/api/communities/{communityId}/family-tree/branches`	Create a branch
`DELETE`	`/api/communities/{communityId}/family-tree/branches/{branchId}`	Delete a branch
`PATCH`	`/api/communities/{communityId}/family-tree/branches/{branchId}`	Update a branch
`GET`	`/api/communities/{communityId}/family-tree/linkable-members`	List members that can be linked to a card
`POST`	`/api/communities/{communityId}/family-tree/me/viewed`	Mark my own card as viewed
`GET`	`/api/communities/{communityId}/family-tree/requests`	List all change requests
`POST`	`/api/communities/{communityId}/family-tree/requests`	Submit a change request
`GET`	`/api/communities/{communityId}/family-tree/requests/{id}`	Get one change request
`POST`	`/api/communities/{communityId}/family-tree/requests/{id}/approve`	Approve a change request
`POST`	`/api/communities/{communityId}/family-tree/requests/{id}/cancel`	Cancel my pending request
`POST`	`/api/communities/{communityId}/family-tree/requests/{id}/reject`	Reject a change request
`POST`	`/api/communities/{communityId}/family-tree/requests/bulk`	Submit several ADD_RELATIVE requests
`GET`	`/api/communities/{communityId}/family-tree/requests/mine`	List my change requests
`POST`	`/api/communities/{communityId}/family-tree/root`	Create the root card

Get the whole family tree

GET /api/communities/{communityId}/family-tree

Every card in the community tree, ordered by sortKey. grantedToMe marks cards the caller may edit directly. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—

Add a wife

POST /api/communities/{communityId}/family-tree/{husbandId}/spouses

Husband must be a male bloodline card. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`husbandId`	path	yes	string (uuid)	—

Request body (required) — multipart/form-data

Field	Type	Required	Description
`payload`	string	no	JSON FamilyMemberCreate
`familyPhoto`	string (binary)	no	—

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Delete a card and its descendants

DELETE /api/communities/{communityId}/family-tree/{id}

Requires ?confirmed=true (otherwise 400 CONFIRM_REQUIRED); the root cannot be deleted. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—
`confirmed`	query	yes	enum: `true`	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Get one card

GET /api/communities/{communityId}/family-tree/{id}

Any member. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Edit a card

PATCH /api/communities/{communityId}/family-tree/{id}

With tree:manage, or an edit grant on this card (grantees cannot change the link). linkedMemberId must be an APPROVED member (400 INVALID_LINKED_MEMBER). The photo comes only from familyPhoto. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Request body (required) — multipart/form-data

Field	Type	Required	Description
`payload`	string	no	JSON partial FamilyMemberCreate
`familyPhoto`	string (binary)	no	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Preview a delete cascade

GET /api/communities/{communityId}/family-tree/{id}/delete-preview

Lists every card that would be removed. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Revoke the edit grant on a card

DELETE /api/communities/{communityId}/family-tree/{id}/edit-grant

Idempotent. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Get the edit grant on a card

GET /api/communities/{communityId}/family-tree/{id}/edit-grant

Null when none. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Grant one member edit access to an unlinked card

POST /api/communities/{communityId}/family-tree/{id}/edit-grant

userId is the User.id of an APPROVED member. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Request body (required) — application/json

Field	Type	Required	Description
`userId`	string	yes	—

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—
`409`	CARD_ALREADY_LINKED	—

Insert a father above a card

POST /api/communities/{communityId}/family-tree/{id}/father

Payload { father, includeSiblingIds }. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Request body (required) — multipart/form-data

Field	Type	Required	Description
`payload`	string	no	JSON `father, includeSiblingIds`
`familyPhoto`	string (binary)	no	—

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Add several children and wives at once

POST /api/communities/{communityId}/family-tree/{id}/relatives/bulk

JSON only, no photos. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Request body (required) — application/json

Type: FamilyRelativesBulk

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Add a child

POST /api/communities/{communityId}/family-tree/{parentId}/children

Parent must be a male bloodline card. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`parentId`	path	yes	string (uuid)	—

Request body (required) — multipart/form-data

Field	Type	Required	Description
`payload`	string	no	JSON FamilyMemberCreate; gender is REQUIRED for a child, motherId optional
`familyPhoto`	string (binary)	no	—

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Reorder children

POST /api/communities/{communityId}/family-tree/{parentId}/reorder

Body must list exactly the current bloodline children. Allowed with tree:manage or an edit grant on the parent card. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`parentId`	path	yes	string (uuid)	—

Request body (required) — application/json

Type: FamilyTreeReorder

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—

List family branches (فخذ)

GET /api/communities/{communityId}/family-tree/branches

Any member. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—

Create a branch

POST /api/communities/{communityId}/family-tree/branches

Creates a فخذ tag. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—

Request body (required) — application/json

Type: FamilyBranchCreate

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`409`	BRANCH_NAME_TAKEN	—

Delete a branch

DELETE /api/communities/{communityId}/family-tree/branches/{branchId}

Cards in it are untagged. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`branchId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Update a branch

PATCH /api/communities/{communityId}/family-tree/branches/{branchId}

Rename or recolour. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`branchId`	path	yes	string (uuid)	—

Request body (required) — application/json

Type: FamilyBranchWrite

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—
`409`	BRANCH_NAME_TAKEN	—

List members that can be linked to a card

GET /api/communities/{communityId}/family-tree/linkable-members

APPROVED members not yet linked to any card. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`excludeFamilyMemberId`	query	no	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—

Mark my own card as viewed

POST /api/communities/{communityId}/family-tree/me/viewed

Idempotent; suppresses the follow-up nudge. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—

List all change requests

GET /api/communities/{communityId}/family-tree/requests

Filters: status, requestType, userId, familyMemberId, page, limit. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`status`	query	no	enum: `PENDING`, `APPROVED`, `REJECTED`, `CANCELLED`	—
`requestType`	query	no	enum: `EDIT_SELF`, `ADD_RELATIVE`, `DELETE_SELF`, `EDIT_CHILD`, `DELETE_CHILD`	—
`userId`	query	no	string	—
`familyMemberId`	query	no	string (uuid)	—
`page`	query	no	integer	—
`limit`	query	no	integer	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—

Submit a change request

POST /api/communities/{communityId}/family-tree/requests

Linked members request EDIT_SELF, ADD_RELATIVE, DELETE_SELF, EDIT_CHILD or DELETE_CHILD. Only the photo in familyPhoto is kept; linkedMemberId and photoKey inside the payload are ignored. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—

Request body (required) — multipart/form-data

Field	Type	Required	Description
`payload`	string	no	JSON FamilyTreeRequestCreate
`familyPhoto`	string (binary)	no	—

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`409`	PENDING_REQUEST_EXISTS — `data.existingRequestId` names the open request	—

Get one change request

GET /api/communities/{communityId}/family-tree/requests/{id}

Owner, or a holder of tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—

Approve a change request

POST /api/communities/{communityId}/family-tree/requests/{id}/approve

Atomic; a second approve returns 409 REQUEST_NOT_PENDING. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—
`409`	REQUEST_NOT_PENDING (`data.currentStatus`), or TARGET_NO_LONGER_ELIGIBLE — card relinked or moved; the request is auto-rejected	—

Cancel my pending request

POST /api/communities/{communityId}/family-tree/requests/{id}/cancel

Owner only; anyone else gets 403 REQUEST_NOT_OWNED. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—
`409`	REQUEST_NOT_PENDING (`data.currentStatus`)	—

Reject a change request

POST /api/communities/{communityId}/family-tree/requests/{id}/reject

Optional rejectionReason. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—
`id`	path	yes	string (uuid)	—

Request body — application/json

Field	Type	Required	Description
`rejectionReason`	string	no	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`404`	Not found	—
`409`	REQUEST_NOT_PENDING (`data.currentStatus`)	—

Submit several ADD_RELATIVE requests

POST /api/communities/{communityId}/family-tree/requests/bulk

Under the caller's own linked card, JSON only. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—

Request body (required) — application/json

Type: FamilyTreeBulkRequest

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—

List my change requests

GET /api/communities/{communityId}/family-tree/requests/mine

Always scoped to the caller. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—

Responses

Status	Description	Body
`200`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—

Create the root card

POST /api/communities/{communityId}/family-tree/root

Only one root per community. Requires tree:manage. Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`—`	—	no	—	—

Request body (required) — multipart/form-data

Field	Type	Required	Description
`payload`	string	no	JSON FamilyMemberCreate
`familyPhoto`	string (binary)	no	—

Responses

Status	Description	Body
`201`	Success	—
`400`	Validation error with a stable `code` (e.g. INVALID_PAYLOAD_JSON, BAD_JSON)	—
`401`	Missing or invalid token	—
`403`	Not a member, missing permission, or FEATURE_NOT_AVAILABLE	—
`409`	ROOT_EXISTS	—