# 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"}]},"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_group":{"anyOf":[{"$ref":"#/components/schemas/AgeGroupEnum"},{"type":"null"}]},"sex":{"anyOf":[{"$ref":"#/components/schemas/SexEnum"},{"type":"null"}]},"race":{"anyOf":[{"$ref":"#/components/schemas/RaceEnum"},{"type":"null"}]}},"type":"object","required":["age_group","sex","race"],"title":"PopulationFilter","description":"Population filters for synthesis generation."},"AgeGroupEnum":{"type":"string","enum":["newborn","pediatric","adults","geriatric"],"title":"AgeGroupEnum","description":"Age group enum."},"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;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.system.com/system/api-docs/synthesize.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.