Response Format - Helios API Documentation

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:

{
  "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

## 👤 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]

The patient response uses numbered citations like [1], [2] that reference entries in the citations.patient object.

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

## 📋 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

{
  "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"]
        }
      }
    }
  }
}

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.

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

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 for more details.

Parsing Citations

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

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
);

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"]
)

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;
  });
}

Rendering a References Section

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

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:

{
  "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:

{
  "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
    }
  }
}

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.

See the Lab Results Agent 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:

{
  "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

Both patientResponse and clinicianResponse are formatted in Markdown. Use a Markdown rendering library to display them properly with headers, lists, tables, and formatting.

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

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

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.

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

Webhooks

Learn about webhook delivery and signature verification.

EHR Agent

Full EHR Agent request and response reference.

Lab Results Agent

Full Lab Results Agent request and response reference.

API Overview

Shared concepts: auth, errors, privacy.

​Response Structure Overview

​Patient Response

​Example Patient Response Structure

​Clinician Response

​Example Clinician Response Structure

​Citations System

​Citations Object Structure

​Citation Types

​Parsing Citations

​Rendering a References Section

​Selected Elements

​Lab Results Agent Response

​Research Tasks (Deep Agent Only)

​Displaying Responses

​Recommended Markdown Libraries

​Example React Implementation

​Citation Counts

​Evidence Sources

​Medical Literature (PubMed / PMC)

​Clinical Guidelines

​Database Insights

​Web Sources

​Next Steps

Webhooks

EHR Agent

Lab Results Agent

API Overview

Response Structure Overview

Patient Response

Example Patient Response Structure

Clinician Response

Example Clinician Response Structure

Citations System

Citations Object Structure

Citation Types

Parsing Citations

Rendering a References Section

Selected Elements

Lab Results Agent Response

Research Tasks (Deep Agent Only)

Displaying Responses

Recommended Markdown Libraries

Example React Implementation

Citation Counts

Evidence Sources

Medical Literature (PubMed / PMC)

Clinical Guidelines

Database Insights

Web Sources

Next Steps