> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hana.health/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API documentation for HANA's patient engagement infrastructure.

## 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:

```bash theme={null}
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

<ParamField body="patient" type="object" required>
  Patient information for this engagement.

  <Expandable title="patient properties">
    <ParamField body="id" type="string" required>
      Your internal patient identifier.
    </ParamField>

    <ParamField body="phone" type="string" required>
      Patient phone number (E.164 format).
    </ParamField>

    <ParamField body="preferred_channel" type="string" default="voice">
      `voice`, `sms`, or `whatsapp`.
    </ParamField>

    <ParamField body="language" type="string" default="en">
      ISO 639-1 language code. Supported: `en`, `it`, `es`, `de`, `fr`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="protocol" type="string" required>
  Protocol identifier. Use a pre-configured protocol ID or `custom` with inline protocol definition.
</ParamField>

<ParamField body="trigger_type" type="string" required>
  `scheduled`, `immediate`, or `event`.
</ParamField>

<ParamField body="scheduled_at" type="string">
  ISO 8601 datetime. Required when `trigger_type` is `scheduled`.
</ParamField>

<ParamField body="context" type="object">
  Additional context from your system to enrich the reasoning engine.

  <Expandable title="context properties">
    <ParamField body="ehr_data" type="object">
      Structured EHR data (diagnoses, medications, vitals).
    </ParamField>

    <ParamField body="recent_events" type="array">
      Recent clinical events (lab results, alerts, appointment changes).
    </ParamField>

    <ParamField body="notes" type="string">
      Free-text clinical notes for reasoning context.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="callback_url" type="string">
  Webhook URL for engagement events.
</ParamField>

<ParamField body="white_label" type="object">
  Branding configuration for white-label deployments.
</ParamField>

**Request:**

```bash theme={null}
POST /v1/engagements
```

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```bash theme={null}
GET /v1/engagements/{engagement_id}
```

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
DELETE /v1/engagements/{engagement_id}
```

***

## Patients

### Create or Update Patient

```bash theme={null}
PUT /v1/patients/{patient_id}
```

```json theme={null}
{
  "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

```bash theme={null}
GET /v1/patients/{patient_id}
```

### List Patient Engagements

```bash theme={null}
GET /v1/patients/{patient_id}/engagements
```

### Get Patient Memory

Retrieve the longitudinal context HANA has built for a patient:

```bash theme={null}
GET /v1/patients/{patient_id}/memory
```

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
GET /v1/protocols
```

Returns all configured protocols for your organization.

### Create Protocol

```bash theme={null}
POST /v1/protocols
```

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```json theme={null}
{
  "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    |

<Card title="Next: SDK Reference" icon="code" href="/developers/sdk">
  Detailed SDK documentation for Node.js and Python.
</Card>