Merge pull request #108 from fingerprintjs/feat/open-api-v2.3.0

ilfa · web-flow · commit 57615d640087 · 2025-03-06T18:31:15.000+01:00
OpenAPI schema sync
diff --git a/.changeset/chubby-ducks-cheer.md b/.changeset/chubby-ducks-cheer.md
@@ -0,0 +1,5 @@
+---
+'fingerprint-pro-server-api-python-sdk': minor
+---
+
+**events-search**: Add `pagination_key` parameter
diff --git a/.changeset/pre.json b/.changeset/pre.json
@@ -0,0 +1,8 @@
+{
+  "mode": "pre",
+  "tag": "rc",
+  "initialVersions": {
+    "fingerprint-pro-server-api-python-sdk": "8.3.0"
+  },
+  "changesets": []
+}
diff --git a/.schema-version b/.schema-version
@@ -1 +1 @@
-v2.2.1
+v2.3.0
diff --git a/README.md b/README.md
@@ -158,6 +158,7 @@ configuration = fingerprint_pro_server_api_sdk.Configuration(api_key="SECRET_API
 api_instance = fingerprint_pro_server_api_sdk.FingerprintApi(configuration)
 
 limit = 20                      # int | Limit the number of events returned.
+pagination_key = 'key_example'  # str | Use `pagination_key` to get the next page of results.   When more results are available (e.g., you requested up to 200 results for your search using `limit`, but there are more than 200 events total matching your request), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `timestamp` of the last returned event. In the following request, use that value in the `pagination_key` parameter to get the next page of results:  1. First request, returning most recent 200 events: `GET api-base-url/events/search?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/events/search?limit=200&pagination_key=1740815825085`  (optional)
 visitor_id = 'VISITOR_ID'       # str | Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Pro. Filter for events matching this `visitor_id`.  (optional)
 bot = 'good'                    # str | Filter events by the bot detection result, specifically: events where <'any'|'good'|'bad'|'none'> kind of bot was detected.  (optional)
 ip_address = '192.168.0.1/32'   # str | Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6)  All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32  (optional)
@@ -169,7 +170,7 @@ suspect = False                # bool | Filter events previously tagged as suspi
 
 try:
     # Get events via search
-    api_response = api_instance.search_events(limit, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
+    api_response = api_instance.search_events(limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
     print(api_response)
 
 except KnownApiException as e:
diff --git a/docs/FingerprintApi.md b/docs/FingerprintApi.md
@@ -221,7 +221,7 @@ Name | Type | Description  | Notes
 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
 
 # **search_events**
-> SearchEventsResponse search_events(limit, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
+> SearchEventsResponse search_events(limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
 
 Get events via search
 
@@ -240,6 +240,7 @@ configuration = fingerprint_pro_server_api_sdk.Configuration(api_key="SECRET_API
 api_instance = fingerprint_pro_server_api_sdk.FingerprintApi(configuration)
 
 limit = 56 # int | Limit the number of events returned. 
+pagination_key = 'pagination_key_example' # str | Use `pagination_key` to get the next page of results.   When more results are available (e.g., you requested up to 200 results for your search using `limit`, but there are more than 200 events total matching your request), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `timestamp` of the last returned event. In the following request, use that value in the `pagination_key` parameter to get the next page of results:  1. First request, returning most recent 200 events: `GET api-base-url/events/search?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/events/search?limit=200&pagination_key=1740815825085`  (optional)
 visitor_id = 'visitor_id_example' # str | Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Pro. Filter for events matching this `visitor_id`.  (optional)
 bot = 'bot_example' # str | Filter events by the bot detection result, specifically:    `all` - events where any kind of bot was detected.   `good` - events where a good bot was detected.   `bad` - events where a bad bot was detected.   `none` - events where no bot was detected.  (optional)
 ip_address = 'ip_address_example' # str | Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6)  All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32  (optional)
@@ -251,7 +252,7 @@ suspect = true # bool | Filter events previously tagged as suspicious via the [U
 
 try:
     # Get events via search
-    api_response = api_instance.search_events(limit, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
+    api_response = api_instance.search_events(limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
     print(api_response)
 except ApiException as e:
     print("Exception when calling FingerprintApi->search_events: %s\n" % e)
@@ -262,6 +263,7 @@ except ApiException as e:
 Name | Type | Description  | Notes
 ------------- | ------------- | ------------- | -------------
  **limit** | **int**| Limit the number of events returned.  | 
+ **pagination_key** | **str**| Use `pagination_key` to get the next page of results.   When more results are available (e.g., you requested up to 200 results for your search using `limit`, but there are more than 200 events total matching your request), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `timestamp` of the last returned event. In the following request, use that value in the `pagination_key` parameter to get the next page of results:  1. First request, returning most recent 200 events: `GET api-base-url/events/search?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/events/search?limit=200&pagination_key=1740815825085`  | [optional] 
  **visitor_id** | **str**| Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Pro. Filter for events matching this `visitor_id`.  | [optional] 
  **bot** | **str**| Filter events by the bot detection result, specifically:    `all` - events where any kind of bot was detected.   `good` - events where a good bot was detected.   `bad` - events where a bad bot was detected.   `none` - events where no bot was detected.  | [optional] 
  **ip_address** | **str**| Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6)  All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32  | [optional] 
diff --git a/docs/SearchEventsResponse.md b/docs/SearchEventsResponse.md
@@ -6,7 +6,7 @@ Contains a list of all identification events matching the specified search crite
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **events** | [**list[SearchEventsResponseEvents]**](SearchEventsResponseEvents.md) |  | [optional] 
-**pagination_key** | **str** |  | [optional] 
+**pagination_key** | **str** | Use this value in the `pagination_key` parameter to request the next page of search results. | [optional] 
 
 [[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
 
diff --git a/fingerprint_pro_server_api_sdk/api/fingerprint_api.py b/fingerprint_pro_server_api_sdk/api/fingerprint_api.py
@@ -507,6 +507,7 @@ def search_events(self, limit: int, **kwargs) -> Union[SearchEventsResponse, Asy
 
         :param async_req bool
         :param limit: Limit the number of events returned.  (required)
+        :param pagination_key: Use `pagination_key` to get the next page of results.   When more results are available (e.g., you requested up to 200 results for your search using `limit`, but there are more than 200 events total matching your request), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `timestamp` of the last returned event. In the following request, use that value in the `pagination_key` parameter to get the next page of results:  1. First request, returning most recent 200 events: `GET api-base-url/events/search?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/events/search?limit=200&pagination_key=1740815825085` 
         :param visitor_id: Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Pro. Filter for events matching this `visitor_id`. 
         :param bot: Filter events by the bot detection result, specifically:    `all` - events where any kind of bot was detected.   `good` - events where a good bot was detected.   `bad` - events where a bad bot was detected.   `none` - events where no bot was detected. 
         :param ip_address: Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6)  All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32 
@@ -537,6 +538,7 @@ def search_events_with_http_info(self, limit: int, **kwargs):  # noqa: E501
 
         :param async_req bool
         :param int limit: Limit the number of events returned.  (required)
+        :param str pagination_key: Use `pagination_key` to get the next page of results.   When more results are available (e.g., you requested up to 200 results for your search using `limit`, but there are more than 200 events total matching your request), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `timestamp` of the last returned event. In the following request, use that value in the `pagination_key` parameter to get the next page of results:  1. First request, returning most recent 200 events: `GET api-base-url/events/search?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/events/search?limit=200&pagination_key=1740815825085` 
         :param str visitor_id: Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Pro. Filter for events matching this `visitor_id`. 
         :param str bot: Filter events by the bot detection result, specifically:    `all` - events where any kind of bot was detected.   `good` - events where a good bot was detected.   `bad` - events where a bad bot was detected.   `none` - events where no bot was detected. 
         :param str ip_address: Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6)  All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32 
@@ -552,6 +554,7 @@ def search_events_with_http_info(self, limit: int, **kwargs):  # noqa: E501
 
         all_params = [
             'limit',
+            'pagination_key',
             'visitor_id',
             'bot',
             'ip_address',
@@ -585,6 +588,8 @@ def search_events_with_http_info(self, limit: int, **kwargs):  # noqa: E501
         query_params = [('ii', 'fingerprint-pro-server-python-sdk/8.3.0')]
         if 'limit' in params:
             query_params.append(('limit', params['limit']))  # noqa: E501
+        if 'pagination_key' in params:
+            query_params.append(('pagination_key', params['pagination_key']))  # noqa: E501
         if 'visitor_id' in params:
             query_params.append(('visitor_id', params['visitor_id']))  # noqa: E501
         if 'bot' in params:
diff --git a/fingerprint_pro_server_api_sdk/models/search_events_response.py b/fingerprint_pro_server_api_sdk/models/search_events_response.py
@@ -79,6 +79,7 @@ def events(self, events: Optional[List[SearchEventsResponseEvents]]):
     def pagination_key(self) -> Optional[str]:
         """Gets the pagination_key of this SearchEventsResponse.  # noqa: E501
 
+        Use this value in the `pagination_key` parameter to request the next page of search results.  # noqa: E501
 
         :return: The pagination_key of this SearchEventsResponse.  # noqa: E501
         """
@@ -88,6 +89,7 @@ def pagination_key(self) -> Optional[str]:
     def pagination_key(self, pagination_key: Optional[str]):
         """Sets the pagination_key of this SearchEventsResponse.
 
+        Use this value in the `pagination_key` parameter to request the next page of search results.  # noqa: E501
 
         :param pagination_key: The pagination_key of this SearchEventsResponse.  # noqa: E501
         """
diff --git a/res/fingerprint-server-api.yaml b/res/fingerprint-server-api.yaml
@@ -168,6 +168,29 @@ paths:
             example: 10
           description: |
             Limit the number of events returned.
+        - name: pagination_key
+          in: query
+          schema:
+            type: string
+          description: >
+            Use `pagination_key` to get the next page of results. 
+
+
+            When more results are available (e.g., you requested up to 200
+            results for your search using `limit`, but there are more than 200
+            events total matching your request), the `paginationKey` top-level
+            attribute is added to the response. The key corresponds to the
+            `timestamp` of the last returned event. In the following request,
+            use that value in the `pagination_key` parameter to get the next
+            page of results:
+
+
+            1. First request, returning most recent 200 events: `GET
+            api-base-url/events/search?limit=200`
+
+            2. Use `response.paginationKey` to get the next page of results:
+            `GET
+            api-base-url/events/search?limit=200&pagination_key=1740815825085`
         - name: visitor_id
           in: query
           schema:
@@ -2023,6 +2046,9 @@ components:
                 $ref: '#/components/schemas/Products'
         paginationKey:
           type: string
+          description: >-
+            Use this value in the `pagination_key` parameter to request the next
+            page of search results.
     Visit:
       type: object
       additionalProperties: false
diff --git a/template/README.mustache b/template/README.mustache
@@ -164,6 +164,7 @@ configuration = fingerprint_pro_server_api_sdk.Configuration(api_key="SECRET_API
 api_instance = fingerprint_pro_server_api_sdk.FingerprintApi(configuration)
 
 limit = 20                      # int | Limit the number of events returned.
+pagination_key = 'key_example'  # str | Use `pagination_key` to get the next page of results.   When more results are available (e.g., you requested up to 200 results for your search using `limit`, but there are more than 200 events total matching your request), the `paginationKey` top-level attribute is added to the response. The key corresponds to the `timestamp` of the last returned event. In the following request, use that value in the `pagination_key` parameter to get the next page of results:  1. First request, returning most recent 200 events: `GET api-base-url/events/search?limit=200` 2. Use `response.paginationKey` to get the next page of results: `GET api-base-url/events/search?limit=200&pagination_key=1740815825085`  (optional)
 visitor_id = 'VISITOR_ID'       # str | Unique [visitor identifier](https://dev.fingerprint.com/reference/get-function#visitorid) issued by Fingerprint Pro. Filter for events matching this `visitor_id`.  (optional)
 bot = 'good'                    # str | Filter events by the bot detection result, specifically: events where <'any'|'good'|'bad'|'none'> kind of bot was detected.  (optional)
 ip_address = '192.168.0.1/32'   # str | Filter events by IP address range. The range can be as specific as a single IP (/32 for IPv4 or /128 for IPv6)  All ip_address filters must use CIDR notation, for example, 10.0.0.0/24, 192.168.0.1/32  (optional)
@@ -175,7 +176,7 @@ suspect = False                # bool | Filter events previously tagged as suspi
 
 try:
     # Get events via search
-    api_response = api_instance.search_events(limit, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
+    api_response = api_instance.search_events(limit, pagination_key=pagination_key, visitor_id=visitor_id, bot=bot, ip_address=ip_address, linked_id=linked_id, start=start, end=end, reverse=reverse, suspect=suspect)
     print(api_response)
 
 except KnownApiException as e:
diff --git a/test/test_fingerprint_api.py b/test/test_fingerprint_api.py
@@ -724,20 +724,21 @@ def test_search_events_all_params(self):
     def test_search_events_partial_params(self):
         """Test that search events returns 200 with partial params provided"""
         LIMIT = 100
+        PAGINATION_KEY = '1741187431959'
         BOT = 'good'
         LINKED_ID = 'some_linked_id'
         START = 1582299576511
         REVERSE = True
         mock_pool = MockPoolManager(self)
         self.api.api_client.rest_client.pool_manager = mock_pool
         mock_pool.expect_request('GET', TestFingerprintApi.get_search_events_path(),
-                                 fields=[self.integration_info, ('limit', LIMIT),
+                                 fields=[self.integration_info, ('limit', LIMIT), ('pagination_key', PAGINATION_KEY),
                                          ('visitor_id', MOCK_SEARCH_EVENTS_200), ('bot', BOT),
                                          ('linked_id', LINKED_ID), ('start', START), ('reverse', REVERSE)],
                                  headers=self.request_headers, preload_content=True, timeout=None)
 
         response = self.api.search_events(LIMIT, visitor_id=MOCK_SEARCH_EVENTS_200, bot=BOT, linked_id=LINKED_ID,
-                                          start=START, reverse=REVERSE)
+                                          start=START, reverse=REVERSE, pagination_key=PAGINATION_KEY)
         self.assertIsInstance(response, SearchEventsResponse)
         event_response = response.events[0]
         self.assertIsInstance(event_response, SearchEventsResponseEvents)

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'fingerprint-pro-server-api-python-sdk': minor
 +---
++
 +**events-search**: Add `pagination_key` parameter