Deep Link Automation

Deep link automations allow you to create REST API automations programmatically using URL schemes. This is ideal for automation scripts, configuration management, or integrating with external systems that need to configure health data exports.

Overview

Deep link automations use a custom URL scheme to create and configure REST API automations without manually entering settings in the app. When you open a deep link URL, the app automatically creates a new automation with the specified configuration.

Use Cases:

• Programmatic automation setup from scripts or tools
• Bulk automation configuration
• Integration with configuration management systems
• Quick setup from external applications or websites
• Testing and development workflows

Key Features:

• Create automations via URL scheme
• Configure all REST API automation settings
• Type-safe parameter validation
• Comprehensive error messages

Limitations

• Deep links only support REST API automations (not Dropbox, Google Drive, etc.)
• URL length limits may restrict very long parameter lists
• All limitations from REST API automations apply (background processing, health data access, etc.)

URL Format

The deep link URL follows this structure:

com.HealthExport://automation?parameter1=value1&parameter2=value2&...

Base URL: com.HealthExport://automation

Parameters: All parameters are optional except name and url. Parameters are case-insensitive.

Parameter Reference

Required Parameters

url (required)

• Type: String (valid URL)
• Description: The endpoint URL where health data will be sent
• Example: https://api.example.com/health-data
• Note: Must be a valid HTTP/HTTPS URL

name (required)

• Type: String
• Description: A descriptive name for the automation
• Example: My%20Backend%20API (URL-encoded: My Backend API")
• Note: Must be URL-encoded if it contains spaces or special characters

Basic Configuration

format

• Type: Enum (json, csv)
• Default: json
• Description: Export format for the data
• Example: format=json or format=csv
• Note: CSV format automatically enables data aggregation

enabled

• Type: Boolean (true, false, 1, 0, yes, no)
• Default: false
• Description: Whether the automation is enabled immediately after creation
• Example: enabled=true

datatype

• Type: Enum (see Data Types below)
• Default: healthMetrics
• Description: Type of health data to export
• Example: datatype=workouts
• Note: Only one data type can be selected. Setting this automatically configures the appropriate include flags.

Valid Data Types:

• healthMetrics - Health metrics (steps, heart rate, sleep, etc.)
• workouts - Exercise and fitness activities
• symptoms - Health symptoms and conditions
• ecg - Electrocardiogram readings
• heartRateNotification - High/low heart rate events
• stateOfMind - Mood and mental state entries (iOS 18.0+)
• cycleTracking - Menstrual cycle and reproductive health data
• medications - Medication logs and adherence (iOS 26.0+)

Export Settings

period

• Type: Enum
• Default: none
• Description: Date range for data export
• Example: period=today

Valid Values:

• none - Default (full previous day plus current day)
• lastsync - Since last sync
• today - Current day
• yesterday - Previous day
• previous7days - Previous 7 days
• realtime - Real-time updates (requires seconds sync interval)

interval

• Type: Enum
• Default: none
• Description: Time grouping/aggregation interval (only valid for healthMetrics data type)
• Example: interval=hours

Valid Values:

• none - Default (no aggregation)
• minutes - Group by minute
• hours - Group by hour
• days - Group by day
• weeks - Group by week
• months - Group by month
• years - Group by year

Note: This parameter is only valid when datatype=healthMetrics. CSV format always aggregates data.

aggregatedata

• Type: Boolean
• Default: true (for CSV), false (for JSON)
• Description: Whether to aggregate/summarize data (only valid for healthMetrics with JSON format)
• Example: aggregatedata=true
• Note: Automatically set to true when format=csv

aggregatesleep

• Type: Boolean
• Default: true
• Description: Whether to aggregate sleep data
• Example: aggregatesleep=true

exportversion

• Type: Enum (v1, v2, 1, 2)
• Default: v2
• Description: Export format version
• Example: exportversion=v2
• Note: Version 2 includes enhanced workout data and more detailed metadata

batchrequests

• Type: Boolean
• Default: false
• Description: Send data in batches over multiple requests (only valid for REST API with JSON format)
• Example: batchrequests=true
• Note: Only valid when format=json and exportDestination=restApi

Sync Cadence

syncinterval

• Type: Enum
• Default: minutes
• Description: Interval for sync cadence
• Example: syncinterval=hours

Valid Values:

• minutes - Sync every N minutes
• hours - Sync every N hours
• days - Sync every N days
• weeks - Sync every N weeks
• seconds - Only valid when period=realtime

Note: For REST API automations, only minutes, hours, days, and weeks are valid unless using real-time export.

syncquantity

• Type: Integer (positive)
• Default: 5
• Description: Number of intervals between syncs
• Example: syncquantity=10 (sync every 10 minutes if syncinterval=minutes)
• Note: Must be greater than 0

HTTP Configuration

headers

• Type: String (comma-separated key-value pairs)
• Default: None
• Description: HTTP headers for authentication or metadata
• Example: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Format: key1,value1,key2,value2,...
• Note: Values should be URL-encoded. Each header requires both a key and value.

Example Headers:

• Authorization, Bearer your-token
• X-API-Key, your-api-key
• Content-Type, application/json

requesttimeout

• Type: Integer (60-86400)
• Default: 60
• Description: Request timeout in seconds
• Example: requesttimeout=300
• Note: Must be between 60 and 86400 seconds (1 minute to 24 hours)

Data Type Specific Settings

Health Metrics Settings

metrics

• Type: String (comma-separated MetricName rawValues)
• Default: All available metrics
• Description: Specific health metrics to include (only valid for healthMetrics data type)
• Example: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Note: Must use exact MetricName rawValues. If not specified, all available metrics are included.

Common Metric Names:

• Step Count
• Heart Rate
• Active Energy
• Apple Exercise Time
• Sleep Analysis
• Walking + Running Distance

See the app's metric selection screen for the complete list of available metrics.

Workout Settings

includeroutes

• Type: Boolean
• Default: true
• Description: Include route data for workouts (only valid for workouts data type)
• Example: includeroutes=true

includeworkoutmetadata

• Type: Boolean
• Default: true
• Description: Include workout metrics (heart rate, calories, etc.) collected during workouts (only valid for workouts data type)
• Example: includeworkoutmetadata=true

workoutsmetadatainterval

• Type: Enum (minutes, seconds)
• Default: minutes
• Description: Time grouping for workout metrics (only valid for workouts data type with exportVersion v2)
• Example: workoutsmetadatainterval=seconds
• Note: Only valid when datatype=workouts and exportversion=v2

workouttypes

• Type: String (comma-separated UInt values)
• Default: Empty (all workout types)
• Description: Specific workout types to include (only valid for workouts data type)
• Example: workouttypes=1,2,3
• Note: Uses HealthKit workout type identifiers

Notifications

notifyonupdate

• Type: Boolean
• Default: true
• Description: Receive notifications when cached data is updated
• Example: notifyonupdate=true

notifywhenrun

• Type: Boolean
• Default: true
• Description: Receive notifications each time the automation executes
• Example: notifywhenrun=false

Examples

Basic REST API Automation

com.HealthExport://automation?url=https://api.example.com/health&name=My%20Automation&format=json&enabled=true

Creates a basic automation that sends JSON data to the specified endpoint.

With Authentication Headers

com.HealthExport://automation?url=https://api.example.com/health&name=Authenticated%20API&format=json&headers=Authorization,Bearer%20your-token-here,X-API-Key,abc123&enabled=true

Creates an automation with custom authentication headers.

Health Metrics with Specific Metrics

com.HealthExport://automation?url=https://api.example.com/metrics&name=Steps%20and%20Heart%20Rate&format=json&datatype=healthMetrics&metrics=Step%20Count,Heart%20Rate&aggregatedata=true&interval=hours&enabled=true

Creates an automation that exports only steps and heart rate, aggregated by hour.

Workouts with Route Data

com.HealthExport://automation?url=https://api.example.com/workouts&name=Workout%20Export&format=json&datatype=workouts&includeroutes=true&includeworkoutmetadata=true&exportversion=v2&workoutsmetadatainterval=minutes&enabled=true

Creates an automation for workouts with route data and workout metrics, using export version 2.

Complete Configuration Example

com.HealthExport://automation?url=https://api.example.com/health-data&name=Complete%20Configuration&format=json&datatype=healthMetrics&period=today&interval=hours&aggregatedata=true&aggregatesleep=true&exportversion=v2&syncinterval=hours&syncquantity=2&headers=Authorization,Bearer%20token123&requesttimeout=300&batchrequests=true&notifyonupdate=true&notifywhenrun=false&enabled=true

A comprehensive example with all major parameters configured.

CSV Format Example

com.HealthExport://automation?url=https://api.example.com/csv&name=CSV%20Export&format=csv&datatype=healthMetrics&period=yesterday&enabled=true

Creates a CSV export automation. Note that CSV format automatically enables data aggregation.

URL Encoding

Special characters in parameter values must be URL-encoded. Common encodings:

• Space: %20
• Comma: %2C
• Colon: %3A
• Semicolon: %3B
• Equals: %3D
• Ampersand: %26
• Plus: %2B

Example:

• Original: My Automation Name
• Encoded: My%20Automation%20Name

Headers Example:

• Original: Authorization, Bearer token123
• Encoded: Authorization,Bearer%20token123

Most programming languages and tools provide URL encoding functions:

• Swift: addingPercentEncoding(withAllowedCharacters:)
• JavaScript: encodeURIComponent()
• Python: urllib.parse.quote()

Testing Deep Links

From Safari (iOS)

1. Open Safari on your iOS device
2. Enter the deep link URL in the address bar
3. Tap Go
4. The app should open and create the automation

From Terminal (macOS/iOS Simulator)

xcrun simctl openurl booted "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true"

From Xcode

Add a breakpoint or use the debugger console:

let url = URL(string: "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true")!
try DataModel.shared.handleAPIDeepLink(url)

From Shortcuts App

1. Create a new shortcut
2. Add "Open URLs" action
3. Enter your deep link URL
4. Run the shortcut

Troubleshooting

Common Issues

"Could not parse the URL"

• Verify the URL scheme is correct: com.HealthExport://automation
• Check that all parameter values are properly URL-encoded
• Ensure parameter names are spelled correctly (case-insensitive)

"Invalid URL parameter value"

• Verify the URL is a valid HTTP/HTTPS URL
• Check for proper URL encoding
• Ensure the URL doesn't contain invalid characters

"Invalid data type"

• Use exact data type values: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Check spelling and case (though case-insensitive matching is supported)

"Invalid sync cadence interval"

• For REST API, use only: minutes, hours, days, weeks
• Use seconds only when period=realtime

"Aggregation settings are only valid for healthMetrics data type"

• aggregatedata and interval parameters only work with datatype=healthMetrics
• Remove these parameters or change the data type

"Batch requests are only valid for REST API with JSON format"

• batchrequests only works when format=json
• Change format to JSON or remove the batchrequests parameter

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata, and workoutsmetadatainterval only work with datatype=workouts
• Change data type to workouts or remove these parameters

"Metrics parameter is only valid for healthMetrics data type"

• metrics parameter only works with datatype=healthMetrics
• Change data type or remove the metrics parameter

"Invalid metric name"

• Use exact MetricName rawValues (e.g., "Step Count", "Heart Rate")
• Check spelling and capitalization
• See the app's metric selection screen for valid names

"Invalid request timeout"

• Must be between 60 and 86400 seconds
• Use a value within this range

"A name is required for the automation"

• Ensure the name parameter is included
• Check that the value is not empty after URL decoding

URL Length Limitations

Very long URLs (especially with many metrics or headers) may exceed system limits. Consider:

• Using fewer metrics in the metrics parameter
• Reducing the number of headers
• Using shorter parameter values where possible
• Splitting complex configurations into multiple simpler automations

Parameter Precedence

When multiple parameters conflict:

1. Data type selection (datatype) automatically resets include flags
2. CSV format (format=csv) automatically sets aggregatedata=true
3. Real-time period (period=realtime) requires syncinterval=seconds
4. Validation errors will be thrown for incompatible combinations

Best Practices

1. Always URL-encode parameter values containing special characters
2. Test with simple URLs first, then add complexity
3. Use descriptive names for easier identification
4. Validate URLs before creating deep links programmatically
5. Handle errors gracefully when parsing deep links
6. Document your deep link formats if building tools that generate them
7. Consider URL length when including many metrics or headers
8. Test on actual devices as well as simulators

Related Documentation

• REST API Automation Guide - Detailed information about REST API automations
• Automations Overview - General automation concepts
• Manual Export Guide - How to manually export data

Support

If you encounter issues not covered in this guide:

1. Check the error message for specific parameter issues
2. Verify your URL encoding is correct
3. Test with a minimal URL first
4. Use the Chat Support button in the app for assistance