API Reference

The Nostavia API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Intelligence Parse

POST /v1/intelligence/parse

This is the core endpoint of the platform. Submit a raw lab report PDF or a standard JSON LIS payload. The SOMA engine will decode the unstructured data, extract all biomarkers, classify them against current clinical guidelines, and return a structured intelligence object.

Request Payload

{
  "file_url": "https://secure-bucket.s3.amazonaws.com/lab-report-smith.pdf",
  "patient_id": "usr_9983421",
  "options": {
    "include_clinical_notes": true,
    "target_guideline": "aha_2024",
    "async": false
  }
}

Massive JSON Response (Success 200 OK)

{
  "id": "rpt_x8291A9f",
  "object": "intelligence_report",
  "created": 1678892314,
  "patient_id": "usr_9983421",
  "biomarkers": [
    {
      "loinc_code": "4548-4",
      "name": "Hemoglobin A1c",
      "value": 6.8,
      "unit": "%",
      "reference_range": "< 5.7",
      "classification": "high",
      "clinical_flags": ["diabetic_range", "action_required"]
    },
    {
      "loinc_code": "2089-1",
      "name": "LDL Cholesterol",
      "value": 142,
      "unit": "mg/dL",
      "reference_range": "< 100",
      "classification": "elevated",
      "clinical_flags": ["borderline_high_risk"]
    }
  ],
  "soma_interpretation": {
    "summary": "Patient exhibits diabetic-range HbA1c (6.8%) alongside elevated LDL-C (142 mg/dL), indicating high risk for metabolic syndrome and early-stage atherosclerosis.",
    "recommended_actions": [
      "Schedule follow-up for fasting glucose and lipid panel in 3 months.",
      "Consider initiation of statin therapy per AHA 2024 guidelines.",
      "Recommend dietary intervention prioritizing low glycemic index foods."
    ],
    "confidence_score": 0.992
  }
}

Wearables Sync

GET /v1/wearables/sync

Fetch normalized telemetry data for a specific user across a date range. This endpoint unifies Apple Health, Oura, and Whoop into a single, standardized schema.

Query Parameters

• user_id (required): The Nostavia user ID.
• start_date (required): ISO 8601 timestamp.
• end_date (required): ISO 8601 timestamp.
• metrics[] (optional): Array of metrics (e.g., hrv, rhr, sleep_stages).

JSON Response

{
  "object": "list",
  "data": [
    {
      "metric": "hrv_rmssd",
      "date": "2023-10-14",
      "value": 42.5,
      "unit": "ms",
      "source": "oura_ring_gen3"
    },
    {
      "metric": "rhr",
      "date": "2023-10-14",
      "value": 54,
      "unit": "bpm",
      "source": "apple_watch_s8"
    }
  ],
  "has_more": false
}

Errors & Rate Limits

Nostavia uses standard HTTP status codes to indicate the success or failure of an API request. In general:

• 2xx indicate success.
• 4xx indicate an error that failed given the information provided (e.g., a required parameter was omitted).
• 5xx indicate an error with Nostavia's servers (these are rare).

Error Response Schema

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The 'file_url' parameter is required for the Intelligence Parse endpoint.",
    "param": "file_url"
  }
}