[api-v3] Update Server API schema version v3.7.1

.changeset/update-schema-v3.7.1.md

@@ -0,0 +1,11 @@
+---
+"@fingerprintjs/fingerprintjs-pro-server-api": minor
+---
+
+Update Server API schema to v3.7.1:
+
+- Require `label` on `Labels`
+- Add `RequestReadTimeout` to `ErrorCode`
+- Add `404`, `429`, and `504` responses to `GET /events/search` and `GET /visitors/{visitor_id}`
+- Clarify that `reverse` on `GET /events/search` defaults to `false` (sorts newest first)
+- Clarify that `GET /visitors/{visitor_id}` currently returns at most one item in `visits`, and deprecate its `limit`/`paginationKey`/`before` pagination parameters in favor of `GET /events/search`

resources/fingerprint-server-api.yaml

@@ -60,8 +60,7 @@ paths:
         >
 
         > This version of Server API is marked as deprecated starting on **Jan
-        7th 2026** and will be fully removed on **Jan 7th 2027** according to
-        our [API Deprecation
+        7th 2026** according to our [API Deprecation
         Policy](https://dev.fingerprint.com/reference/api-deprecation-policy).
         If you still use this version, please follow our [migration
         guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-get-events)
@@ -111,6 +110,24 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: >
+            Too Many Requests. The request is throttled.
+
+            To protect service stability during rare periods of extreme load, we
+            may return HTTP 429 responses with message `too many search
+            requests` even if you are within your assigned rate limits.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '504':
+          description: >-
+            Gateway Timeout. Request processing exceeded the allowed timeout window.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
     put:
       tags:
         - Fingerprint
@@ -122,8 +139,7 @@ paths:
         >
 
         > This version of Server API is marked as deprecated starting on **Jan
-        7th 2026** and will be fully removed on **Jan 7th 2027** according to
-        our [API Deprecation
+        7th 2026** according to our [API Deprecation
         Policy](https://dev.fingerprint.com/reference/api-deprecation-policy).
         If you still use this version, please follow our [migration
         guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-update-events)
@@ -197,8 +213,7 @@ paths:
         >
 
         > This version of Server API is marked as deprecated starting on **Jan
-        7th 2026** and will be fully removed on **Jan 7th 2027** according to
-        our [API Deprecation
+        7th 2026** according to our [API Deprecation
         Policy](https://dev.fingerprint.com/reference/api-deprecation-policy).
         If you still use this version, please follow our [migration
         guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-get-eventssearch)
@@ -320,8 +335,10 @@ paths:
           in: query
           schema:
             type: boolean
-          description: |
-            Sort events in reverse timestamp order.
+            default: false
+          description: >
+            When `true`, sort events oldest first (ascending timestamp order).
+            Default is newest first (descending timestamp order).
         - name: suspect
           in: query
           schema:
@@ -685,6 +702,33 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: >-
+            Not found. The requested visitor does not exist in this
+            application's data.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: >
+            Too Many Requests. The request is throttled.
+
+            To protect service stability during rare periods of extreme load, we
+            may return HTTP 429 responses with message `too many search
+            requests` even if you are within your assigned rate limits.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '504':
+          description: >-
+            Gateway Timeout. Search execution exceeded the allowed timeout
+            window.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
   /visitors/{visitor_id}:
     get:
       tags:
@@ -697,16 +741,19 @@ paths:
         >
 
         > This version of Server API is marked as deprecated starting on **Jan
-        7th 2026** and will be fully removed on **Jan 7th 2027** according to
-        our [API Deprecation
+        7th 2026** according to our [API Deprecation
         Policy](https://dev.fingerprint.com/reference/api-deprecation-policy).
         If you still use this version, please follow our [migration
         guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4#migrating-get-visitors)
         to migrate from this deprecated version to the new one.
 
 
-        Get a history of visits (identification events) for a specific
-        `visitorId`. Use the `visitorId` as a URL path parameter.
+        This endpoint is deprecated. Use `GET /events/search` to query visit
+        history or filter across multiple events.
+
+
+        `GET /visitors/{visitor_id}` currently returns at most one visit in
+        `visits`, even when no filters are provided.
 
         Only information from the _Identification_ product is returned.
 
@@ -769,43 +816,20 @@ paths:
             Limit scanned results.
 
 
-            For performance reasons, the API first scans some number of events
-            before filtering them. Use `limit` to specify how many events are
-            scanned before they are filtered by `requestId` or `linkedId`.
-            Results are always returned sorted by the timestamp (most recent
-            first).
-
-            By default, the most recent 100 visits are scanned, the maximum is
-            500.
+            `GET /visitors/{visitor_id}` currently returns at most one visit.
+            Use `GET /events/search` for paginated multi-event queries.
           x-go-skip-pointer: true
         - name: paginationKey
           in: query
           schema:
             type: string
           description: >
-            Use `paginationKey` to get the next page of results.
-
-
-            When more results are available (e.g., you requested 200 results
-            using `limit` parameter, but a total of 600 results are available),
-            the `paginationKey` top-level attribute is added to the response.
-            The key corresponds to the `requestId` of the last returned event.
-            In the following request, use that value in the `paginationKey`
-            parameter to get the next page of results:
-
-
-            1. First request, returning most recent 200 events: `GET
-            api-base-url/visitors/:visitorId?limit=200`
-
-            2. Use `response.paginationKey` to get the next page of results:
-            `GET
-            api-base-url/visitors/:visitorId?limit=200&paginationKey=1683900801733.Ogvu1j`
+            Deprecated pagination parameter retained for backward compatibility.
 
 
-            Pagination happens during scanning and before filtering, so you can
-            get less visits than the `limit` you specified with more available
-            on the next page. When there are no more results available for
-            scanning, the `paginationKey` attribute is not returned.
+            `GET /visitors/{visitor_id}` currently returns at most one visit, so
+            pagination is not expected. Use `GET /events/search` for paginated
+            results.
           x-go-skip-pointer: true
         - name: before
           in: query
@@ -817,6 +841,9 @@ paths:
           description: >
             ⚠️ Deprecated pagination method, please use `paginationKey` instead.
             Timestamp (in milliseconds since epoch) used to paginate results.
+
+            `GET /visitors/{visitor_id}` currently returns at most one visit, so
+            pagination is not expected.
           x-go-skip-pointer: true
       responses:
         '200':
@@ -839,8 +866,21 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorPlainResponse'
+        '404':
+          description: >-
+            Not found. The visitor ID cannot be found in this application's
+            data.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorPlainResponse'
         '429':
-          description: Too Many Requests. The request is throttled.
+          description: >
+            Too Many Requests. The request is throttled.
+
+            To protect service stability during rare periods of extreme load, we
+            may return HTTP 429 responses with message `too many search
+            requests` even if you are within your assigned rate limits.
           headers:
             Retry-After:
               description: >-
@@ -854,6 +894,14 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorPlainResponse'
+        '504':
+          description: >-
+            Gateway Timeout. Search execution exceeded the allowed timeout
+            window.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
     delete:
       tags:
         - Fingerprint
@@ -865,8 +913,7 @@ paths:
         >
 
         > This version of Server API is marked as deprecated starting on **Jan
-        7th 2026** and will be fully removed on **Jan 7th 2027** according to
-        our [API Deprecation
+        7th 2026** according to our [API Deprecation
         Policy](https://dev.fingerprint.com/reference/api-deprecation-policy).
         If you still use this version, please follow our [migration
         guide](https://dev.fingerprint.com/reference/migrating-from-server-api-v3-to-v4)
@@ -981,8 +1028,7 @@ paths:
         >
 
         > This version of Server API is marked as deprecated starting on **Jan
-        7th 2026** and will be fully removed on **Jan 7th 2027** according to
-        our [API Deprecation
+        7th 2026** according to our [API Deprecation
         Policy](https://dev.fingerprint.com/reference/api-deprecation-policy).
 
 
@@ -1249,12 +1295,12 @@ components:
           type: string
           nullable: true
           format: date-time
-          x-ogen-time-format: 2006-01-02T15:04:05.999Z07:00
+          x-ogen-time-format: 2006-01-02T15:04:05.000Z07:00
         subscription:
           type: string
           nullable: true
           format: date-time
-          x-ogen-time-format: 2006-01-02T15:04:05.999Z07:00
+          x-ogen-time-format: 2006-01-02T15:04:05.000Z07:00
     RawDeviceAttributeError:
       type: object
       additionalProperties: false
@@ -1413,6 +1459,7 @@ components:
       type: string
       enum:
         - RequestCannotBeParsed
+        - RequestReadTimeout
         - TokenRequired
         - TokenNotFound
         - SubscriptionNotActive
@@ -1429,6 +1476,7 @@ components:
         Error code:
          * `RequestCannotBeParsed` - the query parameters or JSON payload contains some errors 
                   that prevented us from parsing it (wrong type/surpassed limits).
+         * `RequestReadTimeout` - the request body could not be read before the connection timed out.
          * `TokenRequired` - `Auth-API-Key` header is missing or empty.
          * `TokenNotFound` - no Fingerprint application found for specified secret key.
          * `SubscriptionNotActive` - Fingerprint application is not active.
@@ -1514,7 +1562,7 @@ components:
         time:
           type: string
           format: date-time
-          x-ogen-time-format: 2006-01-02T15:04:05.999Z07:00
+          x-ogen-time-format: 2006-01-02T15:04:05.000Z07:00
           description: >-
             Time in UTC when the request from the JS agent was made. We
             recommend to treat requests that are older than 2 minutes as
@@ -1797,7 +1845,7 @@ components:
             users in your fraud prevention logic.
         mlPrediction:
           type: boolean
-          description: >-
+          description: >
             `true` if the request came from a device running a VPN, `false`
             otherwise.
     VPN:
@@ -1822,7 +1870,7 @@ components:
           format: double
           minimum: 0
           maximum: 1
-          description: >-
+          description: >
             Machine learning–based VPN score, represented as a floating-point
             value between 0 and 1 (inclusive), with up to three decimal places
             of precision. A higher score means a higher confidence in the
@@ -1871,16 +1919,15 @@ components:
             - residential
             - data_center
             - unknown
-          description: >
-            Residential proxies use real user IP addresses to appear as
-            legitimate traffic, while data center proxies are public proxies
-            hosted in data centers. `unknown` is reported when a proxy is
-            detected solely by the ML model and the IP sources did not determine
-            a specific type.
+          description: |
+            Proxy type:
+             * `residential` - proxies that route through residential and telecom IP addresses to appear as legitimate traffic
+             * `data_center` - proxies which route through data centers
+             * `unknown` - reported when a proxy is detected solely by the ML model and the IP sources did not determine a specific type
         lastSeenAt:
           type: string
           format: date-time
-          x-ogen-time-format: 2006-01-02T15:00:00.000Z
+          x-ogen-time-format: '2006-01-02T15:00:00Z'
           description: |
             ISO 8601 formatted timestamp in UTC with hourly resolution
             of when this IP was last seen as a proxy when available.
@@ -2146,7 +2193,7 @@ components:
             Machine learning-based virtual machine score,  represented as a
             floating-point value between 0 and 1 (inclusive), with up to three
             decimal places of precision. A higher score means a higher
-            confidence in the positive `virtual_machine` detection result    
+            confidence in the positive `virtual_machine` detection result
     ProductVirtualMachine:
       type: object
       additionalProperties: false
@@ -2434,6 +2481,8 @@ components:
       items:
         type: object
         additionalProperties: false
+        required:
+          - label
         properties:
           label:
             type: string
@@ -2687,9 +2736,9 @@ components:
     VisitorsGetResponse:
       type: object
       description: >-
-        Pagination-related fields `lastTimestamp` and `paginationKey` are
-        included if you use a pagination parameter like `limit` or `before` and
-        there is more data available on the next page.
+        Deprecated response shape for `GET /visitors/{visitor_id}`. The `visits`
+        array currently contains at most one item. Use `GET /events/search` for
+        multi-event history and filtering.
       additionalProperties: false
       required:
         - visitorId
@@ -2699,6 +2748,7 @@ components:
           type: string
         visits:
           type: array
+          maxItems: 1
           items:
             $ref: '#/components/schemas/Visit'
         lastTimestamp:
@@ -2711,9 +2761,8 @@ components:
         paginationKey:
           type: string
           description: >-
-            Request ID of the last visit in the current page of results. Use
-            this value in the following request as the `paginationKey` parameter
-            to get the next page of results.
+            Use this value in the following request as the `paginationKey`
+            parameter to get the next result.
     ErrorPlainResponse:
       type: object
       additionalProperties: false
@@ -3257,7 +3306,7 @@ components:
         time:
           type: string
           format: date-time
-          x-ogen-time-format: 2006-01-02T15:04:05.999Z07:00
+          x-ogen-time-format: 2006-01-02T15:04:05.000Z07:00
           description: >-
             Time expressed according to ISO 8601 in UTC format, when the request
             from the JS agent was made. We recommend to treat requests that are