# Families endpoints

Read and create families, edit a couple's status or events, and add or remove partners and children.

Paths are relative to https://kleiobase.com/api/v1. Request and response schemas are in the OpenAPI document at https://kleiobase.com/api/v1/openapi.json.

## List families

`GET /workspaces/{workspace_id}/families`

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `limit` (query, optional): Page size. Default 25, max 100.
- `cursor` (query, optional): The next_cursor of the previous page. Opaque.

Responses:

- `200`: A page of families.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner.
- `422`: Invalid limit or cursor.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Create a family

`POST /workspaces/{workspace_id}/families`

1-2 partner_ids are required; children are optional. At least two people in total. The 201 body carries warnings when an extra child could not be attached. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `201`: The created family.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required). Also: the plan's person limit is reached.
- `404`: The workspace does not exist or is not visible to this key's owner. Also: A person does not exist or is not visible.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Get a family

`GET /workspaces/{workspace_id}/families/{family_id}`

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `family_id` (path, required): The family id.

Responses:

- `200`: The family.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The family does not exist or is not visible.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Edit a couple's status or event

`PATCH /workspaces/{workspace_id}/families/{family_id}`

Set the relationship status, one family event, or both. Setting the same event again replaces it. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `family_id` (path, required): The family id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: The updated family.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The family does not exist or is not visible.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, an empty body, or EVEN without a type.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Add a partner or child

`POST /workspaces/{workspace_id}/families/{family_id}/members`

Matching is queued, never run inline. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `family_id` (path, required): The family id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: The updated family.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The family or person does not exist or is not visible.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: The person is already in the family, or the partner slot is taken.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, or pedigree sent for a partner.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Remove a partner or child

`DELETE /workspaces/{workspace_id}/families/{family_id}/members`

People are not deleted. If removing the last partner leaves an empty family, the family is removed and the response is {ok, family_deleted, id}. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `family_id` (path, required): The family id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: The updated family, or a family_deleted notice.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner. Also: The family does not exist, or the person is not in that role in it.
- `409`: The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

Canonical: https://kleiobase.com/developers/docs/reference/families