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