From 0a5a22ac187a6fd0491b251b79611436f25af8b5 Mon Sep 17 00:00:00 2001 From: JuroUhlar Date: Thu, 23 Apr 2026 13:19:24 +0000 Subject: [PATCH] feat: sync OpenAPI schema to v3.2.0 --- .changeset/developer-tools-android.md | 5 + .changeset/device-rarity-smart-signal.md | 5 + .changeset/proxy-ml-score.md | 5 + ...ce-attributes-font-hash-timezone-offset.md | 5 + .../raw-device-attributes-mobile-android.md | 5 + .../raw-device-attributes-mobile-ios.md | 5 + .changeset/request-read-timeout-error-code.md | 5 + .openapi-generator/FILES | 4 + .schema-version | 2 +- README.md | 2 + docs/ErrorCode.md | 2 + docs/Event.md | 7 +- docs/FingerprintApi.md | 32 +- docs/RareDevicePercentileBucket.md | 16 + docs/RawDeviceAttributes.md | 8 +- .../SearchEventsRareDevicePercentileBucket.md | 21 ++ docs/TamperingConfidence.md | 11 +- docs/TamperingDetails.md | 4 +- fingerprint_server_sdk/__init__.py | 6 + fingerprint_server_sdk/api/fingerprint_api.py | 138 ++++++-- fingerprint_server_sdk/models/__init__.py | 4 + fingerprint_server_sdk/models/error_code.py | 3 +- fingerprint_server_sdk/models/event.py | 25 +- .../models/rare_device_percentile_bucket.py | 39 +++ .../models/raw_device_attributes.py | 32 +- ...ch_events_rare_device_percentile_bucket.py | 39 +++ .../models/tampering_confidence.py | 2 +- .../models/tampering_details.py | 4 +- res/fingerprint-server-api.yaml | 239 ++++++++++++-- test/mocks/errors/400_bot_type_invalid.json | 6 + test/mocks/errors/400_end_time_invalid.json | 6 + test/mocks/errors/400_ip_address_invalid.json | 6 + test/mocks/errors/400_limit_invalid.json | 6 + test/mocks/errors/400_linked_id_invalid.json | 6 + .../errors/400_pagination_key_invalid.json | 6 + test/mocks/errors/400_reverse_invalid.json | 6 + test/mocks/errors/400_ruleset_not_found.json | 6 + test/mocks/errors/400_start_time_invalid.json | 6 + .../errors/403_secret_api_key_not_found.json | 6 + .../errors/403_subscription_not_active.json | 6 + test/mocks/errors/403_wrong_region.json | 6 + .../errors/500_internal_server_error.json | 6 + test/mocks/events/get_event_200.json | 5 +- test/mocks/events/get_event_ruleset_200.json | 3 + .../events/get_event_with_bot_info_200.json | 296 ++++++++++++++++++ .../events/search/get_event_search_200.json | 5 +- test/mocks/webhook/webhook_event.json | 286 +++++++++++++++++ 47 files changed, 1257 insertions(+), 91 deletions(-) create mode 100644 .changeset/developer-tools-android.md create mode 100644 .changeset/device-rarity-smart-signal.md create mode 100644 .changeset/proxy-ml-score.md create mode 100644 .changeset/raw-device-attributes-font-hash-timezone-offset.md create mode 100644 .changeset/raw-device-attributes-mobile-android.md create mode 100644 .changeset/raw-device-attributes-mobile-ios.md create mode 100644 .changeset/request-read-timeout-error-code.md create mode 100644 docs/RareDevicePercentileBucket.md create mode 100644 docs/SearchEventsRareDevicePercentileBucket.md create mode 100644 fingerprint_server_sdk/models/rare_device_percentile_bucket.py create mode 100644 fingerprint_server_sdk/models/search_events_rare_device_percentile_bucket.py create mode 100644 test/mocks/errors/400_bot_type_invalid.json create mode 100644 test/mocks/errors/400_end_time_invalid.json create mode 100644 test/mocks/errors/400_ip_address_invalid.json create mode 100644 test/mocks/errors/400_limit_invalid.json create mode 100644 test/mocks/errors/400_linked_id_invalid.json create mode 100644 test/mocks/errors/400_pagination_key_invalid.json create mode 100644 test/mocks/errors/400_reverse_invalid.json create mode 100644 test/mocks/errors/400_ruleset_not_found.json create mode 100644 test/mocks/errors/400_start_time_invalid.json create mode 100644 test/mocks/errors/403_secret_api_key_not_found.json create mode 100644 test/mocks/errors/403_subscription_not_active.json create mode 100644 test/mocks/errors/403_wrong_region.json create mode 100644 test/mocks/errors/500_internal_server_error.json create mode 100644 test/mocks/events/get_event_with_bot_info_200.json create mode 100644 test/mocks/webhook/webhook_event.json diff --git a/.changeset/developer-tools-android.md b/.changeset/developer-tools-android.md new file mode 100644 index 00000000..259b269a --- /dev/null +++ b/.changeset/developer-tools-android.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add Android platform support to `developer_tools` smart signal for API v3 diff --git a/.changeset/device-rarity-smart-signal.md b/.changeset/device-rarity-smart-signal.md new file mode 100644 index 00000000..655fc144 --- /dev/null +++ b/.changeset/device-rarity-smart-signal.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add Device Rarity Smart Signal diff --git a/.changeset/proxy-ml-score.md b/.changeset/proxy-ml-score.md new file mode 100644 index 00000000..a63f2d05 --- /dev/null +++ b/.changeset/proxy-ml-score.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add `proxy_ml_score` to `Event` diff --git a/.changeset/raw-device-attributes-font-hash-timezone-offset.md b/.changeset/raw-device-attributes-font-hash-timezone-offset.md new file mode 100644 index 00000000..bb9bda28 --- /dev/null +++ b/.changeset/raw-device-attributes-font-hash-timezone-offset.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add `font_hash` and `timezone_offset` fields for the `RawDeviceAttributes` diff --git a/.changeset/raw-device-attributes-mobile-android.md b/.changeset/raw-device-attributes-mobile-android.md new file mode 100644 index 00000000..bf085f6b --- /dev/null +++ b/.changeset/raw-device-attributes-mobile-android.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Enable `raw_device_attributes` for Android devices. Only `device_manufacturer` and `device_model` are currently supported for Android devices. diff --git a/.changeset/raw-device-attributes-mobile-ios.md b/.changeset/raw-device-attributes-mobile-ios.md new file mode 100644 index 00000000..fe26f70e --- /dev/null +++ b/.changeset/raw-device-attributes-mobile-ios.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Enable `raw_device_attributes` for iOS devices. Only `device_manufacturer`, `device_model`, `hardware_concurrency`, `languages`, and `screen_resolution` are currently supported for iOS devices. diff --git a/.changeset/request-read-timeout-error-code.md b/.changeset/request-read-timeout-error-code.md new file mode 100644 index 00000000..355b9bcb --- /dev/null +++ b/.changeset/request-read-timeout-error-code.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add `request_read_timeout` error code diff --git a/.openapi-generator/FILES b/.openapi-generator/FILES index caf60730..75a51835 100644 --- a/.openapi-generator/FILES +++ b/.openapi-generator/FILES @@ -32,6 +32,7 @@ docs/PluginsInnerMimeTypesInner.md docs/Proximity.md docs/ProxyConfidence.md docs/ProxyDetails.md +docs/RareDevicePercentileBucket.md docs/RawDeviceAttributes.md docs/RequestHeaderModifications.md docs/RuleActionHeaderField.md @@ -40,6 +41,7 @@ docs/SDK.md docs/SealedResults.md docs/SearchEventsBot.md docs/SearchEventsIncrementalIdentificationStatus.md +docs/SearchEventsRareDevicePercentileBucket.md docs/SearchEventsSdkPlatform.md docs/SearchEventsVpnConfidence.md docs/SupplementaryIDHighRecall.md @@ -91,6 +93,7 @@ fingerprint_server_sdk/models/plugins_inner_mime_types_inner.py fingerprint_server_sdk/models/proximity.py fingerprint_server_sdk/models/proxy_confidence.py fingerprint_server_sdk/models/proxy_details.py +fingerprint_server_sdk/models/rare_device_percentile_bucket.py fingerprint_server_sdk/models/raw_device_attributes.py fingerprint_server_sdk/models/request_header_modifications.py fingerprint_server_sdk/models/rule_action_header_field.py @@ -98,6 +101,7 @@ fingerprint_server_sdk/models/rule_action_type.py fingerprint_server_sdk/models/sdk.py fingerprint_server_sdk/models/search_events_bot.py fingerprint_server_sdk/models/search_events_incremental_identification_status.py +fingerprint_server_sdk/models/search_events_rare_device_percentile_bucket.py fingerprint_server_sdk/models/search_events_sdk_platform.py fingerprint_server_sdk/models/search_events_vpn_confidence.py fingerprint_server_sdk/models/supplementary_id_high_recall.py diff --git a/.schema-version b/.schema-version index 3a285c2b..aa6c8967 100644 --- a/.schema-version +++ b/.schema-version @@ -1 +1 @@ -v3.1.0 \ No newline at end of file +v3.2.0 \ No newline at end of file diff --git a/README.md b/README.md index 1b9abaf2..6df86d8c 100644 --- a/README.md +++ b/README.md @@ -356,6 +356,7 @@ Class | Method | HTTP request | Description - [Proximity](docs/Proximity.md) - [ProxyConfidence](docs/ProxyConfidence.md) - [ProxyDetails](docs/ProxyDetails.md) + - [RareDevicePercentileBucket](docs/RareDevicePercentileBucket.md) - [RawDeviceAttributes](docs/RawDeviceAttributes.md) - [RequestHeaderModifications](docs/RequestHeaderModifications.md) - [RuleActionHeaderField](docs/RuleActionHeaderField.md) @@ -363,6 +364,7 @@ Class | Method | HTTP request | Description - [SDK](docs/SDK.md) - [SearchEventsBot](docs/SearchEventsBot.md) - [SearchEventsIncrementalIdentificationStatus](docs/SearchEventsIncrementalIdentificationStatus.md) + - [SearchEventsRareDevicePercentileBucket](docs/SearchEventsRareDevicePercentileBucket.md) - [SearchEventsSdkPlatform](docs/SearchEventsSdkPlatform.md) - [SearchEventsVpnConfidence](docs/SearchEventsVpnConfidence.md) - [SupplementaryIDHighRecall](docs/SupplementaryIDHighRecall.md) diff --git a/docs/ErrorCode.md b/docs/ErrorCode.md index ea45e8d1..af757621 100644 --- a/docs/ErrorCode.md +++ b/docs/ErrorCode.md @@ -2,6 +2,7 @@ Error code: * `request_cannot_be_parsed` - The query parameters or JSON payload contains some errors that prevented us from parsing it (wrong type/surpassed limits). +* `request_read_timeout` - The request body could not be read before the connection timed out. * `secret_api_key_required` - secret API key in header is missing or empty. * `secret_api_key_not_found` - No Fingerprint workspace found for specified secret API key. * `public_api_key_required` - public API key in header is missing or empty. @@ -27,6 +28,7 @@ Error code: ## Enum * `REQUEST_CANNOT_BE_PARSED` (value: `'request_cannot_be_parsed'`) +* `REQUEST_READ_TIMEOUT` (value: `'request_read_timeout'`) * `SECRET_API_KEY_REQUIRED` (value: `'secret_api_key_required'`) * `SECRET_API_KEY_NOT_FOUND` (value: `'secret_api_key_not_found'`) * `PUBLIC_API_KEY_REQUIRED` (value: `'public_api_key_required'`) diff --git a/docs/Event.md b/docs/Event.md index 09c810dd..d0ba814d 100644 --- a/docs/Event.md +++ b/docs/Event.md @@ -36,6 +36,7 @@ Name | Type | Description | Notes **proxy** | **bool** | IP address was used by a public proxy provider or belonged to a known recent residential proxy | [optional] **proxy_confidence** | [**ProxyConfidence**](ProxyConfidence.md) | | [optional] **proxy_details** | [**ProxyDetails**](ProxyDetails.md) | | [optional] +**proxy_ml_score** | **float** | Machine learning–based proxy 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 `proxy` detection result | [optional] **incognito** | **bool** | `true` if we detected incognito mode used in the browser, `false` otherwise. | [optional] **jailbroken** | **bool** | iOS specific jailbreak detection. There are 2 values: * `true` - Jailbreak detected. * `false` - No signs of jailbreak or the client is not iOS. | [optional] **location_spoofing** | **bool** | Flag indicating whether the request came from a mobile device with location spoofing enabled. | [optional] @@ -45,9 +46,9 @@ Name | Type | Description | Notes **rule_action** | [**EventRuleAction**](EventRuleAction.md) | | [optional] **simulator** | **bool** | iOS specific simulator detection. There are 2 values: * `true` - Simulator environment detected. * `false` - No signs of simulator or the client is not iOS. | [optional] **suspect_score** | **int** | Suspect Score is an easy way to integrate Smart Signals into your fraud protection work flow. It is a weighted representation of all Smart Signals present in the payload that helps identify suspicious activity. The value range is [0; S] where S is sum of all Smart Signals weights. See more details here: https://docs.fingerprint.com/docs/suspect-score | [optional] -**tampering** | **bool** | Flag indicating browser tampering was detected. This happens when either: * There are inconsistencies in the browser configuration that cross internal tampering thresholds (see `tampering_details.anomaly_score`). * The browser signature resembles an \"anti-detect\" browser specifically designed to evade fingerprinting (see `tampering_details.anti_detect_browser`). | [optional] +**tampering** | **bool** | The field can be used as a standalone flag for tampering detection. Alternatively, the more granular fields documented below can be used for workflows that require more context. * `true` if tampering is detected through an anomalous browser signature, anti-detect browser detection, or other tampering-related methods * `false` if none of the tampering checks return a positive result | [optional] **tampering_confidence** | [**TamperingConfidence**](TamperingConfidence.md) | | [optional] -**tampering_ml_score** | **float** | A score that indicates the models calculated probability that an event is coming from an anti detect browser. * Values above `0.8` indicate that the request is an anti detect browser based on the ml model * Values below `0.8` indicate that the request is not an anti detect browser based on the ml model | [optional] +**tampering_ml_score** | **float** | The output of this model is captured as tampering_ml_score, a number indicating how likely an event is coming from an anti detect browser. Values close to 1 signify higher confidence and we consider anything above the threshold of 0.8 to be actionable (the result and anti_detect_browser fields conveniently captures that fact) | [optional] **tampering_details** | [**TamperingDetails**](TamperingDetails.md) | | [optional] **velocity** | [**Velocity**](Velocity.md) | | [optional] **virtual_machine** | **bool** | `true` if the request came from a browser running inside a virtual machine (e.g. VMWare), `false` otherwise. | [optional] @@ -58,6 +59,8 @@ Name | Type | Description | Notes **vpn_origin_country** | **str** | Country of the request (only for Android SDK version >= 2.4.0, ISO 3166 format or unknown). | [optional] **vpn_methods** | [**VpnMethods**](VpnMethods.md) | | [optional] **high_activity_device** | **bool** | Flag indicating if the request came from a high-activity visitor. | [optional] +**rare_device** | **bool** | `true` if the device is considered rare based on its combination of hardware and software attributes. A device is classified as rare if it falls within the top 99.9 percentile (lowest-frequency segment) of observed traffic, or if its configuration has not been previously seen (`not_seen`). > This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/). | [optional] +**rare_device_percentile_bucket** | [**RareDevicePercentileBucket**](RareDevicePercentileBucket.md) | | [optional] **raw_device_attributes** | [**RawDeviceAttributes**](RawDeviceAttributes.md) | | [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/docs/FingerprintApi.md b/docs/FingerprintApi.md index 0266cbf0..02a791fe 100644 --- a/docs/FingerprintApi.md +++ b/docs/FingerprintApi.md @@ -183,7 +183,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** -> EventSearch search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, linked_id=linked_id, url=url, bundle_id=bundle_id, package_name=package_name, origin=origin, start=start, end=end, reverse=reverse, suspect=suspect, vpn=vpn, virtual_machine=virtual_machine, tampering=tampering, anti_detect_browser=anti_detect_browser, incognito=incognito, privacy_settings=privacy_settings, jailbroken=jailbroken, frida=frida, factory_reset=factory_reset, cloned_app=cloned_app, emulator=emulator, root_apps=root_apps, vpn_confidence=vpn_confidence, min_suspect_score=min_suspect_score, developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, environment=environment, proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, incremental_identification_status=incremental_identification_status, simulator=simulator) +> EventSearch search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, linked_id=linked_id, url=url, bundle_id=bundle_id, package_name=package_name, origin=origin, start=start, end=end, reverse=reverse, suspect=suspect, vpn=vpn, virtual_machine=virtual_machine, tampering=tampering, anti_detect_browser=anti_detect_browser, incognito=incognito, privacy_settings=privacy_settings, jailbroken=jailbroken, frida=frida, factory_reset=factory_reset, cloned_app=cloned_app, emulator=emulator, root_apps=root_apps, vpn_confidence=vpn_confidence, min_suspect_score=min_suspect_score, developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, rare_device=rare_device, rare_device_percentile_bucket=rare_device_percentile_bucket, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, environment=environment, proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, incremental_identification_status=incremental_identification_status, simulator=simulator) Search events @@ -195,7 +195,12 @@ The `/v4/events` endpoint provides a convenient way to search for past events ba - Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier. - Excluding all bot traffic from the query (`good` and `bad` bots) -If you don't provide `start` or `end` parameters, the default search range is the **last 7 days**. +By default, the API searches events from the last 7 days, sorts them by newest first and returns the last 10 events. + +- Use `start` and `end` to specify the time range of the search. +- Use `reverse=true` to sort the results oldest first. +- Use `limit` to specify the number of events to return. +- Use `pagination_key` to get the next page of results if there are more than `limit` events. ### Filtering events with the `suspect` flag @@ -219,6 +224,7 @@ import fingerprint_server_sdk from fingerprint_server_sdk.models.event_search import EventSearch from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot from fingerprint_server_sdk.models.search_events_incremental_identification_status import SearchEventsIncrementalIdentificationStatus +from fingerprint_server_sdk.models.search_events_rare_device_percentile_bucket import SearchEventsRareDevicePercentileBucket from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk import ApiException, ErrorResponse @@ -234,7 +240,7 @@ configuration = fingerprint_server_sdk.Configuration( # Create an instance of the API class api_instance = fingerprint_server_sdk.FingerprintApi(configuration) -limit: int = 10 # Limit the number of events returned. (optional) (default to 10) +limit: int = 10 # Maximum number of events to return. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. (optional) (default to 10) pagination_key: str = 'pagination_key_example' # Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. 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?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` (optional) visitor_id: str = 'visitor_id_example' # Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). (optional) high_recall_id: str = 'high_recall_id_example' # The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). (optional) @@ -246,9 +252,9 @@ url: str = 'url_example' # Filter events by the URL (`url` property) associated bundle_id: str = 'bundle_id_example' # Filter events by the Bundle ID (iOS) associated with the event. (optional) package_name: str = 'package_name_example' # Filter events by the Package Name (Android) associated with the event. (optional) origin: str = 'origin_example' # Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com) (optional) -start: int = 56 # Filter events with a timestamp greater than the start time, in Unix time (milliseconds). (optional) -end: int = 56 # Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). (optional) -reverse: bool = True # Sort events in reverse timestamp order. (optional) +start: int = 1767225600000 # Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. (optional) +end: int = 1769903999000 # Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. (optional) +reverse: bool = False # When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). (optional) (default to False) suspect: bool = True # Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/server-api-v4-update-event). > Note: When using this parameter, only events with the `suspect` property explicitly set to `true` or `false` are returned. Events with undefined `suspect` property are left out of the response. (optional) vpn: bool = True # Filter events by VPN Detection result. > Note: When using this parameter, only events with the `vpn` property set to `true` or `false` are returned. Events without a `vpn` Smart Signal result are left out of the response. (optional) virtual_machine: bool = True # Filter events by Virtual Machine Detection result. > Note: When using this parameter, only events with the `virtual_machine` property set to `true` or `false` are returned. Events without a `virtual_machine` Smart Signal result are left out of the response. (optional) @@ -267,6 +273,8 @@ min_suspect_score: float = 3.4 # Filter events with Suspect Score result above a developer_tools: bool = True # Filter events by Developer Tools detection result. > Note: When using this parameter, only events with the `developer_tools` property set to `true` or `false` are returned. Events without a `developer_tools` Smart Signal result are left out of the response. (optional) location_spoofing: bool = True # Filter events by Location Spoofing detection result. > Note: When using this parameter, only events with the `location_spoofing` property set to `true` or `false` are returned. Events without a `location_spoofing` Smart Signal result are left out of the response. (optional) mitm_attack: bool = True # Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. (optional) +rare_device: bool = True # Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. (optional) +rare_device_percentile_bucket: SearchEventsRareDevicePercentileBucket = fingerprint_server_sdk.SearchEventsRareDevicePercentileBucket() # Filter events by Device Rarity percentile bucket. ` Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response. (optional) sdk_version: str = 'sdk_version_example' # Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14` (optional) sdk_platform: SearchEventsSdkPlatform = fingerprint_server_sdk.SearchEventsSdkPlatform() # Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. (optional) @@ -279,7 +287,7 @@ simulator: bool = True # Filter events by iOS Simulator Detection result. > Not try: # Search events - api_response = api_instance.search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, linked_id=linked_id, url=url, bundle_id=bundle_id, package_name=package_name, origin=origin, start=start, end=end, reverse=reverse, suspect=suspect, vpn=vpn, virtual_machine=virtual_machine, tampering=tampering, anti_detect_browser=anti_detect_browser, incognito=incognito, privacy_settings=privacy_settings, jailbroken=jailbroken, frida=frida, factory_reset=factory_reset, cloned_app=cloned_app, emulator=emulator, root_apps=root_apps, vpn_confidence=vpn_confidence, min_suspect_score=min_suspect_score, developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, environment=environment, proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, incremental_identification_status=incremental_identification_status, simulator=simulator) + api_response = api_instance.search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, ip_address=ip_address, asn=asn, linked_id=linked_id, url=url, bundle_id=bundle_id, package_name=package_name, origin=origin, start=start, end=end, reverse=reverse, suspect=suspect, vpn=vpn, virtual_machine=virtual_machine, tampering=tampering, anti_detect_browser=anti_detect_browser, incognito=incognito, privacy_settings=privacy_settings, jailbroken=jailbroken, frida=frida, factory_reset=factory_reset, cloned_app=cloned_app, emulator=emulator, root_apps=root_apps, vpn_confidence=vpn_confidence, min_suspect_score=min_suspect_score, developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, rare_device=rare_device, rare_device_percentile_bucket=rare_device_percentile_bucket, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, environment=environment, proximity_id=proximity_id, total_hits=total_hits, tor_node=tor_node, incremental_identification_status=incremental_identification_status, simulator=simulator) print("The response of FingerprintApi->search_events:\n") pprint(api_response) except ApiException as e: @@ -298,7 +306,7 @@ except ApiException as e: Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- - **limit** | **int**| Limit the number of events returned. | [optional] [default to 10] + **limit** | **int**| Maximum number of events to return. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. | [optional] [default to 10] **pagination_key** | **str**| Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. 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?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` | [optional] **visitor_id** | **str**| Unique [visitor identifier](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) issued by Fingerprint Identification and all active Smart Signals. Filter events by matching Visitor ID (`identification.visitor_id` property). | [optional] **high_recall_id** | **str**| The High Recall ID is a supplementary browser identifier designed for use cases that require wider coverage over precision. Compared to the standard visitor ID, the High Recall ID strives to match incoming browsers more generously (rather than precisely) with existing browsers and thus identifies fewer browsers as new. The High Recall ID is best suited for use cases that are sensitive to browsers being identified as new and where mismatched browsers are not detrimental. Filter events by matching High Recall ID (`supplementary_id_high_recall.visitor_id` property). | [optional] @@ -310,9 +318,9 @@ Name | Type | Description | Notes **bundle_id** | **str**| Filter events by the Bundle ID (iOS) associated with the event. | [optional] **package_name** | **str**| Filter events by the Package Name (Android) associated with the event. | [optional] **origin** | **str**| Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com) | [optional] - **start** | **int**| Filter events with a timestamp greater than the start time, in Unix time (milliseconds). | [optional] - **end** | **int**| Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). | [optional] - **reverse** | **bool**| Sort events in reverse timestamp order. | [optional] + **start** | **int**| Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. | [optional] + **end** | **int**| Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. | [optional] + **reverse** | **bool**| When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). | [optional] [default to False] **suspect** | **bool**| Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/server-api-v4-update-event). > Note: When using this parameter, only events with the `suspect` property explicitly set to `true` or `false` are returned. Events with undefined `suspect` property are left out of the response. | [optional] **vpn** | **bool**| Filter events by VPN Detection result. > Note: When using this parameter, only events with the `vpn` property set to `true` or `false` are returned. Events without a `vpn` Smart Signal result are left out of the response. | [optional] **virtual_machine** | **bool**| Filter events by Virtual Machine Detection result. > Note: When using this parameter, only events with the `virtual_machine` property set to `true` or `false` are returned. Events without a `virtual_machine` Smart Signal result are left out of the response. | [optional] @@ -331,6 +339,8 @@ Name | Type | Description | Notes **developer_tools** | **bool**| Filter events by Developer Tools detection result. > Note: When using this parameter, only events with the `developer_tools` property set to `true` or `false` are returned. Events without a `developer_tools` Smart Signal result are left out of the response. | [optional] **location_spoofing** | **bool**| Filter events by Location Spoofing detection result. > Note: When using this parameter, only events with the `location_spoofing` property set to `true` or `false` are returned. Events without a `location_spoofing` Smart Signal result are left out of the response. | [optional] **mitm_attack** | **bool**| Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. | [optional] + **rare_device** | **bool**| Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. | [optional] + **rare_device_percentile_bucket** | [**SearchEventsRareDevicePercentileBucket**](.md)| Filter events by Device Rarity percentile bucket. ` Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response. | [optional] **sdk_version** | **str**| Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14` | [optional] **sdk_platform** | [**SearchEventsSdkPlatform**](.md)| Filter events by the SDK Platform associated with the identification event (`sdk.platform` property) . `js` - Javascript agent (Web). `ios` - Apple iOS based devices. `android` - Android based devices. | [optional] diff --git a/docs/RareDevicePercentileBucket.md b/docs/RareDevicePercentileBucket.md new file mode 100644 index 00000000..30862421 --- /dev/null +++ b/docs/RareDevicePercentileBucket.md @@ -0,0 +1,16 @@ +# RareDevicePercentileBucket +The rarity percentile bucket of the device, indicating how uncommon the device configuration is compared to all observed devices. +> This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/). + + +## Enum + +* `LESS_THAN_P95` (value: `' EventSearch: """Search events - ## Search The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include: - Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor. - Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier. - Excluding all bot traffic from the query (`good` and `bad` bots) If you don't provide `start` or `end` parameters, the default search range is the **last 7 days**. ### Filtering events with the `suspect` flag The `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API. You can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior. ### Environment scoping If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments. Smart Signals not activated for your workspace or are not included in the response. + ## Search The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include: - Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor. - Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier. - Excluding all bot traffic from the query (`good` and `bad` bots) By default, the API searches events from the last 7 days, sorts them by newest first and returns the last 10 events. - Use `start` and `end` to specify the time range of the search. - Use `reverse=true` to sort the results oldest first. - Use `limit` to specify the number of events to return. - Use `pagination_key` to get the next page of results if there are more than `limit` events. ### Filtering events with the `suspect` flag The `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API. You can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior. ### Environment scoping If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments. Smart Signals not activated for your workspace or are not included in the response. - :param limit: Limit the number of events returned. + :param limit: Maximum number of events to return. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. :type limit: int :param pagination_key: Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. 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?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` :type pagination_key: str @@ -829,11 +849,11 @@ def search_events( :type package_name: str :param origin: Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com) :type origin: str - :param start: Filter events with a timestamp greater than the start time, in Unix time (milliseconds). + :param start: Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. :type start: int - :param end: Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). + :param end: Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. :type end: int - :param reverse: Sort events in reverse timestamp order. + :param reverse: When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). :type reverse: bool :param suspect: Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/server-api-v4-update-event). > Note: When using this parameter, only events with the `suspect` property explicitly set to `true` or `false` are returned. Events with undefined `suspect` property are left out of the response. :type suspect: bool @@ -871,6 +891,10 @@ def search_events( :type location_spoofing: bool :param mitm_attack: Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. :type mitm_attack: bool + :param rare_device: Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. + :type rare_device: bool + :param rare_device_percentile_bucket: Filter events by Device Rarity percentile bucket. ` Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response. :type proxy: bool :param sdk_version: Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14` @@ -941,6 +965,8 @@ def search_events( developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, + rare_device=rare_device, + rare_device_percentile_bucket=rare_device_percentile_bucket, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, @@ -974,7 +1000,9 @@ def search_events_with_http_info( self, limit: Annotated[ Optional[Annotated[int, Field(le=100, strict=True, ge=1)]], - Field(description='Limit the number of events returned. '), + Field( + description='Maximum number of events to return. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. ' + ), ] = None, pagination_key: Annotated[ Optional[StrictStr], @@ -1043,17 +1071,20 @@ def search_events_with_http_info( start: Annotated[ Optional[StrictInt], Field( - description='Filter events with a timestamp greater than the start time, in Unix time (milliseconds). ' + description="Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. " ), ] = None, end: Annotated[ Optional[StrictInt], Field( - description='Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). ' + description="Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. " ), ] = None, reverse: Annotated[ - Optional[StrictBool], Field(description='Sort events in reverse timestamp order. ') + Optional[StrictBool], + Field( + description='When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). ' + ), ] = None, suspect: Annotated[ Optional[StrictBool], @@ -1163,6 +1194,18 @@ def search_events_with_http_info( description='Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. ' ), ] = None, + rare_device: Annotated[ + Optional[StrictBool], + Field( + description='Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. ' + ), + ] = None, + rare_device_percentile_bucket: Annotated[ + Optional[SearchEventsRareDevicePercentileBucket], + Field( + description='Filter events by Device Rarity percentile bucket. ` ApiResponse[EventSearch]: """Search events - ## Search The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include: - Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor. - Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier. - Excluding all bot traffic from the query (`good` and `bad` bots) If you don't provide `start` or `end` parameters, the default search range is the **last 7 days**. ### Filtering events with the `suspect` flag The `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API. You can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior. ### Environment scoping If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments. Smart Signals not activated for your workspace or are not included in the response. + ## Search The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include: - Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor. - Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier. - Excluding all bot traffic from the query (`good` and `bad` bots) By default, the API searches events from the last 7 days, sorts them by newest first and returns the last 10 events. - Use `start` and `end` to specify the time range of the search. - Use `reverse=true` to sort the results oldest first. - Use `limit` to specify the number of events to return. - Use `pagination_key` to get the next page of results if there are more than `limit` events. ### Filtering events with the `suspect` flag The `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API. You can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior. ### Environment scoping If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments. Smart Signals not activated for your workspace or are not included in the response. - :param limit: Limit the number of events returned. + :param limit: Maximum number of events to return. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. :type limit: int :param pagination_key: Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. 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?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` :type pagination_key: str @@ -1254,11 +1297,11 @@ def search_events_with_http_info( :type package_name: str :param origin: Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com) :type origin: str - :param start: Filter events with a timestamp greater than the start time, in Unix time (milliseconds). + :param start: Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. :type start: int - :param end: Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). + :param end: Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. :type end: int - :param reverse: Sort events in reverse timestamp order. + :param reverse: When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). :type reverse: bool :param suspect: Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/server-api-v4-update-event). > Note: When using this parameter, only events with the `suspect` property explicitly set to `true` or `false` are returned. Events with undefined `suspect` property are left out of the response. :type suspect: bool @@ -1296,6 +1339,10 @@ def search_events_with_http_info( :type location_spoofing: bool :param mitm_attack: Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. :type mitm_attack: bool + :param rare_device: Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. + :type rare_device: bool + :param rare_device_percentile_bucket: Filter events by Device Rarity percentile bucket. ` Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response. :type proxy: bool :param sdk_version: Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14` @@ -1366,6 +1413,8 @@ def search_events_with_http_info( developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, + rare_device=rare_device, + rare_device_percentile_bucket=rare_device_percentile_bucket, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, @@ -1399,7 +1448,9 @@ def search_events_without_preload_content( self, limit: Annotated[ Optional[Annotated[int, Field(le=100, strict=True, ge=1)]], - Field(description='Limit the number of events returned. '), + Field( + description='Maximum number of events to return. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. ' + ), ] = None, pagination_key: Annotated[ Optional[StrictStr], @@ -1468,17 +1519,20 @@ def search_events_without_preload_content( start: Annotated[ Optional[StrictInt], Field( - description='Filter events with a timestamp greater than the start time, in Unix time (milliseconds). ' + description="Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. " ), ] = None, end: Annotated[ Optional[StrictInt], Field( - description='Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). ' + description="Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. " ), ] = None, reverse: Annotated[ - Optional[StrictBool], Field(description='Sort events in reverse timestamp order. ') + Optional[StrictBool], + Field( + description='When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). ' + ), ] = None, suspect: Annotated[ Optional[StrictBool], @@ -1588,6 +1642,18 @@ def search_events_without_preload_content( description='Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. ' ), ] = None, + rare_device: Annotated[ + Optional[StrictBool], + Field( + description='Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. ' + ), + ] = None, + rare_device_percentile_bucket: Annotated[ + Optional[SearchEventsRareDevicePercentileBucket], + Field( + description='Filter events by Device Rarity percentile bucket. ` RESTResponseType: """Search events - ## Search The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include: - Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor. - Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier. - Excluding all bot traffic from the query (`good` and `bad` bots) If you don't provide `start` or `end` parameters, the default search range is the **last 7 days**. ### Filtering events with the `suspect` flag The `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API. You can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior. ### Environment scoping If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments. Smart Signals not activated for your workspace or are not included in the response. + ## Search The `/v4/events` endpoint provides a convenient way to search for past events based on specific parameters. Typical use cases and queries include: - Searching for events associated with a single `visitor_id` within a time range to get historical behavior of a visitor. - Searching for events associated with a single `linked_id` within a time range to get all events associated with your internal account identifier. - Excluding all bot traffic from the query (`good` and `bad` bots) By default, the API searches events from the last 7 days, sorts them by newest first and returns the last 10 events. - Use `start` and `end` to specify the time range of the search. - Use `reverse=true` to sort the results oldest first. - Use `limit` to specify the number of events to return. - Use `pagination_key` to get the next page of results if there are more than `limit` events. ### Filtering events with the `suspect` flag The `/v4/events` endpoint unlocks a powerful method for fraud protection analytics. The `suspect` flag is exposed in all events where it was previously set by the update API. You can also apply the `suspect` query parameter as a filter to find all potentially fraudulent activity that you previously marked as `suspect`. This helps identify patterns of fraudulent behavior. ### Environment scoping If you use a secret key that is scoped to an environment, you will only get events associated with the same environment. With a workspace-scoped environment, you will get events from all environments. Smart Signals not activated for your workspace or are not included in the response. - :param limit: Limit the number of events returned. + :param limit: Maximum number of events to return. Results are selected from the time range (`start`, `end`), ordered by `reverse`, then truncated to provided `limit` size. So `reverse=true` returns the oldest N=`limit` events, otherwise the newest N=`limit` events. :type limit: int :param pagination_key: Use `pagination_key` to get the next page of results. When more results are available (e.g., you requested up to 100 results for your query using `limit`, but there are more than 100 events total matching your request), the `pagination_key` field is added to the response. The pagination key is an arbitrary string that should not be interpreted in any way and should be passed as-is. 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?limit=100` 2. Use `response.pagination_key` to get the next page of results: `GET api-base-url/events?limit=100&pagination_key=1740815825085` :type pagination_key: str @@ -1679,11 +1745,11 @@ def search_events_without_preload_content( :type package_name: str :param origin: Filter events by the origin field of the event. This is applicable to web events only (e.g., https://example.com) :type origin: str - :param start: Filter events with a timestamp greater than the start time, in Unix time (milliseconds). + :param start: Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. :type start: int - :param end: Filter events with a timestamp smaller than the end time, in Unix time (milliseconds). + :param end: Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. :type end: int - :param reverse: Sort events in reverse timestamp order. + :param reverse: When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). :type reverse: bool :param suspect: Filter events previously tagged as suspicious via the [Update API](https://docs.fingerprint.com/reference/server-api-v4-update-event). > Note: When using this parameter, only events with the `suspect` property explicitly set to `true` or `false` are returned. Events with undefined `suspect` property are left out of the response. :type suspect: bool @@ -1721,6 +1787,10 @@ def search_events_without_preload_content( :type location_spoofing: bool :param mitm_attack: Filter events by MITM (Man-in-the-Middle) Attack detection result. > Note: When using this parameter, only events with the `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. :type mitm_attack: bool + :param rare_device: Filter events by Device Rarity detection result. > Note: When using this parameter, only events with the `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. + :type rare_device: bool + :param rare_device_percentile_bucket: Filter events by Device Rarity percentile bucket. ` Note: When using this parameter, only events with the `proxy` property set to `true` or `false` are returned. Events without a `proxy` Smart Signal result are left out of the response. :type proxy: bool :param sdk_version: Filter events by a specific SDK version associated with the identification event (`sdk.version` property). Example: `3.11.14` @@ -1791,6 +1861,8 @@ def search_events_without_preload_content( developer_tools=developer_tools, location_spoofing=location_spoofing, mitm_attack=mitm_attack, + rare_device=rare_device, + rare_device_percentile_bucket=rare_device_percentile_bucket, proxy=proxy, sdk_version=sdk_version, sdk_platform=sdk_platform, @@ -1850,6 +1922,8 @@ def _search_events_serialize( developer_tools: Optional[bool], location_spoofing: Optional[bool], mitm_attack: Optional[bool], + rare_device: Optional[bool], + rare_device_percentile_bucket: Optional[SearchEventsRareDevicePercentileBucket], proxy: Optional[bool], sdk_version: Optional[str], sdk_platform: Optional[SearchEventsSdkPlatform], @@ -2010,6 +2084,16 @@ def _search_events_serialize( if mitm_attack is not None: _query_params.append(('mitm_attack', mitm_attack)) + # process the query parameters + if rare_device is not None: + _query_params.append(('rare_device', rare_device)) + + # process the query parameters + if rare_device_percentile_bucket is not None: + _query_params.append( + ('rare_device_percentile_bucket', rare_device_percentile_bucket.value) + ) + # process the query parameters if proxy is not None: _query_params.append(('proxy', proxy)) diff --git a/fingerprint_server_sdk/models/__init__.py b/fingerprint_server_sdk/models/__init__.py index 5b5528af..d452587d 100644 --- a/fingerprint_server_sdk/models/__init__.py +++ b/fingerprint_server_sdk/models/__init__.py @@ -47,6 +47,7 @@ from fingerprint_server_sdk.models.proximity import Proximity from fingerprint_server_sdk.models.proxy_confidence import ProxyConfidence from fingerprint_server_sdk.models.proxy_details import ProxyDetails +from fingerprint_server_sdk.models.rare_device_percentile_bucket import RareDevicePercentileBucket from fingerprint_server_sdk.models.raw_device_attributes import RawDeviceAttributes from fingerprint_server_sdk.models.request_header_modifications import RequestHeaderModifications from fingerprint_server_sdk.models.rule_action_header_field import RuleActionHeaderField @@ -56,6 +57,9 @@ from fingerprint_server_sdk.models.search_events_incremental_identification_status import ( SearchEventsIncrementalIdentificationStatus, ) +from fingerprint_server_sdk.models.search_events_rare_device_percentile_bucket import ( + SearchEventsRareDevicePercentileBucket, +) from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk.models.supplementary_id_high_recall import SupplementaryIDHighRecall diff --git a/fingerprint_server_sdk/models/error_code.py b/fingerprint_server_sdk/models/error_code.py index 5762c209..f39223c8 100644 --- a/fingerprint_server_sdk/models/error_code.py +++ b/fingerprint_server_sdk/models/error_code.py @@ -20,13 +20,14 @@ class ErrorCode(str, Enum): """ - Error code: * `request_cannot_be_parsed` - The query parameters or JSON payload contains some errors that prevented us from parsing it (wrong type/surpassed limits). * `secret_api_key_required` - secret API key in header is missing or empty. * `secret_api_key_not_found` - No Fingerprint workspace found for specified secret API key. * `public_api_key_required` - public API key in header is missing or empty. * `public_api_key_not_found` - No Fingerprint workspace found for specified public API key. * `subscription_not_active` - Fingerprint workspace is not active. * `wrong_region` - Server and workspace region differ. * `feature_not_enabled` - This feature (for example, Delete API) is not enabled for your workspace. * `visitor_not_found` - The specified visitor ID was not found. It never existed or it may have already been deleted. * `too_many_requests` - The limit on secret API key requests per second has been exceeded. * `state_not_ready` - The event specified with event ID is not ready for updates yet. Try again. This error happens in rare cases when update API is called immediately after receiving the event ID on the client. In case you need to send information right away, we recommend using the JS agent API instead. * `failed` - Internal server error. * `event_not_found` - The specified event ID was not found. It never existed, expired, or it has been deleted. * `missing_module` - The request is invalid because it is missing a required module. * `payload_too_large` - The request payload is too large and cannot be processed. * `service_unavailable` - The service was unable to process the request. * `ruleset_not_found` - The specified ruleset was not found. It never existed or it has been deleted. + Error code: * `request_cannot_be_parsed` - The query parameters or JSON payload contains some errors that prevented us from parsing it (wrong type/surpassed limits). * `request_read_timeout` - The request body could not be read before the connection timed out. * `secret_api_key_required` - secret API key in header is missing or empty. * `secret_api_key_not_found` - No Fingerprint workspace found for specified secret API key. * `public_api_key_required` - public API key in header is missing or empty. * `public_api_key_not_found` - No Fingerprint workspace found for specified public API key. * `subscription_not_active` - Fingerprint workspace is not active. * `wrong_region` - Server and workspace region differ. * `feature_not_enabled` - This feature (for example, Delete API) is not enabled for your workspace. * `visitor_not_found` - The specified visitor ID was not found. It never existed or it may have already been deleted. * `too_many_requests` - The limit on secret API key requests per second has been exceeded. * `state_not_ready` - The event specified with event ID is not ready for updates yet. Try again. This error happens in rare cases when update API is called immediately after receiving the event ID on the client. In case you need to send information right away, we recommend using the JS agent API instead. * `failed` - Internal server error. * `event_not_found` - The specified event ID was not found. It never existed, expired, or it has been deleted. * `missing_module` - The request is invalid because it is missing a required module. * `payload_too_large` - The request payload is too large and cannot be processed. * `service_unavailable` - The service was unable to process the request. * `ruleset_not_found` - The specified ruleset was not found. It never existed or it has been deleted. """ """ allowed enum values """ REQUEST_CANNOT_BE_PARSED = 'request_cannot_be_parsed' + REQUEST_READ_TIMEOUT = 'request_read_timeout' SECRET_API_KEY_REQUIRED = 'secret_api_key_required' SECRET_API_KEY_NOT_FOUND = 'secret_api_key_not_found' PUBLIC_API_KEY_REQUIRED = 'public_api_key_required' diff --git a/fingerprint_server_sdk/models/event.py b/fingerprint_server_sdk/models/event.py index 49a40fd5..2b357aab 100644 --- a/fingerprint_server_sdk/models/event.py +++ b/fingerprint_server_sdk/models/event.py @@ -33,6 +33,7 @@ from fingerprint_server_sdk.models.proximity import Proximity from fingerprint_server_sdk.models.proxy_confidence import ProxyConfidence from fingerprint_server_sdk.models.proxy_details import ProxyDetails +from fingerprint_server_sdk.models.rare_device_percentile_bucket import RareDevicePercentileBucket from fingerprint_server_sdk.models.raw_device_attributes import RawDeviceAttributes from fingerprint_server_sdk.models.sdk import SDK from fingerprint_server_sdk.models.supplementary_id_high_recall import SupplementaryIDHighRecall @@ -135,6 +136,15 @@ class Event(BaseModel): ) proxy_confidence: Optional[ProxyConfidence] = None proxy_details: Optional[ProxyDetails] = None + proxy_ml_score: Optional[ + Union[ + Annotated[float, Field(le=1, strict=True, ge=0)], + Annotated[int, Field(le=1, strict=True, ge=0)], + ] + ] = Field( + default=None, + description='Machine learning–based proxy 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 `proxy` detection result ', + ) incognito: Optional[StrictBool] = Field( default=None, description='`true` if we detected incognito mode used in the browser, `false` otherwise. ', @@ -170,7 +180,7 @@ class Event(BaseModel): ) tampering: Optional[StrictBool] = Field( default=None, - description='Flag indicating browser tampering was detected. This happens when either: * There are inconsistencies in the browser configuration that cross internal tampering thresholds (see `tampering_details.anomaly_score`). * The browser signature resembles an "anti-detect" browser specifically designed to evade fingerprinting (see `tampering_details.anti_detect_browser`). ', + description='The field can be used as a standalone flag for tampering detection. Alternatively, the more granular fields documented below can be used for workflows that require more context. * `true` if tampering is detected through an anomalous browser signature, anti-detect browser detection, or other tampering-related methods * `false` if none of the tampering checks return a positive result ', ) tampering_confidence: Optional[TamperingConfidence] = None tampering_ml_score: Optional[ @@ -180,7 +190,7 @@ class Event(BaseModel): ] ] = Field( default=None, - description='A score that indicates the models calculated probability that an event is coming from an anti detect browser. * Values above `0.8` indicate that the request is an anti detect browser based on the ml model * Values below `0.8` indicate that the request is not an anti detect browser based on the ml model ', + description='The output of this model is captured as tampering_ml_score, a number indicating how likely an event is coming from an anti detect browser. Values close to 1 signify higher confidence and we consider anything above the threshold of 0.8 to be actionable (the result and anti_detect_browser fields conveniently captures that fact) ', ) tampering_details: Optional[TamperingDetails] = None velocity: Optional[Velocity] = None @@ -214,6 +224,11 @@ class Event(BaseModel): default=None, description='Flag indicating if the request came from a high-activity visitor.', ) + rare_device: Optional[StrictBool] = Field( + default=None, + description='`true` if the device is considered rare based on its combination of hardware and software attributes. A device is classified as rare if it falls within the top 99.9 percentile (lowest-frequency segment) of observed traffic, or if its configuration has not been previously seen (`not_seen`). > This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/). ', + ) + rare_device_percentile_bucket: Optional[RareDevicePercentileBucket] = None raw_device_attributes: Optional[RawDeviceAttributes] = None __properties: ClassVar[list[str]] = [ 'event_id', @@ -248,6 +263,7 @@ class Event(BaseModel): 'proxy', 'proxy_confidence', 'proxy_details', + 'proxy_ml_score', 'incognito', 'jailbroken', 'location_spoofing', @@ -270,6 +286,8 @@ class Event(BaseModel): 'vpn_origin_country', 'vpn_methods', 'high_activity_device', + 'rare_device', + 'rare_device_percentile_bucket', 'raw_device_attributes', ] @@ -415,6 +433,7 @@ def from_dict(cls, obj: Optional[dict[str, Any]]) -> Optional[Self]: 'proxy_details': ProxyDetails.from_dict(obj['proxy_details']) if obj.get('proxy_details') is not None else None, + 'proxy_ml_score': obj.get('proxy_ml_score'), 'incognito': obj.get('incognito'), 'jailbroken': obj.get('jailbroken'), 'location_spoofing': obj.get('location_spoofing'), @@ -445,6 +464,8 @@ def from_dict(cls, obj: Optional[dict[str, Any]]) -> Optional[Self]: if obj.get('vpn_methods') is not None else None, 'high_activity_device': obj.get('high_activity_device'), + 'rare_device': obj.get('rare_device'), + 'rare_device_percentile_bucket': obj.get('rare_device_percentile_bucket'), 'raw_device_attributes': RawDeviceAttributes.from_dict( obj['raw_device_attributes'] ) diff --git a/fingerprint_server_sdk/models/rare_device_percentile_bucket.py b/fingerprint_server_sdk/models/rare_device_percentile_bucket.py new file mode 100644 index 00000000..1f186a13 --- /dev/null +++ b/fingerprint_server_sdk/models/rare_device_percentile_bucket.py @@ -0,0 +1,39 @@ +""" +Server API +Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. +Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. + +The version of the OpenAPI document: 4 +Contact: support@fingerprint.com +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + +from __future__ import annotations + +import json +from enum import Enum + +from typing_extensions import Self + + +class RareDevicePercentileBucket(str, Enum): + """ + The rarity percentile bucket of the device, indicating how uncommon the device configuration is compared to all observed devices. > This Smart Signal is currently in beta and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/). + """ + + """ + allowed enum values + """ + LESS_THAN_P95 = ' Self: + """Create an instance of RareDevicePercentileBucket from a JSON string""" + return cls(json.loads(json_str)) diff --git a/fingerprint_server_sdk/models/raw_device_attributes.py b/fingerprint_server_sdk/models/raw_device_attributes.py index 127d117a..aa742f5f 100644 --- a/fingerprint_server_sdk/models/raw_device_attributes.py +++ b/fingerprint_server_sdk/models/raw_device_attributes.py @@ -48,12 +48,15 @@ class RawDeviceAttributes(BaseModel): canvas: Optional[Canvas] = None languages: Optional[list[list[StrictStr]]] = Field( default=None, - description='Navigator languages reported by the agent including fallbacks. Each inner array represents ordered language preferences reported by different APIs. ', + description='Navigator languages reported by the agent including fallbacks. Each inner array represents ordered language preferences reported by different APIs. Available for both browsers and iOS devices ', ) webgl_extensions: Optional[WebGlExtensions] = None webgl_basics: Optional[WebGlBasics] = None screen_resolution: Optional[Annotated[list[StrictInt], Field(min_length=2, max_length=2)]] = ( - Field(default=None, description='Current screen resolution.') + Field( + default=None, + description='Current screen resolution. Available for both browsers and iOS devices', + ) ) touch_support: Optional[TouchSupport] = None oscpu: Optional[StrictStr] = Field(default=None, description='Navigator `oscpu` string.') @@ -64,7 +67,7 @@ class RawDeviceAttributes(BaseModel): cookies_enabled: Optional[StrictBool] = Field( default=None, description='Whether the cookies are enabled in the browser.' ) - hardware_concurrency: Optional[Annotated[int, Field(strict=True, ge=1)]] = Field( + hardware_concurrency: Optional[StrictInt] = Field( default=None, description='Number of logical CPU cores reported by the browser.' ) date_time_locale: Optional[StrictStr] = Field( @@ -95,6 +98,21 @@ class RawDeviceAttributes(BaseModel): math: Optional[StrictStr] = Field( default=None, description='Hash of Math APIs used for entropy collection.' ) + device_model: Optional[StrictStr] = Field( + default=None, + description='Device model string. Available only for Android and iOS devices.', + ) + device_manufacturer: Optional[StrictStr] = Field( + default=None, + description='Device manufacturer string. Available only for Android and iOS devices.', + ) + font_hash: Optional[StrictStr] = Field( + default=None, description='Unique identifier for the user’s installed fonts.' + ) + timezone_offset: Optional[StrictStr] = Field( + default=None, + description='UTC offset in "±HH:MM" format derived from the detected IANA timezone.', + ) __properties: ClassVar[list[str]] = [ 'font_preferences', 'emoji', @@ -121,6 +139,10 @@ class RawDeviceAttributes(BaseModel): 'plugins', 'indexed_db', 'math', + 'device_model', + 'device_manufacturer', + 'font_hash', + 'timezone_offset', ] model_config = ConfigDict( @@ -235,6 +257,10 @@ def from_dict(cls, obj: Optional[dict[str, Any]]) -> Optional[Self]: else None, 'indexed_db': obj.get('indexed_db'), 'math': obj.get('math'), + 'device_model': obj.get('device_model'), + 'device_manufacturer': obj.get('device_manufacturer'), + 'font_hash': obj.get('font_hash'), + 'timezone_offset': obj.get('timezone_offset'), } ) return _obj diff --git a/fingerprint_server_sdk/models/search_events_rare_device_percentile_bucket.py b/fingerprint_server_sdk/models/search_events_rare_device_percentile_bucket.py new file mode 100644 index 00000000..2f82f365 --- /dev/null +++ b/fingerprint_server_sdk/models/search_events_rare_device_percentile_bucket.py @@ -0,0 +1,39 @@ +""" +Server API +Fingerprint Server API allows you to get, search, and update Events in a server environment. It can be used for data exports, decision-making, and data analysis scenarios. +Server API is intended for server-side usage, it's not intended to be used from the client side, whether it's a browser or a mobile device. + +The version of the OpenAPI document: 4 +Contact: support@fingerprint.com +Generated by OpenAPI Generator (https://openapi-generator.tech) + +Do not edit the class manually. +""" # noqa: E501 + +from __future__ import annotations + +import json +from enum import Enum + +from typing_extensions import Self + + +class SearchEventsRareDevicePercentileBucket(str, Enum): + """ + Filter events by Device Rarity percentile bucket. ` Self: + """Create an instance of SearchEventsRareDevicePercentileBucket from a JSON string""" + return cls(json.loads(json_str)) diff --git a/fingerprint_server_sdk/models/tampering_confidence.py b/fingerprint_server_sdk/models/tampering_confidence.py index 42daf1d5..ab829a91 100644 --- a/fingerprint_server_sdk/models/tampering_confidence.py +++ b/fingerprint_server_sdk/models/tampering_confidence.py @@ -20,7 +20,7 @@ class TamperingConfidence(str, Enum): """ - Confidence level of the tampering detection. If a proxy is not detected, confidence is \"high\". If it's detected, can be \"low\", \"medium\", or \"high\". + The confidence level indicates how certain Fingerprint is that the current request involves browser tampering. This confidence level is determined by evaluating multiple factors, such as heuristic rules, probabilistic anomaly detection, an anti detect browser ml model, and other relevant methods. It is conveyed as a string with possible values such as high, medium, or low In case of tampering: `true` * **High confidence**: heuristic anti detect browser signals and the ml model are triggered, or all of the methods are triggered. * **Medium confidence**: either the ml model triggers alone, the anomaly score triggers alone with or without the heuristic anti detect browser methods trigger. * **Low confidence**: only the heuristic anti detect methods are triggered. In case of tampering: `false` * **High confidence:** Strong signals suggest the user is not tampering with their request. """ """ diff --git a/fingerprint_server_sdk/models/tampering_details.py b/fingerprint_server_sdk/models/tampering_details.py index 1d4a1e58..07c4db39 100644 --- a/fingerprint_server_sdk/models/tampering_details.py +++ b/fingerprint_server_sdk/models/tampering_details.py @@ -33,11 +33,11 @@ class TamperingDetails(BaseModel): ] ] = Field( default=None, - description='Confidence score (`0.0 - 1.0`) for tampering detection: * Values above `0.5` indicate tampering. * Values below `0.5` indicate genuine browsers. ', + description="The output of this model is captured as anomaly_score, a statistical score indicating how rare the visitor's browser signature is compared to the overall population. Values close to 1 signify highly anomalous browsers and we consider anything above the threshold of 0.5 to be actionable (the result field conveniently captures that fact). ", ) anti_detect_browser: Optional[StrictBool] = Field( default=None, - description='True if the identified browser resembles an "anti-detect" browser, such as Incognition, which attempts to evade identification by manipulating its fingerprint. ', + description='Detects whether the request shows evidence of anti-detect browser usage. This field may be triggered by: * heuristic detection of known anti-detect browser behavior * machine learning detection of anti-detect browser patterns Examples of anti-detect browsers include tools such as AdsPower, DolphinAnty, OctoBrowser, and GoLogin. ', ) __properties: ClassVar[list[str]] = ['anomaly_score', 'anti_detect_browser'] diff --git a/res/fingerprint-server-api.yaml b/res/fingerprint-server-api.yaml index 8335daf4..376fd8f1 100644 --- a/res/fingerprint-server-api.yaml +++ b/res/fingerprint-server-api.yaml @@ -200,8 +200,18 @@ paths: - Excluding all bot traffic from the query (`good` and `bad` bots) - If you don't provide `start` or `end` parameters, the default search - range is the **last 7 days**. + By default, the API searches events from the last 7 days, sorts them by + newest first and returns the last 10 events. + + + - Use `start` and `end` to specify the time range of the search. + + - Use `reverse=true` to sort the results oldest first. + + - Use `limit` to specify the number of events to return. + + - Use `pagination_key` to get the next page of results if there are more + than `limit` events. ### Filtering events with the `suspect` flag @@ -238,8 +248,11 @@ paths: maximum: 100 default: 10 example: 10 - description: | - Limit the number of events returned. + description: > + Maximum number of events to return. Results are selected from the + time range (`start`, `end`), ordered by `reverse`, then truncated to + provided `limit` size. So `reverse=true` returns the oldest + N=`limit` events, otherwise the newest N=`limit` events. - name: pagination_key in: query schema: @@ -368,23 +381,31 @@ paths: schema: type: integer format: int64 + example: 1767225600000 description: > - Filter events with a timestamp greater than the start time, in Unix - time (milliseconds). + Include events that happened after this point (with timestamp + greater than or equal the provided `start` Unix milliseconds value). + Defaults to 7 days ago. Setting `start` does not change `end`'s + default of `now` — adjust it separately if needed. - name: end in: query schema: type: integer format: int64 + example: 1769903999000 description: > - Filter events with a timestamp smaller than the end time, in Unix - time (milliseconds). + Include events that happened before this point (with timestamp less + than or equal the provided `end` Unix milliseconds value). Defaults + to now. Setting `end` does not change `start`'s default of `7 days + ago` — adjust it separately if needed. - name: reverse 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: @@ -582,6 +603,29 @@ paths: `mitm_attack` property set to `true` or `false` are returned. Events without a `mitm_attack` Smart Signal result are left out of the response. + - name: rare_device + in: query + schema: + type: boolean + description: > + Filter events by Device Rarity detection result. + + > Note: When using this parameter, only events with the + `rare_device` property set to `true` or `false` are returned. Events + without a Device Rarity Smart Signal result are left out of the + response. + - name: rare_device_percentile_bucket + in: query + schema: + $ref: '#/components/schemas/SearchEventsRareDevicePercentileBucket' + description: | + Filter events by Device Rarity percentile bucket. + ` + Machine learning–based proxy 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 + `proxy` detection result Incognito: type: boolean description: > @@ -1528,30 +1582,57 @@ components: Tampering: type: boolean description: > - Flag indicating browser tampering was detected. This happens when - either: - * There are inconsistencies in the browser configuration that cross internal tampering thresholds (see `tampering_details.anomaly_score`). - * The browser signature resembles an "anti-detect" browser specifically designed to evade fingerprinting (see `tampering_details.anti_detect_browser`). + The field can be used as a standalone flag for tampering detection. + Alternatively, the more granular fields documented below can be used for + workflows that require more context. + + * `true` if tampering is detected through an anomalous browser + signature, anti-detect browser detection, or other tampering-related + methods + + * `false` if none of the tampering checks return a positive result TamperingConfidence: type: string enum: - low - medium - high - description: | - Confidence level of the tampering detection. - If a proxy is not detected, confidence is "high". - If it's detected, can be "low", "medium", or "high". + description: > + The confidence level indicates how certain Fingerprint is that the + current request involves browser tampering. This confidence level is + determined by evaluating multiple factors, such as heuristic rules, + probabilistic anomaly detection, an anti detect browser ml model, and + other relevant methods. It is conveyed as a string with possible values + such as high, medium, or low + + In case of tampering: `true` + + * **High confidence**: heuristic anti detect browser signals and the ml + model are triggered, or all of the methods are triggered. + + * **Medium confidence**: either the ml model triggers alone, the anomaly + score triggers alone with or without the heuristic anti detect browser + methods trigger. + + * **Low confidence**: only the heuristic anti detect methods are + triggered. + + + In case of tampering: `false` + + * **High confidence:** Strong signals suggest the user is not tampering + with their request. TamperingMlScore: type: number format: double minimum: 0 maximum: 1 description: > - A score that indicates the models calculated probability that an event - is coming from an anti detect browser. - * Values above `0.8` indicate that the request is an anti detect browser based on the ml model - * Values below `0.8` indicate that the request is not an anti detect browser based on the ml model + The output of this model is captured as tampering_ml_score, a number + indicating how likely an event is coming from an anti detect browser. + Values close to 1 signify higher confidence and we consider anything + above the threshold of 0.8 to be actionable (the result and + anti_detect_browser fields conveniently captures that fact) TamperingDetails: type: object properties: @@ -1564,18 +1645,30 @@ components: - android - ios - browser - description: | - Confidence score (`0.0 - 1.0`) for tampering detection: - * Values above `0.5` indicate tampering. - * Values below `0.5` indicate genuine browsers. + description: > + The output of this model is captured as anomaly_score, a statistical + score indicating how rare the visitor's browser signature is + compared to the overall population. Values close to 1 signify highly + anomalous browsers and we consider anything above the threshold of + 0.5 to be actionable (the result field conveniently captures that + fact). anti_detect_browser: type: boolean x-platforms: - browser description: > - True if the identified browser resembles an "anti-detect" browser, - such as Incognition, which attempts to evade identification by - manipulating its fingerprint. + Detects whether the request shows evidence of anti-detect browser + usage. + + This field may be triggered by: + + * heuristic detection of known anti-detect browser behavior + + * machine learning detection of anti-detect browser patterns + + + Examples of anti-detect browsers include tools such as AdsPower, + DolphinAnty, OctoBrowser, and GoLogin. VelocityData: type: object description: > @@ -1758,6 +1851,34 @@ components: HighActivity: type: boolean description: Flag indicating if the request came from a high-activity visitor. + RareDevice: + type: boolean + description: > + `true` if the device is considered rare based on its combination of + hardware and software attributes. A device is classified as rare if it + falls within the top 99.9 percentile (lowest-frequency segment) of + observed traffic, or if its configuration has not been previously seen + (`not_seen`). + + > This Smart Signal is currently in beta and only available to select + customers. If you are interested, please [contact our support + team](https://fingerprint.com/support/). + RareDevicePercentileBucket: + type: string + description: > + The rarity percentile bucket of the device, indicating how uncommon the + device configuration is compared to all observed devices. + + > This Smart Signal is currently in beta and only available to select + customers. If you are interested, please [contact our support + team](https://fingerprint.com/support/). + enum: + - @@ -1853,7 +1974,7 @@ components: description: > Navigator languages reported by the agent including fallbacks. Each inner array represents ordered language preferences reported by - different APIs. + different APIs. Available for both browsers and iOS devices items: type: array items: @@ -1894,7 +2015,7 @@ components: type: string ScreenResolution: type: array - description: Current screen resolution. + description: Current screen resolution. Available for both browsers and iOS devices minItems: 2 maxItems: 2 items: @@ -1924,7 +2045,6 @@ components: HardwareConcurrency: type: integer format: int32 - minimum: 1 description: Number of logical CPU cores reported by the browser. DateTimeLocale: type: string @@ -1998,6 +2118,18 @@ components: Math: type: string description: Hash of Math APIs used for entropy collection. + DeviceModel: + type: string + description: Device model string. Available only for Android and iOS devices. + DeviceManufacturer: + type: string + description: Device manufacturer string. Available only for Android and iOS devices. + FontHash: + type: string + description: Unique identifier for the user’s installed fonts. + TimezoneOffset: + type: string + description: UTC offset in "±HH:MM" format derived from the detected IANA timezone. RawDeviceAttributes: type: object description: > @@ -2055,6 +2187,14 @@ components: $ref: '#/components/schemas/IndexedDb' math: $ref: '#/components/schemas/Math' + device_model: + $ref: '#/components/schemas/DeviceModel' + device_manufacturer: + $ref: '#/components/schemas/DeviceManufacturer' + font_hash: + $ref: '#/components/schemas/FontHash' + timezone_offset: + $ref: '#/components/schemas/TimezoneOffset' Event: type: object description: >- @@ -2229,6 +2369,10 @@ components: - android - ios - browser + proxy_ml_score: + $ref: '#/components/schemas/ProxyMLScore' + x-platforms: + - browser incognito: $ref: '#/components/schemas/Incognito' x-platforms: @@ -2340,14 +2484,25 @@ components: - android - ios - browser + rare_device: + $ref: '#/components/schemas/RareDevice' + x-platforms: + - browser + rare_device_percentile_bucket: + $ref: '#/components/schemas/RareDevicePercentileBucket' + x-platforms: + - browser raw_device_attributes: $ref: '#/components/schemas/RawDeviceAttributes' x-platforms: + - android + - ios - browser ErrorCode: type: string enum: - request_cannot_be_parsed + - request_read_timeout - secret_api_key_required - secret_api_key_not_found - public_api_key_required @@ -2370,6 +2525,9 @@ components: * `request_cannot_be_parsed` - The query parameters or JSON payload contains some errors that prevented us from parsing it (wrong type/surpassed limits). + * `request_read_timeout` - The request body could not be read before the + connection timed out. + * `secret_api_key_required` - secret API key in header is missing or empty. @@ -2506,6 +2664,23 @@ components: > Note: When using this parameter, only events with the `vpn.confidence` property set to a valid value are returned. Events without a `vpn` Smart Signal result are left out of the response. + SearchEventsRareDevicePercentileBucket: + type: string + enum: + -