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

# API Overview

> Helios API endpoints and shared concepts

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:

```bash theme={null}
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](https://www.heliosai.health). See [Authentication](/authentication) for key management and security best practices.

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

<CardGroup cols={2}>
  <Card title="EHR Agent" icon="file-medical" href="/api-reference/ehr-agent">
    **`POST /api/v1/agent`**

    Use 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
  </Card>

  <Card title="Lab Results Agent" icon="flask-vial" href="/api-reference/lab-results">
    **`POST /api/v1/lab-results`**

    Use 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
  </Card>
</CardGroup>

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

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

| 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](/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](/response-format) for parsing, rendering, citation handling, and details on evidence sources.

### 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](/rate-limits) |
| `500`  | Server error — retry later                                     |

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

<Warning>
  **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.
</Warning>

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.