> ## 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. # 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:** 1. Request validation and API key authentication 2. Immediate response with `runId` and `status: "accepted"` (returns in ~1 second) 3. Background analysis continues (5-8 minutes for Light Agent, 10-13 minutes for Deep Agent) 4. Status updates sent to your webhook during processing 5. 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 ## OpenAPI ````yaml /openapi/v1.json post /api/v1/agent openapi: 3.1.0 info: title: Helios AI Health Agents API version: 1.0.0 description: >- HIPAA-compliant AI health analysis API. Analyze patient health data and receive comprehensive insights via webhook. contact: name: Helios Intelligence url: https://heliosai.health email: support@heliosinc.xyz license: name: Proprietary servers: - url: https://api.heliosai.health description: Production security: - ApiKeyAuth: [] paths: /api/v1/agent: post: summary: POST /api/v1/agent description: >- 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:** 1. Request validation and API key authentication 2. Immediate response with `runId` and `status: "accepted"` (returns in ~1 second) 3. Background analysis continues (5-8 minutes for Light Agent, 10-13 minutes for Deep Agent) 4. Status updates sent to your webhook during processing 5. 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 operationId: analyzeHealthData requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentRequest' examples: minimal: summary: Minimal request with just required fields value: 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: '%' comprehensive: summary: Comprehensive request with all data types value: webhookUrl: https://your-server.com/webhook/helios agentType: light data: patientInfo: age: 45 gender: male recentAbnormalLabs: - date: '2025-01-05' display: Hemoglobin A1c value: '7.2' unit: '%' referenceRange: 4.0-5.6 interpretation: High recentNormalLabs: - date: '2025-01-05' display: Complete Blood Count value: Normal unit: '' labTrends: - code: 4548-4 display: Hemoglobin A1c values: - date: '2024-07-01' value: '6.8' unit: '%' interpretation: High - date: '2024-10-01' value: '7.0' unit: '%' interpretation: High - date: '2025-01-05' value: '7.2' unit: '%' interpretation: High pastMedicalHistory: - display: Type 2 Diabetes Mellitus clinicalStatus: active onsetDate: '2020-03-15' medications: - medication: Metformin 500mg status: active dosage: 500mg frequency: twice daily familyHistory: - relationship: mother condition: Type 2 Diabetes Mellitus onsetAge: '55' imagingStudies: - type: Chest X-Ray date: '2024-12-01' description: Chest X-ray PA and lateral modality: X-Ray geneticData: - date: '2024-06-01' geneCode: rs7903146 geneDisplay: TCF7L2 interpretation: Increased risk for Type 2 Diabetes additionalContext: >- Patient reports increased thirst and frequent urination over past month. fullyPopulated: summary: Complete request with all health data fields populated value: webhookUrl: https://your-server.com/webhook/helios agentType: light data: patientInfo: age: 58 gender: male recentAbnormalLabs: - id: obs-hba1c-001 date: '2025-01-15' code: 4548-4 display: Hemoglobin A1c value: '8.1' unit: '%' referenceRange: 4.0-5.6 % interpretation: High - id: obs-ldl-001 date: '2025-01-15' code: 2089-1 display: LDL Cholesterol value: '165' unit: mg/dL referenceRange: <100 mg/dL interpretation: High - id: obs-egfr-001 date: '2025-01-15' code: 33914-3 display: eGFR value: '52' unit: mL/min/1.73m2 referenceRange: '>60 mL/min/1.73m2' interpretation: Low recentNormalLabs: - id: obs-hgb-001 date: '2025-01-15' code: 718-7 display: Hemoglobin value: '14.2' unit: g/dL referenceRange: 13.5-17.5 g/dL interpretation: Normal - id: obs-tsh-001 date: '2025-01-15' code: 3016-3 display: TSH value: '2.1' unit: mIU/L referenceRange: 0.4-4.0 mIU/L interpretation: Normal labTrends: - code: 4548-4 display: Hemoglobin A1c values: - date: '2024-04-15' value: '7.2' unit: '%' interpretation: High - date: '2024-07-15' value: '7.6' unit: '%' interpretation: High - date: '2024-10-15' value: '7.9' unit: '%' interpretation: High - date: '2025-01-15' value: '8.1' unit: '%' interpretation: High pastMedicalHistory: - id: cond-dm-001 code: E11.9 display: Type 2 Diabetes Mellitus onsetDate: '2018-03-20' recordedDate: '2018-03-20' clinicalStatus: active verificationStatus: confirmed - id: cond-htn-001 code: I10 display: Essential Hypertension onsetDate: '2019-06-15' clinicalStatus: active verificationStatus: confirmed - id: cond-ckd-001 code: N18.3 display: Chronic Kidney Disease, Stage 3 onsetDate: '2023-11-01' clinicalStatus: active verificationStatus: confirmed medications: - id: med-metformin-001 medication: Metformin 1000mg status: active dosage: 1000mg frequency: twice daily startDate: '2018-04-01' source: statement - id: med-lisinopril-001 medication: Lisinopril 20mg status: active dosage: 20mg frequency: once daily startDate: '2019-07-01' source: request - id: med-atorvastatin-001 medication: Atorvastatin 40mg status: active dosage: 40mg frequency: once daily at bedtime startDate: '2020-01-15' source: statement familyHistory: - id: fh-father-dm relationship: father condition: Type 2 Diabetes Mellitus onsetAge: '52' - id: fh-mother-cad relationship: mother condition: Coronary Artery Disease onsetAge: '61' imagingStudies: - id: img-echo-001 type: DiagnosticReport date: '2024-11-15' description: Transthoracic Echocardiogram modality: US findings: >- Mild concentric left ventricular hypertrophy. Normal LV systolic function with EF 55-60%. conclusion: >- Mild LVH consistent with hypertensive heart disease. No significant valvular abnormalities. - id: img-renal-001 type: DiagnosticReport date: '2024-08-10' description: Renal Ultrasound modality: US findings: >- Bilateral kidneys normal in size. No hydronephrosis or masses. conclusion: Normal renal ultrasound. geneticData: - id: gen-tcf7l2-001 date: '2024-06-01' geneCode: rs7903146 geneDisplay: TCF7L2 Gene Variant interpretation: Increased risk for Type 2 Diabetes value: T/T homozygous method: SNP Genotyping additionalContext: >- Patient reports increased fatigue and nocturia over past 2 months. Recent 8 lb weight gain. Admits to dietary lapses during holiday season. Currently sedentary due to knee pain. userInstructions: >- Please focus on cardiovascular risk assessment given the combination of diabetes, hypertension, and CKD. Also interested in medication optimization opportunities. responses: '200': description: Request accepted - analysis started in background headers: X-Concurrent-Limit: description: Maximum concurrent requests allowed for this agent type schema: type: integer example: 7 X-Concurrent-Active: description: Currently active requests (including this one) schema: type: integer example: 3 X-Concurrent-Remaining: description: Available slots for additional requests schema: type: integer example: 4 content: application/json: schema: type: object properties: runId: type: string format: uuid description: Unique identifier for this analysis run example: 550e8400-e29b-41d4-a716-446655440000 status: type: string enum: - accepted description: >- Request was accepted and processing has started in the background example: accepted message: type: string description: Human-readable status message example: >- Request accepted. Results will be delivered to your webhook. required: - runId - status '400': description: Validation error - invalid request body content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized - invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized message: Invalid or missing API key '429': description: Too many concurrent requests headers: X-Concurrent-Limit: description: Maximum concurrent requests allowed schema: type: integer example: 7 X-Concurrent-Active: description: Currently active requests schema: type: integer example: 7 X-Concurrent-Remaining: description: Available slots schema: type: integer example: 0 Retry-After: description: Suggested wait time in seconds before retrying schema: type: integer example: 60 content: application/json: schema: type: object properties: error: type: string example: Too many concurrent requests message: type: string example: You have 7 active light agent requests. Maximum is 7. activeCount: type: integer example: 7 limit: type: integer example: 7 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: AgentRequest: type: object required: - webhookUrl - agentType - data properties: webhookUrl: type: string format: uri description: URL where analysis results will be delivered via webhook example: https://your-server.com/webhook/helios agentType: type: string enum: - light - deep description: Type of analysis to perform example: light data: $ref: '#/components/schemas/HealthDataInput' ValidationError: type: object properties: error: type: string example: Validation error details: type: array items: type: object properties: path: type: string description: Field path with the error example: data.recentAbnormalLabs.0.value message: type: string description: Validation error message example: Required required: - error - details Error: type: object properties: error: type: string description: Error type message: type: string description: Human-readable error message required: - error HealthDataInput: type: object description: >- Patient health data for analysis. All fields are optional except at least some health data should be provided. properties: patientInfo: $ref: '#/components/schemas/PatientInfo' recentAbnormalLabs: type: array description: Recent lab results with abnormal values items: $ref: '#/components/schemas/LabResult' default: [] recentNormalLabs: type: array description: Recent lab results with normal values items: $ref: '#/components/schemas/LabResult' default: [] labTrends: type: array description: Historical trends for specific lab values items: $ref: '#/components/schemas/LabTrend' default: [] pastMedicalHistory: type: array description: Past and current medical conditions items: $ref: '#/components/schemas/Condition' default: [] medications: type: array description: Current and past medications items: $ref: '#/components/schemas/Medication' default: [] familyHistory: type: array description: Family medical history items: $ref: '#/components/schemas/FamilyHistory' default: [] imagingStudies: type: array description: Imaging studies and reports items: $ref: '#/components/schemas/ImagingStudy' default: [] geneticData: type: array description: Genetic test results items: $ref: '#/components/schemas/GeneticData' default: [] additionalContext: type: string description: Free-text additional context about the patient example: Patient reports increased fatigue over past 2 months. userInstructions: type: string description: Optional instructions to focus the analysis example: Please focus on cardiovascular risk assessment. PatientInfo: type: object description: De-identified patient demographics (no PHI) properties: age: type: integer description: Patient age in years example: 45 gender: type: string enum: - male - female - other - unknown description: Patient gender example: male LabResult: type: object required: - display - value - unit description: >- A single lab test result. The date field should always be included - lab results almost always have dates in practice. The API sorts labs by date (most recent first) and applies limits. Labs without dates will be deprioritized during element limiting, potentially causing important recent results to be excluded from analysis. properties: id: type: string description: Unique identifier for this result date: type: string description: >- Date of the lab test (ISO 8601 or YYYY-MM-DD). Strongly recommended - labs should always include dates. Without dates, results may be deprioritized. example: '2025-01-15' code: type: string description: LOINC code for the lab test example: 4548-4 display: type: string description: Human-readable name of the lab test example: Hemoglobin A1c value: type: string description: Test result value example: '7.2' unit: type: string description: Unit of measurement example: '%' referenceRange: type: string description: Normal reference range example: 4.0-5.6 % interpretation: type: string description: Interpretation (High, Low, Normal, etc.) example: High LabTrend: type: object required: - code - display - values description: Historical trend data for a specific lab test properties: code: type: string description: LOINC code example: 4548-4 display: type: string description: Lab test name example: Hemoglobin A1c values: type: array description: Historical values over time items: type: object required: - date - value - unit properties: date: type: string example: '2024-07-01' value: type: string example: '6.8' unit: type: string example: '%' interpretation: type: string example: High Condition: type: object required: - display - clinicalStatus description: A medical condition or diagnosis properties: id: type: string description: Unique identifier code: type: string description: ICD-10 or SNOMED code example: E11.9 display: type: string description: Human-readable condition name example: Type 2 Diabetes Mellitus onsetDate: type: string description: When the condition started example: '2020-03-15' recordedDate: type: string description: When the condition was recorded clinicalStatus: type: string description: Current status enum: - active - recurrence - relapse - inactive - remission - resolved example: active verificationStatus: type: string description: Verification status example: confirmed Medication: type: object required: - medication - status description: A medication record properties: id: type: string description: Unique identifier medication: type: string description: Medication name and strength example: Metformin 500mg status: type: string description: Current status enum: - active - completed - stopped - on-hold example: active dosage: type: string description: Dosage amount example: 500mg frequency: type: string description: How often taken example: twice daily startDate: type: string description: When medication was started example: '2020-04-01' endDate: type: string description: When medication was stopped (if applicable) source: type: string enum: - statement - request description: Whether from MedicationStatement or MedicationRequest FamilyHistory: type: object required: - relationship - condition description: Family medical history entry properties: id: type: string description: Unique identifier relationship: type: string description: Relationship to patient example: mother condition: type: string description: Medical condition example: Type 2 Diabetes Mellitus onsetAge: type: string description: Age when condition developed example: '55' ImagingStudy: type: object required: - type - description description: >- An imaging study or diagnostic report. The date field should always be included - imaging studies always have dates in practice. Studies without dates will be deprioritized during element limiting. properties: id: type: string description: Unique identifier type: type: string description: Type of study example: DiagnosticReport date: type: string description: >- Date of the study. Strongly recommended - imaging studies should always include dates. Without dates, studies may be deprioritized. example: '2024-12-01' description: type: string description: Study description example: Chest X-Ray PA and lateral modality: type: string description: Imaging modality example: X-Ray findings: type: string description: Study findings conclusion: type: string description: Radiologist conclusion reportText: type: string description: Full report text GeneticData: type: object required: - geneCode - geneDisplay - interpretation description: >- Genetic test result. The date field is recommended for proper recency-based sorting. properties: id: type: string description: Unique identifier date: type: string description: >- Date of genetic test. Recommended for proper recency-based sorting. If omitted, original order is preserved. example: '2024-06-01' geneCode: type: string description: Gene or variant identifier example: rs7903146 geneDisplay: type: string description: Human-readable gene name example: TCF7L2 interpretation: type: string description: Clinical interpretation example: Increased risk for Type 2 Diabetes value: type: string description: Genotype value example: T/T homozygous method: type: string description: Testing method example: SNP Genotyping securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key provided by Helios Intelligence ````