> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliosai.health/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Format

> Understanding the structure of patient and clinician responses with citations

This guide explains the structure of Helios API responses, including how to parse and display the patient and clinician reports, and how to use the citations system.

## Response Structure Overview

When analysis completes successfully, you receive a webhook with a `result` object containing:

```json theme={null}
{
  "result": {
    "selectedElements": [...],     // Health elements selected for analysis
    "patientResponse": "...",      // Markdown-formatted patient summary
    "clinicianResponse": "...",    // Markdown-formatted clinical report
    "citations": {
      "patient": {...},            // Citations for patient response
      "clinician": {...}           // Citations for clinician response
    },
    "researchTasks": [...]         // Research tasks executed (Deep Agent only)
  }
}
```

## Patient Response

The `patientResponse` is a **Markdown-formatted** string written in warm, accessible language for patients. It includes:

* **Health Summary**: Overview of the patient's health findings
* **Key Health Areas**: Explanation of conditions and concerns
* **Recommended Tests**: Suggested follow-up tests with timing
* **What You Can Do**: Actionable lifestyle and health recommendations
* **Timeline**: Suggested schedule for follow-up care

### Example Patient Response Structure

```markdown theme={null}
## 👤 Your Health Summary

Based on analysis of your health records.

---

Hello!

We've completed a thorough review of your health record...

**Understanding Your Key Health Areas**

*   **Heart and Metabolic Health**: Your records show... [1] [2]
*   **Diabetes Risk**: You have prediabetes, which means... [3]

### 🧪 Recommended Tests

*   **HbA1c**: Monitor blood sugar control. *Get every 3-6 months.* [4]
*   **Lipid Panel**: Check cholesterol levels. *Get within 6 months.* [5]

### 💡 What You Can Do

*   Focus on a heart-healthy diet... [6]
*   Aim for 150 minutes of exercise weekly... [7]
```

<Info>
  The patient response uses numbered citations like `[1]`, `[2]` that reference entries in the `citations.patient` object.
</Info>

## Clinician Response

The `clinicianResponse` is a **Markdown-formatted** clinical report designed for healthcare providers. It includes:

* **Clinical Summary**: Comprehensive patient overview
* **Problem-by-Problem Analysis**: Detailed analysis of each condition
* **Longitudinal Trends**: Lab value trends over time (tables)
* **Cross-System Analysis**: Connections between conditions
* **Recommendations**: Lab testing, imaging, medications, referrals
* **Monitoring Plan**: Short, medium, and long-term follow-up

### Example Clinician Response Structure

```markdown theme={null}
## 📋 EHR Analysis Report

Based on analysis of 17 EHR element(s) from the patient's record.

---

# 📊 EHR Analysis Report

## 1. Clinical Summary

This 45-year-old male presents with poorly controlled Type 2 Diabetes... [1] [2]

## 2. Chronic Problems — Problem-by-Problem Analysis

### 2.1. Type 2 Diabetes Mellitus

The patient's HbA1c of 7.2% indicates suboptimal glycemic control... [3] [4]

| Lab | Trend | Clinical Comment |
|-----|-------|------------------|
| HbA1c | 6.8% → 7.2% ↑ | Worsening control |

## 3. Recommendations

### 3.1. Laboratory Testing

*   **HbA1c**: Repeat in 3 months to assess intervention effectiveness [5]

### 3.2. Medication Safety Flags

| Drug | Flag | Reason |
|------|------|--------|
| Metformin | CAUTION | Monitor renal function [6] |
```

## Citations System

Both responses include numbered citations `[1]`, `[2]`, etc. that reference the `citations` object in the webhook payload.

### Citations Object Structure

```json theme={null}
{
  "citations": {
    "patient": {
      "1": {
        "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
        "title": "Glycemic Control and Cardiovascular Outcomes",
        "metadata": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
          "type": "pubmed",
          "title": "Glycemic Control and Cardiovascular Outcomes"
        }
      },
      "2": {
        "url": "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1234567/",
        "title": "ADA Standards of Care 2025",
        "metadata": {
          "url": "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1234567/",
          "type": "pmc",
          "title": "ADA Standards of Care 2025"
        }
      },
      "3": {
        "url": "https://doi.org/10.2337/dc24-S006",
        "title": "ADA Standards of Care in Diabetes — Glycemic Goals and Hypoglycemia",
        "metadata": {
          "url": "https://doi.org/10.2337/dc24-S006",
          "type": "guideline",
          "title": "ADA Standards of Care in Diabetes — Glycemic Goals and Hypoglycemia",
          "source": "ADA",
          "author": "American Diabetes Association",
          "doi": "10.2337/dc24-S006",
          "pubdate": "2024-01-01",
          "abstract_snippet": "Glycemic management is primarily assessed with the A1C test, which reflects average glycemia over approximately 2-3 months...",
          "specialties": ["Endocrinology"]
        }
      },
      "4": {
        "url": "https://pubmed.ncbi.nlm.nih.gov/34567890/",
        "title": "Creatinine Clearance as a Marker of GFR in CKD",
        "metadata": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/34567890/",
          "type": "insight",
          "title": "Creatinine Clearance as a Marker of GFR in CKD",
          "source": "pubmed.ncbi.nlm.nih.gov",
          "author": "Published in Kidney International",
          "pubdate": "2023"
        }
      }
    },
    "clinician": {
      "1": {
        "url": "https://pubmed.ncbi.nlm.nih.gov/87654321/",
        "title": "Management of Type 2 Diabetes: A Systematic Review",
        "metadata": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/87654321/",
          "type": "pubmed",
          "title": "Management of Type 2 Diabetes: A Systematic Review"
        }
      },
      "2": {
        "url": "https://doi.org/10.2337/dc24-S009",
        "title": "ADA Standards of Care — Pharmacologic Approaches to Glycemic Treatment",
        "metadata": {
          "url": "https://doi.org/10.2337/dc24-S009",
          "type": "guideline",
          "title": "ADA Standards of Care — Pharmacologic Approaches to Glycemic Treatment",
          "source": "ADA",
          "author": "American Diabetes Association",
          "doi": "10.2337/dc24-S009",
          "specialties": ["Endocrinology"]
        }
      }
    }
  }
}
```

<Note>
  **Guideline citations** include additional metadata fields: `source` (society acronyms like "ACC/AHA", "KDIGO"), `author` (full society names), `doi`, `pubdate`, `abstract_snippet`, and `specialties`. Not all fields are present on every citation — only `type` is guaranteed in the metadata object.
</Note>

### Citation Types

Each citation includes a `type` field in its metadata:

| Type        | Description                                                                                                                                                    | Example URL                     |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `pubmed`    | PubMed article                                                                                                                                                 | `pubmed.ncbi.nlm.nih.gov/...`   |
| `pmc`       | PubMed Central full-text                                                                                                                                       | `ncbi.nlm.nih.gov/pmc/...`      |
| `guideline` | Clinical guideline from curated corpus of 3,000+ articles from leading medical societies (ACC/AHA, KDIGO, ADA, USPSTF, ASCO, ESC, IDSA, NICE, CDC, and others) | `doi.org/...`, society websites |
| `journal`   | Peer-reviewed journal                                                                                                                                          | `bmj.com/...`, `nejm.org/...`   |
| `web`       | Other web source                                                                                                                                               | Various                         |
| `insight`   | Curated medical knowledge insight matched to patient data                                                                                                      | Various                         |

<Tip>
  **Guideline citations** are sourced from a curated database of clinical practice guidelines published by authoritative medical societies. These are prioritized for clinical protocols, treatment recommendations, screening guidance, and standard-of-care references. See [Evidence Sources](#evidence-sources) for more details.
</Tip>

### Parsing Citations

Here's how to match citation numbers in the text to their metadata:

<CodeGroup>
  ```javascript JavaScript theme={null}
  function renderWithCitations(markdownText, citations) {
    // Replace [1], [2], etc. with clickable links
    return markdownText.replace(/\[(\d+)\]/g, (match, num) => {
      const citation = citations[num];
      if (citation) {
        return `<a href="${citation.url}" target="_blank" title="${citation.title}">[${num}]</a>`;
      }
      return match; // Keep original if no citation found
    });
  }

  // Usage
  const patientHtml = renderWithCitations(
    result.patientResponse,
    result.citations.patient
  );
  ```

  ```python Python theme={null}
  import re

  def render_with_citations(markdown_text: str, citations: dict) -> str:
      """Replace [1], [2], etc. with clickable links"""
      def replace_citation(match):
          num = match.group(1)
          citation = citations.get(num)
          if citation:
              return f'<a href="{citation["url"]}" target="_blank" title="{citation["title"]}">[{num}]</a>'
          return match.group(0)
      
      return re.sub(r'\[(\d+)\]', replace_citation, markdown_text)

  # Usage
  patient_html = render_with_citations(
      result["patientResponse"],
      result["citations"]["patient"]
  )
  ```

  ```typescript TypeScript theme={null}
  interface CitationMetadata {
    url: string;
    type: 'pubmed' | 'pmc' | 'guideline' | 'journal' | 'web' | 'insight';
    title: string;
    source?: string;           // Journal name, society acronyms (e.g., "ACC/AHA"), or domain
    author?: string;           // Author name(s) or authoring organization
    pubdate?: string;          // Publication date
    abstract_snippet?: string; // Brief excerpt from the source content
    doi?: string;              // Digital Object Identifier (common on guideline citations)
    specialties?: string[];    // Medical specialties (common on guideline citations)
  }

  interface Citation {
    url: string;
    title: string;
    metadata: CitationMetadata;
  }

  interface Citations {
    patient: Record<string, Citation>;
    clinician: Record<string, Citation>;
  }

  function renderWithCitations(
    markdownText: string,
    citations: Record<string, Citation>
  ): string {
    return markdownText.replace(/\[(\d+)\]/g, (match, num) => {
      const citation = citations[num];
      if (citation) {
        return `<a href="${citation.url}" target="_blank" title="${citation.title}">[${num}]</a>`;
      }
      return match;
    });
  }
  ```
</CodeGroup>

### Rendering a References Section

You can also generate a references list to display at the end of the response:

```javascript theme={null}
function generateReferencesList(citations) {
  const entries = Object.entries(citations)
    .sort(([a], [b]) => parseInt(a) - parseInt(b));
  
  return entries.map(([num, citation]) => {
    const typeLabel = citation.metadata?.type || 'web';
    return `${num}. [${citation.title}](${citation.url}) (${typeLabel})`;
  }).join('\n');
}

// Output:
// 1. [Glycemic Control and Cardiovascular Outcomes](https://pubmed.ncbi.nlm.nih.gov/12345678/) (pubmed)
// 2. [ADA Standards of Care 2025](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC1234567/) (pmc)
```

## Selected Elements

The `selectedElements` array contains the health data elements that were analyzed:

```json theme={null}
{
  "selectedElements": [
    {
      "ehr_element_id": "Lab 1",
      "ehr_element_description": "Hemoglobin A1c [Mass/volume] in Blood",
      "category": "Laboratory Value",
      "patient_value": "7.2%",
      "relevance": "Indicates glycemic control in diabetic patients",
      "insight_ids": []
    },
    {
      "ehr_element_id": "Condition 1", 
      "ehr_element_description": "Type 2 Diabetes Mellitus",
      "category": "Diagnosed Disease",
      "patient_value": "Active",
      "relevance": "Primary diagnosis requiring comprehensive management"
    }
  ]
}
```

| Field                     | Description                                                  |
| ------------------------- | ------------------------------------------------------------ |
| `ehr_element_id`          | Unique identifier for the element                            |
| `ehr_element_description` | Human-readable description                                   |
| `category`                | Element category (Laboratory Value, Diagnosed Disease, etc.) |
| `patient_value`           | The patient's actual value or status                         |
| `relevance`               | Why this element was selected for analysis                   |

## Lab Results Agent Response

The Lab Results Agent response differs slightly from the EHR Agent:

```json theme={null}
{
  "result": {
    "labResults": [...],           // Labs that were analyzed (after limiting)
    "patientResponse": "...",      // Markdown-formatted patient summary
    "clinicianResponse": "...",    // Markdown-formatted clinical report
    "citations": {
      "patient": {...},
      "clinician": {...}
    },
    "metadata": {
      "labsReceived": 15,          // Number of labs sent in request
      "labsAnalyzed": 15,          // Number after 200-lab limit applied
      "insightsMatched": 8         // Database insights matched
    }
  }
}
```

<Note>
  The Lab Results Agent does **not** include `selectedElements` since all provided labs are analyzed directly. Instead, it includes `labResults` (the labs that were processed) and `metadata` with processing statistics.
</Note>

See the [Lab Results Agent](/api-reference/lab-results) documentation for complete request and response details.

## Research Tasks (Deep Agent Only)

For Deep Agent runs, the `researchTasks` array lists the research queries that were executed:

```json theme={null}
{
  "researchTasks": [
    "Research current ADA guidelines for glycemic control in Type 2 Diabetes",
    "Investigate SGLT2 inhibitor cardiovascular benefits in patients with CKD",
    "Analyze optimal statin therapy for diabetic patients with elevated LDL"
  ]
}
```

## Displaying Responses

<Tip>
  Both `patientResponse` and `clinicianResponse` are formatted in **Markdown**. Use a Markdown rendering library to display them properly with headers, lists, tables, and formatting.
</Tip>

### Recommended Markdown Libraries

| Platform | Library                              |
| -------- | ------------------------------------ |
| React    | `react-markdown`, `marked`           |
| Vue      | `vue-markdown-render`                |
| Angular  | `ngx-markdown`                       |
| Python   | `markdown`, `mistune`                |
| Mobile   | Platform-specific Markdown renderers |

### Example React Implementation

```jsx theme={null}
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';

function HeliosReport({ result }) {
  const { patientResponse, clinicianResponse, citations } = result;
  
  // Custom renderer to make citations clickable
  const components = {
    // Transform [1] into clickable links
    p: ({ children }) => {
      const text = children?.toString() || '';
      const withLinks = text.replace(/\[(\d+)\]/g, (match, num) => {
        const citation = citations.patient[num];
        return citation 
          ? `[${num}](${citation.url})`
          : match;
      });
      return <p>{withLinks}</p>;
    }
  };

  return (
    <div>
      <h2>Patient Summary</h2>
      <ReactMarkdown remarkPlugins={[remarkGfm]}>
        {patientResponse}
      </ReactMarkdown>
      
      <h2>Clinical Report</h2>
      <ReactMarkdown remarkPlugins={[remarkGfm]}>
        {clinicianResponse}
      </ReactMarkdown>
    </div>
  );
}
```

## Citation Counts

Typical citation counts vary by agent type and case complexity:

| Agent             | Patient Citations | Clinician Citations |
| ----------------- | ----------------- | ------------------- |
| Light Agent       | 10-20             | 15-30               |
| Deep Agent        | 15-25             | 30-50               |
| Lab Results Agent | 10-20             | 15-30               |

<Note>
  These ranges include citations from all source types — medical literature, clinical guidelines, database insights, and web sources. Citation counts may be lower for cases with limited health data or when external research services have issues. The responses are still valid even with fewer citations.
</Note>

## Evidence Sources

Helios agents draw from multiple evidence sources to provide comprehensive, well-cited analysis. Each source type appears as a distinct `type` in the citation metadata.

### Medical Literature (PubMed / PMC)

Peer-reviewed biomedical articles from the National Library of Medicine. Includes research papers, systematic reviews, meta-analyses, and clinical trials. These are the most common citation type and appear with `type: "pubmed"` or `type: "pmc"`.

### Clinical Guidelines

A curated corpus of **3,000+ clinical practice guideline articles** from authoritative medical societies, including:

* **ACC/AHA** — American College of Cardiology / American Heart Association
* **KDIGO** — Kidney Disease: Improving Global Outcomes
* **ADA** — American Diabetes Association
* **USPSTF** — U.S. Preventive Services Task Force
* **ASCO** — American Society of Clinical Oncology
* **ESC** — European Society of Cardiology
* **IDSA** — Infectious Diseases Society of America
* **NICE** — National Institute for Health and Care Excellence
* **CDC** — Centers for Disease Control and Prevention
* **NLA**, **ATA**, **ASRM**, and many others

Guideline citations are **prioritized for clinical protocols**, treatment recommendations, screening guidance, monitoring schedules, and risk stratification. They appear with `type: "guideline"` and include additional metadata such as `doi`, `source` (society acronyms), and `specialties`.

### Database Insights

Curated medical knowledge entries matched to the patient's specific data. These provide targeted clinical context based on evidence-based findings relevant to the patient's conditions and lab results. They appear with `type: "insight"`. The Lab Results Agent also reports `metadata.insightsMatched` — the number of insights matched for the analysis.

### Web Sources

Additional medical content from peer-reviewed journals, professional society websites, and other authoritative health resources. These appear with `type: "web"` or `type: "journal"` depending on the source.

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Learn about webhook delivery and signature verification.
  </Card>

  <Card title="EHR Agent" icon="file-medical" href="/api-reference/ehr-agent">
    Full EHR Agent request and response reference.
  </Card>

  <Card title="Lab Results Agent" icon="flask-vial" href="/api-reference/lab-results">
    Full Lab Results Agent request and response reference.
  </Card>

  <Card title="API Overview" icon="code" href="/api-reference/introduction">
    Shared concepts: auth, errors, privacy.
  </Card>
</CardGroup>