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

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	`ncbi.nlm.nih.gov/books/...`
`journal`	Peer-reviewed journal	`bmj.com/...`, `nejm.org/...`
`web`	Other web source	Various

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

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

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.

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.

Getting Started

​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

​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

Next Steps