curl --request POST \
  --url https://api.heliosai.health/api/v1/lab-results \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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"
    }
  ]
}
'

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "accepted",
  "message": "Request accepted. Results will be delivered to your webhook."
}

{
  "error": "Validation error",
  "details": [
    {
      "path": "labResults",
      "message": "Array must contain at least 1 element(s)"
    }
  ]
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

{
  "error": "Too many concurrent requests",
  "message": "You have 7 active lab-results requests. Maximum is 7.",
  "activeCount": 7,
  "limit": 7
}

{
  "error": "<string>",
  "message": "<string>"
}

API Reference

POST /api/v1/lab-results

Submit lab results for AI-powered analysis and interpretation. The API validates your request and immediately returns a run ID. Results are delivered asynchronously to your webhook URL.

Use Case: This endpoint is optimized for lab result interpretation. Unlike the general EHR Agent (/api/v1/agent) which performs element selection from comprehensive health data, the Lab Results Agent accepts lab tests directly and focuses on:

Interpreting abnormal values in context
Identifying clinically significant patterns
Providing evidence-based recommendations
Generating patient-friendly explanations

Processing Flow:

Request validation and API key authentication
Immediate response with runId and status: "accepted" (returns in ~1 second)
Background analysis continues (typically 3-6 minutes)
Status updates sent to your webhook during processing
Final results delivered to your webhook URL

Element Limits:

Lab Results: Max 200 (sorted by date if dates provided, most recent first)
Conditions: Max 100
Medications: Max 30
Allergies: Max 20
Family History: Max 20

Pricing: $0.65 per request

curl --request POST \
  --url https://api.heliosai.health/api/v1/lab-results \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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"
    }
  ]
}
'

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "accepted",
  "message": "Request accepted. Results will be delivered to your webhook."
}

{
  "error": "Validation error",
  "details": [
    {
      "path": "labResults",
      "message": "Array must contain at least 1 element(s)"
    }
  ]
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

{
  "error": "Too many concurrent requests",
  "message": "You have 7 active lab-results requests. Maximum is 7.",
  "activeCount": 7,
  "limit": 7
}

{
  "error": "<string>",
  "message": "<string>"
}

Authorizations

x-api-key

string

header

required

API key provided by Helios Intelligence

Body

application/json

labResults

object[]

required

Array of lab test results to analyze. Dates are recommended for proper recency-based sorting. Max 200 labs processed.

Minimum array length: 1

Show child attributes

patientContext

object

Patient context for lab interpretation

Show child attributes

webhookUrl

string<uri>

URL where analysis results will be delivered via webhook

Example:

"https://your-server.com/webhook/helios"

Response

Request accepted - analysis started in background

runId

string<uuid>

required

Unique identifier for this analysis run

Example:

"550e8400-e29b-41d4-a716-446655440000"

status

enum<string>

required

Request was accepted and processing has started

Available options:

accepted

Example:

"accepted"

message

string

Human-readable status message

Example:

"Request accepted. Results will be delivered to your webhook."

Overview

Agents

API Reference

POST /api/v1/lab-results

Authorizations

Body

Response