POST a FHIR R4 Bundle or single resource, check ingest status, and interpret warnings.

Where to start

Send a FHIR R4 Bundle (or any single FHIR resource) to register it against a patient. The patientId in the URL is your registry key (the stable identifier used in all subsequent calls for this patient).

Make the request

curl -X POST "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/ingest/fhir" \
  -H "X-Clinia-API-Key: <clinia-api-key>" \
  -H "Content-Type: application/json" \
  -d @fhir-bundle.json

A successful response:

{
  "ok": true,
  "source": "fhir",
  "stats": { "itemsScanned": 42, "entitiesExtracted": 12, "eventsExtracted": 8 },
  "warnings": 0,
  "patient": { "id": "123", "name": "Jane Smith" }
}

entitiesExtracted and eventsExtracted reflect what was pulled from this source. The final resolved entity count after deduplication across all sources is visible in the ingest status.

Request details

The body must be a valid FHIR R4 JSON document (either a Bundle or a single resource, e.g. Patient, Condition, MedicationRequest). The Content-Type must be application/json.

Supported resource types include: Patient, Condition, MedicationRequest, Observation, AllergyIntolerance, Immunization, Procedure, Encounter, DiagnosticReport, and DocumentReference. Resources of other types are skipped and counted as warnings.

Multiple ingest calls for the same patientId accumulate sources. Each call re-runs entity resolution over all accumulated sources.

Error responses

Status	Cause
`400`	Request body is not valid JSON or is missing a `resourceType` field
`422`	Bundle contains no extractable FHIR resources

Check ingest status

Each ingest call runs entity resolution synchronously, so data is queryable immediately on return. Use the status endpoint to confirm readiness after ingesting multiple sources in sequence, or to inspect extraction warnings:

curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/ingest/status" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

{
  "ready": true,
  "sources": [
    { "label": "FHIR Bundle", "stats": { "itemsScanned": 42, "entitiesExtracted": 12, "eventsExtracted": 8 } }
  ],
  "patient": { "id": "123", "name": "Jane Smith" },
  "loadStats": { "entitiesExtracted": 12, "eventsExtracted": 8, "relationshipsExtracted": 9 },
  "loadMs": 840
}

ready: true means the pipeline has run and the VFS is queryable. When warnings is non-empty, each entry describes a resource that was skipped during extraction. Common causes:

Cause	Example
Unsupported resource type	`ImagingStudy`, `Claim`, `ExplanationOfBenefit`
Missing required code system	A `Condition` with no SNOMED or ICD-10 code
Malformed reference	A `MedicationRequest` pointing to a non-existent `Medication` resource

To see the full list of what was and wasn't extracted, use the reconciliation summary.

Batch ingest

Use the batch endpoint to submit multiple source types in a single call. Entity resolution runs once over all sources rather than once per source call:

curl -X POST "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/ingest" \
  -H "X-Clinia-API-Key: <clinia-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "fhir": [{ "resourceType": "Bundle", "entry": [] }] }'

The batch body accepts any combination of fhir, cda, and document fields. See the REST API reference for the full request shape.

Ingest a FHIR Bundle