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

# Quickstart

> Get started with the Helios API in 5 minutes

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

## Prerequisites

<CardGroup cols={2}>
  <Card title="API Key" icon="key">
    Get your API key from the [Helios Dashboard](https://www.heliosai.health)
  </Card>

  <Card title="Webhook Endpoint" icon="webhook">
    A publicly accessible HTTPS endpoint to receive results
  </Card>
</CardGroup>

## Step 1: Set Up Your Webhook

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

<CodeGroup>
  ```javascript Node.js (Express) theme={null}
  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'));
  ```

  ```python Python (Flask) theme={null}
  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)
  ```
</CodeGroup>

<Tip>
  For local development, use [ngrok](https://ngrok.com) or similar to expose your local server with a public HTTPS URL.
</Tip>

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
          }
        ]
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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}`);
  ```

  ```python Python theme={null}
  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']}")
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash cURL theme={null}
  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" }
        ]
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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}`);
  ```

  ```python Python theme={null}
  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']}")
  ```
</CodeGroup>

Both endpoints return the same immediate response:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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" }
        }
      }
    }
  }
}
```

<Warning>
  **For production, you MUST verify webhook signatures** to ensure requests are authentic. See the [Webhooks](/webhooks) guide for HMAC signature verification.
</Warning>

## What's Next?

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about API key management and security.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks">
    Implement signature verification and handle all webhook events.
  </Card>

  <Card title="EHR Agent" icon="file-medical" href="/api-reference/ehr-agent">
    Full EHR Agent reference — all fields, limits, and response format.
  </Card>

  <Card title="Lab Results Agent" icon="flask-vial" href="/api-reference/lab-results">
    Full Lab Results Agent reference — simplified lab analysis.
  </Card>
</CardGroup>