API Reference

Base URL

Production: https://api.hana.health/v1
Sandbox:    https://sandbox.api.hana.health/v1

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer hana_sk_live_...

API keys are scoped to an organization and environment (production or sandbox). Keys can be rotated without downtime.

Rate Limits

Endpoint	Rate Limit
Engagement creation	100/minute
Patient management	200/minute
Read operations	500/minute
Webhook management	50/minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707300000

Engagements

Engagements are the core resource. An engagement represents a single patient interaction — a call, an SMS sequence, or a multi-channel workflow.

Create Engagement

object

required

Patient information for this engagement.

Show patient properties

string

required

Your internal patient identifier.

string

required

Patient phone number (E.164 format).

string

default:"voice"

voice, sms, or whatsapp.

string

default:"en"

ISO 639-1 language code. Supported: en, it, es, de, fr.

string

required

Protocol identifier. Use a pre-configured protocol ID or custom with inline protocol definition.

string

required

scheduled, immediate, or event.

string

ISO 8601 datetime. Required when trigger_type is scheduled.

object

Additional context from your system to enrich the reasoning engine.

Show context properties

object

Structured EHR data (diagnoses, medications, vitals).

array

Recent clinical events (lab results, alerts, appointment changes).

string

Free-text clinical notes for reasoning context.

string

Webhook URL for engagement events.

object

Branding configuration for white-label deployments.

Request:

POST /v1/engagements

{
  "patient": {
    "id": "P-12345",
    "phone": "+15550123456",
    "preferred_channel": "voice",
    "language": "en"
  },
  "protocol": "medication-adherence-diabetes",
  "trigger_type": "scheduled",
  "scheduled_at": "2026-02-08T10:00:00Z",
  "context": {
    "ehr_data": {
      "diagnoses": [{"code": "E11.9", "description": "Type 2 diabetes"}],
      "medications": [{"name": "Metformin", "dose": "500mg", "frequency": "2x daily"}]
    }
  },
  "callback_url": "https://your-app.com/webhooks/hana"
}

Response:

{
  "id": "eng_abc123",
  "status": "scheduled",
  "patient_id": "P-12345",
  "protocol": "medication-adherence-diabetes",
  "scheduled_at": "2026-02-08T10:00:00Z",
  "created_at": "2026-02-07T14:30:00Z"
}

Get Engagement

GET /v1/engagements/{engagement_id}

Response:

{
  "id": "eng_abc123",
  "status": "completed",
  "patient_id": "P-12345",
  "protocol": "medication-adherence-diabetes",
  "started_at": "2026-02-08T10:02:00Z",
  "completed_at": "2026-02-08T10:08:30Z",
  "outcome": {
    "clinical_note": "...",
    "tasks": [...],
    "risk_flags": [],
    "risk_level": "low",
    "metrics": {
      "engagement_score": 0.92,
      "completion_rate": 1.0,
      "interaction_count": 8,
      "duration_seconds": 390
    }
  }
}

List Engagements

GET /v1/engagements?patient_id=P-12345&status=completed&limit=20

Query Parameters:

Parameter	Type	Description
`patient_id`	string	Filter by patient
`protocol`	string	Filter by protocol
`status`	string	`scheduled`, `in_progress`, `completed`, `failed`, `cancelled`
`from`	datetime	Start of date range
`to`	datetime	End of date range
`limit`	integer	Max results (default 20, max 100)
`cursor`	string	Pagination cursor

Cancel Engagement

DELETE /v1/engagements/{engagement_id}

Patients

Create or Update Patient

PUT /v1/patients/{patient_id}

{
  "first_name": "Maria",
  "last_name": "Garcia",
  "phone": "+15550123456",
  "email": "maria@example.com",
  "preferred_channel": "voice",
  "preferred_language": "en",
  "timezone": "America/New_York",
  "clinical_data": {
    "diagnoses": [{"code": "E11.9", "description": "Type 2 diabetes"}],
    "medications": [{"name": "Metformin", "dose": "500mg", "frequency": "2x daily"}]
  },
  "tags": ["chronic_care", "medication_monitoring"]
}

Get Patient

GET /v1/patients/{patient_id}

List Patient Engagements

GET /v1/patients/{patient_id}/engagements

Get Patient Memory

Retrieve the longitudinal context HANA has built for a patient:

GET /v1/patients/{patient_id}/memory

Response:

{
  "patient_id": "P-12345",
  "interaction_count": 12,
  "first_interaction": "2025-11-15T10:00:00Z",
  "last_interaction": "2026-02-07T10:00:00Z",
  "preferences": {
    "best_contact_time": "morning",
    "preferred_channel": "voice",
    "communication_style": "warm_conversational",
    "language_complexity": "simple"
  },
  "longitudinal_trends": {
    "medication_adherence": [0.4, 0.5, 0.6, 0.6, 0.7],
    "mood_trend": "stable",
    "engagement_quality": "high"
  },
  "active_barriers": [
    {"type": "cost", "detail": "Insurance change increasing copay", "first_reported": "2026-01-20"}
  ]
}

Protocols

List Protocols

GET /v1/protocols

Returns all configured protocols for your organization.

Create Protocol

POST /v1/protocols

{
  "name": "Post-Surgery Day 3 Check-In",
  "description": "Verify patient recovery status 3 days post-surgery",
  "objective": "Assess pain levels, medication compliance, wound status, and mobility",
  "frequency": "one_time",
  "channels": ["voice", "sms"],
  "questions": [
    {
      "id": "pain_level",
      "topic": "pain_assessment",
      "prompt": "How would you rate your pain on a scale of 1 to 10?",
      "response_type": "numeric",
      "escalation_threshold": 8
    },
    {
      "id": "medication",
      "topic": "medication_adherence",
      "prompt": "Have you been able to take your pain medication as prescribed?",
      "response_type": "boolean",
      "follow_up_if_false": "What's been preventing you from taking it?"
    },
    {
      "id": "wound",
      "topic": "wound_status",
      "prompt": "How does the incision site look? Any redness, swelling, or drainage?",
      "response_type": "text",
      "escalation_keywords": ["infected", "pus", "fever", "red", "swollen"]
    }
  ],
  "escalation_policy": "clinic-xyz-post-surgical"
}

Upload Protocol Document

Upload a PDF or document for HANA to parse into a structured protocol:

POST /v1/protocols/upload
Content-Type: multipart/form-data

Webhooks

Webhook Events

Event	Description
`engagement.scheduled`	Engagement has been scheduled
`engagement.started`	Patient interaction has begun
`engagement.completed`	Interaction completed successfully
`engagement.failed`	Interaction could not be completed
`engagement.escalated`	Risk signal detected, escalation triggered
`patient.updated`	Patient memory or profile updated

Webhook Payload

All webhook payloads include:

{
  "event": "engagement.completed",
  "timestamp": "2026-02-08T10:08:30Z",
  "engagement_id": "eng_abc123",
  "data": {
    // Event-specific data
  },
  "signature": "sha256=..."
}

Webhook Security

All webhooks are signed with HMAC-SHA256. Verify the signature using your webhook secret:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "invalid_patient_phone",
    "message": "Phone number must be in E.164 format",
    "status": 400,
    "details": {
      "field": "patient.phone",
      "provided": "555-0123",
      "expected": "+15550123456"
    }
  }
}

Status Code	Meaning
400	Invalid request
401	Authentication failed
403	Insufficient permissions
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Next: SDK Reference

Detailed SDK documentation for Node.js and Python.

​Base URL

​Authentication

​Rate Limits

​Engagements

​Create Engagement

​Get Engagement

​List Engagements

​Cancel Engagement

​Patients

​Create or Update Patient

​Get Patient

​List Patient Engagements

​Get Patient Memory

​Protocols

​List Protocols

​Create Protocol

​Upload Protocol Document

​Webhooks

​Webhook Events

​Webhook Payload

​Webhook Security

​Error Handling

Next: SDK Reference

Base URL

Authentication

Rate Limits

Engagements

Create Engagement

Get Engagement

List Engagements

Cancel Engagement

Patients

Create or Update Patient

Get Patient

List Patient Engagements

Get Patient Memory

Protocols

List Protocols

Create Protocol

Upload Protocol Document

Webhooks

Webhook Events

Webhook Payload

Webhook Security

Error Handling