Quickstart - Helios API Documentation

This guide will walk you through making your first API call and receiving results via webhook.

Prerequisites

API Key

Get your API key from the Helios Dashboard

Webhook Endpoint

A publicly accessible HTTPS endpoint to receive results

Step 1: Set Up Your Webhook

Create an endpoint to receive analysis results. Here’s a minimal example:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/helios', (req, res) => {
  // TODO: Add signature verification for production (see /webhooks)
  const { runId, status, result, error } = req.body;
  
  console.log(`Received webhook for run ${runId}`);
  
  if (status === 'completed') {
    console.log('Patient response:', result.patientResponse);
    console.log('Clinician response:', result.clinicianResponse);
  } else if (status === 'error') {
    console.error('Analysis failed:', error.message);
  }
  
  // Always return 200 to acknowledge receipt
  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook/helios', methods=['POST'])
def webhook():
    # TODO: Add signature verification for production (see /webhooks)
    data = request.get_json()
    run_id = data.get('runId')
    status = data.get('status')
    
    print(f"Received webhook for run {run_id}")
    
    if status == 'completed':
        result = data.get('result', {})
        print(f"Patient response: {result.get('patientResponse')}")
        print(f"Clinician response: {result.get('clinicianResponse')}")
    elif status == 'error':
        error = data.get('error', {})
        print(f"Analysis failed: {error.get('message')}")
    
    # Always return 200 to acknowledge receipt
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)

For local development, use ngrok or similar to expose your local server with a public HTTPS URL.

Step 2: Make Your First API Call

Helios has two endpoints depending on your use case:

Endpoint	Best For	Request Format
`POST /api/v1/agent`	Comprehensive EHR analysis (labs, conditions, medications, imaging, genetics)	Structured EHR data wrapper
`POST /api/v1/lab-results`	Lab result interpretation	Simple lab results array + optional patient context

Option A: EHR Agent (Comprehensive Health Data)

curl -X POST https://api.heliosai.health/api/v1/agent \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook/helios",
    "agentType": "light",
    "data": {
      "patientInfo": {
        "age": 45,
        "gender": "male"
      },
      "recentAbnormalLabs": [
        {
          "date": "2025-01-15",
          "display": "Hemoglobin A1c",
          "value": "7.2",
          "unit": "%",
          "referenceRange": "4.0-5.6",
          "interpretation": "High"
        }
      ],
      "pastMedicalHistory": [
        {
          "display": "Type 2 Diabetes Mellitus",
          "clinicalStatus": "active",
          "onsetDate": "2020-03-15"
        }
      ],
      "medications": [
        {
          "medication": "Metformin 500mg",
          "status": "active",
          "dosage": "500mg",
          "frequency": "twice daily"
        }
      ]
    }
  }'

const response = await fetch('https://api.heliosai.health/api/v1/agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    webhookUrl: 'https://your-server.com/webhook/helios',
    agentType: 'light',
    data: {
      patientInfo: {
        age: 45,
        gender: 'male'
      },
      recentAbnormalLabs: [
        {
          date: '2025-01-15',
          display: 'Hemoglobin A1c',
          value: '7.2',
          unit: '%',
          referenceRange: '4.0-5.6',
          interpretation: 'High'
        }
      ],
      pastMedicalHistory: [
        {
          display: 'Type 2 Diabetes Mellitus',
          clinicalStatus: 'active',
          onsetDate: '2020-03-15'
        }
      ],
      medications: [
        {
          medication: 'Metformin 500mg',
          status: 'active',
          dosage: '500mg',
          frequency: 'twice daily'
        }
      ]
    }
  })
});

const { runId, status } = await response.json();
console.log(`Request accepted with runId: ${runId}`);

import requests

response = requests.post(
    'https://api.heliosai.health/api/v1/agent',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'webhookUrl': 'https://your-server.com/webhook/helios',
        'agentType': 'light',
        'data': {
            'patientInfo': {
                'age': 45,
                'gender': 'male'
            },
            'recentAbnormalLabs': [
                {
                    'date': '2025-01-15',
                    'display': 'Hemoglobin A1c',
                    'value': '7.2',
                    'unit': '%',
                    'referenceRange': '4.0-5.6',
                    'interpretation': 'High'
                }
            ],
            'pastMedicalHistory': [
                {
                    'display': 'Type 2 Diabetes Mellitus',
                    'clinicalStatus': 'active',
                    'onsetDate': '2020-03-15'
                }
            ],
            'medications': [
                {
                    'medication': 'Metformin 500mg',
                    'status': 'active',
                    'dosage': '500mg',
                    'frequency': 'twice daily'
                }
            ]
        }
    }
)

data = response.json()
print(f"Request accepted with runId: {data['runId']}")

Option B: Lab Results Agent (Lab Data Only)

curl -X POST https://api.heliosai.health/api/v1/lab-results \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook/helios",
    "labResults": [
      {
        "name": "Hemoglobin A1c",
        "value": "7.2%",
        "flag": "High",
        "referenceRange": "4.0-5.6%",
        "date": "2025-01-15"
      },
      {
        "name": "Creatinine",
        "value": "1.1 mg/dL",
        "flag": "Normal",
        "referenceRange": "0.7-1.3 mg/dL",
        "date": "2025-01-15"
      }
    ],
    "patientContext": {
      "age": "45",
      "gender": "male",
      "conditions": [
        { "name": "Type 2 Diabetes Mellitus", "status": "active" }
      ],
      "medications": [
        { "name": "Metformin", "dosage": "500mg", "frequency": "twice daily" }
      ]
    }
  }'

const response = await fetch('https://api.heliosai.health/api/v1/lab-results', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    webhookUrl: 'https://your-server.com/webhook/helios',
    labResults: [
      {
        name: 'Hemoglobin A1c',
        value: '7.2%',
        flag: 'High',
        referenceRange: '4.0-5.6%',
        date: '2025-01-15'
      },
      {
        name: 'Creatinine',
        value: '1.1 mg/dL',
        flag: 'Normal',
        referenceRange: '0.7-1.3 mg/dL',
        date: '2025-01-15'
      }
    ],
    patientContext: {
      age: '45',
      gender: 'male',
      conditions: [
        { name: 'Type 2 Diabetes Mellitus', status: 'active' }
      ],
      medications: [
        { name: 'Metformin', dosage: '500mg', frequency: 'twice daily' }
      ]
    }
  })
});

const { runId, status } = await response.json();
console.log(`Request accepted with runId: ${runId}`);

import requests

response = requests.post(
    'https://api.heliosai.health/api/v1/lab-results',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY'
    },
    json={
        'webhookUrl': 'https://your-server.com/webhook/helios',
        'labResults': [
            {
                'name': 'Hemoglobin A1c',
                'value': '7.2%',
                'flag': 'High',
                'referenceRange': '4.0-5.6%',
                'date': '2025-01-15'
            },
            {
                'name': 'Creatinine',
                'value': '1.1 mg/dL',
                'flag': 'Normal',
                'referenceRange': '0.7-1.3 mg/dL',
                'date': '2025-01-15'
            }
        ],
        'patientContext': {
            'age': '45',
            'gender': 'male',
            'conditions': [
                {'name': 'Type 2 Diabetes Mellitus', 'status': 'active'}
            ],
            'medications': [
                {'name': 'Metformin', 'dosage': '500mg', 'frequency': 'twice daily'}
            ]
        }
    }
)

data = response.json()
print(f"Request accepted with runId: {data['runId']}")

Both endpoints return the same immediate response:

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "accepted",
  "message": "Request accepted. Results will be delivered to your webhook."
}

Step 3: Receive the Webhook

After processing (5-8 minutes for EHR Light Agent, 3-6 minutes for Lab Results Agent), you’ll receive a webhook with the results. Here’s an EHR Agent example:

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "agent": "light",
  "timestamp": "2025-01-15T12:01:30.000Z",
  "sequenceNumber": 7,
  "result": {
    "selectedElements": [
      {
        "item": "Hemoglobin A1c",
        "category": "Laboratory Value",
        "patient_value": "7.2%",
        "matching_reason": "Elevated HbA1c indicates suboptimal glycemic control"
      }
    ],
    "patientResponse": "Your recent lab results show that your HbA1c level is 7.2%, which is above the target range...",
    "clinicianResponse": "The patient presents with elevated HbA1c (7.2%) indicating suboptimal glycemic control...",
    "citations": {
      "patient": {
        "1": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
          "title": "Glycemic Control in Type 2 Diabetes",
          "metadata": { "type": "pubmed" }
        }
      },
      "clinician": {
        "1": {
          "url": "https://pubmed.ncbi.nlm.nih.gov/87654321/",
          "title": "ADA Standards of Care 2025",
          "metadata": { "type": "pubmed" }
        }
      }
    }
  }
}

For production, you MUST verify webhook signatures to ensure requests are authentic. See the Webhooks guide for HMAC signature verification.

What’s Next?

Authentication

Learn about API key management and security.

Webhooks

Implement signature verification and handle all webhook events.

EHR Agent

Full EHR Agent reference — all fields, limits, and response format.

Lab Results Agent

Full Lab Results Agent reference — simplified lab analysis.

​Prerequisites

API Key

Webhook Endpoint

​Step 1: Set Up Your Webhook

​Step 2: Make Your First API Call

​Option A: EHR Agent (Comprehensive Health Data)

​Option B: Lab Results Agent (Lab Data Only)

​Step 3: Receive the Webhook

​What’s Next?

Authentication

Webhooks

EHR Agent

Lab Results Agent

Prerequisites

Step 1: Set Up Your Webhook

Step 2: Make Your First API Call

Option A: EHR Agent (Comprehensive Health Data)

Option B: Lab Results Agent (Lab Data Only)

Step 3: Receive the Webhook

What’s Next?