REST API

Base URL

https://api.<workspace-id>.clinia.cloud

Replace <workspace-id> with your workspace identifier.

All patient-scoped routes are prefixed with /patients/{patientId}.

The MCP tools (browse_patient, read_patient, search_patient, get_patient_info) are not part of this spec. See MCP Tools for those.

Authentication

All requests require an API key header:

X-Clinia-API-Key: <clinia-api-key>

Patients

Patient registry management. A patient is created implicitly on first ingest and is identified by a registry key chosen by the caller.

List all patients

GET /patients

Returns all patients currently loaded in the server registry. An empty array is returned if no patients have been ingested yet.

Response 200

Array of PatientRegistryEntry objects.

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

[
  {
    "registryKey": "jane-smith",
    "patient": {
      "id": "p-001",
      "name": "Jane Smith",
      "birthDate": "1968-04-12",
      "gender": "female"
    },
    "ready": true,
    "stats": { "entities": 18, "events": 11, "relationships": 22, "warnings": 1, "loadMs": 840 }
  }
]

Get patient

GET /patients/{patientId}

Returns demographics and pipeline statistics for a single registered patient.

Path parameters

Response 200 (PatientDetail)

Response 404 (ErrorResponse, patient not found or no data ingested yet)

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

{
  "id": "p-001",
  "name": "Jane Smith",
  "birthDate": "1968-04-12",
  "gender": "female",
  "stats": { "entities": 18, "events": 11, "relationships": 22, "warnings": 1, "loadMs": 840 }
}

Delete patient

DELETE /patients/{patientId}

Removes all in-memory state for the patient including the resolved graph, event store, and search index. Does not delete cache files on disk. Use Reset patient to also clear the cache. Safe to call on a patient that does not exist (existed will be false).

Path parameters

Response 200

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

{ "ok": true, "existed": true }

VFS

Browse and read the resolved patient graph through a path-based filesystem metaphor. Content is materialized lazily on each request from the live graph. Nothing is stored as pre-rendered files.

Slugs in path segments are derived from entity display names: lowercased, spaces and special characters replaced with underscores.

Browse VFS

GET /patients/{patientId}/vfs

Returns a directory listing with one-line previews for each entry, or file content if the path resolves to a leaf file. Omit the path parameter to browse the patient root.

Path parameters

Query parameters

Supported path schema

Response 200 (BrowseResult)

Response 404 (ErrorResponse, path not found)

curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/vfs?path=/conditions/active" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

{
  "path": "/patient/jane-smith/conditions/active",
  "type": "directory",
  "children": [
    { "name": "type_2_diabetes_mellitus", "type": "directory", "preview": "active since 2016" },
    {
      "name": "chronic_kidney_disease_stage_3",
      "type": "directory",
      "preview": "active since 2019"
    }
  ]
}

Read VFS path

GET /patients/{patientId}/read

Returns the rendered content of a specific VFS file. The format parameter controls output verbosity.

Path parameters

Query parameters

Format values

Notable file paths

Response 200

Response 404 (ErrorResponse, path not found)

curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/read?path=/conditions/active/type_2_diabetes_mellitus/_story.md" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

Ingest

Submit clinical data for entity resolution. The resolution pipeline runs synchronously after each ingest call. Data is immediately queryable when the response returns. Calling an ingest endpoint multiple times on the same patient accumulates sources; each call re-runs the full resolution pipeline over all accumulated data.

Batch ingest

POST /patients/{patientId}/ingest

Submits FHIR, CDA, and/or document metadata in a single call. More efficient than three separate calls because the resolution pipeline runs only once. At least one of fhir, cda, or documents must be present.

Path parameters

Request body: BatchIngestRequest

Response 200 (IngestResult)

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": [] }], "cda": ["<ClinicalDocument>...</ClinicalDocument>"] }'

Ingest FHIR

POST /patients/{patientId}/ingest/fhir

Accepts a FHIR R4 Bundle or a single FHIR resource. If a Bundle is passed, all entries in bundle.entry[].resource are processed. Single resources are wrapped in a synthetic bundle internally.

Supported resource types: Patient, Condition, MedicationStatement, Observation, Encounter, AllergyIntolerance, Coverage, Procedure, Immunization, FamilyMemberHistory, DocumentReference, DiagnosticReport.

Path parameters

Request body: A FHIR R4 Bundle or any supported single FHIR resource (JSON). Additional FHIR properties are passed through without validation. The FHIR connector handles structural parsing and emits warnings for unrecognised fields.

Response 200 (IngestResult)

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 @bundle.json

Ingest CDA

POST /patients/{patientId}/ingest/cda

Accepts a CDA or C-CDA XML document as a raw string. Sections are identified by LOINC code. Sections with narrative text but no structured entries are extracted as NarrativeSection objects and stored for source browsing.

Supported section types: Problems, Medications, Allergies, Results, Vitals, Encounters, Procedures, Payers, Advance Directives.

Path parameters

Request body: CDA or C-CDA XML document as a raw string. Content-Type: text/xml or text/plain.

Response 200 (IngestResult)

curl -X POST "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/ingest/cda" \
  -H "X-Clinia-API-Key: <clinia-api-key>" \
  -H "Content-Type: text/xml" \
  --data-binary @summary.xml

Ingest document

POST /patients/{patientId}/ingest/document

Registers a PDF, image, or other unstructured file by metadata only (no file bytes are uploaded). Creates a DocumentNode indexed in the full-text search store, making the document discoverable in the VFS at /sources/ even though its content is not parsed. Useful for maintaining provenance references to documents that exist outside the system.

Path parameters

Request body: DocumentMetadata

Response 200 (IngestResult)

curl -X POST "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/ingest/document" \
  -H "X-Clinia-API-Key: <clinia-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "scan_20230801.pdf", "mimeType": "application/pdf" }'

Reset patient

POST /patients/{patientId}/ingest/reset

Removes all ingested data, the resolved graph, the event store, the search index, and any cached pipeline output files on disk. Also removes the patient registry entry. Equivalent to DELETE /patients/{patientId} plus cache file deletion. Use before re-ingesting a corrected data set from scratch.

Path parameters

Response 200

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

Get ingest status

GET /patients/{patientId}/ingest/status

Returns whether data has been ingested and the pipeline has run, current pipeline statistics, and all ExtractionWarning objects emitted during the most recent ingest. Use this to diagnose missing entities. Warnings indicate why a resource was not extracted.

Path parameters

Response 200 (IngestStatus)

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 }
    },
    {
      "label": "Summary_20230907.xml",
      "stats": { "itemsScanned": 28, "entitiesExtracted": 9, "eventsExtracted": 4 }
    }
  ],
  "patient": { "id": "p-001", "name": "Jane Smith" },
  "loadStats": { "entitiesExtracted": 18, "eventsExtracted": 11, "relationshipsExtracted": 22 },
  "loadMs": 840
}

Pipeline

Read-only access to resolution and reconciliation reports produced by the consolidation pipeline. Use these to audit merge decisions, debug unexpected entity behaviour, and review post-processing actions.

Get resolution report

GET /patients/{patientId}/resolution

Returns every entity in the resolved graph with its complete ProvenanceTrace: which sources contributed, what field-level conflicts existed, how each conflict was resolved, and which resolution layer (1–4) made the final merge or no-merge decision.

Path parameters

Response 200 (ResolutionReport)

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

See Audit Entity Resolution for a guide to reading this report.

Get reconciliation summary

GET /patients/{patientId}/reconciliation

Returns a summary of what the consolidation pipeline did: merge statistics, the full list of inferred relationships added by the relationship resolver, and all post-processing actions applied by the condition post-processor.

Path parameters

Query parameters

Response 200 (ReconciliationReport or Markdown string)

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

curl "https://api.<workspace-id>.clinia.cloud/patients/{patientId}/reconciliation?format=json" \
  -H "X-Clinia-API-Key: <clinia-api-key>"

See Review the Reconciliation Summary for a guide to reading this report.

Schemas

PatientInfo

Demographics extracted from ingested source data. Populated from the FHIR Patient resource or equivalent CDA patient header.

PipelineStats

Counts produced by the entity resolution pipeline after the most recent ingest call.

PatientRegistryEntry

A single entry in the patient registry, as returned by GET /patients.

PatientDetail

Full patient detail returned by GET /patients/{patientId}. Combines PatientInfo fields with pipeline statistics.

VfsEntry

A single entry in a VFS directory listing.

BrowseResult

The result of a VFS browse operation.

DocumentMetadata

Metadata for registering an unstructured document without uploading file bytes.

BatchIngestRequest

Request body for batch ingest. At least one of fhir, cda, or documents must be present.

ConnectorStats

Extraction statistics produced by a single connector run.

ExtractionWarning

A warning emitted when a source item could be partially parsed but not fully extracted. Warnings do not halt ingestion.

IngestResult

The result of a completed ingest operation. Returned after the connector and resolution pipeline have both completed.

IngestStatus

Current state of a patient in the registry.

SourceStat

LoadStats

SourceRef

A reference to a single source that contributed to a merged entity.

ConflictRecord

A field-level conflict between two or more sources during entity resolution.

ProvenanceTrace

The complete audit record attached to every merged ClinicalEntity.

resolvedBy values

ClinicalCode

A single clinical code from a standardized coding system.

ResolvedEntity

A single deduplicated clinical entity in the resolved graph.

ResolutionReport

The complete entity resolution report for a patient.

InferredRelationship

A typed directed edge inferred by the relationship resolver using the clinical knowledge base. Only created when no explicit edge of the same type already exists between the same pair.

Relationship types

PostProcessAction

A single action taken by the condition post-processor heuristic pass to fix a common EHR data quality issue.

Action types

ReconciliationReport

A summary of all consolidation pipeline activity for a patient.

stats fields

ErrorResponse

Standard error response for 4xx responses.