From 00cc797a89eed64bf014fc2cc896d4178cf73774 Mon Sep 17 00:00:00 2001 From: Juraj Uhlar Date: Thu, 15 Oct 2026 14:05:27 +0100 Subject: [PATCH 1/3] INTER-2457: sync v4 Event union from koala#18895 --- .changeset/event-source-union.md | 5 + schemas/components/schemas/Event.yaml | 363 +----------------- schemas/components/schemas/EventDevice.yaml | 353 +++++++++++++++++ .../{EdgeResponse.yaml => EventEdge.yaml} | 6 +- schemas/paths/edge.yaml | 2 +- 5 files changed, 377 insertions(+), 352 deletions(-) create mode 100644 .changeset/event-source-union.md create mode 100644 schemas/components/schemas/EventDevice.yaml rename schemas/components/schemas/{EdgeResponse.yaml => EventEdge.yaml} (62%) diff --git a/.changeset/event-source-union.md b/.changeset/event-source-union.md new file mode 100644 index 00000000..5fb26704 --- /dev/null +++ b/.changeset/event-source-union.md @@ -0,0 +1,5 @@ +--- +'openapi': minor +--- + +**events**: Model `Event` as a union of `EventDevice` and `EventEdge`, discriminated by `source`, in the docs and the Node SDK schema. Other SDK schemas keep a single flat `Event` with optional `source` diff --git a/schemas/components/schemas/Event.yaml b/schemas/components/schemas/Event.yaml index 65b2872f..4812bf12 100644 --- a/schemas/components/schemas/Event.yaml +++ b/schemas/components/schemas/Event.yaml @@ -1,351 +1,14 @@ type: object -description: Contains results from Fingerprint Identification and all active Smart Signals. Some Smart Signals are only supported for certain device types, these fields will be omitted for events not generated from the supported devices. Consult the [Smart Signals reference](https://docs.fingerprint.com/docs/smart-signals-reference) for more details. -additionalProperties: false -required: - - event_id - - timestamp -properties: - event_id: - $ref: platform/EventId.yaml - x-platforms: - - android - - ios - - browser - timestamp: - $ref: platform/Timestamp.yaml - x-platforms: - - android - - ios - - browser - source: - $ref: platform/EventSource.yaml - x-platforms: - - android - - ios - - browser - incremental_identification_status: - $ref: platform/IncrementalIdentificationStatus.yaml - x-platforms: - - browser - linked_id: - $ref: platform/LinkedId.yaml - x-platforms: - - android - - ios - - browser - environment_id: - $ref: platform/EnvironmentId.yaml - x-platforms: - - android - - ios - - browser - suspect: - $ref: platform/Suspect.yaml - x-platforms: - - android - - ios - - browser - sdk: - $ref: platform/SDK.yaml - x-platforms: - - android - - ios - - browser - replayed: - $ref: platform/Replayed.yaml - x-platforms: - - android - - ios - - browser - triggered_by: - $ref: platform/webhook/TriggeredBy.yaml - identification: - $ref: identification/Identification.yaml - x-platforms: - - android - - ios - - browser - supplementary_id_high_recall: - $ref: identification/SupplementaryIDHighRecall.yaml - x-platforms: - - android - - ios - - browser - tags: - $ref: identification/Tags.yaml - x-platforms: - - android - - ios - - browser - url: - $ref: identification/Url.yaml - x-platforms: - - browser - bundle_id: - $ref: identification/BundleId.yaml - x-platforms: - - ios - package_name: - $ref: identification/PackageName.yaml - x-platforms: - - android - ip_address: - $ref: identification/IpAddress.yaml - x-platforms: - - android - - ios - - browser - user_agent: - $ref: identification/UserAgent.yaml - x-platforms: - - android - - ios - - browser - device: - $ref: identification/Device.yaml - x-platforms: - - android - - ios - - browser - os: - $ref: identification/Os.yaml - x-platforms: - - android - - ios - - browser - os_version: - $ref: identification/OsVersion.yaml - x-platforms: - - android - - ios - - browser - client_referrer: - $ref: identification/ClientReferrer.yaml - x-platforms: - - browser - browser_details: - $ref: identification/BrowserDetails.yaml - x-platforms: - - browser - proximity: - $ref: identification/Proximity.yaml - x-platforms: - - android - - ios - - browser - active_call: - $ref: smartsignals/ActiveCall.yaml - x-platforms: - - android - - ios - bot: - $ref: smartsignals/BotResult.yaml - x-platforms: - - browser - bot_type: - $ref: smartsignals/BotType.yaml - x-platforms: - - browser - bot_info: - $ref: smartsignals/BotInfo.yaml - x-platforms: - - browser - cloned_app: - $ref: smartsignals/ClonedApp.yaml - x-platforms: - - android - developer_tools: - $ref: smartsignals/DeveloperTools.yaml - x-platforms: - - browser - - android - - ios - device_details: - $ref: smartsignals/DeviceDetails.yaml - x-platforms: - - android - - ios - emulator: - $ref: smartsignals/Emulator.yaml - x-platforms: - - android - factory_reset_timestamp: - $ref: smartsignals/FactoryReset.yaml - x-platforms: - - android - - ios - frida: - $ref: smartsignals/Frida.yaml - x-platforms: - - android - - ios - ip_blocklist: - $ref: smartsignals/IPBlockList.yaml - x-platforms: - - android - - ios - - browser - ip_info: - $ref: smartsignals/IPInfo.yaml - x-platforms: - - android - - ios - - browser - proxy: - $ref: smartsignals/Proxy.yaml - x-platforms: - - android - - ios - - browser - proxy_confidence: - $ref: smartsignals/ProxyConfidence.yaml - x-platforms: - - android - - ios - - browser - proxy_details: - $ref: smartsignals/ProxyDetails.yaml - x-platforms: - - android - - ios - - browser - proxy_ml_score: - $ref: smartsignals/ProxyMLScore.yaml - x-platforms: - - browser - incognito: - $ref: smartsignals/Incognito.yaml - x-platforms: - - browser - jailbroken: - $ref: smartsignals/Jailbroken.yaml - x-platforms: - - ios - location_spoofing: - $ref: smartsignals/LocationSpoofing.yaml - x-platforms: - - android - - ios - mitm_attack: - $ref: smartsignals/MitMAttack.yaml - x-platforms: - - android - - ios - privacy_settings: - $ref: smartsignals/PrivacySettings.yaml - x-platforms: - - browser - root_apps: - $ref: smartsignals/RootApps.yaml - x-platforms: - - android - rule_action: - $ref: platform/EventRuleAction.yaml - simulator: - $ref: smartsignals/Simulator.yaml - x-platforms: - - ios - suspect_score: - $ref: smartsignals/SuspectScore.yaml - x-platforms: - - android - - ios - - browser - tampering: - $ref: smartsignals/Tampering.yaml - x-platforms: - - android - - ios - - browser - tampering_confidence: - $ref: smartsignals/TamperingConfidence.yaml - x-platforms: - - android - - ios - - browser - tampering_ml_score: - $ref: smartsignals/TamperingMlScore.yaml - x-platforms: - - android - - ios - - browser - tampering_details: - $ref: smartsignals/TamperingDetails.yaml - x-platforms: - - android - - ios - - browser - velocity: - $ref: smartsignals/Velocity.yaml - x-platforms: - - android - - ios - - browser - virtual_machine: - $ref: smartsignals/VirtualMachine.yaml - x-platforms: - - browser - virtual_machine_ml_score: - $ref: smartsignals/VirtualMachineMLScore.yaml - x-platforms: - - browser - vpn: - $ref: smartsignals/Vpn.yaml - x-platforms: - - android - - ios - - browser - vpn_confidence: - $ref: smartsignals/VpnConfidence.yaml - x-platforms: - - android - - ios - - browser - vpn_ml_score: - $ref: smartsignals/VpnMLScore.yaml - x-platforms: - - browser - vpn_origin_timezone: - $ref: smartsignals/VpnOriginTimezone.yaml - x-platforms: - - android - - ios - - browser - vpn_origin_country: - $ref: smartsignals/VpnOriginCountry.yaml - x-platforms: - - android - - ios - - browser - vpn_methods: - $ref: smartsignals/VpnMethods.yaml - x-platforms: - - android - - ios - - browser - high_activity_device: - $ref: smartsignals/HighActivity.yaml - x-platforms: - - android - - ios - - browser - rare_device: - $ref: smartsignals/RareDevice.yaml - x-platforms: - - browser - rare_device_percentile_bucket: - $ref: smartsignals/RareDevicePercentileBucket.yaml - x-platforms: - - browser - raw_device_attributes: - $ref: smartsignals/RawDeviceAttributes.yaml - x-platforms: - - browser - - ios - - android - labels: - $ref: smartsignals/Labels.yaml - x-platforms: - - browser - - ios - - android +description: | + An event, discriminated by its `source` property. Check `source` before reading other properties, because each source populates a different set of them: + - `device` - an identification event generated by the JS agent or a mobile SDK running on an end-user device. + - `edge` - an event generated by the Automation Intelligence API (`/edge` endpoint), analyzing a request intercepted at the edge. It contains only IP and bot analysis, and never contains Identification (`visitor_id`) or Smart Signals derived from device telemetry. +required: [] +oneOf: + - $ref: EventDevice.yaml + - $ref: EventEdge.yaml +discriminator: + propertyName: source + mapping: + device: EventDevice.yaml + edge: EventEdge.yaml diff --git a/schemas/components/schemas/EventDevice.yaml b/schemas/components/schemas/EventDevice.yaml new file mode 100644 index 00000000..9ffea6b3 --- /dev/null +++ b/schemas/components/schemas/EventDevice.yaml @@ -0,0 +1,353 @@ +type: object +description: An event generated by the JS agent or a mobile SDK running on an end-user device (`source` is `device`). Contains results from Fingerprint Identification and all active Smart Signals. Some Smart Signals are only supported for certain device types, these fields will be omitted for events not generated from the supported devices. Consult the [Smart Signals reference](https://docs.fingerprint.com/docs/smart-signals-reference) for more details. +additionalProperties: false +required: + - event_id + - timestamp + - source +properties: + event_id: + $ref: platform/EventId.yaml + x-platforms: + - android + - ios + - browser + timestamp: + $ref: platform/Timestamp.yaml + x-platforms: + - android + - ios + - browser + source: + $ref: platform/EventSource.yaml + const: device + x-platforms: + - android + - ios + - browser + incremental_identification_status: + $ref: platform/IncrementalIdentificationStatus.yaml + x-platforms: + - browser + linked_id: + $ref: platform/LinkedId.yaml + x-platforms: + - android + - ios + - browser + environment_id: + $ref: platform/EnvironmentId.yaml + x-platforms: + - android + - ios + - browser + suspect: + $ref: platform/Suspect.yaml + x-platforms: + - android + - ios + - browser + sdk: + $ref: platform/SDK.yaml + x-platforms: + - android + - ios + - browser + replayed: + $ref: platform/Replayed.yaml + x-platforms: + - android + - ios + - browser + triggered_by: + $ref: platform/webhook/TriggeredBy.yaml + identification: + $ref: identification/Identification.yaml + x-platforms: + - android + - ios + - browser + supplementary_id_high_recall: + $ref: identification/SupplementaryIDHighRecall.yaml + x-platforms: + - android + - ios + - browser + tags: + $ref: identification/Tags.yaml + x-platforms: + - android + - ios + - browser + url: + $ref: identification/Url.yaml + x-platforms: + - browser + bundle_id: + $ref: identification/BundleId.yaml + x-platforms: + - ios + package_name: + $ref: identification/PackageName.yaml + x-platforms: + - android + ip_address: + $ref: identification/IpAddress.yaml + x-platforms: + - android + - ios + - browser + user_agent: + $ref: identification/UserAgent.yaml + x-platforms: + - android + - ios + - browser + device: + $ref: identification/Device.yaml + x-platforms: + - android + - ios + - browser + os: + $ref: identification/Os.yaml + x-platforms: + - android + - ios + - browser + os_version: + $ref: identification/OsVersion.yaml + x-platforms: + - android + - ios + - browser + client_referrer: + $ref: identification/ClientReferrer.yaml + x-platforms: + - browser + browser_details: + $ref: identification/BrowserDetails.yaml + x-platforms: + - browser + proximity: + $ref: identification/Proximity.yaml + x-platforms: + - android + - ios + - browser + active_call: + $ref: smartsignals/ActiveCall.yaml + x-platforms: + - android + - ios + bot: + $ref: smartsignals/BotResult.yaml + x-platforms: + - browser + bot_type: + $ref: smartsignals/BotType.yaml + x-platforms: + - browser + bot_info: + $ref: smartsignals/BotInfo.yaml + x-platforms: + - browser + cloned_app: + $ref: smartsignals/ClonedApp.yaml + x-platforms: + - android + developer_tools: + $ref: smartsignals/DeveloperTools.yaml + x-platforms: + - browser + - android + - ios + device_details: + $ref: smartsignals/DeviceDetails.yaml + x-platforms: + - android + - ios + emulator: + $ref: smartsignals/Emulator.yaml + x-platforms: + - android + factory_reset_timestamp: + $ref: smartsignals/FactoryReset.yaml + x-platforms: + - android + - ios + frida: + $ref: smartsignals/Frida.yaml + x-platforms: + - android + - ios + ip_blocklist: + $ref: smartsignals/IPBlockList.yaml + x-platforms: + - android + - ios + - browser + ip_info: + $ref: smartsignals/IPInfo.yaml + x-platforms: + - android + - ios + - browser + proxy: + $ref: smartsignals/Proxy.yaml + x-platforms: + - android + - ios + - browser + proxy_confidence: + $ref: smartsignals/ProxyConfidence.yaml + x-platforms: + - android + - ios + - browser + proxy_details: + $ref: smartsignals/ProxyDetails.yaml + x-platforms: + - android + - ios + - browser + proxy_ml_score: + $ref: smartsignals/ProxyMLScore.yaml + x-platforms: + - browser + incognito: + $ref: smartsignals/Incognito.yaml + x-platforms: + - browser + jailbroken: + $ref: smartsignals/Jailbroken.yaml + x-platforms: + - ios + location_spoofing: + $ref: smartsignals/LocationSpoofing.yaml + x-platforms: + - android + - ios + mitm_attack: + $ref: smartsignals/MitMAttack.yaml + x-platforms: + - android + - ios + privacy_settings: + $ref: smartsignals/PrivacySettings.yaml + x-platforms: + - browser + root_apps: + $ref: smartsignals/RootApps.yaml + x-platforms: + - android + rule_action: + $ref: platform/EventRuleAction.yaml + simulator: + $ref: smartsignals/Simulator.yaml + x-platforms: + - ios + suspect_score: + $ref: smartsignals/SuspectScore.yaml + x-platforms: + - android + - ios + - browser + tampering: + $ref: smartsignals/Tampering.yaml + x-platforms: + - android + - ios + - browser + tampering_confidence: + $ref: smartsignals/TamperingConfidence.yaml + x-platforms: + - android + - ios + - browser + tampering_ml_score: + $ref: smartsignals/TamperingMlScore.yaml + x-platforms: + - android + - ios + - browser + tampering_details: + $ref: smartsignals/TamperingDetails.yaml + x-platforms: + - android + - ios + - browser + velocity: + $ref: smartsignals/Velocity.yaml + x-platforms: + - android + - ios + - browser + virtual_machine: + $ref: smartsignals/VirtualMachine.yaml + x-platforms: + - browser + virtual_machine_ml_score: + $ref: smartsignals/VirtualMachineMLScore.yaml + x-platforms: + - browser + vpn: + $ref: smartsignals/Vpn.yaml + x-platforms: + - android + - ios + - browser + vpn_confidence: + $ref: smartsignals/VpnConfidence.yaml + x-platforms: + - android + - ios + - browser + vpn_ml_score: + $ref: smartsignals/VpnMLScore.yaml + x-platforms: + - browser + vpn_origin_timezone: + $ref: smartsignals/VpnOriginTimezone.yaml + x-platforms: + - android + - ios + - browser + vpn_origin_country: + $ref: smartsignals/VpnOriginCountry.yaml + x-platforms: + - android + - ios + - browser + vpn_methods: + $ref: smartsignals/VpnMethods.yaml + x-platforms: + - android + - ios + - browser + high_activity_device: + $ref: smartsignals/HighActivity.yaml + x-platforms: + - android + - ios + - browser + rare_device: + $ref: smartsignals/RareDevice.yaml + x-platforms: + - browser + rare_device_percentile_bucket: + $ref: smartsignals/RareDevicePercentileBucket.yaml + x-platforms: + - browser + raw_device_attributes: + $ref: smartsignals/RawDeviceAttributes.yaml + x-platforms: + - browser + - ios + - android + labels: + $ref: smartsignals/Labels.yaml + x-platforms: + - browser + - ios + - android diff --git a/schemas/components/schemas/EdgeResponse.yaml b/schemas/components/schemas/EventEdge.yaml similarity index 62% rename from schemas/components/schemas/EdgeResponse.yaml rename to schemas/components/schemas/EventEdge.yaml index 33292f5f..8c0ce6cb 100644 --- a/schemas/components/schemas/EdgeResponse.yaml +++ b/schemas/components/schemas/EventEdge.yaml @@ -1,9 +1,10 @@ type: object -description: IP and bot analysis for a request submitted through the Automation Intelligence API. +description: An event generated by the Automation Intelligence API (`source` is `edge`), containing IP and bot analysis for a request intercepted at the edge. No client-side agent is involved, so Identification (`visitor_id`) and Smart Signals derived from device telemetry are not available. `ip_info` is always present, but is empty when no IP intelligence is available for the request. additionalProperties: false required: - event_id - timestamp + - source - ip_info properties: event_id: @@ -12,8 +13,11 @@ properties: $ref: platform/Timestamp.yaml source: $ref: platform/EventSource.yaml + const: edge linked_id: $ref: platform/LinkedId.yaml + environment_id: + $ref: platform/EnvironmentId.yaml tags: $ref: identification/Tags.yaml url: diff --git a/schemas/paths/edge.yaml b/schemas/paths/edge.yaml index 3ac4227f..09945227 100644 --- a/schemas/paths/edge.yaml +++ b/schemas/paths/edge.yaml @@ -37,7 +37,7 @@ post: content: application/json: schema: - $ref: ../components/schemas/EdgeResponse.yaml + $ref: ../components/schemas/EventEdge.yaml examples: 200-ok-bot-detected: summary: Example response when a bot was detected. From 6639cc35045d6d620b402960426c6ff8c48496bd Mon Sep 17 00:00:00 2001 From: Juraj Uhlar Date: Thu, 15 Oct 2026 14:05:36 +0100 Subject: [PATCH 2/3] INTER-2457: fix changeset punctuation --- .changeset/event-source-union.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/event-source-union.md b/.changeset/event-source-union.md index 5fb26704..cee50e1c 100644 --- a/.changeset/event-source-union.md +++ b/.changeset/event-source-union.md @@ -2,4 +2,4 @@ 'openapi': minor --- -**events**: Model `Event` as a union of `EventDevice` and `EventEdge`, discriminated by `source`, in the docs and the Node SDK schema. Other SDK schemas keep a single flat `Event` with optional `source` +**events**: Model `Event` as a union of `EventDevice` and `EventEdge`, discriminated by `source`, in the docs and the Node SDK schema. Other SDK schemas keep a single flat `Event` with optional `source`. From 35345bd5e89ec1ca23df01482bf8b275edf896a0 Mon Sep 17 00:00:00 2001 From: Juraj Uhlar Date: Thu, 15 Oct 2026 14:11:41 +0100 Subject: [PATCH 3/3] INTER-2457: sync webhook_event.json example from koala#18895 --- .../paths/examples/webhook/webhook_event.json | 57 +++++++++++++++---- 1 file changed, 47 insertions(+), 10 deletions(-) diff --git a/schemas/paths/examples/webhook/webhook_event.json b/schemas/paths/examples/webhook/webhook_event.json index 35567917..c50663be 100644 --- a/schemas/paths/examples/webhook/webhook_event.json +++ b/schemas/paths/examples/webhook/webhook_event.json @@ -3,9 +3,14 @@ "tags": {}, "timestamp": 1708102555327, "event_id": "1708102555327.NLOjmg", + "source": "device", + "incremental_identification_status": "completed", "url": "https://www.example.com/login?hope{this{works[!", "ip_address": "61.127.217.15", "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ....", + "device": "Other", + "os": "Windows", + "os_version": "7", "client_referrer": "https://example.com/blog/my-article", "browser_details": { "browser_name": "Chrome", @@ -26,14 +31,14 @@ "last_seen_at": 1708102555327 }, "supplementary_id_high_recall": { - "visitor_id": "3HNey93AkBW6CRbxV6xP", + "visitor_id": "0jnGMkPYXX37DqVa4ZIO3f_hr", "visitor_found": true, "confidence": { - "score": 0.97, - "version": "1.1" + "score": 0, + "version": "Not Supported" }, - "first_seen_at": 1708102555327, - "last_seen_at": 1708102555327 + "first_seen_at": 1778086556130, + "last_seen_at": 1778604975494 }, "proximity": { "id": "w1aTfd4MCvl", @@ -111,8 +116,10 @@ "last_seen_at": 1708102555327, "provider": "Massive" }, + "proxy_ml_score": 0.2, "vpn": false, "vpn_confidence": "high", + "vpn_ml_score": 0.2, "vpn_origin_timezone": "Europe/Berlin", "vpn_origin_country": "unknown", "vpn_methods": { @@ -120,10 +127,13 @@ "public_vpn": false, "auxiliary_mobile": false, "os_mismatch": false, - "relay": false + "relay": false, + "ml_prediction": false }, "incognito": false, "tampering": false, + "tampering_confidence": "high", + "tampering_ml_score": 0.3231, "tampering_details": { "anomaly_score": 0.1955, "anti_detect_browser": false @@ -143,6 +153,11 @@ "1_hour": 1, "24_hours": 1 }, + "distinct_linked_id": { + "5_minutes": 1, + "1_hour": 5, + "24_hours": 5 + }, "distinct_country": { "5_minutes": 1, "1_hour": 2, @@ -170,6 +185,11 @@ } }, "developer_tools": false, + "device_details": { + "device_manufacturer": "samsung", + "device_model": "SM-G991U", + "os_version": "13" + }, "mitm_attack": false, "sdk": { "platform": "js", @@ -187,8 +207,6 @@ }, "replayed": false, "high_activity_device": false, - "rare_device": false, - "rare_device_percentile_bucket": "