# KleioBase API

A REST API for reading and writing your own KleioBase genealogy research data - workspaces, people, families, records, places, events, conflicts, matches, findings, folders and tags, the Trash, past Research Companion conversations and GEDCOM import and export - over HTTPS and JSON. Included with the Researcher, Archivist and Professional plans.

- Base URL: https://kleiobase.com/api/v1
- Auth: `Authorization: Bearer kb_live_...`
- API keys: https://kleiobase.com/settings/developer
- OpenAPI document: https://kleiobase.com/api/v1/openapi.json
- Agent summary: https://kleiobase.com/developers/llms.txt

## Rules

- **Authentication.** Send `Authorization: Bearer kb_live_...` on every request. Keys are created at https://kleiobase.com/settings/developer and need a paid plan (Researcher, Archivist or Professional); an Explorer account gets `403 forbidden`. A read key can only call GET; writes need a read and write key. Stop on the first `401`. See https://kleiobase.com/developers/docs/authentication.
- **Workspaces.** Every resource lives under `/workspaces/{workspace_id}`. Call `GET /workspaces` first to find the id. See https://kleiobase.com/developers/docs/workspaces.
- **Pagination.** List endpoints take `limit` (default 25, maximum 100) and an opaque `cursor`, and return `{ data, next_cursor }`. Follow `next_cursor` until it is `null`; a page can be shorter than `limit`. See https://kleiobase.com/developers/docs/pagination.
- **Errors.** Errors are `{ "error": { "code", "message", "request_id", "details"? } }`. Branch on `code`, never on `message`. The set of codes is open, so treat an unknown code like its HTTP status class. See https://kleiobase.com/developers/docs/errors.
- **Idempotency.** Send an `Idempotency-Key` header (1 to 255 characters, kept 24 hours) on every write. The same key with the same request replays the original response; the same key with a different request is `409 conflict`. Uploads (`POST .../records`) are not idempotent. See https://kleiobase.com/developers/docs/idempotency.
- **Asynchronous processing.** `POST .../records/{record_id}/process` returns `202` and runs in the background. Poll `GET .../records/{record_id}` every few seconds until `status` is `review` or `failed`, review the extraction, then `POST .../records/{record_id}/confirm`. See https://kleiobase.com/developers/docs/uploads.
- **Background jobs.** GEDCOM imports and exports run in the background like record processing: the start request returns `202`, then poll `GET .../gedcom/imports/{import_id}` or `GET .../gedcom/exports/{export_id}` until the job is done. An import stops at `awaiting_confirmation` until you `POST .../confirm` it. The API never sends email. See https://kleiobase.com/developers/docs/background-jobs.
- **Bulk requests.** Bulk requests take at most 100 UUIDs and are all or nothing: if any id is not in the path workspace, the whole request is `404 not_found` and nothing changes. Deleting, merging and every other action is a single request. See https://kleiobase.com/developers/docs/trash.
- **Rate limits.** A limited request returns `429 rate_limited` with a `Retry-After` header in seconds. Wait that long, then retry. Limits are per account and shared by all of its keys. See https://kleiobase.com/developers/docs/rate-limits.
- **Response headers.** Every response carries `API-Version` and `Request-Id`. Quote the `Request-Id` when reporting a problem. See https://kleiobase.com/developers/docs/versioning.

## Guides

- [Getting started](https://kleiobase.com/developers/docs/getting-started): Create an API key, list your workspaces, and read your first people in a few minutes.
- [Authentication](https://kleiobase.com/developers/docs/authentication): How API keys work, the difference between read and read-write keys, and what happens when your plan changes.
- [Workspaces](https://kleiobase.com/developers/docs/workspaces): Every resource lives under a workspace id. How to find yours, create, rename, archive and restore workspaces, and what archived workspaces allow.
- [Pagination](https://kleiobase.com/developers/docs/pagination): How list endpoints page with limit and cursor.
- [Errors](https://kleiobase.com/developers/docs/errors): The error format and every error code the API returns.
- [Idempotency](https://kleiobase.com/developers/docs/idempotency): Make write requests safe to retry with the Idempotency-Key header.
- [MCP server](https://kleiobase.com/developers/docs/mcp): Connect Claude, ChatGPT or any MCP client to KleioBase. Sign in with OAuth or use an API key, then read, upload, process and confirm records through tools.
- [Uploads and processing](https://kleiobase.com/developers/docs/uploads): Upload a record, start AI extraction, poll for the result, review it and confirm. Includes credits and what happens when processing stalls.
- [Rate limits](https://kleiobase.com/developers/docs/rate-limits): How many requests and uploads your plan allows per minute, and what to do on a 429.
- [Versioning](https://kleiobase.com/developers/docs/versioning): What can change within v1, what counts as a breaking change, and how long old versions are supported.
- [People, families and merges](https://kleiobase.com/developers/docs/people-and-families): Read a person's close family and tree, add or remove relatives, merge and unmerge duplicates, and resolve conflicts.
- [Trash and bulk actions](https://kleiobase.com/developers/docs/trash): Move people and records to the Trash one at a time or in bulk, restore them, and delete them for good.
- [Folders and tags](https://kleiobase.com/developers/docs/organising): Organise people and records with folders and tags, and filter lists by them.
- [Places, search, notifications and health](https://kleiobase.com/developers/docs/places-and-search): Read places with their coordinates, search a workspace, read and clear notifications, and get the tree health score.
- [Research Companion conversations](https://kleiobase.com/developers/docs/conversations): Read past Research Companion conversations with their messages and attached files, rename them or delete them.
- [GEDCOM import and export](https://kleiobase.com/developers/docs/gedcom): Import a GEDCOM file into a workspace, and export a workspace as a GEDCOM file or GEDZIP archive.
- [Background jobs](https://kleiobase.com/developers/docs/background-jobs): Record processing, GEDCOM import and GEDCOM export run in the background. How to start them, poll them and act on the result.
- [API reference](https://kleiobase.com/developers/docs/reference): Every endpoint with its parameters, request bodies and responses.
- [API changelog](https://kleiobase.com/developers/changelog): Dated changes to the API.

Canonical: https://kleiobase.com/developers