# Synthesize

```
The Synthesize API returns a summary of guidelines and research for any clinical query
```

#### How it works

{% stepper %}
{% step %}

### Craft query with or without patient context

{% endstep %}

{% step %}

### Retrieve response with references & scores

{% endstep %}
{% endstepper %}

#### API specifications

<details>

<summary>Initiate a synthesis</summary>

{% if  %}

## Initiate synthesis

> Initiate synthesis.

```json
{"openapi":"3.1.0","info":{"title":"Clinical Graph (CG) REST API","version":"0.1.0"},"servers":[{"url":"https://cg-api-prod.system.com","description":"Production API"},{"url":"https://cg-api-stage.system.com","description":"Staging API"},{"url":"https://cg-api-dev.system.com","description":"Development API"},{"url":"http://localhost:80","description":"Local API"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SynthesisIn":{"properties":{"user_query":{"type":"string","title":"User Query","description":"User query."},"population_filter":{"anyOf":[{"$ref":"#/components/schemas/PopulationFilter"},{"type":"null"}]},"publication_filter":{"anyOf":[{"$ref":"#/components/schemas/PublicationFilter"},{"type":"null"}]},"fast_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Fast Mode","description":"Fast mode flag for fast synthesis generation.","default":false},"assembled_patient":{"anyOf":[{"$ref":"#/components/schemas/AssembledPatient-Input"},{"type":"null"}]}},"type":"object","required":["user_query"],"title":"SynthesisIn","description":"Payload to kickoff synthesis generation."},"PopulationFilter":{"properties":{"age":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age"},"sex":{"anyOf":[{"$ref":"#/components/schemas/SexEnum"},{"type":"null"}]},"race":{"anyOf":[{"$ref":"#/components/schemas/RaceEnum"},{"type":"null"}]}},"type":"object","required":["age","sex","race"],"title":"PopulationFilter","description":"Population filters for synthesis generation."},"SexEnum":{"type":"string","enum":["female","male","unknown"],"title":"SexEnum","description":"Male/Female Sex Enum."},"RaceEnum":{"type":"string","enum":["american indian or alaskan native","asian or pacific-islander","black","hispanic","white"],"title":"RaceEnum","description":"Race enum."},"PublicationFilter":{"properties":{"publication_date":{"anyOf":[{"$ref":"#/components/schemas/PublicationDate"},{"type":"null"}]},"publication_type":{"anyOf":[{"items":{"$ref":"#/components/schemas/PublicationTypeEnum"},"type":"array"},{"type":"null"}],"title":"Publication Type"},"publication_quality":{"anyOf":[{"$ref":"#/components/schemas/PublicationStrengthEnum"},{"type":"null"}]}},"type":"object","title":"PublicationFilter","description":"Publication filters for synthesis generation."},"PublicationDate":{"properties":{"start_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Start Year"},"end_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"End Year"}},"type":"object","title":"PublicationDate","description":"Publication date range for filtering."},"PublicationTypeEnum":{"type":"string","enum":["experimental trial","guideline"],"title":"PublicationTypeEnum","description":"PublicationType enum."},"PublicationStrengthEnum":{"type":"string","enum":["high"],"const":"high","title":"PublicationStrengthEnum","description":"JournalStrength enum."},"AssembledPatient-Input":{"properties":{"nodes":{"items":{"$ref":"#/components/schemas/AssembleNode-Input"},"type":"array","title":"Nodes","description":"Graph nodes"},"relationships":{"items":{"$ref":"#/components/schemas/guideline_synthesis_client__models__assemble_edge__AssembleEdge"},"type":"array","title":"Relationships","description":"Graph edges between nodes"},"demographics":{"allOf":[{"$ref":"#/components/schemas/AppApiSchemasAssemblePatientDemographics"}],"description":"Patient demographics"}},"type":"object","required":["nodes","relationships","demographics"],"title":"AssembledPatient","description":"AssembledPatient"},"AssembleNode-Input":{"properties":{"node_type":{"type":"string","title":"Node Type","description":"Discriminator for the node subtype"},"fhir_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fhir Id"},"notable":{"type":"boolean","title":"Notable","description":"Whether this node is notable/important"},"system_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Id"},"system_preferred_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Preferred Name"},"other_system_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Other System Ids"},"coding":{"anyOf":[{"items":{"$ref":"#/components/schemas/ExternalCoding"},"type":"array"},{"type":"null"}],"title":"Coding"},"metadata":{"anyOf":[{"$ref":"#/components/schemas/AssembleNodeMetadata-Input"},{"type":"null"}]}},"type":"object","required":["node_type","fhir_id","notable","system_id","system_preferred_name"],"title":"AssembleNode","description":"AssembleNode"},"ExternalCoding":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"system":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System"},"display":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display"}},"type":"object","required":["code","system","display"],"title":"ExternalCoding","description":"ExternalCoding"},"AssembleNodeMetadata-Input":{"properties":{"condition_metadata":{"anyOf":[{"$ref":"#/components/schemas/guideline_synthesis_client__models__condition_metadata__ConditionMetadata"},{"type":"null"}]},"observation_metadata":{"anyOf":[{"$ref":"#/components/schemas/ObservationMetadata-Input"},{"type":"null"}]},"intervention_metadata":{"anyOf":[{"$ref":"#/components/schemas/InterventionMetadata"},{"type":"null"}]},"allergy_metadata":{"anyOf":[{"$ref":"#/components/schemas/guideline_synthesis_client__models__allergy_metadata__AllergyMetadata"},{"type":"null"}]}},"type":"object","title":"AssembleNodeMetadata","description":"AssembleNodeMetadata"},"guideline_synthesis_client__models__condition_metadata__ConditionMetadata":{"properties":{"clinicalStatus":{"anyOf":[{"$ref":"#/components/schemas/ClinicalStatusEnum"},{"type":"null"}]},"family_history":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Family History"}},"type":"object","required":["clinicalStatus","family_history"],"title":"ConditionMetadata","description":"ConditionMetadata"},"ClinicalStatusEnum":{"type":"string","enum":["active","recurrence","relapse","inactive","remission","resolved","unknown"],"title":"ClinicalStatusEnum","description":"ClinicalStatusEnum"},"ObservationMetadata-Input":{"properties":{"interpretation":{"anyOf":[{"$ref":"#/components/schemas/ObservationInterpretationEnum"},{"type":"null"}]},"risk":{"anyOf":[{"$ref":"#/components/schemas/RiskTypeEnum"},{"type":"null"}]},"risk_direction":{"anyOf":[{"$ref":"#/components/schemas/RiskDirectionEnum"},{"type":"null"}]},"observation_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Observation Time"}},"type":"object","required":["risk","risk_direction","observation_time"],"title":"ObservationMetadata","description":"ObservationMetadata"},"ObservationInterpretationEnum":{"type":"string","enum":["carrier","better","significant change down","significant change up","worse","off scale low","off scale high","insufficient evidence","abnormal","critical abnormal","critical high","critical low","high","significantly high","low","significantly low","normal","intermediate","no clsi defined breakpoint","non-susceptible","resistant","synergy - resistant","susceptible","susceptible-dose dependent","synergy - susceptible","outside threshold","above high threshold","below low threshold","indeterminate","equivocal","negative","not detected","positive","detected","expected","unexpected","non-reactive","reactive","weakly reactive"],"title":"ObservationInterpretationEnum","description":"ObservationInterpretationEnum"},"RiskTypeEnum":{"type":"string","enum":["optimal","low","normal","high"],"title":"RiskTypeEnum","description":"RiskTypeEnum"},"RiskDirectionEnum":{"type":"string","enum":["high","very high","low","very low"],"title":"RiskDirectionEnum","description":"RiskDirectionEnum"},"InterventionMetadata":{"properties":{"intervention_type":{"allOf":[{"$ref":"#/components/schemas/InterventionTypeEnum"}],"description":"Medication or procedure"},"status":{"anyOf":[{"$ref":"#/components/schemas/InterventionStatusEnum"},{"type":"null"}]},"intervention_time":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Intervention Time"}},"type":"object","required":["intervention_type","status","intervention_time"],"title":"InterventionMetadata","description":"InterventionMetadata"},"InterventionTypeEnum":{"type":"string","enum":["medication","procedure","immunization"],"title":"InterventionTypeEnum","description":"InterventionTypeEnum"},"InterventionStatusEnum":{"type":"string","enum":["active","on-hold","cancelled","completed","stopped","draft","unknown","entered-in-error","not-done","in-progress"],"title":"InterventionStatusEnum","description":"InterventionStatusEnum"},"guideline_synthesis_client__models__allergy_metadata__AllergyMetadata":{"properties":{"clinicalStatus":{"anyOf":[{"$ref":"#/components/schemas/ClinicalStatusEnum"},{"type":"null"}]},"verificationStatus":{"anyOf":[{"$ref":"#/components/schemas/VerificationStatusEnum"},{"type":"null"}]},"criticality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Criticality"}},"type":"object","title":"AllergyMetadata","description":"AllergyMetadata"},"VerificationStatusEnum":{"type":"string","enum":["unconfirmed","confirmed","refuted","entered-in-error"],"title":"VerificationStatusEnum","description":"VerificationStatusEnum"},"guideline_synthesis_client__models__assemble_edge__AssembleEdge":{"properties":{"source":{"type":"string","title":"Source","description":"system_id of source node"},"target":{"type":"string","title":"Target","description":"system_id of target node"}},"type":"object","required":["source","target"],"title":"AssembleEdge","description":"AssembleEdge"},"AppApiSchemasAssemblePatientDemographics":{"properties":{"age":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender"},"race":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Race"}},"type":"object","required":["age","gender","race"],"title":"AppApiSchemasAssemblePatientDemographics","description":"AppApiSchemasAssemblePatientDemographics"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/synthesis":{"post":{"tags":["Synthesize"],"summary":"Initiate synthesis","description":"Initiate synthesis.","operationId":"synthesize","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesisIn"}}},"required":true},"responses":{"202":{"description":"Job ID","content":{"application/json":{"schema":{"type":"string","title":"Response Synthesize"}}}},"204":{"description":"No content"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Service Unavailable"}}}}}}
```

{% endif %}

</details>

<details>

<summary>Retrieve response from <code>job_id</code></summary>

{% if  %}

## Get synthesis by ID

> Get synthesis.

```json
{"openapi":"3.1.0","info":{"title":"Clinical Graph (CG) REST API","version":"0.1.0"},"servers":[{"url":"https://cg-api-prod.system.com","description":"Production API"},{"url":"https://cg-api-stage.system.com","description":"Staging API"},{"url":"https://cg-api-dev.system.com","description":"Development API"},{"url":"http://localhost:80","description":"Local API"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SynthesisOut":{"properties":{"status":{"$ref":"#/components/schemas/SynthesisPollingStatus"},"synthesis":{"anyOf":[{"$ref":"#/components/schemas/SynthesisAgentOutput"},{"type":"null"}]}},"type":"object","required":["status","synthesis"],"title":"SynthesisOut","description":"Synthesis fetching output schema."},"SynthesisPollingStatus":{"type":"string","enum":["not_exists","submitted","running","success","failed"],"title":"SynthesisPollingStatus","description":"Polling status enum."},"SynthesisAgentOutput":{"properties":{"synthesis":{"$ref":"#/components/schemas/Synthesis"},"response_flags":{"anyOf":[{"$ref":"#/components/schemas/ResponseFlags"},{"type":"null"}]},"synthesis_logs":{"anyOf":[{"$ref":"#/components/schemas/SynthesisLogs"},{"type":"null"}]}},"type":"object","required":["synthesis"],"title":"SynthesisAgentOutput","description":"Synthesis agent output."},"Synthesis":{"properties":{"text":{"type":"string","title":"Text"},"references":{"anyOf":[{"items":{"$ref":"#/components/schemas/SynthesisReference"},"type":"array"},{"type":"null"}],"title":"References"}},"type":"object","required":["text"],"title":"Synthesis","description":"Final synthesis output with authors populated."},"SynthesisReference":{"properties":{"index":{"type":"integer","title":"Index"},"reference_text":{"type":"string","title":"Reference Text"},"document_title":{"type":"string","title":"Document Title"},"authoring_societies_or_journal":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Authoring Societies Or Journal"},"publish_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publish Date"},"link_or_doi":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Link Or Doi"},"cited_by":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cited By"},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type"},"authors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Authors"},"journal_quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Quality"}},"type":"object","required":["index","reference_text","document_title"],"title":"SynthesisReference","description":"Synthesis reference with authors populated."},"ResponseFlags":{"properties":{"contains_guideline":{"type":"boolean","title":"Contains Guideline","description":"The synthesis includes recommendations from at least one guideline of any type"},"contains_trial":{"type":"boolean","title":"Contains Trial","description":"The synthesis includes evidence from at least one experimental trial"},"quality":{"allOf":[{"$ref":"#/components/schemas/Quality"}],"description":"The synthesis cites both guidelines and studies of any type"},"quantity":{"allOf":[{"$ref":"#/components/schemas/Quantity"}],"description":"The synthesis cites both guidelines and studies of any type"},"relevance":{"allOf":[{"$ref":"#/components/schemas/Relevance"}],"description":"The synthesis is relevant to the query"},"confidence_score":{"allOf":[{"$ref":"#/components/schemas/Quality"}],"description":"A confidence score for the produced synthesis."}},"type":"object","required":["contains_guideline","contains_trial","quality","quantity","relevance","confidence_score"],"title":"ResponseFlags","description":"Confidence indicators."},"Quality":{"type":"string","enum":["low","medium","high"],"title":"Quality","description":"Quality indicators."},"Quantity":{"type":"string","enum":["limited","sufficient","abundant"],"title":"Quantity","description":"Quantity indicators."},"Relevance":{"type":"string","enum":["unanswered","indirect","direct"],"title":"Relevance","description":"Relevance indicators."},"SynthesisLogs":{"properties":{"total_time_seconds":{"anyOf":[{"type":"number"},{"type":"integer"}],"title":"Total Time Seconds","description":"Total time taken for the entire synthesis process"},"guideline_search_time_seconds":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Guideline Search Time Seconds"},"guideline_lookup_time_seconds":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Guideline Lookup Time Seconds"},"evidence_retrieval_time_seconds":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Evidence Retrieval Time Seconds"},"blending_time_seconds":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Blending Time Seconds"}},"type":"object","required":["total_time_seconds"],"title":"SynthesisLogs","description":"Logs for synthesis."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/synthesis/{job_id}":{"get":{"tags":["Synthesize"],"summary":"Get synthesis by ID","description":"Get synthesis.","operationId":"get_synthesis_by_id","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesisOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

{% endif %}

</details>

### Using Assembled Patient as Context

The `assembled_patient` field in the synthesis request body allows you to pass a structured patient graph as clinical context. When provided, the synthesis engine uses the patient's conditions, observations, interventions, allergies, and demographics to **personalize and focus the evidence synthesis** to be directly relevant to that specific patient's clinical profile.

#### How It Works

The `assembled_patient` field accepts an `AssembledPatient` object — the same output structure returned by the **`POST /v1/assemble`** endpoint. This creates a natural integration pattern:

Copy`POST /v1/assemble (FHIR bundle) → AssembledPatient ↓ POST /v1/synthesis (user_query + assembled_patient) → Personalized Synthesis`

The Assemble endpoint converts a FHIR bundle into a structured patient graph of typed nodes and edges. Passing this output directly into the synthesis request contextualizes the evidence retrieval and blending pipeline around the patient's specific clinical picture.

#### `AssembledPatient` Structure

| Field         | Type                | Required | Description                                                                 |
| ------------- | ------------------- | -------- | --------------------------------------------------------------------------- |
| nodes         | AssembleNode\[]     | Yes      | Patient clinical nodes (conditions, observations, interventions, allergies) |
| relationships | AssembleEdge\[]     | Yes      | Edges connecting nodes in the patient graph                                 |
| demographics  | PatientDemographics | Yes      | Patient age, gender, and race                                               |

#### `AssembleNode` Fields

| Field                   | Type                 | Required | Description                                                       |
| ----------------------- | -------------------- | -------- | ----------------------------------------------------------------- |
| node\_type              | string               | Yes      | Discriminator for the node subtype (e.g., condition, observation) |
| fhir\_id                | string               | Yes      | Original FHIR resource identifier                                 |
| notable                 | boolean              | Yes      | Whether this node is clinically notable/important                 |
| system\_id              | string               | Yes      | System-assigned identifier for the concept                        |
| system\_preferred\_name | string               | Yes      | Preferred clinical name of the concept                            |
| other\_system\_ids      | string\[]            | No       | Additional system identifiers                                     |
| coding                  | ExternalCoding\[]    | No       | External coding references (e.g., SNOMED, ICD-10)                 |
| metadata                | AssembleNodeMetadata | No       | Type-specific clinical metadata                                   |

#### `AssembleNodeMetadata`

Each node can carry rich clinical metadata depending on its type:

| Metadata Type          | Key Fields                                                              | Description                                    |
| ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------- |
| condition\_metadata    | clinicalStatus, family\_history, ccsr\_categories, onsetDateTime        | For diagnosis/condition nodes                  |
| observation\_metadata  | risk, risk\_direction, interpretation, observation\_time, valueQuantity | For lab results and clinical observations      |
| intervention\_metadata | intervention\_type, status, intervention\_time                          | For medications, procedures, and immunizations |
| allergy\_metadata      | clinicalStatus, criticality, verificationStatus                         | For allergy and intolerance nodes              |

#### `AssembleEdge` Fields

| 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 between nodes |

#### Data security

Synthesize can be integrated into electronic health records (EHRs) to receive de-identified patient data as context for clinical queries. No requests include patient identifiers.&#x20;