Uploads and processing

Turning an image into people and facts takes five steps: upload, process, poll, review, confirm. Processing is asynchronous: POST .../records/{record_id}/process returns 202, then you poll GET .../records/{record_id} until status is review or failed.

1. Upload

Upload a JPG or PNG (up to 10 MB) as multipart form data:

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/records \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -F "file=@birth-record.jpg"

You get 201 with the record in status pending. Optional fields source_text and source_text_layout let you send a text transcription along with the image.

Through the MCP server, the same upload also works from an https URL, from a short-lived upload link that a script fills with curl --upload-file (or a person fills in the browser), or as base64 content. All of them take the same JPG or PNG images and end in this endpoint.

Uploads are not idempotent. Retrying creates another record, and Idempotency-Key is ignored on this endpoint. If an upload times out, list your records before retrying.

2. Process

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/records/RECORD_ID/process \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: process-record-1" \
  -H "Content-Type: application/json" \
  -d '{"deep": false}'

Processing is asynchronous. The call returns 202 as soon as credits are charged, and the extraction runs in the background.

Credits

• A normal extraction costs 1 credit.
• A deep scan ("deep": true) costs 5 credits.
• If you do not have enough, you get 402 insufficient_credits, with used, limit, credits_remaining and shortfall in details.
• Too many records processing at once returns 429.

Credits are your account's monthly credits, shared with the KleioBase app.

3. Poll

curl https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/records/RECORD_ID \
  -H "Authorization: Bearer kb_live_YOUR_KEY"

Check every few seconds until status is review (ready for you) or failed.

4. Review and edit

Read the extraction:

curl https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/records/RECORD_ID/extraction \
  -H "Authorization: Bearer kb_live_YOUR_KEY"

To correct it, send the whole edited extraction with PATCH to the same URL. Nothing is created until you confirm. Dates are corrected here, in the extraction. PATCH .../records/{id} only changes the record's title and type, and it returns 409 while the record is processing.

5. Confirm

curl -X POST https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/records/RECORD_ID/confirm \
  -H "Authorization: Bearer kb_live_YOUR_KEY" \
  -H "Idempotency-Key: confirm-record-1"

This creates the people, links and families from the extraction. If it would exceed your plan's person limit you get 403 forbidden. Without an Idempotency-Key, retrying after success returns 409 because the record is already confirmed.

When processing stalls

If a run crashes or never finishes, KleioBase recovers it automatically. A cleanup job runs every 5 minutes and handles any run older than 30 minutes, so allow about 35 minutes:

• The credits are refunded.
• The record goes to failed, or back to review if it already had an extraction (for example an interrupted re-scan).

Until then, calling process again can return 409 "already being processed". That can last up to about 35 minutes after a crashed run. Keep polling the record rather than retrying in a loop.

Rate limits

An upload counts against both your request budget and the smaller upload budget. See Rate limits.