Diagnose

The Diagnose endpoint surfaces potential differential diagnoses for clinicians to consider with explainable and referenced rationale

Overview

The Diagnose API analyzes a patient's clinical data — represented as a structured graph — and returns a ranked list of candidate diagnoses, each supported by evidence-based rationale drawn from clinical guidelines and diagnostic criteria.

The patient graph submitted to the Diagnose API follows the same structure produced by the Assemble API, which builds a patient graph from a FHIR bundle. It is recommended to use the Assemble API to construct and validate your patient graph before passing it to the Diagnose API.

---

Workflow

FHIR Bundle ──► POST /v1/assemble ──► Patient Graph ──► POST /v1/diagnose ──► Diagnoses

1

Assemble

Submit a FHIR bundle to POST /v1/assemble to construct a structured patient graph (AssembledPatient).

2

Diagnose

Submit the resulting patient graph to POST /v1/diagnose to retrieve ranked candidate diagnoses.

Note: While the Assemble API returns an AssembledPatient object, the Diagnose API accepts a CustomAssembledPatient object. This is an extended variant that supports additional metadata fields such as family_member_history_metadata and a custom observation metadata model. Ensure your patient graph conforms to the CustomAssembledPatient schema described below before submitting to the Diagnose endpoint.

---

Endpoint

POST /v1/diagnose

Authentication

All requests require an API key passed in the request header:

x-api-key: <your-api-key>

---

Request

Headers

Header	Value	Required
x-api-key	Your API key	Yes
Content-Type	application/json	Yes

Request Body

The request body must be a CustomAssembledPatient object — an extended form of the patient graph produced by the Assemble API. It contains the patient's clinical graph as a set of nodes, edges, and demographic information.

Field	Type	Required	Description
nodes	CustomAssembleNode[]	Yes	Array of clinical graph nodes representing patient findings
relationships	AssembleEdge[]	Yes	Array of edges connecting nodes in the patient graph
demographics	PatientDemographics	Yes	Patient demographic information

Patient Demographics

Field	Type	Required	Description
age	integer | null	Yes	Patient age
gender	string | null	Yes	Patient gender
race	string | null	Yes	Patient race

Node Object (CustomAssembleNode)

Each node represents a clinical finding or concept in the patient's history. This extends the AssembleNode structure returned by the Assemble API with additional metadata support.

Field	Type	Required	Description
node_type	string	Yes	Discriminator for the node subtype
fhir_id	string | null	Yes	FHIR resource identifier
notable	boolean	Yes	Whether this node is notable/clinically important
system_id	string | null	Yes	System identifier for the node
system_preferred_name	string | null	Yes	Preferred clinical name
other_system_ids	string[] | null	No	Additional system identifiers
coding	ExternalCoding[] | null	No	External coding references (e.g. SNOMED, ICD)
metadata	CustomAssembleNodeMetadata | null	No	Clinical metadata for the node

External Coding (ExternalCoding)

Field	Type	Required	Description
code	string | null	Yes	Clinical code
system	string | null	Yes	Coding system (e.g. http://snomed.info/sct)
display	string | null	Yes	Human-readable display name

Node Metadata (CustomAssembleNodeMetadata)

This extends the AssembleNodeMetadata structure from the Assemble API with support for family_member_history_metadata and a custom observation metadata model.

Field	Type	Required	Description
condition_metadata	ConditionMetadata | null	No	Metadata for condition nodes
observation_metadata	CustomObservationMetadata | null	No	Metadata for observation nodes
intervention_metadata	InterventionMetadata | null	No	Metadata for medication/procedure nodes
allergy_metadata	AllergyMetadata | null	No	Metadata for allergy nodes
family_member_history_metadata	FamilyMemberHistoryMetadata | null	No	Metadata for family history nodes

Condition Metadata

Field	Type	Required	Description
clinicalStatus	ClinicalStatusEnum	Yes	Clinical status of the condition
ccsr_categories	string[] | null	No	CCSR classification categories
ccsr_body_systems	string[] | null	No	Affected body systems
onsetDateTime	datetime | null	No	Date/time of condition onset
recordedDate	datetime | null	No	Date/time condition was recorded

ClinicalStatusEnum values: active | recurrence | relapse | inactive | remission | resolved | unknown

Observation Metadata (CustomObservationMetadata)

Note: The Diagnose API uses a CustomObservationMetadata model rather than the standard ObservationMetadata returned by the Assemble API. The key difference is the addition of a value_quantity field using a CustomQuantityType, which corrects a known handling issue with numeric values in the standard QuantityType.

Field	Type	Required	Description
category	string[] | null	No	Observation category
interpretation	ObservationInterpretationEnum | null	No	Clinical interpretation of the value
risk	RiskTypeEnum	Yes	Risk classification
risk_direction	RiskDirectionEnum	Yes	Direction of risk
observation_time	datetime	Yes	Time the observation was recorded
value_quantity	CustomQuantityType | null	No	Quantitative observation value

RiskTypeEnum values:** optimal | low | normal | high RiskDirectionEnum values:** high | very high | low | very low

Quantity Type (CustomQuantityType)

Field	Type	Required	Description
value	number | null	No	Numeric value
unit	string | null	No	Unit of measure
system	string | null	No	Unit coding system
code	string | null	No	Unit code
comparator	string | null	No	Comparator (e.g. <, >=)

Intervention Metadata

Field	Type	Required	Description
intervention_type	InterventionTypeEnum	Yes	Type of intervention
status	InterventionStatusEnum	Yes	Current status
intervention_time	datetime	Yes	Time of intervention

InterventionTypeEnum values:** medication | procedure | immunization InterventionStatusEnum values:** active | on-hold | cancelled | completed | stopped | draft | unknown | entered-in-error | not-done | in-progress

Allergy Metadata

Field	Type	Required	Description
clinicalStatus	ClinicalStatusEnum | null	No	Clinical status of the allergy
verificationStatus	VerificationStatusEnum | null	No	Verification status
criticality	CriticalityEnum | null	No	Criticality level
recordedDate	datetime | null	No	Date allergy was recorded

VerificationStatusEnum values:** unconfirmed | confirmed | refuted | entered-in-error CriticalityEnum values:** low | high | unable-to-assess

Family Member History Metadata

Note: This metadata type is available in the Diagnose API's CustomAssembleNodeMetadata but is not present in the base AssembleNodeMetadata returned by the Assemble API. It must be added to the patient graph prior to submitting to the Diagnose endpoint where family history is clinically relevant.

Field	Type	Required	Description
status	FamilyMemberHistoryStatusEnum | null	No	Status of the family history record
relation	string | null	No	Relationship to patient (e.g. father, mother)
sex	string | null	No	Sex of the family member
onsetAge	integer | null	No	Age of condition onset in the family member

FamilyMemberHistoryStatusEnum values:** partial | completed | entered-in-error | health-unknown

Edge Object (AssembleEdge)

Edges follow the same structure as those produced by the Assemble API.

Field	Type	Required	Description
source	string	Yes	system_id of the source node
target	string	Yes	system_id of the target node
relationship_id	string	Yes	Identifier of the relationship type

---

Response

Success Response — 200 OK

Returns a DiagnoseOutput object containing a ranked list of candidate diagnoses.

{
  "diagnoses": [
    {
      "system_id": "string",
      "display_name": "string",
      "score": 0.95,
      "rationale": {
        "overview": {
          "text": "string",
          "references": []
        },
        "diagnostic_evidence": [],
        "relevant_family_history": []
      }
    }
  ]
}

Response Schema

DiagnoseOutput

Field	Type	Required	Description
diagnoses	Diagnosis[]	Yes	Ranked list of candidate diagnoses

Diagnosis

Field	Type	Required	Description
system_id	string	Yes	System Interoperable Variable ID for the diagnosis
display_name	string | null	No	Human-readable diagnosis name
score	number | integer	Yes	Evidence score — higher values indicate stronger support
rationale	Rationale | null	No	Detailed evidence rationale for the diagnosis

Rationale

Field	Type	Description
overview	DiagnosisOverview | null	Summary and guideline references
diagnostic_evidence	DiagnosticCriterion[] | null	Criteria evaluated against patient data
relevant_family_history	RelevantFamilyHistory[] | null	Clinically relevant family history entries

DiagnosisOverview

Field	Type	Description
text	string | null	Plain-language summary of why the diagnosis is being considered
references	GuidelineReference[] | null	Clinical guidelines used to evaluate the diagnosis

GuidelineReference

Field	Type	Required	Description
title	string	Yes	Title of the guideline document
authoring_societies	string[] | null	No	Organizations that authored the guideline

DiagnosticCriterion

Represents a single diagnostic criterion evaluated against the patient's data.

Field	Type	Required	Description
evidence_type	string	Yes	Whether this criterion matches, is missing, or contradicts patient data
criterion	string	Yes	Criterion expression as stated in guidelines (e.g. "TSH high")
patient_finding	string | null	No	The corresponding patient finding
fhir_id	string | null	No	FHIR ID of the supporting resource
patient_value	string | null	No	Observed value from the patient
time_recorded	datetime | null	No	When the finding was recorded

RelevantFamilyHistory

Field	Type	Required	Description
condition_name	string	Yes	Name of the family member's condition
explanation	string	Yes	Clinical explanation of relevance to the diagnosis
relation_code	string | null	No	Coded relation to patient
relation_display	string | null	No	Human-readable relation (e.g. "mother")
onset_age	integer | null	No	Age of onset in the family member
references	GuidelineReference[] | null	No	Supporting guideline references

---

Error Responses

HTTP Status	Description
200 OK	Successful response with diagnoses
422 Unprocessable Entity	Request body failed validation — check field types and required fields

Validation Error Schema

{
  "detail": [
    {
      "loc": ["body", "nodes"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

---

Example Request

The following example submits a patient graph with a single condition node (hypothyroidism) and observation node (elevated TSH) to retrieve candidate diagnoses. This graph was first assembled using the Assemble API from a FHIR bundle, then extended with family history metadata before being submitted here.

curl -X POST https://cg-api-prod.system.com/v1/diagnose \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "nodes": [
    {
      "node_type": "condition",
      "fhir_id": "condition-001",
      "notable": true,
      "system_id": "sys-hypothyroidism",
      "system_preferred_name": "Hypothyroidism",
      "coding": [
        {
          "code": "40930008",
          "system": "http://snomed.info/sct",
          "display": "Hypothyroidism"
        }
      ],
      "metadata": {
        "condition_metadata": {
          "clinicalStatus": "active",
          "ccsr_body_systems": ["Endocrine system"],
          "onsetDateTime": "2023-01-15T00:00:00Z"
        }
      }
    },
    {
      "node_type": "observation",
      "fhir_id": "obs-001",
      "notable": true,
      "system_id": "sys-tsh-high",
      "system_preferred_name": "TSH elevated",
      "metadata": {
        "observation_metadata": {
          "risk": "high",
          "risk_direction": "high",
          "observation_time": "2024-03-01T08:30:00Z",
          "interpretation": "high",
          "value_quantity": {
            "value": 8.5,
            "unit": "mIU/L",
            "system": "http://unitsofmeasure.org",
            "code": "mIU/L"
          }
        }
      }
    },
    {
      "node_type": "family_history",
      "fhir_id": "fh-001",
      "notable": false,
      "system_id": "sys-fh-thyroid",
      "system_preferred_name": "Family history of thyroid disorder",
      "metadata": {
        "family_member_history_metadata": {
          "status": "completed",
          "relation": "mother",
          "sex": "female",
          "onsetAge": 52
        }
      }
    }
  ],
  "relationships": [
    {
      "source": "sys-tsh-high",
      "target": "sys-hypothyroidism",
      "relationship_id": "rel-tsh-hypothyroidism"
    },
    {
      "source": "sys-fh-thyroid",
      "target": "sys-hypothyroidism",
      "relationship_id": "rel-fh-hypothyroidism"
    }
  ],
  "demographics": {
    "age": 45,
    "gender": "female",
    "race": "white"
  }
}'

Example Response

{
  "diagnoses": [
    {
      "system_id": "sys-hypothyroidism-primary",
      "display_name": "Primary Hypothyroidism",
      "score": 0.92,
      "rationale": {
        "overview": {
          "text": "Patient presents with elevated TSH and active hypothyroidism diagnosis, consistent with primary hypothyroidism per ATA guidelines. Maternal history of thyroid disorder further supports this diagnosis.",
          "references": [
            {
              "title": "American Thyroid Association Guidelines for Hypothyroidism in Adults",
              "authoring_societies": ["American Thyroid Association"]
            }
          ]
        },
        "diagnostic_evidence": [
          {
            "evidence_type": "matches",
            "criterion": "TSH high",
            "patient_finding": "TSH elevated",
            "fhir_id": "obs-001",
            "patient_value": "8.5 mIU/L",
            "time_recorded": "2024-03-01T08:30:00Z"
          }
        ],
        "relevant_family_history": [
          {
            "condition_name": "Thyroid disorder",
            "explanation": "Maternal history of thyroid disorder increases risk of primary hypothyroidism.",
            "relation_code": "MTH",
            "relation_display": "mother",
            "onset_age": 52,
            "references": [
              {
                "title": "American Thyroid Association Guidelines for Hypothyroidism in Adults",
                "authoring_societies": ["American Thyroid Association"]
              }
            ]
          }
        ]
      }
    }
  ]
}

---

Key Concepts

Patient Graph and the Assemble API

The Diagnose API requires the patient's clinical data to be represented as a structured graph. The recommended approach is to use the POST /v1/assemble endpoint to generate this graph from a FHIR bundle. The Assemble API resolves FHIR resources into typed, system-mapped nodes and edges that are directly compatible with the Diagnose API's input schema.

Once assembled, the graph may be enriched with additional data — such as family member history metadata — before being submitted to the Diagnose endpoint.

• Nodes represent individual clinical findings such as conditions, observations, medications, allergies, and family history entries

• Edges (Relationships) represent the clinical connections between those findings

Evidence Scoring

Each returned diagnosis is assigned a score reflecting the strength of supporting evidence from clinical guidelines and diagnostic criteria. Higher scores indicate stronger alignment with established diagnostic criteria.

Diagnostic Evidence Types

Each DiagnosticCriterion within the rationale includes an evidence_type field indicating its relationship to the patient's data:

Evidence Type	Meaning
matches	The patient's data satisfies this diagnostic criterion
missing	This criterion is expected but absent from the patient's data
contradicts	The patient's data is inconsistent with this criterion

---

Notes

• Use POST /v1/assemble to build the patient graph from a FHIR bundle before calling this endpoint.

• The demographics object requires age, gender, and race — all are required fields.

• The notable flag on each node should be set to true for clinically significant findings that should be weighted more heavily during diagnosis evaluation.

• Family history nodes with family_member_history_metadata can influence diagnosis scoring where hereditary factors are clinically relevant. This metadata is an extension beyond what the Assemble API returns and must be added manually if required.

• The CustomObservationMetadata used by this endpoint differs from the standard ObservationMetadata in the Assemble API — specifically in its handling of the value_quantity field. Ensure observation nodes use the CustomQuantityType format when submitting quantitative values.