Skip to main content
The Helios API provides two endpoints for AI-powered health data analysis. Both use the same authentication, webhook pattern, and response format.

​
Base URL

https://api.heliosai.health

​
Authentication

All requests require an API key in the x-api-key header. The same API key works for both endpoints: 
curl -X POST https://api.heliosai.health/api/v1/agent \
  -H "x-api-key: sk_live_your_api_key"
Get your API key from the Dashboard. See Authentication for key management and security best practices.

​
Endpoints

MethodEndpointAgentProcessing TimeCost
POST/api/v1/agentEHR Agent (Light)5-8 min$0.65
POST/api/v1/agentEHR Agent (Deep)10-13 min$3.50
POST/api/v1/lab-resultsLab Results Agent3-6 min$0.65

​
Which Endpoint Should I Use?

EHR Agent

POST /api/v1/agentUse when you have comprehensive health data: labs, conditions, medications, imaging, genetics, vital signs.
  • Light mode: Fast analysis for routine cases
  • Deep mode: Multi-step literature research for complex cases
  • Supports 10+ data categories

Lab Results Agent

POST /api/v1/lab-resultsUse when you primarily have lab results to analyze.
  • Simpler request format (no EHR wrapper)
  • Faster turnaround (3-6 minutes)
  • Optimized for lab interpretation workflows
  • Optional patient context for better results

​
Shared Concepts

Both endpoints share the same patterns for authentication, responses, webhooks, and rate limiting.

​
Async Webhook Pattern

Both endpoints are asynchronous. You submit data, receive an immediate confirmation with a runId, and results are delivered to your webhook URL when processing completes. 
{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "accepted",
  "message": "Request accepted. Results will be delivered to your webhook."
}

​
Response Headers

Every API response includes concurrency status headers:
HeaderDescriptionExample
X-Concurrent-LimitMaximum concurrent requests for this agent type7
X-Concurrent-ActiveCurrently active requests (including this one)3
X-Concurrent-RemainingAvailable slots4

​
Webhook Delivery

Both agents deliver results as JSON to your webhookUrl. All webhooks include:
  • HMAC-SHA256 signature in X-Helios-Signature for verification
  • Timestamp in X-Helios-Timestamp for replay protection
  • Sequence numbers for ordering webhooks that arrive out of order
See Webhooks for payload formats, signature verification, and best practices.

​
Response Format

Both agents return Markdown-formatted responses with numbered citations from multiple evidence sources — medical literature, clinical guidelines from 30+ medical societies, database insights, and web sources:
  • patientResponse — Patient-friendly summary
  • clinicianResponse — Clinical report for providers
  • citations — Citation metadata keyed by number, with source type classification
See Response Format for parsing, rendering, citation handling, and details on evidence sources.

​
Error Handling

Both endpoints use the same error format:
StatusDescription
400Validation error — check request body
401Unauthorized — invalid or missing API key
429Too many concurrent requests — see Rate Limits
500Server error — retry later
{
  "error": "Validation error",
  "details": [
    { "path": "webhookUrl", "message": "Invalid URL format" }
  ]
}

​
Rate Limits

Concurrency limits are tracked separately per agent type. Default is 7 concurrent requests per agent type. See Rate Limits for details.

​
Data Privacy & Logging

Helios is designed for HIPAA compliance. We maintain operational logs for billing, monitoring, and debugging, but patient health data is never stored.

​
What We Store

Each API request creates a log entry containing operational metadata only:
  • Request identifiers: Run ID, API key used, company ID
  • Processing metrics: Agent type, duration, token usage, success/error status
  • Aggregate counts: Number of elements analyzed, citations generated
  • Error information: Error codes and types (if processing failed)

​
What We Do NOT Store

Your patient health data is never persisted to our database. All health information is processed in-memory only and discarded immediately after results are delivered to your webhook.
The following data is processed transiently but never stored:
  • Patient health data (labs, conditions, medications, imaging, genetics)
  • Patient demographics (age, gender)
  • Free-text context and user instructions
  • Generated responses (patient and clinician summaries)
  • Research citations, clinical guideline references, and literature content
Even your webhook URL is not stored — only a truncated hash is kept for operational metrics.

​
Logging & Observability

We use HIPAA-compliant logging and error observability tools for operational monitoring. These systems:
  • Track request success/failure rates and latency
  • Alert on errors and service degradation
  • Support debugging without exposing health data
All logging infrastructure is configured to exclude PHI and health data from traces, logs, and error reports.