INTER-2457: [schema review prototype] Sync v4 Event union from koala#18895 by JuroUhlar · Pull Request #493 · fingerprintjs/openapi

JuroUhlar · 2026-10-15T13:05:52Z

Note

Schema review prototype, do not merge. This is to test the schema Event split (EventDevice | EventEdge) as part of reviewing koala#18895.

INTER-2457 | CORE-783 | koala#18895 @ e650844 | stacked: #494

Why

Edge and device events share one flat Event, so nothing tells SDK users or AI agents that edge events never have identification. This PR syncs koala's EventDevice | EventEdge union so the schema says it.

Things to note

Do not merge before INTER-2457: [schema review prototype] Flatten Event for non-Node SDK schemas #494. On its own, this PR gives every SDK the union instead of a flat Event.
This PR duplicates the one koala's sync workflow will open when koala#18895 merges. It exists for review and for stacking INTER-2457: [schema review prototype] Flatten Event for non-Node SDK schemas #494. Close it, or rebase the stack onto the bot PR, once that PR exists.
The changeset bump is minor. In the Node SDK, code that reads event.identification without first checking source stops compiling. Push back if this should be major.

Change outline

The schema now has one Event with two variants. source is required on both.

- Event            { event_id*, timestamp*, source?, identification?, …65 props }
+ Event = oneOf    discriminator: source
+   EventDevice    { event_id*, timestamp*, source* (const device), identification?, … }   # old Event, same order
+   EventEdge      { event_id*, timestamp*, source* (const edge), environment_id?, ip_info*, bot_info?, proxy_*?, vpn_*? }
- EdgeResponse                                                                           # renamed to EventEdge

Endpoints:

  GET  /events/{event_id}   → Event   (now the union)
  GET  /events              → EventSearch { events: Event[] }
- POST /edge                → EdgeResponse
+ POST /edge                → EventEdge
  webhook                   → Event

Files:

schemas/components/schemas/
├── Event.yaml          # now only the oneOf + discriminator
├── EventDevice.yaml    # new: the old Event + required source
└── EventEdge.yaml      # renamed from EdgeResponse
schemas/paths/edge.yaml # points at EventEdge
schemas/paths/examples/webhook/webhook_event.json  # copied from koala, now has source
.changeset/event-source-union.md

The changes were produced by running action-openapi-sync locally against the koala PR head. The action copies only files reached through a $ref, so webhook_event.json, which isn't referenced but is validated against Event, was copied by hand.

changeset-bot · 2026-10-15T13:06:02Z

🦋 Changeset detected

Latest commit: 35345bd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
openapi	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-10-15T13:06:22Z

Schema Diff vs Published Schemas

Generated at: 2026-10-15T13:12:13.756Z
Published source: https://fingerprintjs.github.io/openapi/schemas
Compared schemas: 8
Changed schemas: 3

`fingerprint-server-api-v4-normalized.yaml`

Published URL: https://fingerprintjs.github.io/openapi/schemas/fingerprint-server-api-v4-normalized.yaml
Summary: +4 added, -3 removed, ~1 modified

Added elements (4)

/components/schemas/Event/discriminator
/components/schemas/Event/oneOf
/components/schemas/EventDevice
/components/schemas/EventEdge

Removed elements (3)

/components/schemas/Event/properties
/components/schemas/Event/required/0
/components/schemas/Event/required/1

Modified elements (1)

/components/schemas/Event/description

Changed lines patch

--- a/schemas/fingerprint-server-api-v4-normalized.yaml
+++ b/schemas/fingerprint-server-api-v4-normalized.yaml
@@ -1202,10 +1202,15 @@
         - `edge` - the event was generated by the Automation Intelligence API
         (`/edge` endpoint), analyzing a request intercepted at the edge.
       enum:
         - device
         - edge
+    EnvironmentId:
+      type: string
+      examples:
+        - ae_47abaca3db2c7c43
+      description: Environment ID of the event.
     Url:
       type: string
       examples:
         - https://www.example.com/login
       description: Page URL from which the request was sent.
@@ -1609,10 +1614,56 @@
           x-platforms:
             - browser
           description: >
             `true` if the request came from a device running a VPN, `false`
             otherwise.  
+    EventEdge:
+      type: object
+      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.
+      required:
+        - event_id
+        - timestamp
+        - source
+        - ip_info
+      properties:
+        event_id:
+          $ref: '#/components/schemas/EventId'
+        timestamp:
+          $ref: '#/components/schemas/Timestamp'
+        source:
+          $ref: '#/components/schemas/EventSource'
+          const: edge
+        linked_id:
+          $ref: '#/components/schemas/LinkedId'
+        environment_id:
+          $ref: '#/components/schemas/EnvironmentId'
+        tags:
+          $ref: '#/components/schemas/Tags'
+        url:
+          $ref: '#/components/schemas/Url'
+        bot_info:
+          $ref: '#/components/schemas/BotInfo'
+        ip_info:
+          $ref: '#/components/schemas/IPInfo'
+        proxy:
+          $ref: '#/components/schemas/Proxy'
+        proxy_confidence:
+          $ref: '#/components/schemas/ProxyConfidence'
+        proxy_details:
+          $ref: '#/components/schemas/ProxyDetails'
+        vpn:
+          $ref: '#/components/schemas/Vpn'
+        vpn_confidence:
+          $ref: '#/components/schemas/VpnConfidence'
+        vpn_methods:
+          $ref: '#/components/schemas/VpnMethods'
     ErrorCode:
       type: string
       enum:
         - request_cannot_be_parsed
         - request_read_timeout
@@ -1718,15 +1769,10 @@
         request. Smart Signals, if included in your plan, are computed; hence,
         their values are valid and relevant. 
       enum:
         - partially_completed
         - completed
-    EnvironmentId:
-      type: string
-      examples:
-        - ae_47abaca3db2c7c43
-      description: Environment ID of the event.
     Suspect:
       type: boolean
       description: >-
         Field is `true` if you have previously set the `suspect` flag for this
         event using the [Server API Update event
@@ -3142,22 +3188,25 @@
         (label field) based on a machine learning score. The machine learning
         score is determined by a model trained on customer data for that use
         case. This field is in the beta phase and only available to select
         customers. If you are interested, please [contact our support
         team](https://fingerprint.com/support/).
-    Event:
+    EventDevice:
       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
+        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.
       required:
         - event_id
         - timestamp
+        - source
       properties:
         event_id:
           $ref: '#/components/schemas/EventId'
           x-platforms:
             - android
@@ -3169,10 +3218,11 @@
             - android
             - ios
             - browser
         source:
           $ref: '#/components/schemas/EventSource'
+          const: device
           x-platforms:
             - android
             - ios
             - browser
         incremental_identification_status:
@@ -3497,10 +3547,33 @@
           $ref: '#/components/schemas/Labels'
           x-platforms:
             - browser
             - ios
             - android
+    Event:
+      type: object
+      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: '#/components/schemas/EventDevice'
+        - $ref: '#/components/schemas/EventEdge'
+      discriminator:
+        propertyName: source
+        mapping:
+          device: '#/components/schemas/EventDevice'
+          edge: '#/components/schemas/EventEdge'
     EventUpdate:
       type: object
       required: []
       properties:
         linked_id:

`fingerprint-server-api-v4-with-examples.yaml`

Published URL: https://fingerprintjs.github.io/openapi/schemas/fingerprint-server-api-v4-with-examples.yaml
Summary: +4 added, -5 removed, ~2 modified

Added elements (4)

/components/schemas/Event/discriminator
/components/schemas/Event/oneOf
/components/schemas/EventDevice
/components/schemas/EventEdge

Removed elements (5)

/components/schemas/EdgeResponse
/components/schemas/Event/additionalProperties
/components/schemas/Event/properties
/components/schemas/Event/required/0
/components/schemas/Event/required/1

Modified elements (2)

/components/schemas/Event/description
/paths/~1edge/post/responses/200/content/application~1json/schema/$ref

Changed lines patch

--- a/schemas/fingerprint-server-api-v4-with-examples.yaml
+++ b/schemas/fingerprint-server-api-v4-with-examples.yaml
@@ -117,11 +117,11 @@
         '200':
           description: OK.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/EdgeResponse'
+                $ref: '#/components/schemas/EventEdge'
               examples:
                 200-ok-bot-detected:
                   summary: Example response when a bot was detected.
                   value:
                     event_id: 1758130560902.8tRtrH
@@ -3180,10 +3180,15 @@
         - `edge` - the event was generated by the Automation Intelligence API
         (`/edge` endpoint), analyzing a request intercepted at the edge.
       enum:
         - device
         - edge
+    EnvironmentId:
+      type: string
+      examples:
+        - ae_47abaca3db2c7c43
+      description: Environment ID of the event.
     Url:
       type: string
       examples:
         - https://www.example.com/login
       description: Page URL from which the request was sent.
@@ -3577,29 +3582,37 @@
           x-platforms:
             - browser
           description: >
             `true` if the request came from a device running a VPN, `false`
             otherwise.  
-    EdgeResponse:
+    EventEdge:
       type: object
       description: >-
-        IP and bot analysis for a request submitted through the Automation
-        Intelligence API.
+        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:
           $ref: '#/components/schemas/EventId'
         timestamp:
           $ref: '#/components/schemas/Timestamp'
         source:
           $ref: '#/components/schemas/EventSource'
+          const: edge
         linked_id:
           $ref: '#/components/schemas/LinkedId'
+        environment_id:
+          $ref: '#/components/schemas/EnvironmentId'
         tags:
           $ref: '#/components/schemas/Tags'
         url:
           $ref: '#/components/schemas/Url'
         bot_info:
@@ -3727,15 +3740,10 @@
         request. Smart Signals, if included in your plan, are computed; hence,
         their values are valid and relevant. 
       enum:
         - partially_completed
         - completed
-    EnvironmentId:
-      type: string
-      examples:
-        - ae_47abaca3db2c7c43
-      description: Environment ID of the event.
     Suspect:
       type: boolean
       description: >-
         Field is `true` if you have previously set the `suspect` flag for this
         event using the [Server API Update event
@@ -5176,23 +5184,26 @@
         (label field) based on a machine learning score. The machine learning
         score is determined by a model trained on customer data for that use
         case. This field is in the beta phase and only available to select
         customers. If you are interested, please [contact our support
         team](https://fingerprint.com/support/).
-    Event:
+    EventDevice:
       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
+        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: '#/components/schemas/EventId'
           x-platforms:
             - android
@@ -5204,10 +5215,11 @@
             - android
             - ios
             - browser
         source:
           $ref: '#/components/schemas/EventSource'
+          const: device
           x-platforms:
             - android
             - ios
             - browser
         incremental_identification_status:
@@ -5532,10 +5544,33 @@
           $ref: '#/components/schemas/Labels'
           x-platforms:
             - browser
             - ios
             - android
+    Event:
+      type: object
+      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: '#/components/schemas/EventDevice'
+        - $ref: '#/components/schemas/EventEdge'
+      discriminator:
+        propertyName: source
+        mapping:
+          device: '#/components/schemas/EventDevice'
+          edge: '#/components/schemas/EventEdge'
     EventUpdate:
       type: object
       required: []
       properties:
         linked_id:

`fingerprint-server-api-v4.yaml`

Published URL: https://fingerprintjs.github.io/openapi/schemas/fingerprint-server-api-v4.yaml
Summary: +4 added, -3 removed, ~1 modified

Added elements (4)

/components/schemas/Event/discriminator
/components/schemas/Event/oneOf
/components/schemas/EventDevice
/components/schemas/EventEdge

Removed elements (3)

/components/schemas/Event/properties
/components/schemas/Event/required/0
/components/schemas/Event/required/1

Modified elements (1)

/components/schemas/Event/description

Changed lines patch

--- a/schemas/fingerprint-server-api-v4.yaml
+++ b/schemas/fingerprint-server-api-v4.yaml
@@ -1188,10 +1188,15 @@
         - `edge` - the event was generated by the Automation Intelligence API
         (`/edge` endpoint), analyzing a request intercepted at the edge.
       enum:
         - device
         - edge
+    EnvironmentId:
+      type: string
+      examples:
+        - ae_47abaca3db2c7c43
+      description: Environment ID of the event.
     Url:
       type: string
       examples:
         - https://www.example.com/login
       description: Page URL from which the request was sent.
@@ -1595,10 +1600,56 @@
           x-platforms:
             - browser
           description: >
             `true` if the request came from a device running a VPN, `false`
             otherwise.  
+    EventEdge:
+      type: object
+      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.
+      required:
+        - event_id
+        - timestamp
+        - source
+        - ip_info
+      properties:
+        event_id:
+          $ref: '#/components/schemas/EventId'
+        timestamp:
+          $ref: '#/components/schemas/Timestamp'
+        source:
+          $ref: '#/components/schemas/EventSource'
+          const: edge
+        linked_id:
+          $ref: '#/components/schemas/LinkedId'
+        environment_id:
+          $ref: '#/components/schemas/EnvironmentId'
+        tags:
+          $ref: '#/components/schemas/Tags'
+        url:
+          $ref: '#/components/schemas/Url'
+        bot_info:
+          $ref: '#/components/schemas/BotInfo'
+        ip_info:
+          $ref: '#/components/schemas/IPInfo'
+        proxy:
+          $ref: '#/components/schemas/Proxy'
+        proxy_confidence:
+          $ref: '#/components/schemas/ProxyConfidence'
+        proxy_details:
+          $ref: '#/components/schemas/ProxyDetails'
+        vpn:
+          $ref: '#/components/schemas/Vpn'
+        vpn_confidence:
+          $ref: '#/components/schemas/VpnConfidence'
+        vpn_methods:
+          $ref: '#/components/schemas/VpnMethods'
     ErrorCode:
       type: string
       enum:
         - request_cannot_be_parsed
         - request_read_timeout
@@ -1704,15 +1755,10 @@
         request. Smart Signals, if included in your plan, are computed; hence,
         their values are valid and relevant. 
       enum:
         - partially_completed
         - completed
-    EnvironmentId:
-      type: string
-      examples:
-        - ae_47abaca3db2c7c43
-      description: Environment ID of the event.
     Suspect:
       type: boolean
       description: >-
         Field is `true` if you have previously set the `suspect` flag for this
         event using the [Server API Update event
@@ -3128,22 +3174,25 @@
         (label field) based on a machine learning score. The machine learning
         score is determined by a model trained on customer data for that use
         case. This field is in the beta phase and only available to select
         customers. If you are interested, please [contact our support
         team](https://fingerprint.com/support/).
-    Event:
+    EventDevice:
       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
+        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.
       required:
         - event_id
         - timestamp
+        - source
       properties:
         event_id:
           $ref: '#/components/schemas/EventId'
           x-platforms:
             - android
@@ -3155,10 +3204,11 @@
             - android
             - ios
             - browser
         source:
           $ref: '#/components/schemas/EventSource'
+          const: device
           x-platforms:
             - android
             - ios
             - browser
         incremental_identification_status:
@@ -3483,10 +3533,33 @@
           $ref: '#/components/schemas/Labels'
           x-platforms:
             - browser
             - ios
             - android
+    Event:
+      type: object
+      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: '#/components/schemas/EventDevice'
+        - $ref: '#/components/schemas/EventEdge'
+      discriminator:
+        propertyName: source
+        mapping:
+          device: '#/components/schemas/EventDevice'
+          edge: '#/components/schemas/EventEdge'
     EventUpdate:
       type: object
       required: []
       properties:
         linked_id:

github-actions · 2026-10-15T13:12:19Z

🚀 Following releases will be created using changesets from this PR:

openapi@3.10.0

Minor Changes

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. (00cc797)

Patch Changes

Set the Server API v3 deprecation date to October 31, 2026 and the end-of-life date to October 31, 2027 in the endpoint descriptions (9790b00)

JuroUhlar added 2 commits October 15, 2026 14:05

INTER-2457: sync v4 Event union from koala#18895

00cc797

INTER-2457: fix changeset punctuation

6639cc3

JuroUhlar had a problem deploying to test October 15, 2026 13:05 — with GitHub Actions Failure

JuroUhlar mentioned this pull request Oct 15, 2026

INTER-2457: [schema review prototype] Flatten Event for non-Node SDK schemas #494

Draft

INTER-2457: sync webhook_event.json example from koala#18895

35345bd

JuroUhlar deployed to test October 15, 2026 13:11 — with GitHub Actions Active

JuroUhlar changed the title ~~INTER-2457: Sync v4 Event union from koala#18895~~ Spike: Sync v4 Event union from koala#18895 Oct 15, 2026

JuroUhlar changed the title ~~Spike: Sync v4 Event union from koala#18895~~ [SPIKE] Spike: Sync v4 Event union from koala#18895 Oct 15, 2026

JuroUhlar changed the title ~~[SPIKE] Spike: Sync v4 Event union from koala#18895~~ [SPIKE] INTER-2457: Sync v4 Event union from koala#18895 Oct 15, 2026

JuroUhlar changed the title ~~[SPIKE] INTER-2457: Sync v4 Event union from koala#18895~~ [schema review prototype] INTER-2457: Sync v4 Event union from koala#18895 Oct 15, 2026

JuroUhlar changed the title ~~[schema review prototype] INTER-2457: Sync v4 Event union from koala#18895~~ INTER-2457: [schema review prototype] Sync v4 Event union from koala#18895 Oct 16, 2026

Navigation Menu

Repository navigation

INTER-2457: [schema review prototype] Sync v4 Event union from koala#18895 - #493

INTER-2457: [schema review prototype] Sync v4 Event union from koala#18895#493
JuroUhlar wants to merge 3 commits into
mainfrom
INTER-2457/sync-event-union-schema

JuroUhlar commented Oct 15, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Oct 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 15, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

JuroUhlar commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Things to note

Change outline

Uh oh!

changeset-bot Bot commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Oct 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Schema Diff vs Published Schemas

fingerprint-server-api-v4-normalized.yaml

fingerprint-server-api-v4-with-examples.yaml

fingerprint-server-api-v4.yaml

Uh oh!

github-actions Bot commented Oct 15, 2026

🚀 Following releases will be created using changesets from this PR:

openapi@3.10.0

Minor Changes

Patch Changes

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

JuroUhlar commented Oct 15, 2026 •

edited

Loading

changeset-bot Bot commented Oct 15, 2026 •

edited

Loading

github-actions Bot commented Oct 15, 2026 •

edited

Loading

`fingerprint-server-api-v4-normalized.yaml`

`fingerprint-server-api-v4-with-examples.yaml`

`fingerprint-server-api-v4.yaml`