Skip to main content
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'));
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:
EndpointBest ForRequest Format
POST /api/v1/agentComprehensive EHR analysis (labs, conditions, medications, imaging, genetics)Structured EHR data wrapper
POST /api/v1/lab-resultsLab result interpretationSimple 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"
        }
      ]
    }
  }'

​
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" }
      ]
    }
  }'
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.