> ## 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/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:**
1. Request validation and API key authentication
2. Immediate response with `runId` and `status: "accepted"` (returns in ~1 second)
3. Background analysis continues (typically 3-6 minutes)
4. Status updates sent to your webhook during processing
5. 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



## OpenAPI

````yaml /openapi/v1.json post /api/v1/lab-results
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/lab-results:
    post:
      summary: POST /api/v1/lab-results
      description: >-
        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:**

        1. Request validation and API key authentication

        2. Immediate response with `runId` and `status: "accepted"` (returns in
        ~1 second)

        3. Background analysis continues (typically 3-6 minutes)

        4. Status updates sent to your webhook during processing

        5. 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
      operationId: analyzeLabResults
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabResultsRequest'
            examples:
              minimal:
                summary: Minimal request with just lab results
                value:
                  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'
              withPatientContext:
                summary: Request with patient context for better interpretation
                value:
                  webhookUrl: https://your-server.com/webhook/helios
                  labResults:
                    - name: Creatinine
                      value: '1.8'
                      unit: mg/dL
                      flag: High
                      referenceRange: 0.7-1.3 mg/dL
                      date: '2025-01-15'
                      category: Renal
                    - name: eGFR
                      value: '38'
                      unit: mL/min/1.73m2
                      flag: Low
                      referenceRange: '>60 mL/min/1.73m2'
                      date: '2025-01-15'
                      category: Renal
                    - name: Hemoglobin A1c
                      value: 8.1%
                      flag: High
                      referenceRange: 4.0-5.6%
                      date: '2025-01-15'
                  patientContext:
                    name: Patient
                    age: '58'
                    gender: male
                    conditions:
                      - name: Type 2 Diabetes Mellitus
                        status: active
                        onsetDate: 2018-03
                      - name: Essential Hypertension
                        status: active
                        onsetDate: 2019-06
                      - name: Chronic Kidney Disease, Stage 3b
                        status: active
                        onsetDate: 2023-11
                    medications:
                      - name: Metformin
                        dosage: 1000mg
                        frequency: twice daily
                        status: active
                      - name: Lisinopril
                        dosage: 20mg
                        frequency: once daily
                        status: active
                    familyHistory:
                      - 'Father: Type 2 Diabetes (onset age 52)'
                      - 'Mother: Coronary Artery Disease (onset age 61)'
      responses:
        '200':
          description: Request accepted - analysis started in background
          headers:
            X-Concurrent-Limit:
              description: 'Maximum concurrent requests allowed (default: 7)'
              schema:
                type: integer
                example: 7
            X-Concurrent-Active:
              description: Currently active lab-results requests (including this one)
              schema:
                type: integer
                example: 2
            X-Concurrent-Remaining:
              description: Available slots for additional requests
              schema:
                type: integer
                example: 5
          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
                    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'
              example:
                error: Validation error
                details:
                  - path: labResults
                    message: Array must contain at least 1 element(s)
        '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 lab-results 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:
    LabResultsRequest:
      type: object
      required:
        - labResults
      properties:
        labResults:
          type: array
          description: >-
            Array of lab test results to analyze. Dates are recommended for
            proper recency-based sorting. Max 200 labs processed.
          minItems: 1
          items:
            $ref: '#/components/schemas/LabResultItem'
        patientContext:
          $ref: '#/components/schemas/LabResultsPatientContext'
        webhookUrl:
          type: string
          format: uri
          description: URL where analysis results will be delivered via webhook
          example: https://your-server.com/webhook/helios
    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
    LabResultItem:
      type: object
      required:
        - name
        - value
      description: A single lab test result
      properties:
        name:
          type: string
          description: Lab test name
          example: Creatinine
        value:
          type: string
          description: Result value (may include unit)
          example: 1.8 mg/dL
        flag:
          type: string
          description: Abnormality flag
          enum:
            - High
            - Low
            - Normal
            - Critical
          example: High
        referenceRange:
          type: string
          description: Normal reference range
          example: 0.7-1.3 mg/dL
        date:
          type: string
          description: >-
            Date of the lab test (ISO 8601 or YYYY-MM-DD). Recommended for
            proper recency sorting.
          example: '2025-01-15'
        unit:
          type: string
          description: Unit of measurement (if not in value)
          example: mg/dL
        category:
          type: string
          description: Lab category for DB matching
          example: Renal
        notes:
          type: string
          description: Additional context
    LabResultsPatientContext:
      type: object
      description: Patient context for lab interpretation
      properties:
        name:
          type: string
          description: Patient name or identifier
          example: Patient
        age:
          type: string
          description: Patient age
          example: '58'
        gender:
          type: string
          description: Patient gender
          example: male
        conditions:
          type: array
          description: Medical conditions (max 100)
          items:
            $ref: '#/components/schemas/LabResultsCondition'
        medications:
          type: array
          description: Current medications (max 30)
          items:
            $ref: '#/components/schemas/LabResultsMedication'
        allergies:
          type: array
          description: Known allergies (max 20)
          items:
            type: string
        familyHistory:
          type: array
          description: Family history items (max 20)
          items:
            type: string
        vitalSigns:
          type: array
          description: Recent vital signs
          items:
            $ref: '#/components/schemas/LabResultsVitalSign'
        socialHistory:
          type: string
          description: Social history (smoking, alcohol, diet, exercise)
        clinicalNotes:
          type: string
          description: Free-text clinical notes
    LabResultsCondition:
      type: object
      required:
        - name
      description: Medical condition for lab interpretation context
      properties:
        name:
          type: string
          description: Condition name
          example: Type 2 Diabetes Mellitus
        status:
          type: string
          description: Condition status
          example: active
        onsetDate:
          type: string
          description: When the condition started
          example: 2019-03
        notes:
          type: string
          description: Additional context
    LabResultsMedication:
      type: object
      required:
        - name
      description: Medication for lab interpretation context
      properties:
        name:
          type: string
          description: Medication name
          example: Metformin
        dosage:
          type: string
          description: Dosage amount
          example: 500mg
        frequency:
          type: string
          description: How often taken
          example: twice daily
        status:
          type: string
          description: Medication status
          example: active
    LabResultsVitalSign:
      type: object
      required:
        - display
        - value
      description: Vital sign measurement
      properties:
        display:
          type: string
          description: Vital sign name
          example: Systolic blood pressure
        value:
          type: string
          description: Measurement value
          example: '142'
        unit:
          type: string
          description: Unit of measurement
          example: mmHg
        referenceRange:
          type: string
          description: Normal reference range
          example: 90-120 mmHg
        interpretation:
          type: string
          description: Interpretation
          example: High
        date:
          type: string
          description: Measurement date
          example: '2025-01-15'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key provided by Helios Intelligence

````