# API reference

Every endpoint of the KleioBase API, grouped by resource and generated from the OpenAPI document at https://kleiobase.com/api/v1/openapi.json. Base URL: https://kleiobase.com/api/v1. Send `Authorization: Bearer kb_live_...` on every request.

## [Meta](https://kleiobase.com/developers/docs/reference/meta)

The API's own description: this OpenAPI document, readable without a key.

- `GET /openapi.json`: This document

## [Workspaces](https://kleiobase.com/developers/docs/reference/workspaces)

List, create, rename, archive and restore your workspaces. Every other resource lives under one.

- `GET /workspaces`: List workspaces
- `POST /workspaces`: Create a workspace
- `PATCH /workspaces/{workspace_id}`: Rename a workspace
- `POST /workspaces/{workspace_id}/archive`: Archive a workspace
- `POST /workspaces/{workspace_id}/restore`: Restore an archived workspace

## [People](https://kleiobase.com/developers/docs/reference/people)

Read, create, edit, merge, unmerge and delete the people in a workspace; read a person's timeline, close family, tree and expected records; add and remove relatives.

- `GET /workspaces/{workspace_id}/people`: List people
- `POST /workspaces/{workspace_id}/people`: Create a person
- `GET /workspaces/{workspace_id}/people/{person_id}`: Get a person
- `PATCH /workspaces/{workspace_id}/people/{person_id}`: Update a person
- `DELETE /workspaces/{workspace_id}/people/{person_id}`: Move a person to Trash
- `POST /workspaces/{workspace_id}/people/delete`: Move many people to Trash
- `GET /workspaces/{workspace_id}/people/{person_id}/timeline`: Get a person's timeline
- `POST /workspaces/{workspace_id}/people/{person_id}/merge`: Merge two people
- `GET /workspaces/{workspace_id}/people/{person_id}/family`: Get a person's parents, partners and children
- `GET /workspaces/{workspace_id}/people/{person_id}/tree`: Get tree data from a person
- `GET /workspaces/{workspace_id}/people/{person_id}/expected-records`: List records a person should have
- `POST /workspaces/{workspace_id}/people/{person_id}/relatives`: Add a relative
- `DELETE /workspaces/{workspace_id}/people/{person_id}/relatives`: Remove a relationship
- `POST /workspaces/{workspace_id}/people/{person_id}/unmerge`: Undo a merge
- `PATCH /workspaces/{workspace_id}/expected-records/{expected_record_id}`: Dismiss an expected record

## [Families](https://kleiobase.com/developers/docs/reference/families)

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

- `GET /workspaces/{workspace_id}/families`: List families
- `POST /workspaces/{workspace_id}/families`: Create a family
- `GET /workspaces/{workspace_id}/families/{family_id}`: Get a family
- `PATCH /workspaces/{workspace_id}/families/{family_id}`: Edit a couple's status or event
- `POST /workspaces/{workspace_id}/families/{family_id}/members`: Add a partner or child
- `DELETE /workspaces/{workspace_id}/families/{family_id}/members`: Remove a partner or child

## [Records](https://kleiobase.com/developers/docs/reference/records)

Upload a record, run AI extraction, review and confirm the result, link or unlink people, and move records to the Trash.

- `GET /workspaces/{workspace_id}/records`: List records
- `POST /workspaces/{workspace_id}/records`: Upload a record
- `GET /workspaces/{workspace_id}/records/{record_id}`: Get a record
- `PATCH /workspaces/{workspace_id}/records/{record_id}`: Edit a record's title or type
- `DELETE /workspaces/{workspace_id}/records/{record_id}`: Move a record to Trash
- `POST /workspaces/{workspace_id}/records/delete`: Move many records to Trash
- `GET /workspaces/{workspace_id}/records/{record_id}/image`: Get a signed image URL
- `POST /workspaces/{workspace_id}/records/{record_id}/process`: Start AI extraction
- `GET /workspaces/{workspace_id}/records/{record_id}/extraction`: Get the extraction
- `PATCH /workspaces/{workspace_id}/records/{record_id}/extraction`: Replace the extraction
- `POST /workspaces/{workspace_id}/records/{record_id}/confirm`: Confirm a reviewed record
- `POST /workspaces/{workspace_id}/records/{record_id}/people`: Link a person to a record
- `DELETE /workspaces/{workspace_id}/records/{record_id}/people`: Unlink a person from a record

## [Trash](https://kleiobase.com/developers/docs/reference/trash)

Trashed people and records: list, restore or permanently delete them.

- `GET /workspaces/{workspace_id}/trash`: List the Trash
- `POST /workspaces/{workspace_id}/trash/restore`: Restore from Trash
- `POST /workspaces/{workspace_id}/trash/delete`: Permanently delete from Trash

## [Places](https://kleiobase.com/developers/docs/reference/places)

Places derived from a workspace's people and confirmed records: list them, read one with its people and events, and get place-name suggestions.

- `GET /workspaces/{workspace_id}/places`: List places
- `GET /workspaces/{workspace_id}/places/{place_id}`: Get a place
- `GET /workspaces/{workspace_id}/places/suggestions`: Suggest place names

## [Events](https://kleiobase.com/developers/docs/reference/events)

Dated life events derived from people's facts, filterable by person and year.

- `GET /workspaces/{workspace_id}/events`: List events

## [Conflicts](https://kleiobase.com/developers/docs/reference/conflicts)

Conflicting facts in a workspace, computed on demand: resolve a person's competing birth families, or fold spelling variants of a fact into one value.

- `GET /workspaces/{workspace_id}/conflicts`: List conflicts
- `POST /workspaces/{workspace_id}/conflicts/resolve`: Resolve a birth-family conflict
- `POST /workspaces/{workspace_id}/conflicts/fact-variants/resolve`: Resolve spelling variants of a fact

## [Matches](https://kleiobase.com/developers/docs/reference/matches)

Suggested duplicate people: review them, then accept (merge) or reject. A group of duplicates can be merged in one request.

- `GET /workspaces/{workspace_id}/matches`: List pending match suggestions
- `POST /workspaces/{workspace_id}/matches/{match_id}/reject`: Reject a match
- `POST /workspaces/{workspace_id}/matches/{match_id}/accept`: Accept a match (merge)
- `POST /workspaces/{workspace_id}/matches/merge-group`: Merge a group of duplicates

## [Findings](https://kleiobase.com/developers/docs/reference/findings)

Research findings the app has detected, such as gaps: read, resolve or dismiss.

- `GET /workspaces/{workspace_id}/findings`: List findings
- `GET /workspaces/{workspace_id}/findings/{finding_id}`: Get a finding
- `POST /workspaces/{workspace_id}/findings/{finding_id}/resolve`: Resolve a finding
- `POST /workspaces/{workspace_id}/findings/{finding_id}/dismiss`: Dismiss a finding

## [Folders](https://kleiobase.com/developers/docs/reference/folders)

Folders for people and records: list, create, rename, move and delete them, and move items into one.

- `GET /workspaces/{workspace_id}/folders`: List folders
- `POST /workspaces/{workspace_id}/folders`: Create a folder
- `PATCH /workspaces/{workspace_id}/folders/{folder_id}`: Rename or move a folder
- `DELETE /workspaces/{workspace_id}/folders/{folder_id}`: Delete a folder
- `POST /workspaces/{workspace_id}/folders/{folder_id}/items`: Move items into a folder
- `POST /workspaces/{workspace_id}/folders/unfile`: Move items to the top level

## [Tags](https://kleiobase.com/developers/docs/reference/tags)

Tags for people and records: list, create, rename, recolour and delete them, and add or remove them on many items at once.

- `GET /workspaces/{workspace_id}/tags`: List tags
- `POST /workspaces/{workspace_id}/tags`: Create a tag
- `PATCH /workspaces/{workspace_id}/tags/{tag_id}`: Rename or recolour a tag
- `DELETE /workspaces/{workspace_id}/tags/{tag_id}`: Delete a tag
- `POST /workspaces/{workspace_id}/tags/apply`: Add or remove tags on items

## [Search](https://kleiobase.com/developers/docs/reference/search)

Search a workspace's people, records and places, as the app's search box.

- `GET /workspaces/{workspace_id}/search`: Search

## [Notifications](https://kleiobase.com/developers/docs/reference/notifications)

The notifications the app shows in a workspace: list them, count the unread ones, and mark them read.

- `GET /workspaces/{workspace_id}/notifications`: List notifications
- `GET /workspaces/{workspace_id}/notifications/unread-count`: Count unread notifications
- `POST /workspaces/{workspace_id}/notifications/read`: Mark notifications read

## [Health](https://kleiobase.com/developers/docs/reference/health)

The tree health score of a workspace, its pillars and suggested quick wins.

- `GET /workspaces/{workspace_id}/health`: Get the tree health score
- `POST /workspaces/{workspace_id}/health/refresh`: Recompute the tree health score

## [Conversations](https://kleiobase.com/developers/docs/reference/conversations)

Past Research Companion conversations: read them with their messages and attached files, rename or delete them. Nothing can be sent through the API.

- `GET /workspaces/{workspace_id}/conversations`: List conversations
- `GET /workspaces/{workspace_id}/conversations/{conversation_id}`: Get a conversation with its messages
- `PATCH /workspaces/{workspace_id}/conversations/{conversation_id}`: Rename a conversation
- `DELETE /workspaces/{workspace_id}/conversations/{conversation_id}`: Delete a conversation
- `GET /workspaces/{workspace_id}/conversations/{conversation_id}/files/{file_id}`: Get a download URL for an attached file

## [GEDCOM](https://kleiobase.com/developers/docs/reference/gedcom)

Import a GEDCOM file into a workspace, and export a workspace as GEDCOM. Both run in the background: start, then poll the job.

- `POST /workspaces/{workspace_id}/gedcom/imports`: Upload a GEDCOM file to import
- `GET /workspaces/{workspace_id}/gedcom/imports/{import_id}`: Get a GEDCOM import
- `DELETE /workspaces/{workspace_id}/gedcom/imports/{import_id}`: Cancel a GEDCOM import
- `POST /workspaces/{workspace_id}/gedcom/imports/{import_id}/confirm`: Confirm a GEDCOM import
- `POST /workspaces/{workspace_id}/gedcom/exports`: Export the workspace as GEDCOM
- `GET /workspaces/{workspace_id}/gedcom/exports/{export_id}`: Get a GEDCOM export
- `GET /workspaces/{workspace_id}/gedcom/exports/redaction-preview`: Preview who redact_living hides

Each group page lists parameters and responses; full request and response schemas are in the OpenAPI document.

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