GEDCOM import and export

GEDCOM is how genealogy programs exchange family trees. Both directions run in the background: you start a job, then poll it. See Background jobs for the polling pattern.

Import

1. Upload the file

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/gedcom/imports \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -F "file=@family-tree.ged"

A .ged file can be up to 75 MB, a .gdz (GEDZIP) archive up to 300 MB. A GEDZIP archive named .zip is accepted too. You get 202 with the job's id in status analyzing. Nothing is added to the workspace yet.

The upload is not idempotent: a retry uploads the file again. It counts against both your request and upload rate limits.

2. Check the analysis

Poll GET .../gedcom/imports/{import_id} until status is awaiting_confirmation. Then:

• analysis says what the file holds: people, families, sources, events, media, and how many people are already in this workspace from an earlier import (existing_people, changed_people). Sources are counted but not imported: an import adds people and families.
• cap_check, cap_check_skip and cap_check_changed say whether each import mode fits your plan's person limit (allowed).

3. Confirm or cancel

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/gedcom/imports/IMPORT_ID/confirm \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: confirm-import-1" \
  -H "Content-Type: application/json" \
  -d '{"mode": "skip"}'

• all (the default) imports everyone in the file.
• skip leaves out people already in the workspace.
• changed is like skip, but also imports existing people who changed in the file. It needs the Researcher plan or above.

You get 202. Poll the job until status is completed, when result says what was added. An import that would pass your plan's person limit is refused with 403 forbidden.

To cancel instead, send DELETE .../gedcom/imports/{import_id}. Nothing is added and the uploaded file is deleted. An import left unconfirmed expires after about an hour, and its file is deleted then.

Export

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/gedcom/exports \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: export-1" \
  -H "Content-Type: application/json" \
  -d '{"version": "7.0.18", "format": "ged", "redact_living": true}'

All fields are optional:

• version: 7.0.18 (default) or 5.5.1.
• format: ged (default) for the tree as text, or gdz for a GEDZIP archive with the record images.
• filename: the base name of the downloaded file. Default kleiobase-export.
• redact_living: leave out the details of living people. GET .../gedcom/exports/redaction-preview lists who that is.

You get 202 with the job's id. Poll GET .../gedcom/exports/{export_id} until status is ready, then download the file from download.url. The URL works for 5 minutes; poll again for a new one. Finished exports are deleted after 7 days.

• One export at a time per account. Starting another while one is being prepared returns 409 conflict.
• No email is sent. The app emails a download link; the API does not.
• An archived workspace can still be exported.