Skip to main content
The mobile package uses standard HTTP headers for device detection, versioning, and synchronization.

​
Request Headers

Headers sent by mobile clients:
HeaderDescriptionExample
X-Device-IDUnique device identifier550e8400-e29b-41d4-a716-446655440000
X-App-VersionClient app version2.1.0
X-App-BuildBuild number2024.01.15
X-Device-ModelDevice modeliPhone15,2
X-PlatformOperating systemios, android
X-OS-VersionOS version17.0, 14
X-TimezoneIANA timezoneAmerica/New_York
X-LocaleDevice localeen-US, ja-JP
X-Push-TokenPush notification tokenabc123...
X-API-VersionAPI versionv2, v2.1
X-Sync-TokenLast sync tokenYWJjMTIz...
X-Idempotency-KeyRequest idempotencyreq-abc-123
X-Request-IDRequest trace IDtrace-123

​
Response Headers

Headers sent by the server:
HeaderDescriptionExample
X-API-VersionAPI version usedv2
X-API-DeprecatedDeprecation warningtrue
X-Min-App-VersionMinimum required version1.5.0
X-Sync-TokenNew sync tokenZGVmNDU2...
X-Request-IDRequest trace IDtrace-123

​
Header Details

​
X-Device-ID

A unique identifier for the device. Should persist across app reinstalls if possible. iOS: 
UIDevice.current.identifierForVendor?.uuidString
Android: 
Settings.Secure.getString(context.contentResolver, Settings.Secure.ANDROID_ID)

​
X-App-Version

Semantic version of the client application. 
X-App-Version: 2.1.0

​
X-Platform

Operating system identifier. Used for platform detection when User-Agent parsing is disabled. Valid values:
  • ios
  • android
  • windows
  • macos
  • web

​
X-API-Version

API version requested by the client. Supports formats:
  • v2
  • v2.1
  • 2
  • 2.1

​
X-Sync-Token

Opaque token for delta synchronization. Clients store and send back on subsequent sync requests.

​
X-API-Deprecated

Response header indicating the requested API version is deprecated. Clients should plan to upgrade. 
X-API-Deprecated: true

​
X-Min-App-Version

Response header indicating the minimum required app version. Clients below this version should prompt for update. 
X-Min-App-Version: 1.5.0

​
Client Implementation

​
iOS (Swift)

extension URLRequest {
    mutating func addMizuHeaders() {
        setValue(DeviceInfo.deviceId, forHTTPHeaderField: "X-Device-ID")
        setValue(Bundle.main.appVersion, forHTTPHeaderField: "X-App-Version")
        setValue(Bundle.main.buildNumber, forHTTPHeaderField: "X-App-Build")
        setValue(UIDevice.current.modelIdentifier, forHTTPHeaderField: "X-Device-Model")
        setValue("ios", forHTTPHeaderField: "X-Platform")
        setValue(UIDevice.current.systemVersion, forHTTPHeaderField: "X-OS-Version")
        setValue(TimeZone.current.identifier, forHTTPHeaderField: "X-Timezone")
        setValue(Locale.current.identifier, forHTTPHeaderField: "X-Locale")
        setValue("v2", forHTTPHeaderField: "X-API-Version")
    }
}

​
Android (Kotlin)

class MizuHeaderInterceptor(private val context: Context) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request().newBuilder()
            .header("X-Device-ID", getDeviceId())
            .header("X-App-Version", BuildConfig.VERSION_NAME)
            .header("X-App-Build", BuildConfig.VERSION_CODE.toString())
            .header("X-Device-Model", Build.MODEL)
            .header("X-Platform", "android")
            .header("X-OS-Version", Build.VERSION.RELEASE)
            .header("X-Timezone", TimeZone.getDefault().id)
            .header("X-Locale", Locale.getDefault().toLanguageTag())
            .header("X-API-Version", "v2")
            .build()
        return chain.proceed(request)
    }
}

​
Flutter (Dart)

final headers = {
  'X-Device-ID': deviceId,
  'X-App-Version': packageInfo.version,
  'X-App-Build': packageInfo.buildNumber,
  'X-Platform': Platform.operatingSystem,
  'X-OS-Version': Platform.operatingSystemVersion,
  'X-Timezone': DateTime.now().timeZoneName,
  'X-Locale': Platform.localeName,
  'X-API-Version': 'v2',
};

​
Next Steps

Device Detection

How headers are parsed

API Reference

Complete API documentation