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"
Endpoints
| Method | Endpoint | Agent | Processing Time | Cost |
|---|
POST | /api/v1/agent | EHR Agent (Light) | 5-8 min | $0.65 |
POST | /api/v1/agent | EHR Agent (Deep) | 10-13 min | $3.50 |
POST | /api/v1/lab-results | Lab Results Agent | 3-6 min | $0.65 |
Which Endpoint Should I Use?
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."
}
| Header | Description | Example |
|---|
X-Concurrent-Limit | Maximum concurrent requests for this agent type | 7 |
X-Concurrent-Active | Currently active requests (including this one) | 3 |
X-Concurrent-Remaining | Available slots | 4 |
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.
Both agents return Markdown-formatted responses with numbered citations:
patientResponse — Patient-friendly summaryclinicianResponse — Clinical report for providerscitations — Citation metadata keyed by number
See Response Format for parsing, rendering, and citation handling.
Error Handling
Both endpoints use the same error format:
| Status | Description |
|---|
400 | Validation error — check request body |
401 | Unauthorized — invalid or missing API key |
429 | Too many concurrent requests — see Rate Limits |
500 | Server 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.
- 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 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. 
