Stridee
Stridee Platform Docs

Apple Health

New

Apple Watch and iPhone workouts and wellness from HealthKit, pushed from your own iOS app by the StrideeHealth SDK and delivered like any other provider's — and the workouts you push, scheduled on the watch by the same SDK.

HealthKit has no server API. An Apple Watch's runs and nights live on the iPhone, readable only by an app the user has granted access to — yours. There is no URL to send them to and no consent page of ours: the permission sheet is iOS's own, and the only thing that can read the data is code running in your app.

So the direction flips. Instead of us fetching from a provider, your app reads HealthKit and pushes to us, and our Swift package does the reading, the batching and the retrying. What reaches your webhook is the same as from Garmin: activity.created with a FIT file, wellness.created with the same metrics, under provider: "apple".

It works in the other direction too: a workout you create with POST /v1/workouts is scheduled on the athlete's Apple Watch by the same package. See Workouts on Apple Watch.

How it fits together

Your app must never hold your signing key — anyone with the IPA would have it, and it signs for every user on your account. So your server mints a short-lived device token for the one signed-in user, and the app pushes with that.

A device token is the same idea as a Stripe ephemeral key or a Plaid link token:

  • It lasts an hour. The SDK asks for a fresh one when it runs out.
  • It pushes for one user and reads none of their data. A stolen one can add workouts to one person's history for the rest of its hour. The only thing it can read is the workouts you scheduled for that person's Apple Watch — what tomorrow's session is, not anything they recorded.
  • We keep only its SHA-256. We cannot show it back to you, and you should not store it either — mint one each time the app asks.

Calls made with one appear in your request log without a key id, since no key signed them.

Who talks to whom
Your app                     Your server                       Stridee
   │  "a token, please"           │                               │
   │  (your own session) ───────▶ │  POST /v1/device-tokens       │
   │                              │  signed ────────────────────▶ │
   │                              │ ◀──── { token: "sdt_…", … }   │
   │ ◀───────── token ─────────── │                               │
   │                                                              │
   │  Authorization: Bearer sdt_…                                 │
   │  PUT  /v1/device/connections/apple ────────────────────────▶ │ ─▶ account.connected
   │  POST /v1/device/apple/workouts ───────────────────────────▶ │ ─▶ activity.created
   │  POST /v1/device/apple/recordings ─────────────────────────▶ │ ─▶ activity.created
   │  POST /v1/device/apple/wellness ───────────────────────────▶ │ ─▶ wellness.created
   │  GET  /v1/device/apple/scheduled-workouts ◀─────────────────  │    your POST /v1/workouts

1. Mint tokens on your server

Add a route to your own backend, behind your own sign-in, that calls this and hands the token to the app. Your server has already decided who the person is; that signed call is how it vouches for them to us.

post /v1/device-tokens
Reference

Mint a device token.

Call this from your server, when your app asks for one on behalf of a user who is signed in to it. The token lets the app push that user's Apple Health data directly to Stridee — and fetch the workouts you scheduled for their Apple Watch — so your signing key never has to leave your server and workouts never have to pass through it.

Mint freely: every call returns a new token, tokens expire after an hour, and a person may hold several at once — one per device.

Body parameters
external_user_idstringRequired

Your id for the person whose phone this is — the same value you would pass to POST /v1/connect. Creates them on first sight, so there is no separate call to register a user.

signRequest is the helper from Signing requests.

  • Mint per request. Every call returns a new token, and a user may hold several live ones at once — one per device is normal.
  • external_user_id is the same id you pass to /v1/connect. It creates the user on first sight, so someone with an Apple Watch and a Garmin is one user with two connections, not two users.
POST /v1/device-tokens
POST /v1/device-tokens HTTP/1.1
Host: api.stridee.com
Content-Type: application/json
Content-Digest: sha-256=:…:
Signature-Input: sig1=(…);keyid="…";alg="ed25519"
Signature: sig1=:…:

{
  "external_user_id": "user_4821"
}
Response · 201
{
  "expires_at": "2026-08-05T11:44:02Z",
  "token": "string",
  "user_id": "4c9a7e15-6d3b-42f8-91c0-8e5b2a7d04f6"
}
device-token.js
import { signRequest } from './sign-request.js'; // from "Signing requests"

app.post('/stridee/device-token', requireUser, async (req, res) => {
  const url = 'https://api.stridee.com/v1/device-tokens';
  const body = JSON.stringify({ external_user_id: req.user.id });

  const response = await fetch(url, {
    method: 'POST',
    headers: { 'content-type': 'application/json', ...signRequest({ method: 'POST', url, body }) },
    body,
  });

  const { token, expires_at } = await response.json();
  res.json({ token, expires_at });
});

2. Add the SDK

StrideeHealth is a Swift package for iOS 17 and later. In Xcode, File → Add Package Dependencies… and paste:

Then three things in your app target. Miss the first two and nothing fails loudly — data simply stops arriving whenever the app is not open.

HealthKit capabilitySigning & Capabilities → + Capability → HealthKit.
Background DeliveryTick it under the HealthKit capability. It adds com.apple.developer.healthkit.background-delivery, which lets iOS wake your app when a new workout lands.
NSHealthShareUsageDescriptionThe sentence on iOS's permission sheet. Without it, asking for access crashes the app. The SDK only reads, so you don't need NSHealthUpdateUsageDescription.
Package URL
https://github.com/stridee-fit/stridee-health-ios
YourApp.entitlements
<key>com.apple.developer.healthkit</key>
<true/>
<key>com.apple.developer.healthkit.background-delivery</key>
<true/>
Info.plist
<key>NSHealthShareUsageDescription</key>
<string>YourApp reads your workouts, sleep and heart rate to build your training plan.</string>

3. Configure it at launch

Call configure in application(_:didFinishLaunchingWithOptions:) — every launch, not only when the user taps something. When iOS wakes your app in the background to deliver new health data, it is this call that registers the observers that receive it; configure later and the wake-up is wasted. A SwiftUI app uses @UIApplicationDelegateAdaptor to get a delegate.

tokenProvider is the only required setting. The rest:

SettingDefault
dataTypes[.workouts, .wellness]Drop one to sync only the other.
excludedSourceBundleIDsGarmin Connect and WahooWorkouts written into HealthKit by these apps are skipped. If you also connect those providers, their workouts already arrive natively, and syncing the HealthKit copy would deliver each run twice.
wellnessHistoryDays90How far back wellness goes on the first sync.
baseURLhttps://api.stridee.comChange it only if we tell you to.
importWorkoutAnchorFromUserDefaultsKeynoneFor an app moving from its own HealthKit sync: the UserDefaults key holding its workout query anchor, so the SDK starts where your code stopped instead of sending every workout again.
schedulesWorkoutsfalsePut the workouts you push on the athlete's Apple Watch. See Workouts on Apple Watch.
AppDelegate.swift
import StrideeHealth

final class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        HealthSync.configure(HealthSync.Configuration(
            // Your route from step 1, called with your own session.
            tokenProvider: {
                let minted = try await MyAPI.strideeDeviceToken()
                return HealthSync.DeviceToken(token: minted.token, expiresAt: minted.expiresAt)
            }
        ))
        return true
    }
}

4. Connect

When your user taps "Connect Apple Health":

That shows iOS's permission sheet, connects the user (your webhook gets account.connected), and starts syncing — history first, then each new workout and night as HealthKit records it. From then on:

  • disconnect(revokeOnServer: false) stops this device only — on sign-out, say — and leaves the user connected, so their other devices keep syncing. The default disconnects them everywhere: see Disconnecting.
  • connect(requestingAuthorization: false) connects without showing the sheet, for an app that already holds HealthKit access from its own integration. needsAuthorization() tells you beforehand whether connect() would show it.
  • lastError is a HealthSyncError: healthDataUnavailable (no HealthKit on this device), notConfigured, notConnected, disconnectedRemotely (your server disconnected them), tokenUnavailable (your token route failed), rejected (we refused an upload, with our status and message) or transport.

Three things about the phone that shape your UI:

  • iOS never says whether read access was granted. That is deliberate on Apple's part — a denial would itself reveal something about the user's health. See Permissions for what you can know instead, and how to ask well.
  • Health data is unreadable while the phone is locked. A workout that ends with the phone in a pocket syncs after the next unlock, not before.
  • Nothing is lost to an outage. Uploads are queued on disk and retried. If your token route is down, the queue waits for it.
SettingsView.swift
try await HealthSync.shared.connect()
SWIFT
let status = HealthSync.shared.status   // @Published on HealthSync.shared, an ObservableObject
// isConnected, isSyncing, lastSyncDate, lastError, pendingUploads, progress

try await HealthSync.shared.syncNow()
await HealthSync.shared.disconnect()

5. Permissions

Apple shows its permission sheet once per data type, ever. A user who meets it cold tends to switch everything off, and from then on the only way back is the Settings app. So the SDK gives you the pieces to ask well, and to notice when the answer was no.

Explain first, then ask

HealthAccessPrimer is a ready-made SwiftUI screen to show before Apple's sheet: what you read, what it is for, Continue and Not now. Continue connects — which shows Apple's sheet — and onFinished fires once it has.

The words are yours. HealthAccessPrimer.Copy.english is a starting point; pass your own Copy with localized strings — the SDK ships no translations. To do something other than connect on Continue, pass action:.

SettingsView.swift
.sheet(isPresented: $showPrimer) {
    HealthAccessPrimer(
        onFinished: { showPrimer = false },
        onNotNow: { showPrimer = false }
    )
}

Ask without connecting

To ask during onboarding and connect later — or to ask for types you added to dataTypes after users had already answered — call:

iOS only shows the sheet for types never asked about, so calling it again is harmless.

SWIFT
try await HealthSync.shared.requestAuthorization()            // the configured types
try await HealthSync.shared.requestAuthorization(for: [.wellness])

What you can know

status.authorization.unavailable (no HealthKit on this device), .notRequested (the sheet would appear) or .requested (the user has answered for every type). There is no granted: .requested means they answered, not that they said yes. authorizationStatus() asks HealthKit afresh.
status.lastDataFoundWhen a sync last found new data, per data type — [.workouts: Date, .wellness: Date]. The closest thing to a permission check iOS allows.

Put them together for the one case worth handling: connected for a few days, lastDataFound still empty for .workouts, from a user you know trains. That usually means they left the switches off. Tell them so, with a button:

It opens your app's page in Settings — iOS has no link straight to the Health switches. On recent iOS the page lists Health; otherwise the switches are at Settings → Health → Data Access & Devices → your app. Say which in the sentence around the button.

SWIFT
await HealthSync.shared.openSettings()

6. Workouts on Apple Watch

Apple has no server API for putting a workout on a watch. The only way in is WorkoutKit, which runs inside an iOS app on the athlete's phone — so for Apple, the last step of a workout push happens in your app, and the SDK does it.

That shows iOS's own sheet, once. When the athlete allows it, their Apple connection gains the workout_scheduling scope and becomes a device POST /v1/workouts pushes to — by name with provider: "apple", or with every other connected device when you omit provider. Nothing changes on your server: the same call, the same pushes array.

  • pending until the phone syncs. We cannot reach the phone; it has to come to us. The SDK fetches and schedules on every sync — the app coming to the foreground, HealthKit waking it for new data — and the push turns synced. To put a workout on the watch right away, send your app a silent push and call HealthSync.shared.syncScheduledWorkouts().
  • The soonest workouts go first. The Workout app holds a small fixed number of scheduled workouts (WorkoutScheduler.maxAllowedScheduledWorkoutCount). The SDK fills it with the nearest dates and leaves the rest pending until earlier ones have passed, so a season's plan can be created in one go.
  • It needs a date. The Workout app has a calendar and no library. A workout with no scheduled_date, or one dated before today, comes back unsupported for Apple.
  • Edits and deletes follow. A PATCH replaces the scheduled workout at the next sync; a DELETE takes it off the watch then.
  • If the athlete says no, the push becomes failed with reason: "not_permitted", and lands by itself the moment they allow it — no new push. status.workoutScheduling .authorization is .denied, a real answer here, unlike reading health data. Show openSettings().
  • Before anyone has allowed it, naming apple is a 409, and omitting provider skips Apple, exactly as before this existed.
AppDelegate.swift
HealthSync.configure(HealthSync.Configuration(
    tokenProvider: { … },
    schedulesWorkouts: true
))
SettingsView.swift
// When the athlete turns on "Send workouts to my Apple Watch":
await HealthSync.shared.requestWorkoutSchedulingAuthorization()
POST /v1/workouts → 201
"pushes": [
  { "provider": "garmin", "status": "synced", "external_id": "1284410973" },
  { "provider": "apple", "status": "pending" }
]
SWIFT
let scheduling = HealthSync.shared.status.workoutScheduling
// authorization, scheduledCount, waitingCount, lastSyncDate, lastError

What an Apple Watch can carry

A WorkoutKit custom workout is a warm-up, blocks of steps that repeat, and a cool-down. A step ends on a time, a distance, calories or the lap button, and holds the athlete to one target.

Sportsrunning, treadmill_running, cycling, indoor_cycling, swimming, hiking, cardio, hiit, yoga, pilates and generic — as far as the phone's iOS supports each as a custom workout. treadmill_running and indoor_cycling start the indoor run and ride.
Durationstime, distance, yards, miles, calories and open. A reps step becomes an open step named for its count.
Targetspace, heart_rate, power, cadence, heart_rate_zone and power_zone. An average of lap holds the step's average; 3s, 10s and 30s become the watch's live reading.
Repeatsrepeat.
NamesEach step's name, from watchOS 11.

Anything else comes back unsupported with a sentence saying what — a strength exercise, a multi_sport workout, a repeat_until, a send-off, a threshold duration, a percentage, grade, resistance, a swim-only target or a secondary_target. Stroke, drill and equipment are not shown, so name your drill steps. And where the athlete's version of iOS cannot build something WorkoutKit otherwise has, the SDK reports unsupported from the phone rather than scheduling a different workout.

When they do it

A workout the athlete starts from the one you pushed comes back saying so: its activity.created carries data.workout_id, the id POST /v1/workouts gave you. No matching on start times — WorkoutKit keeps the link, and the SDK sends it with the recording. A workout started any other way has no workout_id.

Its FIT file then has one lap per step, each with the step's intensity and wkt_step_index, and the plan itself as workout and workout_step messages — the shape a Garmin file has for a structured workout. A repeat's steps keep one index across its rounds, as on Garmin, and recording that runs on past the last step is a final lap with neither field.

HealthKit does not hand us the watch's own step boundaries, so we place them from the plan: a time step ends when its time is up, a distance step when its distance is covered, both counted on the timer. A pause holds the step it falls in, so that lap's total_elapsed_time takes in the pause and its total_timer_time does not. Where it would be a guess the file keeps a single lap, as for any other Apple workout — when a step ends on the lap button or on calories, when the workout was paused for longer than its pause events account for (as with an SDK older than they are), when it ended before the plan did, or when a distance step has no GPS route to be measured on.

7. Recording workouts with GPS

The SDK records runs, rides, walks and hikes on the iPhone itself. Your app draws the screens and the SDK does the rest: GPS filtering, auto-pause, elevation from the barometer, auto-laps, structured-workout steps, pace cues and a Bluetooth heart-rate strap. A finished recording is saved to Apple Health and arrives on your webhook as activity.created with a FIT file, like any Apple Watch workout.

The SDK sends it to POST /v1/device/apple/recordings. That takes the same healthkit.v1 body as POST /v1/device/apple/workouts, with one difference: recording a workout in your app is the athlete's say-so, so it connects them if they are not connected (account.connected the first time) instead of refusing with a 409. Someone who never turned on Apple Health sync can still record. The workout is not sent a second time by the Apple Health sync.

SWIFT
let recorder = WorkoutRecorder.shared
await recorder.requestAuthorization()   // location, then Apple Health
try recorder.start(.running)
let workout = try await recorder.finish()

What you receive

The same events as any provider, with provider: "apple":

EventWhen
account.connectedThe first time the user connects — again only after a disconnect.
activity.createdA workout arrived. data.file.format is fit.
wellness.created / wellness.updatedA summary arrived, or one you have was revised.
account.disconnectedThe user turned syncing off in your app, or you disconnected them.

Workouts

HealthKit has no workout file, so the SDK sends the workout and its samples — heart rate, running and cycling power, cadence, the GPS route — and we encode a FIT file from them. You fetch it from GET /v1/activities/{id}/file like any other recording, so the parser you already run for Garmin reads it.

  • Idempotent on the HealthKit workout's UUID. A workout sent twice is delivered once.
  • Timer events where it was paused. The FIT has a timer event when the workout starts, stop_all and start around each pause, and stop_all at the end, as a Garmin file does. data is the timer_trigger: auto for the watch's auto-pause, manual otherwise. Records keep coming during a pause when the watch kept measuring, so read the events to tell moving time from stopped time.
  • workout_id and a lap per step when it was one of yours. See When they do it. Any other workout is one lap.
  • Only your account ever receives a given Apple workout. Each app has its own HealthKit grant, so unlike Garmin — where one athlete can be connected to several developers at once — the same workout never fans out to anyone else.

Wellness

Nine of the twelve kinds. The SDK computes daily totals on the phone with HealthKit's statistics queries, which merge iPhone and Apple Watch correctly: summed raw, the steps both of them counted would be counted twice.

kindFrom HealthKitIn metrics
dailyTotals from local midnightsteps, distance_meters, active_kilocalories, bmr_kilocalories, floors_climbed, moderate_intensity_seconds, resting_hr, avg_hr, min_hr, max_hr
sleepSleep stagestotal_sleep_seconds, light_sleep_seconds, deep_sleep_seconds, rem_sleep_seconds, awake_seconds
hrvHRV samples (SDNN, ms)hrv_sdrr — not hrv_avg, see below
fitnessVO₂maxvo2_max
respirationBreaths per minuterespiration_min, respiration_avg, respiration_max
pulse_oxBlood oxygen, percentspo2_min, spo2_avg
body_compositionWeight, body fat, BMIweight_grams, body_fat_percent, body_mass_index
blood_pressureOne cuff readingsystolic, diastolic
skin_temperatureSleeping wrist temperatureskin_temp_celsius

Apple's HRV is SDNN, and it is in hrv_sdrr. Garmin, Zepp and Fitbit report RMSSD in hrv_avg. The two are different statistics with different normal ranges, so we keep them in different fields: a chart that plots hrv_avg shows no Apple data rather than a wrong line. Don't merge them without converting — and there is no exact conversion.

The rest of the mapping:

  • Sleep: Apple's core is light sleep. inBed counts toward nothing. asleepUnspecified — older watches, or sleep tracked by the iPhone alone — counts toward the total but toward no stage, so the stages can add up to less than total_sleep_seconds.
  • Overlapping sleep samples are counted once. Some sources (Oura, for one) write stage samples that overlap each other. Each moment of the night counts toward a single stage: awake first, then deep, rem, core, asleepUnspecified. The totals can therefore be less than the sum of the samples' durations at series_url.
  • moderate_intensity_seconds is Apple's exercise minutes × 60. Apple doesn't split exercise by intensity, so all of it is filed as moderate and none as vigorous.
  • skin_temp_celsius is absolute, not a deviation from baseline: the baseline the Health app shows is not exported. Garmin's deviation is in skin_temp_deviation_celsius.
  • finality is set on every kind, from the item's final. Today's daily arrives tentative and is resent as the day goes on; each change is a wellness.updated.
  • summary is the item as the SDK sent it, camelCase; the samples and stage list behind it are at series_url.
  • Never from Apple: stress, epoch and health_snapshot. HealthKit has nothing they could be built from.

History

On the first sync, every workout HealthKit holds — Apple Watch history routinely goes back years — and the last wellnessHistoryDays of wellness (90 by default). It is uploaded from the phone, so it arrives over the app's first runs and background wake-ups rather than in one go.

Relaying through your own server

If your app already reads HealthKit itself, you can skip the SDK and the device token and send the same JSON from your backend, signed like every other /v1/* call. {id} is the user_id from GET /v1/accounts or a device-token call.

post /v1/accounts/{id}/apple/workouts
Reference

Push a HealthKit workout from your own server.

For apps that read HealthKit themselves and relay through their backend rather than using the SDK's direct upload. Same body and same behavior as POST /v1/device/apple/workouts, signed like the rest of /v1/*.

Relaying connects the user if they are not already — your server sending their workouts is the consent — and sends account.connected the first time.

Path parameters
idstring · uuidRequired

The user's user_id

Body parameters
activityTypeinteger · int32Required

HKWorkoutActivityType's raw value, kept for reference.

durationnumber · doubleRequired

Seconds, as HKWorkout.duration reports it (paused time excluded).

endDatestring · date-timeRequired
serverTypestringRequired

The discipline: RUNNING, CYCLING, SWIMMING, WALKING, HIKING, ROWING, CROSS_COUNTRY_SKIING, ALPINE_SKIING, SNOWBOARDING, PADDLING, ROCK_CLIMBING, TRAINING or GENERIC. Becomes the FIT file's sport.

startDatestring · date-timeRequired
uuidstringRequired

The HKWorkout's UUID. Its identity: sending the same one twice delivers it once.

cyclingCadenceRawSample[]

Revolutions per minute.

Show child attributes
tstring · date-timeRequired

When it was measured.

vnumber · doubleRequired

The value, in the stream's unit.

cyclingPowerRawSample[]

Watts.

Same RawSample shape as above.

deviceNamestring

The recording device's name or model, when HealthKit has one.

eventsRawEvent[]

The workout's pause and resume events, HKWorkout.workoutEvents of those types. They become the FIT file's timer events. Omitted by SDKs that predate them, which then read as a workout never paused.

Show child attributes
tstring · date-timeRequired

When it happened.

typestringRequired

pause or resume, pressed by the athlete, or motionPaused or motionResumed, the watch's auto-pause. Anything else is ignored.

formatstring

healthkit.v1. Optional, but anything else is refused.

heartRateRawSample[]

Beats per minute.

Same RawSample shape as above.

routeRawLocation[]

GPS points, HKWorkoutRoute's CLLocations in time order. Empty for an indoor workout.

Show child attributes
latnumber · doubleRequired

Degrees.

lonnumber · doubleRequired

Degrees.

tstring · date-timeRequired
altitudenumber · double

Meters above sea level.

coursenumber · double

Degrees from true north.

horizontalAccuracynumber · double

Meters.

speednumber · double

Meters per second.

verticalAccuracynumber · double

Meters.

runningPowerRawSample[]

Watts.

Same RawSample shape as above.

sourceBundleIdstring

That app's bundle id — com.apple.health for an Apple Watch workout.

sourceNamestring

The app that wrote the workout into HealthKit, by name.

totalDistanceMetersnumber · double
totalEnergyKcalnumber · double

Active energy, kilocalories.

workoutPlanIdstring

The WorkoutKit WorkoutPlan this workout was started from — HKWorkout.workoutPlan?.id — when there was one. For a workout you pushed to the athlete's Apple Watch it is the plan_id the schedule listed, and it is what puts workout_id on the resulting activity.created. Omit it for a workout started any other way.

post /v1/accounts/{id}/apple/wellness
Reference

Push Apple Health wellness data from your own server.

The relay counterpart of POST /v1/device/apple/wellness: same body, same behavior, signed. Connects the user if they are not already.

Path parameters
idstring · uuidRequired

The user's user_id

Body parameters
itemsany[]Required

One object per measurement. Every item carries kind, calendarDate and startTime; the rest depends on the kind.

formatstring

healthkit.wellness.v1.

Relaying connects the user if they aren't already — your server sending their data is the consent — and sends account.connected the first time.

You take on what the SDK otherwise does: registering background delivery, querying HealthKit, computing daily totals with statistics queries rather than summing samples, and retrying. Workouts pass through your server, and so does their size.

POST /v1/accounts/{id}/apple/workouts
POST /v1/accounts/4c9a7e15-6d3b-42f8-91c0-8e5b2a7d04f6/apple/workouts HTTP/1.1
Host: api.stridee.com
Content-Type: application/json
Content-Digest: sha-256=:…:
Signature-Input: sig1=(…);keyid="…";alg="ed25519"
Signature: sig1=:…:

{
  "activityType": 0,
  "cyclingCadence": [
    {
      "t": "2026-08-05T11:44:02Z",
      "v": 0
    }
  ],
  "cyclingPower": [
    {
      "t": "2026-08-05T11:44:02Z",
      "v": 0
    }
  ],
  "deviceName": null,
  "duration": 0,
  "endDate": "2026-08-05T11:44:02Z",
  "events": [
    {
      "t": "2026-08-05T11:44:02Z",
      "type": "string"
    }
  ],
  "format": null,
  "heartRate": [
    {
      "t": "2026-08-05T11:44:02Z",
      "v": 0
    }
  ],
  "route": [
    {
      "altitude": null,
      "course": null,
      "horizontalAccuracy": null,
      "lat": 0,
      "lon": 0,
      "speed": null,
      "t": "2026-08-05T11:44:02Z",
      "verticalAccuracy": null
    }
  ],
  "runningPower": [
    {
      "t": "2026-08-05T11:44:02Z",
      "v": 0
    }
  ],
  "serverType": "string",
  "sourceBundleId": null,
  "sourceName": null,
  "startDate": "2026-08-05T11:44:02Z",
  "totalDistanceMeters": null,
  "totalEnergyKcal": null,
  "uuid": "string",
  "workoutPlanId": null
}
Response · 202
{
  "status": "active",
  "uuid": "string"
}
POST /v1/accounts/{id}/apple/wellness
POST /v1/accounts/4c9a7e15-6d3b-42f8-91c0-8e5b2a7d04f6/apple/wellness HTTP/1.1
Host: api.stridee.com
Content-Type: application/json
Content-Digest: sha-256=:…:
Signature-Input: sig1=(…);keyid="…";alg="ed25519"
Signature: sig1=:…:

{
  "format": null,
  "items": [
    null
  ]
}
Response · 202
{
  "items": 0,
  "status": "active"
}

The payload formats

The SDK writes these; you need them only if you relay, or push from the device yourself with a token. Both are camelCase JSON with ISO 8601 dates.

healthkit.v1 — one workout

post /v1/device/apple/workouts
Reference

Push a HealthKit workout from the athlete's device.

The Stridee SDK calls this for every new workout HealthKit reports. The body is the healthkit.v1 JSON: the workout, its sample streams and its route. We turn it into a FIT file and deliver it like any provider's workout — activity.created on your webhook, the file on GET /v1/activities/{id}/file.

Idempotent on the workout's uuid: sending one twice delivers it once. A 409 means the user is not connected (never connected, or disconnected since); a 503 means retry later.

Body parameters
activityTypeinteger · int32Required

HKWorkoutActivityType's raw value, kept for reference.

durationnumber · doubleRequired

Seconds, as HKWorkout.duration reports it (paused time excluded).

endDatestring · date-timeRequired
serverTypestringRequired

The discipline: RUNNING, CYCLING, SWIMMING, WALKING, HIKING, ROWING, CROSS_COUNTRY_SKIING, ALPINE_SKIING, SNOWBOARDING, PADDLING, ROCK_CLIMBING, TRAINING or GENERIC. Becomes the FIT file's sport.

startDatestring · date-timeRequired
uuidstringRequired

The HKWorkout's UUID. Its identity: sending the same one twice delivers it once.

cyclingCadenceRawSample[]

Revolutions per minute.

Show child attributes
tstring · date-timeRequired

When it was measured.

vnumber · doubleRequired

The value, in the stream's unit.

cyclingPowerRawSample[]

Watts.

Same RawSample shape as above.

deviceNamestring

The recording device's name or model, when HealthKit has one.

eventsRawEvent[]

The workout's pause and resume events, HKWorkout.workoutEvents of those types. They become the FIT file's timer events. Omitted by SDKs that predate them, which then read as a workout never paused.

Show child attributes
tstring · date-timeRequired

When it happened.

typestringRequired

pause or resume, pressed by the athlete, or motionPaused or motionResumed, the watch's auto-pause. Anything else is ignored.

formatstring

healthkit.v1. Optional, but anything else is refused.

heartRateRawSample[]

Beats per minute.

Same RawSample shape as above.

routeRawLocation[]

GPS points, HKWorkoutRoute's CLLocations in time order. Empty for an indoor workout.

Show child attributes
latnumber · doubleRequired

Degrees.

lonnumber · doubleRequired

Degrees.

tstring · date-timeRequired
altitudenumber · double

Meters above sea level.

coursenumber · double

Degrees from true north.

horizontalAccuracynumber · double

Meters.

speednumber · double

Meters per second.

verticalAccuracynumber · double

Meters.

runningPowerRawSample[]

Watts.

Same RawSample shape as above.

sourceBundleIdstring

That app's bundle id — com.apple.health for an Apple Watch workout.

sourceNamestring

The app that wrote the workout into HealthKit, by name.

totalDistanceMetersnumber · double
totalEnergyKcalnumber · double

Active energy, kilocalories.

workoutPlanIdstring

The WorkoutKit WorkoutPlan this workout was started from — HKWorkout.workoutPlan?.id — when there was one. For a workout you pushed to the athlete's Apple Watch it is the plan_id the schedule listed, and it is what puts workout_id on the resulting activity.created. Omit it for a workout started any other way.

Field
uuidThe HKWorkout's UUID. The idempotency key.
activityTypeHKWorkoutActivityType's raw value.
serverTypeThe sport, as RUNNING, CYCLING, SWIMMING, WALKING, HIKING, ROWING, … — what the FIT's sport is set from.
sourceName, sourceBundleId, deviceNameWhich app and device recorded it. Optional.
startDate, endDate, durationDuration in seconds.
totalDistanceMeters, totalEnergyKcalOptional.
workoutPlanIdOptional: HKWorkout.workoutPlan?.id, the WorkoutKit plan the workout was started from. When it is a plan we listed, the activity gets its workout_id.
heartRate, runningPower, cyclingPower, cyclingCadence[{ t, v }] in bpm, watts, watts and rpm. Empty when the workout has none.
route[{ t, lat, lon, altitude, speed, course, horizontalAccuracy, verticalAccuracy }] — metres, m/s and degrees, as CLLocation reports them.
eventsOptional: [{ t, type }], the workout's pauses and resumes from HKWorkout.workoutEvents. type is pause or resume for the athlete's, motionPaused or motionResumed for the watch's auto-pause; anything else is ignored. They become the FIT's timer events. Left out, the workout reads as never paused.
healthkit.v1
{
  "format": "healthkit.v1",
  "uuid": "5D1E8C1A-2F7B-4E0C-9A43-71C6B0F8D2E4",
  "activityType": 37,
  "serverType": "RUNNING",
  "sourceName": "Apple Watch",
  "sourceBundleId": "com.apple.health.7B3C0E5A-…",
  "deviceName": "Apple Watch",
  "startDate": "2026-10-01T06:02:11Z",
  "endDate": "2026-10-01T06:48:40Z",
  "duration": 2789.0,
  "totalDistanceMeters": 8412.6,
  "totalEnergyKcal": 612.0,
  "workoutPlanId": "7B1F6F0E-52A8-4B53-9A53-0D6F1C7B9E21",
  "heartRate": [{ "t": "2026-10-01T06:02:16Z", "v": 112 }],
  "runningPower": [{ "t": "2026-10-01T06:02:16Z", "v": 246 }],
  "cyclingPower": [],
  "cyclingCadence": [],
  "route": [
    {
      "t": "2026-10-01T06:02:12Z",
      "lat": 47.3769, "lon": 8.5417, "altitude": 408.2,
      "speed": 2.9, "course": 184.0,
      "horizontalAccuracy": 4.1, "verticalAccuracy": 3.0
    }
  ],
  "events": [
    { "t": "2026-10-01T06:20:03Z", "type": "pause" },
    { "t": "2026-10-01T06:22:41Z", "type": "resume" }
  ]
}

healthkit.wellness.v1 — a batch of summaries

post /v1/device/apple/wellness
Reference

Push Apple Health wellness data from the athlete's device.

A batch of healthkit.wellness.v1 items — daily totals, sleep, HRV, VO₂max, respiration, blood oxygen, body composition, blood pressure and wrist temperature. The Stridee SDK assembles these from HealthKit and calls this for you. Each item is stored like any provider's wellness summary and announced on your webhook.

An item's kind and startTime are its identity: sending it again replaces it, which is how a day still in progress stays current. Mark those "final": false.

Body parameters
itemsany[]Required

One object per measurement. Every item carries kind, calendarDate and startTime; the rest depends on the kind.

formatstring

healthkit.wellness.v1.

Every item carries:

Field
kindOne of the nine above. Anything else refuses the batch.
calendarDateYYYY-MM-DD, the user's local day.
startTimeWith kind, the item's identity: an item sent again with the same pair replaces the first, and emits wellness.updated only if something changed. A daily item starts at local midnight.
endTimeOptional. Not before startTime.
tzOffsetSecondsThe user's UTC offset on that day.
finalfalse while the value can still change — stored as tentative.
idOptional: the HealthKit sample's UUID, when the item is one sample. Recorded, not used to deduplicate.

And then the kind's own fields:

kindFields
dailysteps, distanceMeters, activeKilocalories, basalKilocalories, flightsClimbed, exerciseMinutes, restingHeartRate, avgHeartRate, minHeartRate, maxHeartRate
sleepstages: [{ stage, start, end }], stage one of core, deep, rem, awake, inBed, asleepUnspecified
hrvsamples: [{ t, v }], SDNN in ms
fitnessvo2Max
respirationsamples: [{ t, v }], breaths per minute
pulse_oxsamples: [{ t, v }], percent, 0–100
body_compositionweightKg, bodyFatPercent (0–100), bodyMassIndex
blood_pressuresystolic, diastolic
skin_temperaturecelsius
healthkit.wellness.v1
{
  "format": "healthkit.wellness.v1",
  "items": [
    {
      "kind": "daily",
      "calendarDate": "2026-10-01",
      "startTime": "2026-09-30T22:00:00Z",
      "endTime": "2026-10-01T22:00:00Z",
      "tzOffsetSeconds": 7200,
      "final": true,
      "steps": 8123,
      "activeKilocalories": 512.5,
      "restingHeartRate": 52
    },
    {
      "kind": "sleep",
      "calendarDate": "2026-10-02",
      "startTime": "2026-10-01T20:30:00Z",
      "endTime": "2026-10-02T04:10:00Z",
      "tzOffsetSeconds": 7200,
      "final": true,
      "stages": [
        { "stage": "core", "start": "2026-10-01T20:41:00Z", "end": "2026-10-01T22:05:00Z" },
        { "stage": "deep", "start": "2026-10-01T22:05:00Z", "end": "2026-10-01T22:58:00Z" }
      ]
    },
    {
      "kind": "hrv",
      "calendarDate": "2026-10-02",
      "startTime": "2026-10-02T01:00:00Z",
      "final": true,
      "samples": [{ "t": "2026-10-02T01:00:00Z", "v": 48.2 }]
    }
  ]
}

workoutkit.v1 — a workout to schedule

The three calls the SDK makes for workouts on the watch, with a device token. You need them only if you schedule with WorkoutKit yourself.

put /v1/device/apple/workout-scheduling
Reference

Say whether this device can schedule workouts.

The SDK calls this for you whenever WorkoutKit's authorization changes. Once a device reports authorized, the athlete's Apple connection carries the workout_scheduling scope and POST /v1/workouts treats it as a device to push to. Any other value takes the scope away again.

Body parameters
authorizationSchedulingAuthorizationRequired
Possible enum values
authorizeddeniedrestrictednot_determined

authorization is WorkoutKit's own answer — authorized, denied, restricted or not_determined — and only authorized makes the connection a workout target. The list is what should be on the watch, soonest first:

get /v1/device/apple/scheduled-workouts
Reference

The workouts that should be on this athlete's Apple Watch.

The Stridee SDK calls this on every sync and makes WorkoutKit's schedule match it: new workouts are added, edited ones replaced, and ones no longer listed — deleted, taken off the calendar, or dated in the past — removed.

Each workout arrives already encoded as workoutkit.v1, the shape WorkoutKit's CustomWorkout takes, so the device builds it without interpreting anything.

Field
plan_idThe id to give the WorkoutPlan. Use it as given: it is how an edit replaces the plan instead of adding one, and how a finished workout is matched back.
revisionWhich version of the workout this is. Opaque; send it back in the report. A report with an old one is a 412 and changes nothing.
workout.activityAn HKWorkoutActivityType case by name: running, cycling, swimming, hiking, walking, rowing, mixedCardio, highIntensityIntervalTraining, yoga, pilates or other.
workout.locationoutdoor, indoor or unknown.
goal{ type: "open" }, { type: "time", seconds }, { type: "distance", value, unit } with meters, kilometers, yards or miles, or { type: "energy", kilocalories }.
alertheartRateRange and cadenceRange (low, high, per minute), speedRange (m/s) and powerRange (watts) with a metric of current or average, heartRateZone and powerZone (zone).

Anything of yours on the watch that is not in the list should come off it. Report each workout with an outcome of synced, not_permitted, unsupported or failed, and an error sentence for the last two.

put /v1/device/apple/scheduled-workouts/{id}
Reference

Report what happened to one scheduled workout.

The SDK calls this after scheduling. It is what moves the workout's apple push from pending to synced — or to failed or unsupported, with the reason — in GET /v1/workouts/{id}.

A report carrying an old revision is a 412 and changes nothing: the workout was edited after the device read it, and the next sync will schedule the new version and report on that.

Path parameters
idstring · uuidRequired

The workout id

Body parameters
outcomeScheduleOutcomeRequired
Possible enum values
syncednot_permittedunsupportedfailed
revisionstringRequired

The revision the workout was listed with.

errorstring

One sentence about why, for unsupported and failed. Shown to you as the push's error.

PUT /v1/device/apple/workout-scheduling
PUT /v1/device/apple/workout-scheduling HTTP/1.1
Host: api.stridee.com
Content-Type: application/json
Content-Digest: sha-256=:…:
Signature-Input: sig1=(…);keyid="…";alg="ed25519"
Signature: sig1=:…:

{
  "authorization": "authorized"
}
Response · 204
HTTP/1.1 204 No Content
GET /v1/device/apple/scheduled-workouts
{
  "workouts": [
    {
      "id": "7b1f6f0e-52a8-4b53-9a53-0d6f1c7b9e21",
      "plan_id": "7b1f6f0e-52a8-4b53-9a53-0d6f1c7b9e21",
      "revision": "2026-10-02T09:15:04.123456Z",
      "scheduled_date": "2026-10-05",
      "status": "pending",
      "workout": {
        "format": "workoutkit.v1",
        "activity": "running",
        "location": "outdoor",
        "displayName": "6 × 800 m",
        "warmup": { "purpose": "work", "goal": { "type": "time", "seconds": 600 } },
        "blocks": [
          {
            "iterations": 6,
            "steps": [
              {
                "purpose": "work",
                "goal": { "type": "distance", "value": 800, "unit": "meters" },
                "alert": { "type": "speedRange", "low": 4.444, "high": 4.762, "metric": "current" }
              },
              { "purpose": "recovery", "goal": { "type": "time", "seconds": 120 } }
            ]
          }
        ],
        "cooldown": { "purpose": "recovery", "goal": { "type": "time", "seconds": 300 } }
      }
    }
  ]
}
PUT /v1/device/apple/scheduled-workouts/{id}
PUT /v1/device/apple/scheduled-workouts/{id} HTTP/1.1
Host: api.stridee.com
Content-Type: application/json
Content-Digest: sha-256=:…:
Signature-Input: sig1=(…);keyid="…";alg="ed25519"
Signature: sig1=:…:

{
  "error": null,
  "outcome": "synced",
  "revision": "string"
}
Response · 204
HTTP/1.1 204 No Content

Limits

Workout body30 MB — a 413 over it.
Wellness body10 MB and 2,000 items. The SDK pages above that.
A bad wellness itemRefuses the whole batch with a 400 naming it, so nothing is half-stored:

A 409 on a device push means the user is not connected — never connected, or disconnected since. A 503 means we could not store it right now; retry it, which the SDK does on its own.

Text
items[12]: `stress` is not a kind Apple Health sends

Disconnecting

From the app, HealthSync.shared.disconnect(). From your server, DELETE /v1/connections/{id}. Either way the connection is revoked, every device token for that user stops working, and you get account.disconnected. Data already delivered stays yours. Workouts the SDK scheduled come off the watch.

What it cannot do is take back iOS's permission: that grant is between the user and your app, and only they can turn it off in Settings. Connecting again later is another connect().

ToCall
Check from the device whether the user is connectedGET /v1/device/connections/{provider}
Connect from the devicePUT /v1/device/connections/{provider}
Disconnect from the deviceDELETE /v1/device/connections/{provider}

POST /v1/connect with provider: "apple" is a 400 pointing here: there is no consent page to send anyone to.

Shipping it to the App Store

Apple reviews health apps closely, and these are the parts that touch this integration:

  • Guideline 5.1.3. Health data may not be used for advertising, marketing or data mining, and may not be sold or shared with third parties for those purposes. Using it to run your product is fine; feeding it to an ad network is not.
  • Say where it goes. Your privacy policy and your App Store privacy labels must disclose that health and fitness data leaves the device for your backend and your processors — which includes us.
  • Explain the permission. Call connect() from a screen that says why, not at first launch. A permission sheet with no context is one users decline — and since iOS won't tell you they did, it looks exactly like a user with no data.

Something wrong or missing on this page? Tell us in Discord. Need something the API doesn’t do yet? Request it on the roadmap.