HealthSave API Contract

Updated April 2026

HealthSave can sync Apple Health data to any self-hosted server that implements this contract. Configure the app with the base server URL only, such as https://health.example.com; HealthSave appends the endpoint paths below.

Endpoints

Method	Path	Purpose
GET	/health	Minimal process health check.
GET	/api/health	App-friendly health check.
POST	/api/apple/batch	Receives one HealthKit metric batch.
GET	/api/apple/status	Returns per-metric server counts for the sync status screen.

Authentication

If your backend requires an API key, HealthSave sends it with protected requests as an x-api-key header.

x-api-key: your-api-key

Health Checks

Both health endpoints should return a simple success object.

{
  "status": "ok"
}

Batch Ingest

POST /api/apple/batch receives one metric at a time. A successful 2xx response is enough for the app; the response body below matches the reference backend.

{
  "metric": "heart_rate",
  "batch_index": 0,
  "total_batches": 1,
  "samples": [
    {
      "date": "2026-04-10T12:00:00Z",
      "qty": 72,
      "source": "Apple Watch"
    }
  ]
}

{
  "status": "processed",
  "metric": "heart_rate",
  "batch": 0,
  "total_batches": 1,
  "records": 1
}

Quantity Samples

Quantity-like metrics use date, qty, and source. Some compatible servers also accept unit, but HealthSave does not require it on every sample.

Sleep Samples

{
  "metric": "sleep_analysis",
  "samples": [
    {
      "startDate": "2026-04-09T23:20:00Z",
      "endDate": "2026-04-10T06:45:00Z",
      "value": 3,
      "source": "Apple Watch"
    }
  ]
}

Workout Samples

{
  "metric": "workouts",
  "samples": [
    {
      "name": "Running",
      "start": "2026-04-10T07:00:00Z",
      "end": "2026-04-10T07:45:00Z",
      "duration": 2700,
      "source": "Apple Watch",
      "activeEnergy": 420,
      "distance": 6500,
      "avgHeartRate": 145,
      "maxHeartRate": 178,
      "heartRateData": [
        {"date": "2026-04-10T07:01:00Z", "qty": 132}
      ],
      "route": [
        {
          "latitude": 41.01,
          "longitude": 28.97,
          "altitude": 42.0,
          "speed": 2.8,
          "timestamp": "2026-04-10T07:01:00Z"
        }
      ]
    }
  ]
}

Activity Summary Samples

{
  "metric": "activity_summaries",
  "samples": [
    {
      "date": "2026-04-10",
      "activeEnergyBurned": 540,
      "activeEnergyBurnedGoal": 600,
      "appleExerciseTime": 42,
      "appleExerciseTimeGoal": 30,
      "appleStandHours": 12,
      "appleStandHoursGoal": 12
    }
  ]
}

Blood Pressure Correlations

Blood pressure batches use metric: "blood_pressure" at the batch level. Each sample carries its own inner metric value so systolic and diastolic readings remain distinct.

{
  "metric": "blood_pressure",
  "samples": [
    {
      "metric": "blood_pressure_systolic",
      "date": "2026-04-10T09:00:00Z",
      "qty": 120,
      "source": "Blood Pressure Monitor"
    },
    {
      "metric": "blood_pressure_diastolic",
      "date": "2026-04-10T09:00:00Z",
      "qty": 80,
      "source": "Blood Pressure Monitor"
    }
  ]
}

Category Event Samples

Category events use date, qty, source, and, when available, endDate plus rawValue. For duration-based events, qty is the duration in seconds and rawValue keeps the raw HealthKit category value. For instant events, qty is the raw category value.

{
  "metric": "mindful_session",
  "samples": [
    {
      "date": "2026-04-10T08:00:00Z",
      "endDate": "2026-04-10T08:15:00Z",
      "qty": 900,
      "rawValue": 0,
      "source": "Apple Watch"
    }
  ]
}

ECG Samples

ECG batches can include start, end, classification, numberOfVoltageMeasurements, samplingFrequency, and averageHeartRate. Store them if your backend has an ECG model, or accept the batch for compatibility.

Status Contract

GET /api/apple/status must return a flat JSON object. Every top-level key is treated as a metric name, and every top-level value should be an object with at least count. oldest and newest are optional.

{
  "heart_rate": {
    "count": 123,
    "oldest": "2026-04-01T08:00:00Z",
    "newest": "2026-04-10T12:00:00Z"
  },
  "heart_rate_variability": {
    "count": 45,
    "oldest": "2026-04-01T08:00:00Z",
    "newest": "2026-04-10T12:00:00Z"
  },
  "quantity_samples": {
    "count": 900
  }
}

Do not return {"status":"ok","counts":{...}} from this endpoint. That wrapped shape makes status look like a metric and makes counts look like one metric instead of the metric dictionary.

Metric Catalog

HealthSave accepts compatible backends that store unknown metrics generically. The names below are the source-derived catalog the app can send.