API Documentation - HealerAgent

Base URL

https://api.healeragent.com/v1

All API requests should be made to this base URL. For sandbox/testing, use https://api-sandbox.healeragent.com/v1

Getting Started

1. Obtain API Credentials

To use the HealerAgent API, you'll need API credentials. Contact api@healeragent.com to request access or visit the Enterprise page for more information.

2. Authentication

The HealerAgent API uses OAuth 2.0 for authentication. All requests require a valid access token in the Authorization header.

3. Make Your First Request

Once authenticated, you can start making API calls. See the examples below for common use cases.

Authentication

HealerAgent API uses OAuth 2.0 with client credentials flow for server-to-server authentication. All API requests must include an access token in the Authorization header.

Obtaining an Access Token

POST /oauth/token

curl -X POST https://api.healeragent.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Using the Access Token

Include the access token in the Authorization header of all subsequent requests:

curl -X GET https://api.healeragent.com/v1/patients \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

API Endpoints

Patients

GET /patients

Retrieve a list of patients. Supports pagination and filtering.

curl -X GET "https://api.healeragent.com/v1/patients?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "pat_1234567890",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "date_of_birth": "1985-05-15",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

GET /patients/{patient_id}

Retrieve detailed information about a specific patient.

curl -X GET "https://api.healeragent.com/v1/patients/pat_1234567890" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST /patients

Create a new patient record.

curl -X POST https://api.healeragent.com/v1/patients \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "date_of_birth": "1990-08-22",
    "phone": "+1234567890"
  }'

Symptoms

POST /patients/{patient_id}/symptoms

Record a new symptom entry for a patient.

curl -X POST "https://api.healeragent.com/v1/patients/pat_1234567890/symptoms" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symptom": "headache",
    "severity": 7,
    "description": "Persistent headache in the front of head",
    "duration_minutes": 120,
    "location": "forehead",
    "timestamp": "2024-01-20T14:30:00Z"
  }'

GET /patients/{patient_id}/symptoms

Retrieve symptom history for a patient with optional date range filtering.

curl -X GET "https://api.healeragent.com/v1/patients/pat_1234567890/symptoms?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Vital Signs

POST /patients/{patient_id}/vitals

Record vital signs measurements for remote patient monitoring.

curl -X POST "https://api.healeragent.com/v1/patients/pat_1234567890/vitals" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "blood_pressure_systolic": 120,
    "blood_pressure_diastolic": 80,
    "heart_rate": 72,
    "temperature": 98.6,
    "oxygen_saturation": 98,
    "weight": 175.5,
    "timestamp": "2024-01-20T14:30:00Z"
  }'

GET /patients/{patient_id}/vitals

Retrieve vital signs history with trend analysis.

curl -X GET "https://api.healeragent.com/v1/patients/pat_1234567890/vitals?days=30" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Medications

GET /patients/{patient_id}/medications

Retrieve a patient's current medications and medication history.

curl -X GET "https://api.healeragent.com/v1/patients/pat_1234567890/medications" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST /patients/{patient_id}/medications

Add a new medication to a patient's record.

curl -X POST "https://api.healeragent.com/v1/patients/pat_1234567890/medications" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lisinopril",
    "dosage": "10mg",
    "frequency": "once daily",
    "start_date": "2024-01-15",
    "prescribed_by": "Dr. Smith"
  }'

POST /patients/{patient_id}/medications/{medication_id}/adherence

Record medication adherence (taken/missed) for tracking.

curl -X POST "https://api.healeragent.com/v1/patients/pat_1234567890/medications/med_123/adherence" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "taken": true,
    "timestamp": "2024-01-20T08:00:00Z",
    "notes": "Taken with breakfast"
  }'

Reports & Analytics

POST /patients/{patient_id}/reports

Generate a comprehensive health report for a patient covering symptoms, vitals, and medication adherence.

curl -X POST "https://api.healeragent.com/v1/patients/pat_1234567890/reports" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "format": "pdf",
    "include_symptoms": true,
    "include_vitals": true,
    "include_medications": true
  }'

GET /patients/{patient_id}/analytics/patterns

Retrieve pattern analysis and correlations between symptoms, vitals, and other health factors.

curl -X GET "https://api.healeragent.com/v1/patients/pat_1234567890/analytics/patterns?days=90" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Providers

GET /providers

Retrieve a list of healthcare providers.

curl -X GET "https://api.healeragent.com/v1/providers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST /patients/{patient_id}/providers/{provider_id}/share

Grant a healthcare provider access to a patient's health data.

curl -X POST "https://api.healeragent.com/v1/patients/pat_1234567890/providers/prov_123/share" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["read_symptoms", "read_vitals", "read_medications"],
    "expires_at": "2024-12-31T23:59:59Z"
  }'

FHIR Resources

HealerAgent API supports FHIR R4 resources for interoperability with Electronic Health Record (EHR) systems. All FHIR endpoints follow the standard FHIR RESTful API conventions.

GET /fhir/Patient/{patient_id}

Retrieve a patient resource in FHIR format.

curl -X GET "https://api.healeragent.com/v1/fhir/Patient/pat_1234567890" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/fhir+json"

GET /fhir/Observation?patient={patient_id}

Retrieve observations (symptoms, vitals) in FHIR format.

curl -X GET "https://api.healeragent.com/v1/fhir/Observation?patient=pat_1234567890&date=ge2024-01-01" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/fhir+json"

GET /fhir/MedicationStatement?patient={patient_id}

Retrieve medication statements in FHIR format.

curl -X GET "https://api.healeragent.com/v1/fhir/MedicationStatement?patient=pat_1234567890" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/fhir+json"

Error Handling

The API uses standard HTTP status codes and returns error details in a consistent JSON format.

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request is missing a required parameter",
    "details": {
      "field": "patient_id",
      "reason": "required"
    }
  }
}

HTTP Status Codes

400 Bad Request - Invalid request parameters

401 Unauthorized - Invalid or missing access token

403 Forbidden - Insufficient permissions

404 Not Found - Resource does not exist

429 Too Many Requests - Rate limit exceeded

500 Internal Server Error - Server error occurred

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability. Rate limits vary by plan:

Free Tier

100 requests per hour

Professional

1,000 requests per hour

Enterprise

10,000+ requests per hour (custom limits available)

Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset

Webhooks

Subscribe to real-time events to receive notifications when patient data is updated. Webhooks are available for Enterprise plans.

Supported Events

symptom.recorded - New symptom entry created
vital.recorded - New vital signs measurement recorded
medication.adherence - Medication adherence event
patient.created - New patient registered
alert.triggered - Health alert triggered (e.g., abnormal vital signs)

Webhook Payload Example

{
  "event": "symptom.recorded",
  "timestamp": "2024-01-20T14:30:00Z",
  "data": {
    "patient_id": "pat_1234567890",
    "symptom_id": "sym_9876543210",
    "symptom": "headache",
    "severity": 7,
    "timestamp": "2024-01-20T14:30:00Z"
  }
}

SDKs & Libraries

Official SDKs and libraries are available to simplify integration with your preferred programming language.

JavaScript/TypeScript

npm install @healeragent/sdk

Python

pip install healeragent-sdk

PHP

composer require healeragent/sdk

Request SDK Access

Support & Resources

API Support

Need help integrating? Our API support team is here to assist you.

api@healeragent.com →

Documentation

Additional resources and examples are available in our developer portal.

View Resources →