curl --request POST \
  --url https://api.heliosai.health/api/v1/agent \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "webhookUrl": "https://your-server.com/webhook/helios",
  "agentType": "light",
  "data": {
    "patientInfo": {
      "age": 45
    },
    "recentAbnormalLabs": [
      {
        "date": "2025-01-05",
        "display": "Hemoglobin A1c",
        "value": "7.2",
        "unit": "%"
      }
    ]
  }
}
'

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

{
  "error": "Validation error",
  "details": [
    {
      "path": "data.recentAbnormalLabs.0.value",
      "message": "Required"
    }
  ]
}

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

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

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

API Reference

POST /api/v1/agent

Submit health data for AI analysis. The API validates your request and immediately returns a run ID. Results are delivered asynchronously to your webhook URL.

Processing Flow:

Request validation and API key authentication
Immediate response with runId and status: "accepted" (returns in ~1 second)
Background analysis continues (5-8 minutes for Light Agent, 10-13 minutes for Deep Agent)
Status updates sent to your webhook during processing
Final results delivered to your webhook URL

Agent Types:

light: Fast analysis (5-8 minutes), $0.65/run
deep: Comprehensive analysis (10-13 minutes), $3.50/run

curl --request POST \
  --url https://api.heliosai.health/api/v1/agent \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "webhookUrl": "https://your-server.com/webhook/helios",
  "agentType": "light",
  "data": {
    "patientInfo": {
      "age": 45
    },
    "recentAbnormalLabs": [
      {
        "date": "2025-01-05",
        "display": "Hemoglobin A1c",
        "value": "7.2",
        "unit": "%"
      }
    ]
  }
}
'

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

{
  "error": "Validation error",
  "details": [
    {
      "path": "data.recentAbnormalLabs.0.value",
      "message": "Required"
    }
  ]
}

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

{
  "error": "Too many concurrent requests",
  "message": "You have 7 active light agent 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

webhookUrl

string<uri>

required

URL where analysis results will be delivered via webhook

Example:

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

agentType

enum<string>

required

Type of analysis to perform

Available options:

light,

deep

Example:

"light"

data

object

required

Patient health data for analysis. All fields are optional except at least some health data should be provided.

Show child attributes

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 in the background

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/agent

Authorizations

Body

Response