# GEDCOM endpoints

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

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.

## Upload a GEDCOM file to import

`POST /workspaces/{workspace_id}/gedcom/imports`

Starts reading the file in the background; nothing is added to the workspace yet. Poll GET .../gedcom/imports/{import_id} until status is awaiting_confirmation, check the analysis and the plan limit check, then confirm. Counts against the upload rate limit as well. Not idempotent: a retry uploads the file again.

Parameters:

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

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

Responses:

- `202`: The import job, analyzing.
- `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.
- `409`: The workspace is archived (writes are refused).
- `422`: Not multipart, no file, not a .ged, .gdz or .zip file, or the file is too large.
- `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 GEDCOM import

`GET /workspaces/{workspace_id}/gedcom/imports/{import_id}`

Poll this after uploading. When awaiting_confirmation, `analysis` describes the file and the cap_check fields say whether each import mode fits the plan's person limit. When completed, `result` says what was added.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `import_id` (path, required): The GEDCOM import id, from POST .../gedcom/imports.

Responses:

- `200`: The import job.
- `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 import is not in this workspace.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Cancel a GEDCOM import

`DELETE /workspaces/{workspace_id}/gedcom/imports/{import_id}`

Cancels an import that is awaiting confirmation, as cancelling the preview in the app does: nothing is added to the workspace and the uploaded file is deleted. The status becomes cancelled. 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.
- `import_id` (path, required): The GEDCOM import id, from POST .../gedcom/imports.
- `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.

Responses:

- `200`: Cancelled.
- `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 import is not in this workspace.
- `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 import is not awaiting confirmation (still analyzing, already confirmed, failed, cancelled or expired).
- `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.

## Confirm a GEDCOM import

`POST /workspaces/{workspace_id}/gedcom/imports/{import_id}/confirm`

Adds the people, families and sources to the workspace in the background, as confirming the import in the app does. Poll GET .../gedcom/imports/{import_id} until completed. Counts against the upload rate limit as well. 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.
- `import_id` (path, required): The GEDCOM import id, from POST .../gedcom/imports.
- `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:

- `202`: Importing.
- `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 import would pass the plan's person limit (details: limit, used, needed, plan), or mode changed needs the Researcher plan or above.
- `404`: The workspace does not exist or is not visible to this key's owner. Also: the import is not in this workspace.
- `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 import is not awaiting confirmation (still analyzing, already confirmed, failed, cancelled or expired), or its file is no longer available.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Export the workspace as GEDCOM

`POST /workspaces/{workspace_id}/gedcom/exports`

Builds the file in the background. Poll GET .../gedcom/exports/{export_id} until ready for a download URL. No email is sent. One export at a time per account. Archived workspaces can be exported. 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:

- `202`: The export job, queued.
- `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.
- `409`: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: an export is already being prepared.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body.
- `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 GEDCOM export

`GET /workspaces/{workspace_id}/gedcom/exports/{export_id}`

When ready, `download` has a signed URL that works for 5 minutes; poll again for a new one. Finished exports are deleted after 7 days.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `export_id` (path, required): The GEDCOM export id, from POST .../gedcom/exports.

Responses:

- `200`: The export job.
- `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 export is not in this workspace.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Preview who redact_living hides

`GET /workspaces/{workspace_id}/gedcom/exports/redaction-preview`

The people whose details an export with redact_living leaves out, by the same rule the export uses.

Parameters:

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

Responses:

- `200`: The people that would be hidden.
- `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.
- `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/gedcom