diff --git a/.changeset/all-showers-trade.md b/.changeset/all-showers-trade.md new file mode 100644 index 00000000..2fbf6a2a --- /dev/null +++ b/.changeset/all-showers-trade.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': patch +--- + +**events-search**: Remove `default` property from `reverse` query parameter \ No newline at end of file diff --git a/.changeset/beige-places-drop.md b/.changeset/beige-places-drop.md new file mode 100644 index 00000000..0f0e407f --- /dev/null +++ b/.changeset/beige-places-drop.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': patch +--- + +**events**: Clarify availability of proxy and VM ML score signals \ No newline at end of file diff --git a/.changeset/blue-roses-film.md b/.changeset/blue-roses-film.md new file mode 100644 index 00000000..3ef74aeb --- /dev/null +++ b/.changeset/blue-roses-film.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': patch +--- + +**events**: Clarify semantics of `incremental_identification_status` \ No newline at end of file diff --git a/.changeset/curvy-rice-chew.md b/.changeset/curvy-rice-chew.md new file mode 100644 index 00000000..096d1bc5 --- /dev/null +++ b/.changeset/curvy-rice-chew.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': patch +--- + +**visitors**: Clarify rate limits for `deleteVisitorData` operation \ No newline at end of file diff --git a/.changeset/cute-pumas-pull.md b/.changeset/cute-pumas-pull.md new file mode 100644 index 00000000..7db03cea --- /dev/null +++ b/.changeset/cute-pumas-pull.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events-search**: Add `start_date_time` and `end_date_time` RFC3339 timestamp filters \ No newline at end of file diff --git a/.changeset/developer-tools-android-v4.md b/.changeset/developer-tools-android-v4.md new file mode 100644 index 00000000..7b3e405f --- /dev/null +++ b/.changeset/developer-tools-android-v4.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add Android platform support to `developer_tools` smart signal diff --git a/.changeset/developer-tools-ios.md b/.changeset/developer-tools-ios.md new file mode 100644 index 00000000..fd551d37 --- /dev/null +++ b/.changeset/developer-tools-ios.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add iOS platform support to `developer_tools` smart signal for API v3 diff --git a/.changeset/events-rfc3339-timestamps.md b/.changeset/events-rfc3339-timestamps.md new file mode 100644 index 00000000..93039c4b --- /dev/null +++ b/.changeset/events-rfc3339-timestamps.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events-search**: Accept RFC3339 timestamps for `start` and `end` filter parameters in addition to Unix milliseconds diff --git a/.changeset/fancy-spiders-flash.md b/.changeset/fancy-spiders-flash.md new file mode 100644 index 00000000..ffd47313 --- /dev/null +++ b/.changeset/fancy-spiders-flash.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add `labels` to `Event` \ No newline at end of file diff --git a/.changeset/loud-donuts-lead.md b/.changeset/loud-donuts-lead.md new file mode 100644 index 00000000..435235ae --- /dev/null +++ b/.changeset/loud-donuts-lead.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': patch +--- + +**events-search**: Clarify availability of `rare_device` and `rare_device_percentile_bucket` query parameters \ No newline at end of file diff --git a/.changeset/quick-cows-battle.md b/.changeset/quick-cows-battle.md new file mode 100644 index 00000000..bb8b129c --- /dev/null +++ b/.changeset/quick-cows-battle.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events**: Add iOS platform support to `developer_tools` \ No newline at end of file diff --git a/.changeset/wet-socks-fold.md b/.changeset/wet-socks-fold.md new file mode 100644 index 00000000..766aa802 --- /dev/null +++ b/.changeset/wet-socks-fold.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': patch +--- + +**events-search**: Fix `pagination_key` example \ No newline at end of file diff --git a/.changeset/witty-lions-worry.md b/.changeset/witty-lions-worry.md new file mode 100644 index 00000000..4cf50574 --- /dev/null +++ b/.changeset/witty-lions-worry.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events-search**: Add `bot_info` filter parameters \ No newline at end of file diff --git a/.changeset/yellow-ducks-spend.md b/.changeset/yellow-ducks-spend.md new file mode 100644 index 00000000..d44f3a85 --- /dev/null +++ b/.changeset/yellow-ducks-spend.md @@ -0,0 +1,5 @@ +--- +'@fingerprint/python-sdk': minor +--- + +**events-search**: Add `unknown` value to `BotInfoCategory` \ No newline at end of file diff --git a/.openapi-generator/FILES b/.openapi-generator/FILES index 75a51835..611a9343 100644 --- a/.openapi-generator/FILES +++ b/.openapi-generator/FILES @@ -1,5 +1,8 @@ README.md docs/BotInfo.md +docs/BotInfoCategory.md +docs/BotInfoConfidence.md +docs/BotInfoIdentity.md docs/BotResult.md docs/BrowserDetails.md docs/Canvas.md @@ -27,6 +30,7 @@ docs/IdentificationConfidence.md docs/IncrementalIdentificationStatus.md docs/Integration.md docs/IntegrationSubintegration.md +docs/LabelsInner.md docs/PluginsInner.md docs/PluginsInnerMimeTypesInner.md docs/Proximity.md @@ -40,9 +44,12 @@ docs/RuleActionType.md docs/SDK.md docs/SealedResults.md docs/SearchEventsBot.md +docs/SearchEventsBotInfo.md +docs/SearchEventsEndParameter.md docs/SearchEventsIncrementalIdentificationStatus.md docs/SearchEventsRareDevicePercentileBucket.md docs/SearchEventsSdkPlatform.md +docs/SearchEventsStartParameter.md docs/SearchEventsVpnConfidence.md docs/SupplementaryIDHighRecall.md docs/TamperingConfidence.md @@ -63,6 +70,9 @@ fingerprint_server_sdk/configuration.py fingerprint_server_sdk/exceptions.py fingerprint_server_sdk/models/__init__.py fingerprint_server_sdk/models/bot_info.py +fingerprint_server_sdk/models/bot_info_category.py +fingerprint_server_sdk/models/bot_info_confidence.py +fingerprint_server_sdk/models/bot_info_identity.py fingerprint_server_sdk/models/bot_result.py fingerprint_server_sdk/models/browser_details.py fingerprint_server_sdk/models/canvas.py @@ -88,6 +98,7 @@ fingerprint_server_sdk/models/ip_block_list.py fingerprint_server_sdk/models/ip_info.py fingerprint_server_sdk/models/ip_info_v4.py fingerprint_server_sdk/models/ip_info_v6.py +fingerprint_server_sdk/models/labels_inner.py fingerprint_server_sdk/models/plugins_inner.py fingerprint_server_sdk/models/plugins_inner_mime_types_inner.py fingerprint_server_sdk/models/proximity.py @@ -100,9 +111,12 @@ fingerprint_server_sdk/models/rule_action_header_field.py 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_bot_info.py +fingerprint_server_sdk/models/search_events_end_parameter.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_start_parameter.py fingerprint_server_sdk/models/search_events_vpn_confidence.py fingerprint_server_sdk/models/supplementary_id_high_recall.py fingerprint_server_sdk/models/tampering_confidence.py diff --git a/.schema-version b/.schema-version index aa6c8967..e682ea42 100644 --- a/.schema-version +++ b/.schema-version @@ -1 +1 @@ -v3.2.0 \ No newline at end of file +v3.3.0 \ No newline at end of file diff --git a/README.md b/README.md index 0abedbc2..a421b8a8 100644 --- a/README.md +++ b/README.md @@ -317,7 +317,7 @@ All URIs are relative to *https://api.fpjs.io/v4* Class | Method | HTTP request | Description ------------ | ------------- | ------------- | ------------- -*FingerprintApi* | [**delete_visitor_data**](docs/FingerprintApi.md#delete_visitor_data) | **DELETE** /visitors/{visitor_id} | Delete data by visitor ID +*FingerprintApi* | [**delete_visitor_data**](docs/FingerprintApi.md#delete_visitor_data) | **DELETE** /visitors/{visitor_id} | Delete a visitor ID *FingerprintApi* | [**get_event**](docs/FingerprintApi.md#get_event) | **GET** /events/{event_id} | Get an event by event ID *FingerprintApi* | [**search_events**](docs/FingerprintApi.md#search_events) | **GET** /events | Search events *FingerprintApi* | [**update_event**](docs/FingerprintApi.md#update_event) | **PATCH** /events/{event_id} | Update an event @@ -326,6 +326,9 @@ Class | Method | HTTP request | Description ## Documentation For Models - [BotInfo](docs/BotInfo.md) + - [BotInfoCategory](docs/BotInfoCategory.md) + - [BotInfoConfidence](docs/BotInfoConfidence.md) + - [BotInfoIdentity](docs/BotInfoIdentity.md) - [BotResult](docs/BotResult.md) - [BrowserDetails](docs/BrowserDetails.md) - [Canvas](docs/Canvas.md) @@ -351,6 +354,7 @@ Class | Method | HTTP request | Description - [IncrementalIdentificationStatus](docs/IncrementalIdentificationStatus.md) - [Integration](docs/Integration.md) - [IntegrationSubintegration](docs/IntegrationSubintegration.md) + - [LabelsInner](docs/LabelsInner.md) - [PluginsInner](docs/PluginsInner.md) - [PluginsInnerMimeTypesInner](docs/PluginsInnerMimeTypesInner.md) - [Proximity](docs/Proximity.md) @@ -363,9 +367,12 @@ Class | Method | HTTP request | Description - [RuleActionType](docs/RuleActionType.md) - [SDK](docs/SDK.md) - [SearchEventsBot](docs/SearchEventsBot.md) + - [SearchEventsBotInfo](docs/SearchEventsBotInfo.md) + - [SearchEventsEndParameter](docs/SearchEventsEndParameter.md) - [SearchEventsIncrementalIdentificationStatus](docs/SearchEventsIncrementalIdentificationStatus.md) - [SearchEventsRareDevicePercentileBucket](docs/SearchEventsRareDevicePercentileBucket.md) - [SearchEventsSdkPlatform](docs/SearchEventsSdkPlatform.md) + - [SearchEventsStartParameter](docs/SearchEventsStartParameter.md) - [SearchEventsVpnConfidence](docs/SearchEventsVpnConfidence.md) - [SupplementaryIDHighRecall](docs/SupplementaryIDHighRecall.md) - [TamperingConfidence](docs/TamperingConfidence.md) diff --git a/docs/BotInfo.md b/docs/BotInfo.md index bfd7f406..40fd0516 100644 --- a/docs/BotInfo.md +++ b/docs/BotInfo.md @@ -4,12 +4,12 @@ Extended bot information. ## Properties Name | Type | Description | Notes ------------ | ------------- | ------------- | ------------- -**category** | **str** | The type and purpose of the bot. | +**category** | [**BotInfoCategory**](BotInfoCategory.md) | | **provider** | **str** | The organization or company operating the bot. | **provider_url** | **str** | The URL of the bot provider's website. | [optional] **name** | **str** | The specific name or identifier of the bot. | -**identity** | **str** | The verification status of the bot's identity: * `verified` - well-known bot with publicly verifiable identity, directed by the bot provider. * `signed` - bot that signs its platform via Web Bot Auth, directed by the bot provider’s customers. * `spoofed` - bot that claims a public identity but fails verification. * `unknown` - bot that does not publish a verifiable identity. | -**confidence** | **str** | Confidence level of the bot identification. | +**identity** | [**BotInfoIdentity**](BotInfoIdentity.md) | | +**confidence** | [**BotInfoConfidence**](BotInfoConfidence.md) | | [[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/BotInfoCategory.md b/docs/BotInfoCategory.md new file mode 100644 index 00000000..a4487a38 --- /dev/null +++ b/docs/BotInfoCategory.md @@ -0,0 +1,25 @@ +# BotInfoCategory +The type and purpose of the bot. + + +## Enum + +* `ADVERTISING_AND_MARKETING` (value: `'advertising_and_marketing'`) +* `AGGREGATOR` (value: `'aggregator'`) +* `AI_AGENT` (value: `'ai_agent'`) +* `AI_ASSISTANT` (value: `'ai_assistant'`) +* `AI_BROWSER` (value: `'ai_browser'`) +* `AI_CRAWLER` (value: `'ai_crawler'`) +* `AI_SEARCH` (value: `'ai_search'`) +* `BROWSER_AUTOMATION` (value: `'browser_automation'`) +* `ECOMMERCE` (value: `'ecommerce'`) +* `MONITORING_AND_ANALYTICS` (value: `'monitoring_and_analytics'`) +* `OTHER` (value: `'other'`) +* `SCRAPING` (value: `'scraping'`) +* `SECURITY` (value: `'security'`) +* `SEARCH_ENGINE_CRAWLER` (value: `'search_engine_crawler'`) +* `SEARCH_ENGINE_OPTIMIZATION` (value: `'search_engine_optimization'`) +* `UNKNOWN` (value: `'unknown'`) + +[[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/BotInfoConfidence.md b/docs/BotInfoConfidence.md new file mode 100644 index 00000000..b95d2b2e --- /dev/null +++ b/docs/BotInfoConfidence.md @@ -0,0 +1,11 @@ +# BotInfoConfidence +Confidence level of the bot identification. + +## Enum + +* `LOW` (value: `'low'`) +* `MEDIUM` (value: `'medium'`) +* `HIGH` (value: `'high'`) + +[[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/BotInfoIdentity.md b/docs/BotInfoIdentity.md new file mode 100644 index 00000000..acbd1e62 --- /dev/null +++ b/docs/BotInfoIdentity.md @@ -0,0 +1,17 @@ +# BotInfoIdentity +The verification status of the bot's identity: + * `verified` - well-known bot with publicly verifiable identity, directed by the bot provider. + * `signed` - bot that signs its platform via Web Bot Auth, directed by the bot provider's customers. + * `spoofed` - bot that claims a public identity but fails verification. + * `unknown` - bot that does not publish a verifiable identity. + + +## Enum + +* `VERIFIED` (value: `'verified'`) +* `SIGNED` (value: `'signed'`) +* `SPOOFED` (value: `'spoofed'`) +* `UNKNOWN` (value: `'unknown'`) + +[[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/Event.md b/docs/Event.md index d0ba814d..7e0412f8 100644 --- a/docs/Event.md +++ b/docs/Event.md @@ -27,7 +27,7 @@ Name | Type | Description | Notes **bot_type** | **str** | Additional classification of the bot type if detected. | [optional] **bot_info** | [**BotInfo**](BotInfo.md) | | [optional] **cloned_app** | **bool** | Android specific cloned application detection. There are 2 values: * `true` - Presence of app cloners work detected (e.g. fully cloned application found or launch of it inside of a not main working profile detected). * `false` - No signs of cloned application detected or the client is not Android. | [optional] -**developer_tools** | **bool** | `true` if the browser is Chrome with DevTools open or Firefox with Developer Tools open, `false` otherwise. | [optional] +**developer_tools** | **bool** | `true` if the browser has DevTools open (Chrome, Firefox) or the Android/iOS device has Developer Tools enabled, `false` otherwise. | [optional] **emulator** | **bool** | Android specific emulator detection. There are 2 values: * `true` - Emulated environment detected (e.g. launch inside of AVD). * `false` - No signs of emulated environment detected or the client is not Android. | [optional] **factory_reset_timestamp** | **int** | The time of the most recent factory reset that happened on the **mobile device** is expressed as Unix epoch time. When a factory reset cannot be detected on the mobile device or when the request is initiated from a browser, this field will correspond to the *epoch* time (i.e 1 Jan 1970 UTC) as a value of 0. See [Factory Reset Detection](https://docs.fingerprint.com/docs/smart-signals-reference#factory-reset-detection) to learn more about this Smart Signal. | [optional] **frida** | **bool** | [Frida](https://frida.re/docs/) detection for Android and iOS devices. There are 2 values: * `true` - Frida detected * `false` - No signs of Frida or the client is not a mobile device. | [optional] @@ -36,7 +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] +**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. 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] **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] @@ -52,7 +52,7 @@ Name | Type | Description | Notes **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] -**virtual_machine_ml_score** | **float** | Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `virtual_machine` detection result | [optional] +**virtual_machine_ml_score** | **float** | Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `virtual_machine` detection result. 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] **vpn** | **bool** | VPN or other anonymizing service has been used when sending the request. | [optional] **vpn_confidence** | [**VpnConfidence**](VpnConfidence.md) | | [optional] **vpn_origin_timezone** | **str** | Local timezone which is used in timezone_mismatch method. | [optional] @@ -62,6 +62,7 @@ Name | Type | Description | Notes **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] +**labels** | [**List[LabelsInner]**](LabelsInner.md) | Each label returns a prediction (true or false) for a specific use case (label field) based on a machine learning score. The machine learning score is determined by a model trained on customer data for that use case. This field is in the beta phase and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/). | [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 4c39203f..4bafcdaf 100644 --- a/docs/FingerprintApi.md +++ b/docs/FingerprintApi.md @@ -4,7 +4,7 @@ All URIs are relative to *https://api.fpjs.io/v4* Method | HTTP request | Description ------------- | ------------- | ------------- -[**delete_visitor_data**](FingerprintApi.md#delete_visitor_data) | **DELETE** /visitors/{visitor_id} | Delete data by visitor ID +[**delete_visitor_data**](FingerprintApi.md#delete_visitor_data) | **DELETE** /visitors/{visitor_id} | Delete a visitor ID [**get_event**](FingerprintApi.md#get_event) | **GET** /events/{event_id} | Get an event by event ID [**search_events**](FingerprintApi.md#search_events) | **GET** /events | Search events [**update_event**](FingerprintApi.md#update_event) | **PATCH** /events/{event_id} | Update an event @@ -13,31 +13,35 @@ Method | HTTP request | Description # **delete_visitor_data** > delete_visitor_data(visitor_id) -Delete data by visitor ID +Delete a visitor ID -Request deleting all data associated with the specified visitor ID. This API is useful for compliance with privacy regulations. +Use this API to request the deletion of all data associated with a specific visitor ID. -### Which data is deleted? -- Browser (or device) properties -- Identification requests made from this browser (or device) +Upon a request to delete data for a visitor ID, +- The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID. +- The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. +- The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention). -#### Browser (or device) properties -- Represents the data that Fingerprint collected from this specific browser (or device) and everything inferred and derived from it. -- Upon request to delete, this data is deleted asynchronously (typically within a few minutes) and it will no longer be used to identify this browser (or device) for your [Fingerprint Workspace](https://docs.fingerprint.com/docs/glossary#fingerprint-workspace). +The following timeline illustrates which events are deleted and which remain after a DELETE API request: +``` +Day 1: First visit from browser A. (Assigned visitor ID: VID1000) +Day 2: Browser A revisits. (Assigned the same visitor ID: VID1000) +Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000) +Day 14: Delete VID1000 +Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999) +Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted) +Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available) +``` + +### Availability +This API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/). -#### Identification requests made from this browser (or device) -- Fingerprint stores the identification requests made from a browser (or device) for up to 30 (or 90) days depending on your plan. To learn more, see [Data Retention](https://docs.fingerprint.com/docs/regions#data-retention). -- Upon request to delete, the identification requests that were made by this browser - - Within the past 10 days are deleted within 24 hrs. - - Outside of 10 days are allowed to purge as per your data retention period. +### Rate limits and daily quota +The rate limits and daily quota for this API **differ** from those for our other API. -### Corollary -After requesting to delete a visitor ID, -- If the same browser (or device) requests to identify, it will receive a different visitor ID. -- If you request [`/v4/events` API](https://docs.fingerprint.com/reference/server-api-v4-get-event) with an `event_id` that was made outside of the 10 days, you will still receive a valid response. +The maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD. -### Interested? -Please [contact our support team](https://fingerprint.com/support/) to enable it for you. Otherwise, you will receive a 403. +You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). ### Example @@ -62,7 +66,7 @@ api_instance = fingerprint_server_sdk.FingerprintApi(configuration) visitor_id: str = 'visitor_id_example' # The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete. try: - # Delete data by visitor ID + # Delete a visitor ID api_instance.delete_visitor_data(visitor_id) except ApiException as e: if e.body is not None: @@ -183,7 +187,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, 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) +> EventSearch search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, bot_info=bot_info, bot_info_category=bot_info_category, bot_info_identity=bot_info_identity, bot_info_confidence=bot_info_confidence, bot_info_provider=bot_info_provider, bot_info_name=bot_info_name, 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 @@ -221,8 +225,12 @@ Smart Signals not activated for your workspace or are not included in the respon import os import fingerprint_server_sdk +from fingerprint_server_sdk.models.bot_info_category import BotInfoCategory +from fingerprint_server_sdk.models.bot_info_confidence import BotInfoConfidence +from fingerprint_server_sdk.models.bot_info_identity import BotInfoIdentity 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_bot_info import SearchEventsBotInfo 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 @@ -241,10 +249,16 @@ configuration = fingerprint_server_sdk.Configuration( api_instance = fingerprint_server_sdk.FingerprintApi(configuration) 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) +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 100 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) bot: SearchEventsBot = fingerprint_server_sdk.SearchEventsBot() # Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. (optional) +bot_info: SearchEventsBotInfo = fingerprint_server_sdk.SearchEventsBotInfo() # Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. (optional) +bot_info_category: List[BotInfoCategory] = [fingerprint_server_sdk.BotInfoCategory()] # Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. (optional) +bot_info_identity: List[BotInfoIdentity] = [fingerprint_server_sdk.BotInfoIdentity()] # Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. (optional) +bot_info_confidence: List[BotInfoConfidence] = [fingerprint_server_sdk.BotInfoConfidence()] # Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. (optional) +bot_info_provider: List[str] = ['bot_info_provider_example'] # Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. (optional) +bot_info_name: List[str] = ['bot_info_name_example'] # Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. (optional) ip_address: str = 'ip_address_example' # Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 (optional) asn: str = 'asn_example' # Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response. (optional) linked_id: str = 'linked_id_example' # Filter events by your custom identifier. You can use [linked Ids](https://docs.fingerprint.com/reference/js-agent-v4-get-function#linkedid) to associate identification requests with your own identifier, for example, session Id, purchase Id, or transaction Id. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier. (optional) @@ -252,9 +266,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 = 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 = True # When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). (optional) +start: SearchEventsStartParameter = fingerprint_server_sdk.SearchEventsStartParameter() # Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. (optional) +end: SearchEventsEndParameter = fingerprint_server_sdk.SearchEventsEndParameter() # Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. (optional) +reverse: bool = True # When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (newest first, descending timestamp order). (optional) 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) @@ -273,8 +287,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 `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. > 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: SearchEventsRareDevicePercentileBucket = fingerprint_server_sdk.SearchEventsRareDevicePercentileBucket() # Filter events by Device Rarity percentile bucket. ` 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) proxy: bool = True # Filter events by Proxy detection result. > 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) @@ -287,7 +301,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, 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) + api_response = api_instance.search_events(limit=limit, pagination_key=pagination_key, visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, bot_info=bot_info, bot_info_category=bot_info_category, bot_info_identity=bot_info_identity, bot_info_confidence=bot_info_confidence, bot_info_provider=bot_info_provider, bot_info_name=bot_info_name, 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: @@ -307,10 +321,16 @@ except ApiException as e: Name | Type | Description | Notes ------------- | ------------- | ------------- | ------------- **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] + **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 100 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] **bot** | [**SearchEventsBot**](.md)| Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. | [optional] + **bot_info** | [**SearchEventsBotInfo**](.md)| Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. | [optional] + **bot_info_category** | [**List[BotInfoCategory]**](BotInfoCategory.md)| Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. | [optional] + **bot_info_identity** | [**List[BotInfoIdentity]**](BotInfoIdentity.md)| Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. | [optional] + **bot_info_confidence** | [**List[BotInfoConfidence]**](BotInfoConfidence.md)| Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. | [optional] + **bot_info_provider** | [**List[str]**](str.md)| Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. | [optional] + **bot_info_name** | [**List[str]**](str.md)| Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. | [optional] **ip_address** | **str**| Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 | [optional] **asn** | **str**| Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response. | [optional] **linked_id** | **str**| Filter events by your custom identifier. You can use [linked Ids](https://docs.fingerprint.com/reference/js-agent-v4-get-function#linkedid) to associate identification requests with your own identifier, for example, session Id, purchase Id, or transaction Id. You can then use this `linked_id` parameter to retrieve all events associated with your custom identifier. | [optional] @@ -318,9 +338,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**| 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] + **start** | [**SearchEventsStartParameter**](.md)| Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. | [optional] + **end** | [**SearchEventsEndParameter**](.md)| Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). 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). Defaults to `false` (newest first, descending timestamp order). | [optional] **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] @@ -339,8 +359,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 `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. > 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** | [**SearchEventsRareDevicePercentileBucket**](.md)| Filter events by Device Rarity percentile bucket. ` 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] **proxy** | **bool**| Filter events by Proxy detection result. > 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/IncrementalIdentificationStatus.md b/docs/IncrementalIdentificationStatus.md index 779ea103..49b7380d 100644 --- a/docs/IncrementalIdentificationStatus.md +++ b/docs/IncrementalIdentificationStatus.md @@ -1,7 +1,7 @@ # IncrementalIdentificationStatus Only included for requests using incremental identification. -- `partially_completed` - the event did not receive the second "update" request. -- `completed` - the event was updated and all information is available. +- `partially_completed` - Indicates this event corresponds to a 'minimal' request. Smart Signals, even if included in your plan, are not computed; hence, their values must be ignored. +- `completed` - Indicates this event corresponds to a 'complete' request. Smart Signals, if included in your plan, are computed; hence, their values are valid and relevant. ## Enum diff --git a/docs/LabelsInner.md b/docs/LabelsInner.md new file mode 100644 index 00000000..14c0b45f --- /dev/null +++ b/docs/LabelsInner.md @@ -0,0 +1,10 @@ +# LabelsInner +## Properties +Name | Type | Description | Notes +------------ | ------------- | ------------- | ------------- +**label** | **str** | | [optional] +**prediction** | **bool** | | [optional] +**ml_score** | **float** | | [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/SearchEventsBotInfo.md b/docs/SearchEventsBotInfo.md new file mode 100644 index 00000000..dc9d2897 --- /dev/null +++ b/docs/SearchEventsBotInfo.md @@ -0,0 +1,13 @@ +# SearchEventsBotInfo +Filter events by their Bot Info result, specifically: + - `all` - events where any kind of bot was detected. + - `none` - events where no bot was detected. + + +## Enum + +* `ALL` (value: `'all'`) +* `NONE` (value: `'none'`) + +[[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/SearchEventsEndParameter.md b/docs/SearchEventsEndParameter.md new file mode 100644 index 00000000..3a6341b1 --- /dev/null +++ b/docs/SearchEventsEndParameter.md @@ -0,0 +1,7 @@ +# SearchEventsEndParameter +## Type alias + +`Union[datetime,int]` + +[[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/SearchEventsRareDevicePercentileBucket.md b/docs/SearchEventsRareDevicePercentileBucket.md index 6ce01bf5..2d88c66d 100644 --- a/docs/SearchEventsRareDevicePercentileBucket.md +++ b/docs/SearchEventsRareDevicePercentileBucket.md @@ -7,6 +7,8 @@ Filter events by Device Rarity percentile bucket. `p99.9+` - device is in the top 0.1% (rarest). `not_seen` - device configuration has never been observed before. +> 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 diff --git a/docs/SearchEventsStartParameter.md b/docs/SearchEventsStartParameter.md new file mode 100644 index 00000000..6fab9151 --- /dev/null +++ b/docs/SearchEventsStartParameter.md @@ -0,0 +1,7 @@ +# SearchEventsStartParameter +## Type alias + +`Union[datetime,int]` + +[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md) + diff --git a/fingerprint_server_sdk/__init__.py b/fingerprint_server_sdk/__init__.py index 012853b5..c3bdaa4f 100644 --- a/fingerprint_server_sdk/__init__.py +++ b/fingerprint_server_sdk/__init__.py @@ -42,6 +42,9 @@ 'UnsealAggregateError', 'unseal_event_response', 'BotInfo', + 'BotInfoCategory', + 'BotInfoConfidence', + 'BotInfoIdentity', 'BotResult', 'BrowserDetails', 'Canvas', @@ -67,6 +70,7 @@ 'IncrementalIdentificationStatus', 'Integration', 'IntegrationSubintegration', + 'LabelsInner', 'PluginsInner', 'PluginsInnerMimeTypesInner', 'Proximity', @@ -79,9 +83,12 @@ 'RuleActionType', 'SDK', 'SearchEventsBot', + 'SearchEventsBotInfo', + 'SearchEventsEndParameter', 'SearchEventsIncrementalIdentificationStatus', 'SearchEventsRareDevicePercentileBucket', 'SearchEventsSdkPlatform', + 'SearchEventsStartParameter', 'SearchEventsVpnConfidence', 'SupplementaryIDHighRecall', 'TamperingConfidence', @@ -119,6 +126,9 @@ # import models into sdk package from fingerprint_server_sdk.models.bot_info import BotInfo +from fingerprint_server_sdk.models.bot_info_category import BotInfoCategory +from fingerprint_server_sdk.models.bot_info_confidence import BotInfoConfidence +from fingerprint_server_sdk.models.bot_info_identity import BotInfoIdentity from fingerprint_server_sdk.models.bot_result import BotResult from fingerprint_server_sdk.models.browser_details import BrowserDetails from fingerprint_server_sdk.models.canvas import Canvas @@ -148,6 +158,7 @@ ) from fingerprint_server_sdk.models.integration import Integration from fingerprint_server_sdk.models.integration_subintegration import IntegrationSubintegration +from fingerprint_server_sdk.models.labels_inner import LabelsInner from fingerprint_server_sdk.models.plugins_inner import PluginsInner from fingerprint_server_sdk.models.plugins_inner_mime_types_inner import PluginsInnerMimeTypesInner from fingerprint_server_sdk.models.proximity import Proximity @@ -160,6 +171,8 @@ from fingerprint_server_sdk.models.rule_action_type import RuleActionType from fingerprint_server_sdk.models.sdk import SDK from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot +from fingerprint_server_sdk.models.search_events_bot_info import SearchEventsBotInfo +from fingerprint_server_sdk.models.search_events_end_parameter import SearchEventsEndParameter from fingerprint_server_sdk.models.search_events_incremental_identification_status import ( SearchEventsIncrementalIdentificationStatus, ) @@ -167,6 +180,7 @@ SearchEventsRareDevicePercentileBucket, ) from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform +from fingerprint_server_sdk.models.search_events_start_parameter import SearchEventsStartParameter from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk.models.supplementary_id_high_recall import SupplementaryIDHighRecall from fingerprint_server_sdk.models.tampering_confidence import TamperingConfidence diff --git a/fingerprint_server_sdk/api/fingerprint_api.py b/fingerprint_server_sdk/api/fingerprint_api.py index 71dd5ed4..8ae28855 100644 --- a/fingerprint_server_sdk/api/fingerprint_api.py +++ b/fingerprint_server_sdk/api/fingerprint_api.py @@ -10,6 +10,7 @@ Do not edit the class manually. """ # noqa: E501 +from datetime import date, datetime from typing import Annotated, Any, Optional, Union # noqa: UP035 from pydantic import Field, StrictBool, StrictFloat, StrictInt, StrictStr, validate_call @@ -17,10 +18,15 @@ from fingerprint_server_sdk.api_client import ApiClient, RequestSerialized from fingerprint_server_sdk.api_response import ApiResponse from fingerprint_server_sdk.configuration import Configuration +from fingerprint_server_sdk.models.bot_info_category import BotInfoCategory +from fingerprint_server_sdk.models.bot_info_confidence import BotInfoConfidence +from fingerprint_server_sdk.models.bot_info_identity import BotInfoIdentity from fingerprint_server_sdk.models.event import Event from fingerprint_server_sdk.models.event_search import EventSearch from fingerprint_server_sdk.models.event_update import EventUpdate from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot +from fingerprint_server_sdk.models.search_events_bot_info import SearchEventsBotInfo +from fingerprint_server_sdk.models.search_events_end_parameter import SearchEventsEndParameter from fingerprint_server_sdk.models.search_events_incremental_identification_status import ( SearchEventsIncrementalIdentificationStatus, ) @@ -28,6 +34,7 @@ SearchEventsRareDevicePercentileBucket, ) from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform +from fingerprint_server_sdk.models.search_events_start_parameter import SearchEventsStartParameter from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk.rest import RESTResponseType @@ -64,9 +71,9 @@ def delete_visitor_data( _content_type: Optional[StrictStr] = None, _headers: Optional[dict[StrictStr, Any]] = None, ) -> None: - """Delete data by visitor ID + """Delete a visitor ID - Request deleting all data associated with the specified visitor ID. This API is useful for compliance with privacy regulations. ### Which data is deleted? - Browser (or device) properties - Identification requests made from this browser (or device) #### Browser (or device) properties - Represents the data that Fingerprint collected from this specific browser (or device) and everything inferred and derived from it. - Upon request to delete, this data is deleted asynchronously (typically within a few minutes) and it will no longer be used to identify this browser (or device) for your [Fingerprint Workspace](https://docs.fingerprint.com/docs/glossary#fingerprint-workspace). #### Identification requests made from this browser (or device) - Fingerprint stores the identification requests made from a browser (or device) for up to 30 (or 90) days depending on your plan. To learn more, see [Data Retention](https://docs.fingerprint.com/docs/regions#data-retention). - Upon request to delete, the identification requests that were made by this browser - Within the past 10 days are deleted within 24 hrs. - Outside of 10 days are allowed to purge as per your data retention period. ### Corollary After requesting to delete a visitor ID, - If the same browser (or device) requests to identify, it will receive a different visitor ID. - If you request [`/v4/events` API](https://docs.fingerprint.com/reference/server-api-v4-get-event) with an `event_id` that was made outside of the 10 days, you will still receive a valid response. ### Interested? Please [contact our support team](https://fingerprint.com/support/) to enable it for you. Otherwise, you will receive a 403. + Use this API to request the deletion of all data associated with a specific visitor ID. Upon a request to delete data for a visitor ID, - The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID. - The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. - The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention). The following timeline illustrates which events are deleted and which remain after a DELETE API request: ``` Day 1: First visit from browser A. (Assigned visitor ID: VID1000) Day 2: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 14: Delete VID1000 Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999) Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted) Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available) ``` ### Availability This API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/). ### Rate limits and daily quota The rate limits and daily quota for this API **differ** from those for our other API. The maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD. You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). :param visitor_id: The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete. (required) :type visitor_id: str @@ -128,9 +135,9 @@ def delete_visitor_data_with_http_info( _content_type: Optional[StrictStr] = None, _headers: Optional[dict[StrictStr, Any]] = None, ) -> ApiResponse[None]: - """Delete data by visitor ID + """Delete a visitor ID - Request deleting all data associated with the specified visitor ID. This API is useful for compliance with privacy regulations. ### Which data is deleted? - Browser (or device) properties - Identification requests made from this browser (or device) #### Browser (or device) properties - Represents the data that Fingerprint collected from this specific browser (or device) and everything inferred and derived from it. - Upon request to delete, this data is deleted asynchronously (typically within a few minutes) and it will no longer be used to identify this browser (or device) for your [Fingerprint Workspace](https://docs.fingerprint.com/docs/glossary#fingerprint-workspace). #### Identification requests made from this browser (or device) - Fingerprint stores the identification requests made from a browser (or device) for up to 30 (or 90) days depending on your plan. To learn more, see [Data Retention](https://docs.fingerprint.com/docs/regions#data-retention). - Upon request to delete, the identification requests that were made by this browser - Within the past 10 days are deleted within 24 hrs. - Outside of 10 days are allowed to purge as per your data retention period. ### Corollary After requesting to delete a visitor ID, - If the same browser (or device) requests to identify, it will receive a different visitor ID. - If you request [`/v4/events` API](https://docs.fingerprint.com/reference/server-api-v4-get-event) with an `event_id` that was made outside of the 10 days, you will still receive a valid response. ### Interested? Please [contact our support team](https://fingerprint.com/support/) to enable it for you. Otherwise, you will receive a 403. + Use this API to request the deletion of all data associated with a specific visitor ID. Upon a request to delete data for a visitor ID, - The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID. - The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. - The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention). The following timeline illustrates which events are deleted and which remain after a DELETE API request: ``` Day 1: First visit from browser A. (Assigned visitor ID: VID1000) Day 2: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 14: Delete VID1000 Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999) Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted) Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available) ``` ### Availability This API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/). ### Rate limits and daily quota The rate limits and daily quota for this API **differ** from those for our other API. The maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD. You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). :param visitor_id: The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete. (required) :type visitor_id: str @@ -192,9 +199,9 @@ def delete_visitor_data_without_preload_content( _content_type: Optional[StrictStr] = None, _headers: Optional[dict[StrictStr, Any]] = None, ) -> RESTResponseType: - """Delete data by visitor ID + """Delete a visitor ID - Request deleting all data associated with the specified visitor ID. This API is useful for compliance with privacy regulations. ### Which data is deleted? - Browser (or device) properties - Identification requests made from this browser (or device) #### Browser (or device) properties - Represents the data that Fingerprint collected from this specific browser (or device) and everything inferred and derived from it. - Upon request to delete, this data is deleted asynchronously (typically within a few minutes) and it will no longer be used to identify this browser (or device) for your [Fingerprint Workspace](https://docs.fingerprint.com/docs/glossary#fingerprint-workspace). #### Identification requests made from this browser (or device) - Fingerprint stores the identification requests made from a browser (or device) for up to 30 (or 90) days depending on your plan. To learn more, see [Data Retention](https://docs.fingerprint.com/docs/regions#data-retention). - Upon request to delete, the identification requests that were made by this browser - Within the past 10 days are deleted within 24 hrs. - Outside of 10 days are allowed to purge as per your data retention period. ### Corollary After requesting to delete a visitor ID, - If the same browser (or device) requests to identify, it will receive a different visitor ID. - If you request [`/v4/events` API](https://docs.fingerprint.com/reference/server-api-v4-get-event) with an `event_id` that was made outside of the 10 days, you will still receive a valid response. ### Interested? Please [contact our support team](https://fingerprint.com/support/) to enable it for you. Otherwise, you will receive a 403. + Use this API to request the deletion of all data associated with a specific visitor ID. Upon a request to delete data for a visitor ID, - The data collected from the corresponding browser (or device) will be deleted asynchronously, typically within a few minutes. This data will no longer be available to identify this browser (or device). When the same browser (or device) revisits, it will receive a new visitor ID. - The identification events made from this browser (or device) in the past 10 days are typically deleted within 24 hrs. - The identification events made from this browser (or device) outside of the 10 days will be purged as per your [data retention period](https://docs.fingerprint.com/docs/regions#data-retention). The following timeline illustrates which events are deleted and which remain after a DELETE API request: ``` Day 1: First visit from browser A. (Assigned visitor ID: VID1000) Day 2: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000) Day 14: Delete VID1000 Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999) Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days of deleting VID1000 and will have been deleted) Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 days of deleting VID1000 and is still available) ``` ### Availability This API is available only for Enterprise plans **upon request**. If you are interested, please [contact our support team](https://fingerprint.com/support/). ### Rate limits and daily quota The rate limits and daily quota for this API **differ** from those for our other API. The maximum number of DELETE requests that can be made in an hour cannot exceed 30 RPH, and the maximum number that can be made in a day cannot exceed 500 RPD. You can request an increase to these limits by contacting [our support team](https://fingerprint.com/support/). :param visitor_id: The [visitor ID](https://docs.fingerprint.com/reference/js-agent-v4-get-function#visitor_id) you want to delete. (required) :type visitor_id: str @@ -559,7 +566,7 @@ def search_events( pagination_key: Annotated[ Optional[StrictStr], Field( - description='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` ' + description='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 100 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` ' ), ] = None, visitor_id: Annotated[ @@ -580,6 +587,42 @@ def search_events( description='Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. ' ), ] = None, + bot_info: Annotated[ + Optional[SearchEventsBotInfo], + Field( + description='Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. ' + ), + ] = None, + bot_info_category: Annotated[ + Optional[list[BotInfoCategory]], + Field( + description='Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_identity: Annotated[ + Optional[list[BotInfoIdentity]], + Field( + description='Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_confidence: Annotated[ + Optional[list[BotInfoConfidence]], + Field( + description='Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_provider: Annotated[ + Optional[list[StrictStr]], + Field( + description='Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_name: Annotated[ + Optional[list[StrictStr]], + Field( + description='Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, ip_address: Annotated[ Optional[StrictStr], Field( @@ -621,21 +664,21 @@ def search_events( ), ] = None, start: Annotated[ - Optional[StrictInt], + Optional[SearchEventsStartParameter], Field( - 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. " + description="Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). 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], + Optional[SearchEventsEndParameter], Field( - 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. " + description="Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). 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='When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). ' + description='When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (newest first, descending timestamp order). ' ), ] = None, suspect: Annotated[ @@ -749,13 +792,13 @@ def search_events( 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. ' + 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. > 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/). ' ), ] = None, rare_device_percentile_bucket: Annotated[ Optional[SearchEventsRareDevicePercentileBucket], Field( - description='Filter events by Device Rarity percentile bucket. ` Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. :type bot: SearchEventsBot + :param bot_info: Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. + :type bot_info: SearchEventsBotInfo + :param bot_info_category: Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_category: List[BotInfoCategory] + :param bot_info_identity: Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_identity: List[BotInfoIdentity] + :param bot_info_confidence: Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_confidence: List[BotInfoConfidence] + :param bot_info_provider: Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_provider: List[str] + :param bot_info_name: Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_name: List[str] :param ip_address: Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 :type ip_address: str :param asn: Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response. @@ -849,11 +904,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: 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: 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: When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). + :param start: Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. + :type start: SearchEventsStartParameter + :param end: Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. + :type end: SearchEventsEndParameter + :param reverse: When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (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 @@ -891,9 +946,9 @@ 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. + :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. > 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/). :type rare_device: bool - :param rare_device_percentile_bucket: Filter events by Device Rarity percentile bucket. ` 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/). :type rare_device_percentile_bucket: SearchEventsRareDevicePercentileBucket :param proxy: Filter events by Proxy detection result. > 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 @@ -937,6 +992,12 @@ def search_events( visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, + bot_info=bot_info, + bot_info_category=bot_info_category, + bot_info_identity=bot_info_identity, + bot_info_confidence=bot_info_confidence, + bot_info_provider=bot_info_provider, + bot_info_name=bot_info_name, ip_address=ip_address, asn=asn, linked_id=linked_id, @@ -1007,7 +1068,7 @@ def search_events_with_http_info( pagination_key: Annotated[ Optional[StrictStr], Field( - description='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` ' + description='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 100 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` ' ), ] = None, visitor_id: Annotated[ @@ -1028,6 +1089,42 @@ def search_events_with_http_info( description='Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. ' ), ] = None, + bot_info: Annotated[ + Optional[SearchEventsBotInfo], + Field( + description='Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. ' + ), + ] = None, + bot_info_category: Annotated[ + Optional[list[BotInfoCategory]], + Field( + description='Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_identity: Annotated[ + Optional[list[BotInfoIdentity]], + Field( + description='Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_confidence: Annotated[ + Optional[list[BotInfoConfidence]], + Field( + description='Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_provider: Annotated[ + Optional[list[StrictStr]], + Field( + description='Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_name: Annotated[ + Optional[list[StrictStr]], + Field( + description='Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, ip_address: Annotated[ Optional[StrictStr], Field( @@ -1069,21 +1166,21 @@ def search_events_with_http_info( ), ] = None, start: Annotated[ - Optional[StrictInt], + Optional[SearchEventsStartParameter], Field( - 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. " + description="Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). 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], + Optional[SearchEventsEndParameter], Field( - 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. " + description="Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). 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='When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). ' + description='When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (newest first, descending timestamp order). ' ), ] = None, suspect: Annotated[ @@ -1197,13 +1294,13 @@ def search_events_with_http_info( 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. ' + 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. > 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/). ' ), ] = None, rare_device_percentile_bucket: Annotated[ Optional[SearchEventsRareDevicePercentileBucket], Field( - description='Filter events by Device Rarity percentile bucket. ` Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. :type bot: SearchEventsBot + :param bot_info: Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. + :type bot_info: SearchEventsBotInfo + :param bot_info_category: Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_category: List[BotInfoCategory] + :param bot_info_identity: Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_identity: List[BotInfoIdentity] + :param bot_info_confidence: Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_confidence: List[BotInfoConfidence] + :param bot_info_provider: Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_provider: List[str] + :param bot_info_name: Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_name: List[str] :param ip_address: Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 :type ip_address: str :param asn: Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response. @@ -1297,11 +1406,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: 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: 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: When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). + :param start: Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. + :type start: SearchEventsStartParameter + :param end: Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. + :type end: SearchEventsEndParameter + :param reverse: When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (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 @@ -1339,9 +1448,9 @@ 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. + :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. > 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/). :type rare_device: bool - :param rare_device_percentile_bucket: Filter events by Device Rarity percentile bucket. ` 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/). :type rare_device_percentile_bucket: SearchEventsRareDevicePercentileBucket :param proxy: Filter events by Proxy detection result. > 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 @@ -1385,6 +1494,12 @@ def search_events_with_http_info( visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, + bot_info=bot_info, + bot_info_category=bot_info_category, + bot_info_identity=bot_info_identity, + bot_info_confidence=bot_info_confidence, + bot_info_provider=bot_info_provider, + bot_info_name=bot_info_name, ip_address=ip_address, asn=asn, linked_id=linked_id, @@ -1455,7 +1570,7 @@ def search_events_without_preload_content( pagination_key: Annotated[ Optional[StrictStr], Field( - description='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` ' + description='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 100 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` ' ), ] = None, visitor_id: Annotated[ @@ -1476,6 +1591,42 @@ def search_events_without_preload_content( description='Filter events by the Bot Detection result, specifically: `all` - events where any kind of bot was detected. `good` - events where a good bot was detected. `bad` - events where a bad bot was detected. `none` - events where no bot was detected. > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. ' ), ] = None, + bot_info: Annotated[ + Optional[SearchEventsBotInfo], + Field( + description='Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. ' + ), + ] = None, + bot_info_category: Annotated[ + Optional[list[BotInfoCategory]], + Field( + description='Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_identity: Annotated[ + Optional[list[BotInfoIdentity]], + Field( + description='Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_confidence: Annotated[ + Optional[list[BotInfoConfidence]], + Field( + description='Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_provider: Annotated[ + Optional[list[StrictStr]], + Field( + description='Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, + bot_info_name: Annotated[ + Optional[list[StrictStr]], + Field( + description='Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. ' + ), + ] = None, ip_address: Annotated[ Optional[StrictStr], Field( @@ -1517,21 +1668,21 @@ def search_events_without_preload_content( ), ] = None, start: Annotated[ - Optional[StrictInt], + Optional[SearchEventsStartParameter], Field( - 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. " + description="Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). 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], + Optional[SearchEventsEndParameter], Field( - 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. " + description="Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). 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='When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). ' + description='When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (newest first, descending timestamp order). ' ), ] = None, suspect: Annotated[ @@ -1645,13 +1796,13 @@ def search_events_without_preload_content( 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. ' + 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. > 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/). ' ), ] = None, rare_device_percentile_bucket: Annotated[ Optional[SearchEventsRareDevicePercentileBucket], Field( - description='Filter events by Device Rarity percentile bucket. ` Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. :type bot: SearchEventsBot + :param bot_info: Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. + :type bot_info: SearchEventsBotInfo + :param bot_info_category: Filter events by their Bot Info Category. Multiple categories can be provided using the repeated keys syntax. For example, `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will match events with a Bot Info Category of `ai_agent` or `ai_assistant`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_category: List[BotInfoCategory] + :param bot_info_identity: Filter events by their Bot Info Identity type. Multiple identity types can be provided using the repeated keys syntax. For example, `bot_info_identity=verified&bot_info_identity=signed`, will match events with a Bot Info Identity of `verified` or `signed`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_identity: List[BotInfoIdentity] + :param bot_info_confidence: Filter events by their Bot Info Confidence. Multiple confidences can be provided using the repeated keys syntax. For example, `bot_info_confidence=high&bot_info_confidence=medium`, will match events with a Bot Info Confidence of `high` or `medium`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_confidence: List[BotInfoConfidence] + :param bot_info_provider: Filter events by their Bot Info Provider. The provider must match exactly, partial or wildcard matching is not supported. Multiple Providers can be provided using the repeated keys syntax. For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will match events with a Bot Info Provider of `OpenAI` or `AWS`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_provider: List[str] + :param bot_info_name: Filter events by their Bot Info Name. The name must match exactly, partial or wildcard matching is not supported. Multiple Names can be provided using the repeated keys syntax. For example, `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, will match events with a Bot Info Name of `ChatGPT Agent` or `Bedrock AgentCore`. Other notations like comma-separated or bracket notation are not supported. + :type bot_info_name: List[str] :param ip_address: Filter events by IP address or IP range (if CIDR notation is used). If CIDR notation is not used, a /32 for IPv4 or /128 for IPv6 is assumed. Examples of range based queries: 10.0.0.0/24, 192.168.0.1/32 :type ip_address: str :param asn: Filter events by the ASN associated with the event's IP address. This corresponds to the `ip_info.(v4|v6).asn` property in the response. @@ -1745,11 +1908,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: 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: 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: When `true`, sort events oldest first (ascending timestamp order). Default is newest first (descending timestamp order). + :param start: Include events that happened after this point (with timestamp greater than or equal the provided `start` Unix milliseconds value or RFC3339 timestamp). Defaults to 7 days ago. Setting `start` does not change `end`'s default of `now` — adjust it separately if needed. + :type start: SearchEventsStartParameter + :param end: Include events that happened before this point (with timestamp less than or equal the provided `end` Unix milliseconds value or RFC3339 timestamp). Defaults to now. Setting `end` does not change `start`'s default of `7 days ago` — adjust it separately if needed. + :type end: SearchEventsEndParameter + :param reverse: When `true`, sort events oldest first (ascending timestamp order). Defaults to `false` (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 @@ -1787,9 +1950,9 @@ 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. + :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. > 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/). :type rare_device: bool - :param rare_device_percentile_bucket: Filter events by Device Rarity percentile bucket. ` 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/). :type rare_device_percentile_bucket: SearchEventsRareDevicePercentileBucket :param proxy: Filter events by Proxy detection result. > 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 @@ -1833,6 +1996,12 @@ def search_events_without_preload_content( visitor_id=visitor_id, high_recall_id=high_recall_id, bot=bot, + bot_info=bot_info, + bot_info_category=bot_info_category, + bot_info_identity=bot_info_identity, + bot_info_confidence=bot_info_confidence, + bot_info_provider=bot_info_provider, + bot_info_name=bot_info_name, ip_address=ip_address, asn=asn, linked_id=linked_id, @@ -1894,6 +2063,12 @@ def _search_events_serialize( visitor_id: Optional[str], high_recall_id: Optional[str], bot: Optional[SearchEventsBot], + bot_info: Optional[SearchEventsBotInfo], + bot_info_category: Optional[list[BotInfoCategory]], + bot_info_identity: Optional[list[BotInfoIdentity]], + bot_info_confidence: Optional[list[BotInfoConfidence]], + bot_info_provider: Optional[list[str]], + bot_info_name: Optional[list[str]], ip_address: Optional[str], asn: Optional[str], linked_id: Optional[str], @@ -1901,8 +2076,8 @@ def _search_events_serialize( bundle_id: Optional[str], package_name: Optional[str], origin: Optional[str], - start: Optional[int], - end: Optional[int], + start: Optional[SearchEventsStartParameter], + end: Optional[SearchEventsEndParameter], reverse: Optional[bool], suspect: Optional[bool], vpn: Optional[bool], @@ -1939,6 +2114,11 @@ def _search_events_serialize( ) -> RequestSerialized: _collection_formats: dict[str, str] = { + 'bot_info_category': 'multi', + 'bot_info_identity': 'multi', + 'bot_info_confidence': 'multi', + 'bot_info_provider': 'multi', + 'bot_info_name': 'multi', 'environment': 'multi', } @@ -1972,6 +2152,30 @@ def _search_events_serialize( if bot is not None: _query_params.append(('bot', bot.value)) + # process the query parameters + if bot_info is not None: + _query_params.append(('bot_info', bot_info.value)) + + # process the query parameters + if bot_info_category is not None: + _query_params.append(('bot_info_category', bot_info_category)) + + # process the query parameters + if bot_info_identity is not None: + _query_params.append(('bot_info_identity', bot_info_identity)) + + # process the query parameters + if bot_info_confidence is not None: + _query_params.append(('bot_info_confidence', bot_info_confidence)) + + # process the query parameters + if bot_info_provider is not None: + _query_params.append(('bot_info_provider', bot_info_provider)) + + # process the query parameters + if bot_info_name is not None: + _query_params.append(('bot_info_name', bot_info_name)) + # process the query parameters if ip_address is not None: _query_params.append(('ip_address', ip_address)) @@ -2002,12 +2206,20 @@ def _search_events_serialize( # process the query parameters if start is not None: - _query_params.append(('start', start)) - + if isinstance(start, datetime): + _query_params.append(('start', start.isoformat(timespec='microseconds'))) + elif isinstance(start, date): + _query_params.append(('start', start.isoformat())) + else: + _query_params.append(('start', start)) # process the query parameters if end is not None: - _query_params.append(('end', end)) - + if isinstance(end, datetime): + _query_params.append(('end', end.isoformat(timespec='microseconds'))) + elif isinstance(end, date): + _query_params.append(('end', end.isoformat())) + else: + _query_params.append(('end', end)) # process the query parameters if reverse is not None: _query_params.append(('reverse', reverse)) diff --git a/fingerprint_server_sdk/models/__init__.py b/fingerprint_server_sdk/models/__init__.py index d452587d..74980247 100644 --- a/fingerprint_server_sdk/models/__init__.py +++ b/fingerprint_server_sdk/models/__init__.py @@ -13,6 +13,9 @@ # import models into model package from fingerprint_server_sdk.models.bot_info import BotInfo +from fingerprint_server_sdk.models.bot_info_category import BotInfoCategory +from fingerprint_server_sdk.models.bot_info_confidence import BotInfoConfidence +from fingerprint_server_sdk.models.bot_info_identity import BotInfoIdentity from fingerprint_server_sdk.models.bot_result import BotResult from fingerprint_server_sdk.models.browser_details import BrowserDetails from fingerprint_server_sdk.models.canvas import Canvas @@ -42,6 +45,7 @@ ) from fingerprint_server_sdk.models.integration import Integration from fingerprint_server_sdk.models.integration_subintegration import IntegrationSubintegration +from fingerprint_server_sdk.models.labels_inner import LabelsInner from fingerprint_server_sdk.models.plugins_inner import PluginsInner from fingerprint_server_sdk.models.plugins_inner_mime_types_inner import PluginsInnerMimeTypesInner from fingerprint_server_sdk.models.proximity import Proximity @@ -54,6 +58,8 @@ from fingerprint_server_sdk.models.rule_action_type import RuleActionType from fingerprint_server_sdk.models.sdk import SDK from fingerprint_server_sdk.models.search_events_bot import SearchEventsBot +from fingerprint_server_sdk.models.search_events_bot_info import SearchEventsBotInfo +from fingerprint_server_sdk.models.search_events_end_parameter import SearchEventsEndParameter from fingerprint_server_sdk.models.search_events_incremental_identification_status import ( SearchEventsIncrementalIdentificationStatus, ) @@ -61,6 +67,7 @@ SearchEventsRareDevicePercentileBucket, ) from fingerprint_server_sdk.models.search_events_sdk_platform import SearchEventsSdkPlatform +from fingerprint_server_sdk.models.search_events_start_parameter import SearchEventsStartParameter from fingerprint_server_sdk.models.search_events_vpn_confidence import SearchEventsVpnConfidence from fingerprint_server_sdk.models.supplementary_id_high_recall import SupplementaryIDHighRecall from fingerprint_server_sdk.models.tampering_confidence import TamperingConfidence diff --git a/fingerprint_server_sdk/models/bot_info.py b/fingerprint_server_sdk/models/bot_info.py index f3d10232..f2714d8d 100644 --- a/fingerprint_server_sdk/models/bot_info.py +++ b/fingerprint_server_sdk/models/bot_info.py @@ -17,25 +17,27 @@ import re # noqa: F401 from typing import Any, ClassVar, Optional -from pydantic import BaseModel, ConfigDict, Field, StrictStr, field_validator +from pydantic import BaseModel, ConfigDict, Field, StrictStr from typing_extensions import Self +from fingerprint_server_sdk.models.bot_info_category import BotInfoCategory +from fingerprint_server_sdk.models.bot_info_confidence import BotInfoConfidence +from fingerprint_server_sdk.models.bot_info_identity import BotInfoIdentity + class BotInfo(BaseModel): """ Extended bot information. """ - category: StrictStr = Field(description='The type and purpose of the bot.') + category: BotInfoCategory provider: StrictStr = Field(description='The organization or company operating the bot.') provider_url: Optional[StrictStr] = Field( default=None, description="The URL of the bot provider's website." ) name: StrictStr = Field(description='The specific name or identifier of the bot.') - identity: StrictStr = Field( - description="The verification status of the bot's identity: * `verified` - well-known bot with publicly verifiable identity, directed by the bot provider. * `signed` - bot that signs its platform via Web Bot Auth, directed by the bot provider’s customers. * `spoofed` - bot that claims a public identity but fails verification. * `unknown` - bot that does not publish a verifiable identity. " - ) - confidence: StrictStr = Field(description='Confidence level of the bot identification.') + identity: BotInfoIdentity + confidence: BotInfoConfidence __properties: ClassVar[list[str]] = [ 'category', 'provider', @@ -45,22 +47,6 @@ class BotInfo(BaseModel): 'confidence', ] - @field_validator('identity') - def identity_validate_enum(cls, value: Any) -> Any: - """Validates the enum""" - if value not in set(['verified', 'signed', 'spoofed', 'unknown']): - raise ValueError( - "must be one of enum values ('verified', 'signed', 'spoofed', 'unknown')" - ) - return value - - @field_validator('confidence') - def confidence_validate_enum(cls, value: Any) -> Any: - """Validates the enum""" - if value not in set(['low', 'medium', 'high']): - raise ValueError("must be one of enum values ('low', 'medium', 'high')") - return value - model_config = ConfigDict( populate_by_name=True, validate_assignment=True, diff --git a/fingerprint_server_sdk/models/bot_info_category.py b/fingerprint_server_sdk/models/bot_info_category.py new file mode 100644 index 00000000..048bff29 --- /dev/null +++ b/fingerprint_server_sdk/models/bot_info_category.py @@ -0,0 +1,49 @@ +""" +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 BotInfoCategory(str, Enum): + """ + The type and purpose of the bot. + """ + + """ + allowed enum values + """ + ADVERTISING_AND_MARKETING = 'advertising_and_marketing' + AGGREGATOR = 'aggregator' + AI_AGENT = 'ai_agent' + AI_ASSISTANT = 'ai_assistant' + AI_BROWSER = 'ai_browser' + AI_CRAWLER = 'ai_crawler' + AI_SEARCH = 'ai_search' + BROWSER_AUTOMATION = 'browser_automation' + ECOMMERCE = 'ecommerce' + MONITORING_AND_ANALYTICS = 'monitoring_and_analytics' + OTHER = 'other' + SCRAPING = 'scraping' + SECURITY = 'security' + SEARCH_ENGINE_CRAWLER = 'search_engine_crawler' + SEARCH_ENGINE_OPTIMIZATION = 'search_engine_optimization' + UNKNOWN = 'unknown' + + @classmethod + def from_json(cls, json_str: str) -> Self: + """Create an instance of BotInfoCategory from a JSON string""" + return cls(json.loads(json_str)) diff --git a/fingerprint_server_sdk/models/bot_info_confidence.py b/fingerprint_server_sdk/models/bot_info_confidence.py new file mode 100644 index 00000000..84668e2e --- /dev/null +++ b/fingerprint_server_sdk/models/bot_info_confidence.py @@ -0,0 +1,36 @@ +""" +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 BotInfoConfidence(str, Enum): + """ + Confidence level of the bot identification. + """ + + """ + allowed enum values + """ + LOW = 'low' + MEDIUM = 'medium' + HIGH = 'high' + + @classmethod + def from_json(cls, json_str: str) -> Self: + """Create an instance of BotInfoConfidence from a JSON string""" + return cls(json.loads(json_str)) diff --git a/fingerprint_server_sdk/models/bot_info_identity.py b/fingerprint_server_sdk/models/bot_info_identity.py new file mode 100644 index 00000000..38f88951 --- /dev/null +++ b/fingerprint_server_sdk/models/bot_info_identity.py @@ -0,0 +1,37 @@ +""" +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 BotInfoIdentity(str, Enum): + """ + The verification status of the bot's identity: * `verified` - well-known bot with publicly verifiable identity, directed by the bot provider. * `signed` - bot that signs its platform via Web Bot Auth, directed by the bot provider's customers. * `spoofed` - bot that claims a public identity but fails verification. * `unknown` - bot that does not publish a verifiable identity. + """ + + """ + allowed enum values + """ + VERIFIED = 'verified' + SIGNED = 'signed' + SPOOFED = 'spoofed' + UNKNOWN = 'unknown' + + @classmethod + def from_json(cls, json_str: str) -> Self: + """Create an instance of BotInfoIdentity from a JSON string""" + return cls(json.loads(json_str)) diff --git a/fingerprint_server_sdk/models/event.py b/fingerprint_server_sdk/models/event.py index 2b357aab..9936ad9a 100644 --- a/fingerprint_server_sdk/models/event.py +++ b/fingerprint_server_sdk/models/event.py @@ -30,6 +30,7 @@ ) from fingerprint_server_sdk.models.ip_block_list import IPBlockList from fingerprint_server_sdk.models.ip_info import IPInfo +from fingerprint_server_sdk.models.labels_inner import LabelsInner 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 @@ -114,7 +115,7 @@ class Event(BaseModel): ) developer_tools: Optional[StrictBool] = Field( default=None, - description='`true` if the browser is Chrome with DevTools open or Firefox with Developer Tools open, `false` otherwise. ', + description='`true` if the browser has DevTools open (Chrome, Firefox) or the Android/iOS device has Developer Tools enabled, `false` otherwise. ', ) emulator: Optional[StrictBool] = Field( default=None, @@ -143,7 +144,7 @@ class Event(BaseModel): ] ] = 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 ', + 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. 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/). ', ) incognito: Optional[StrictBool] = Field( default=None, @@ -205,7 +206,7 @@ class Event(BaseModel): ] ] = Field( default=None, - description='Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `virtual_machine` detection result ', + description='Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in the positive `virtual_machine` detection result. 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/). ', ) vpn: Optional[StrictBool] = Field( default=None, @@ -230,6 +231,10 @@ class Event(BaseModel): ) rare_device_percentile_bucket: Optional[RareDevicePercentileBucket] = None raw_device_attributes: Optional[RawDeviceAttributes] = None + labels: Optional[list[LabelsInner]] = Field( + default=None, + description='Each label returns a prediction (true or false) for a specific use case (label field) based on a machine learning score. The machine learning score is determined by a model trained on customer data for that use case. This field is in the beta phase and only available to select customers. If you are interested, please [contact our support team](https://fingerprint.com/support/). ', + ) __properties: ClassVar[list[str]] = [ 'event_id', 'timestamp', @@ -289,6 +294,7 @@ class Event(BaseModel): 'rare_device', 'rare_device_percentile_bucket', 'raw_device_attributes', + 'labels', ] model_config = ConfigDict( @@ -370,6 +376,13 @@ def to_dict(self) -> dict[str, Any]: # override the default output from pydantic by calling `to_dict()` of raw_device_attributes if self.raw_device_attributes: _dict['raw_device_attributes'] = self.raw_device_attributes.to_dict() + # override the default output from pydantic by calling `to_dict()` of each item in labels (list) + _items = [] + if self.labels: + for _item_labels in self.labels: + if _item_labels: + _items.append(_item_labels.to_dict()) + _dict['labels'] = _items return _dict @classmethod @@ -471,6 +484,9 @@ def from_dict(cls, obj: Optional[dict[str, Any]]) -> Optional[Self]: ) if obj.get('raw_device_attributes') is not None else None, + 'labels': [LabelsInner.from_dict(_item) for _item in obj['labels']] + if obj.get('labels') is not None + else None, } ) return _obj diff --git a/fingerprint_server_sdk/models/incremental_identification_status.py b/fingerprint_server_sdk/models/incremental_identification_status.py index 81060b60..40a52686 100644 --- a/fingerprint_server_sdk/models/incremental_identification_status.py +++ b/fingerprint_server_sdk/models/incremental_identification_status.py @@ -20,7 +20,7 @@ class IncrementalIdentificationStatus(str, Enum): """ - Only included for requests using incremental identification. - `partially_completed` - the event did not receive the second \"update\" request. - `completed` - the event was updated and all information is available. + Only included for requests using incremental identification. - `partially_completed` - Indicates this event corresponds to a 'minimal' request. Smart Signals, even if included in your plan, are not computed; hence, their values must be ignored. - `completed` - Indicates this event corresponds to a 'complete' request. Smart Signals, if included in your plan, are computed; hence, their values are valid and relevant. """ """ diff --git a/fingerprint_server_sdk/models/labels_inner.py b/fingerprint_server_sdk/models/labels_inner.py new file mode 100644 index 00000000..0e953611 --- /dev/null +++ b/fingerprint_server_sdk/models/labels_inner.py @@ -0,0 +1,94 @@ +""" +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 +import pprint +import re # noqa: F401 +from typing import Annotated, Any, ClassVar, Optional, Union + +from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictStr +from typing_extensions import Self + + +class LabelsInner(BaseModel): + """ + LabelsInner + """ + + label: Optional[StrictStr] = None + prediction: Optional[StrictBool] = None + ml_score: Optional[ + Union[ + Annotated[float, Field(le=1, strict=True, ge=0)], + Annotated[int, Field(le=1, strict=True, ge=0)], + ] + ] = None + __properties: ClassVar[list[str]] = ['label', 'prediction', 'ml_score'] + + model_config = ConfigDict( + populate_by_name=True, + validate_assignment=True, + protected_namespaces=(), + ) + + def to_str(self) -> str: + """Returns the string representation of the model using alias""" + return pprint.pformat(self.model_dump(by_alias=True)) + + def to_json(self) -> str: + """Returns the JSON representation of the model using alias""" + # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead + return json.dumps(self.to_dict()) + + @classmethod + def from_json(cls, json_str: str) -> Optional[Self]: + """Create an instance of LabelsInner from a JSON string""" + return cls.from_dict(json.loads(json_str)) + + def to_dict(self) -> dict[str, Any]: + """Return the dictionary representation of the model using alias. + + This has the following differences from calling pydantic's + `self.model_dump(by_alias=True)`: + + * `None` is only added to the output dict for nullable fields that + were set at model initialization. Other fields with value `None` + are ignored. + """ + excluded_fields: set[str] = set([]) + + _dict = self.model_dump( + by_alias=True, + exclude=excluded_fields, + exclude_none=True, + ) + return _dict + + @classmethod + def from_dict(cls, obj: Optional[dict[str, Any]]) -> Optional[Self]: + """Create an instance of LabelsInner from a dict""" + if obj is None: + return None + + if not isinstance(obj, dict): + return cls.model_validate(obj) + + _obj = cls.model_validate( + { + 'label': obj.get('label'), + 'prediction': obj.get('prediction'), + 'ml_score': obj.get('ml_score'), + } + ) + return _obj diff --git a/fingerprint_server_sdk/models/search_events_bot_info.py b/fingerprint_server_sdk/models/search_events_bot_info.py new file mode 100644 index 00000000..97cddc4b --- /dev/null +++ b/fingerprint_server_sdk/models/search_events_bot_info.py @@ -0,0 +1,35 @@ +""" +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 SearchEventsBotInfo(str, Enum): + """ + Filter events by their Bot Info result, specifically: - `all` - events where any kind of bot was detected. - `none` - events where no bot was detected. + """ + + """ + allowed enum values + """ + ALL = 'all' + NONE = 'none' + + @classmethod + def from_json(cls, json_str: str) -> Self: + """Create an instance of SearchEventsBotInfo from a JSON string""" + return cls(json.loads(json_str)) diff --git a/fingerprint_server_sdk/models/search_events_end_parameter.py b/fingerprint_server_sdk/models/search_events_end_parameter.py new file mode 100644 index 00000000..f6e07dd2 --- /dev/null +++ b/fingerprint_server_sdk/models/search_events_end_parameter.py @@ -0,0 +1,17 @@ +""" +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 typing import Union + +from pydantic import AwareDatetime + +SearchEventsEndParameter = Union[int, AwareDatetime] 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 index 2f82f365..5984862e 100644 --- a/fingerprint_server_sdk/models/search_events_rare_device_percentile_bucket.py +++ b/fingerprint_server_sdk/models/search_events_rare_device_percentile_bucket.py @@ -20,7 +20,7 @@ class SearchEventsRareDevicePercentileBucket(str, Enum): """ - Filter events by Device Rarity percentile bucket. ` 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/). """ """ diff --git a/fingerprint_server_sdk/models/search_events_start_parameter.py b/fingerprint_server_sdk/models/search_events_start_parameter.py new file mode 100644 index 00000000..7004b67c --- /dev/null +++ b/fingerprint_server_sdk/models/search_events_start_parameter.py @@ -0,0 +1,17 @@ +""" +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 typing import Union + +from pydantic import AwareDatetime + +SearchEventsStartParameter = Union[int, AwareDatetime] diff --git a/res/fingerprint-server-api.yaml b/res/fingerprint-server-api.yaml index 9ac62608..037e39f3 100644 --- a/res/fingerprint-server-api.yaml +++ b/res/fingerprint-server-api.yaml @@ -270,7 +270,7 @@ paths: `pagination_key` parameter to get the next page of results: - 1. First request, returning most recent 200 events: `GET + 1. First request, returning most recent 100 events: `GET api-base-url/events?limit=100` 2. Use `response.pagination_key` to get the next page of results: @@ -317,6 +317,99 @@ paths: > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. + - name: bot_info + in: query + schema: + $ref: '#/components/schemas/SearchEventsBotInfo' + description: | + Filter events by their Bot Info result, specifically: + - `all` - events where any kind of bot was detected. + - `none` - events where no bot was detected. + - name: bot_info_category + in: query + style: form + schema: + type: array + items: + $ref: '#/components/schemas/BotInfoCategory' + description: > + Filter events by their Bot Info Category. + + + Multiple categories can be provided using the repeated keys syntax. + For example, + `bot_info_category=ai_agent&bot_info_category=ai_assistant`, will + match events with a Bot Info Category of `ai_agent` or + `ai_assistant`. Other notations like comma-separated or bracket + notation are not supported. + - name: bot_info_identity + in: query + style: form + schema: + type: array + items: + $ref: '#/components/schemas/BotInfoIdentity' + description: > + Filter events by their Bot Info Identity type. + + + Multiple identity types can be provided using the repeated keys + syntax. For example, + `bot_info_identity=verified&bot_info_identity=signed`, will match + events with a Bot Info Identity of `verified` or `signed`. Other + notations like comma-separated or bracket notation are not + supported. + - name: bot_info_confidence + in: query + style: form + schema: + type: array + items: + $ref: '#/components/schemas/BotInfoConfidence' + description: > + Filter events by their Bot Info Confidence. + + + Multiple confidences can be provided using the repeated keys syntax. + For example, `bot_info_confidence=high&bot_info_confidence=medium`, + will match events with a Bot Info Confidence of `high` or `medium`. + Other notations like comma-separated or bracket notation are not + supported. + - name: bot_info_provider + in: query + style: form + schema: + type: array + items: + type: string + description: > + Filter events by their Bot Info Provider. The provider must match + exactly, partial or wildcard matching is not supported. + + + Multiple Providers can be provided using the repeated keys syntax. + For example, `bot_info_provider=OpenAI&bot_info_provider=AWS`, will + match events with a Bot Info Provider of `OpenAI` or `AWS`. Other + notations like comma-separated or bracket notation are not + supported. + - name: bot_info_name + in: query + style: form + schema: + type: array + items: + type: string + description: > + Filter events by their Bot Info Name. The name must match exactly, + partial or wildcard matching is not supported. + + + Multiple Names can be provided using the repeated keys syntax. For + example, + `bot_info_name=ChatGPT%20Agent&bot_info_name=Bedrock%20AgentCore`, + will match events with a Bot Info Name of `ChatGPT Agent` or + `Bedrock AgentCore`. Other notations like comma-separated or bracket + notation are not supported. - name: ip_address in: query schema: @@ -379,32 +472,41 @@ paths: - name: start in: query schema: - type: integer - format: int64 - example: 1767225600000 + oneOf: + - type: integer + format: int64 + example: 1767225600000 + - type: string + format: date-time + example: '2026-01-01T00:00:00Z' 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. + greater than or equal the provided `start` Unix milliseconds value + or RFC3339 timestamp). 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 + oneOf: + - type: integer + format: int64 + example: 1769903999000 + - type: string + format: date-time + example: '2026-01-31T23:59:59Z' 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. + than or equal the provided `end` Unix milliseconds value or RFC3339 + timestamp). 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: > When `true`, sort events oldest first (ascending timestamp order). - Default is newest first (descending timestamp order). + Defaults to `false` (newest first, descending timestamp order). - name: suspect in: query schema: @@ -613,18 +715,34 @@ paths: `rare_device` property set to `true` or `false` are returned. Events without a Device Rarity Smart Signal result are left out of the response. + + + > 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/). - name: rare_device_percentile_bucket in: query schema: $ref: '#/components/schemas/SearchEventsRareDevicePercentileBucket' - description: | + description: > Filter events by Device Rarity percentile bucket. + ` 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/). - name: proxy in: query schema: @@ -758,59 +876,71 @@ paths: tags: - Fingerprint operationId: deleteVisitorData - summary: Delete data by visitor ID + summary: Delete a visitor ID description: > - Request deleting all data associated with the specified visitor ID. This - API is useful for compliance with privacy regulations. + Use this API to request the deletion of all data associated with a + specific visitor ID. - ### Which data is deleted? + Upon a request to delete data for a visitor ID, - - Browser (or device) properties + - The data collected from the corresponding browser (or device) will be + deleted asynchronously, typically within a few minutes. This data will + no longer be available to identify this browser (or device). When the + same browser (or device) revisits, it will receive a new visitor ID. - - Identification requests made from this browser (or device) + - The identification events made from this browser (or device) in the + past 10 days are typically deleted within 24 hrs. + - The identification events made from this browser (or device) outside + of the 10 days will be purged as per your [data retention + period](https://docs.fingerprint.com/docs/regions#data-retention). - #### Browser (or device) properties - - Represents the data that Fingerprint collected from this specific - browser (or device) and everything inferred and derived from it. + The following timeline illustrates which events are deleted and which + remain after a DELETE API request: - - Upon request to delete, this data is deleted asynchronously (typically - within a few minutes) and it will no longer be used to identify this - browser (or device) for your [Fingerprint - Workspace](https://docs.fingerprint.com/docs/glossary#fingerprint-workspace). + ``` + Day 1: First visit from browser A. (Assigned visitor ID: VID1000) - #### Identification requests made from this browser (or device) + Day 2: Browser A revisits. (Assigned the same visitor ID: VID1000) - - Fingerprint stores the identification requests made from a browser (or - device) for up to 30 (or 90) days depending on your plan. To learn more, - see [Data - Retention](https://docs.fingerprint.com/docs/regions#data-retention). + Day 13: Browser A revisits. (Assigned the same visitor ID: VID1000) - - Upon request to delete, the identification requests that were made by - this browser - - Within the past 10 days are deleted within 24 hrs. - - Outside of 10 days are allowed to purge as per your data retention period. + Day 14: Delete VID1000 - ### Corollary + Day 15: Browser A re-visits. (Assigned a different visitor ID: VID9999) - After requesting to delete a visitor ID, + Day 15: GET /events/day-13 (Returns 404. The event is within the 10 days + of deleting VID1000 and will have been deleted) - - If the same browser (or device) requests to identify, it will receive - a different visitor ID. + Day 16: GET /events/day-2 (Returns 200. The event is outside of the 10 + days of deleting VID1000 and is still available) - - If you request [`/v4/events` - API](https://docs.fingerprint.com/reference/server-api-v4-get-event) - with an `event_id` that was made outside of the 10 days, you will still - receive a valid response. + ``` - ### Interested? + ### Availability - Please [contact our support team](https://fingerprint.com/support/) to - enable it for you. Otherwise, you will receive a 403. + This API is available only for Enterprise plans **upon request**. If you + are interested, please [contact our support + team](https://fingerprint.com/support/). + + + ### Rate limits and daily quota + + The rate limits and daily quota for this API **differ** from those for + our other API. + + + The maximum number of DELETE requests that can be made in an hour cannot + exceed 30 RPH, and the maximum number that can be made in a day cannot + exceed 500 RPD. + + + You can request an increase to these limits by contacting [our support + team](https://fingerprint.com/support/). parameters: - name: visitor_id in: path @@ -875,10 +1005,13 @@ components: description: > Only included for requests using incremental identification. - - `partially_completed` - the event did not receive the second "update" - request. + - `partially_completed` - Indicates this event corresponds to a + 'minimal' request. Smart Signals, even if included in your plan, are not + computed; hence, their values must be ignored. - - `completed` - the event was updated and all information is available. + - `completed` - Indicates this event corresponds to a 'complete' + request. Smart Signals, if included in your plan, are computed; hence, + their values are valid and relevant. enum: - partially_completed - completed @@ -1146,6 +1279,47 @@ components: type: string description: | Additional classification of the bot type if detected. + BotInfoCategory: + type: string + enum: + - advertising_and_marketing + - aggregator + - ai_agent + - ai_assistant + - ai_browser + - ai_crawler + - ai_search + - browser_automation + - ecommerce + - monitoring_and_analytics + - other + - scraping + - security + - search_engine_crawler + - search_engine_optimization + - unknown + description: | + The type and purpose of the bot. + BotInfoIdentity: + type: string + enum: + - verified + - signed + - spoofed + - unknown + description: | + The verification status of the bot's identity: + * `verified` - well-known bot with publicly verifiable identity, directed by the bot provider. + * `signed` - bot that signs its platform via Web Bot Auth, directed by the bot provider's customers. + * `spoofed` - bot that claims a public identity but fails verification. + * `unknown` - bot that does not publish a verifiable identity. + BotInfoConfidence: + type: string + enum: + - low + - medium + - high + description: Confidence level of the bot identification. BotInfo: type: object description: Extended bot information. @@ -1157,8 +1331,7 @@ components: - confidence properties: category: - type: string - description: The type and purpose of the bot. + $ref: '#/components/schemas/BotInfoCategory' provider: type: string description: The organization or company operating the bot. @@ -1169,25 +1342,9 @@ components: type: string description: The specific name or identifier of the bot. identity: - type: string - enum: - - verified - - signed - - spoofed - - unknown - description: | - The verification status of the bot's identity: - * `verified` - well-known bot with publicly verifiable identity, directed by the bot provider. - * `signed` - bot that signs its platform via Web Bot Auth, directed by the bot provider’s customers. - * `spoofed` - bot that claims a public identity but fails verification. - * `unknown` - bot that does not publish a verifiable identity. + $ref: '#/components/schemas/BotInfoIdentity' confidence: - type: string - enum: - - low - - medium - - high - description: Confidence level of the bot identification. + $ref: '#/components/schemas/BotInfoConfidence' ClonedApp: type: boolean description: > @@ -1202,8 +1359,8 @@ components: DeveloperTools: type: boolean description: > - `true` if the browser is Chrome with DevTools open or Firefox with - Developer Tools open, `false` otherwise. + `true` if the browser has DevTools open (Chrome, Firefox) or the + Android/iOS device has Developer Tools enabled, `false` otherwise. Emulator: type: boolean description: > @@ -1402,7 +1559,9 @@ components: 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 + `proxy` detection result. 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/). Incognito: type: boolean description: > @@ -1762,10 +1921,13 @@ components: minimum: 0 maximum: 1 description: > - Machine learning–based virtual machine score, represented as a + Machine learning–based virtual machine score, represented as a floating-point value between 0 and 1 (inclusive), with up to three decimal places of precision. A higher score means a higher confidence in - the positive `virtual_machine` detection result + the positive `virtual_machine` detection result. 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/). Vpn: type: boolean description: | @@ -2194,6 +2356,27 @@ components: $ref: '#/components/schemas/FontHash' timezone_offset: $ref: '#/components/schemas/TimezoneOffset' + Labels: + type: array + items: + type: object + properties: + label: + type: string + prediction: + type: boolean + ml_score: + type: number + format: double + minimum: 0 + maximum: 1 + description: > + Each label returns a prediction (true or false) for a specific use case + (label field) based on a machine learning score. The machine learning + score is determined by a model trained on customer data for that use + case. This field is in the beta phase and only available to select + customers. If you are interested, please [contact our support + team](https://fingerprint.com/support/). Event: type: object description: >- @@ -2324,6 +2507,8 @@ components: $ref: '#/components/schemas/DeveloperTools' x-platforms: - browser + - android + - ios emulator: $ref: '#/components/schemas/Emulator' x-platforms: @@ -2494,9 +2679,15 @@ components: raw_device_attributes: $ref: '#/components/schemas/RawDeviceAttributes' x-platforms: - - android + - browser - ios + - android + labels: + $ref: '#/components/schemas/Labels' + x-platforms: - browser + - ios + - android ErrorCode: type: string enum: @@ -2645,6 +2836,15 @@ components: > Note: When using this parameter, only events with the `bot` property set to a valid value are returned. Events without a `bot` Smart Signal result are left out of the response. + SearchEventsBotInfo: + type: string + enum: + - all + - none + description: | + Filter events by their Bot Info result, specifically: + - `all` - events where any kind of bot was detected. + - `none` - events where no bot was detected. SearchEventsVpnConfidence: type: string enum: @@ -2672,14 +2872,25 @@ components: - p99.5-p99.9 - p99.9+ - not_seen - description: | + description: > Filter events by Device Rarity percentile bucket. + ` 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/). SearchEventsSdkPlatform: type: string enum: diff --git a/test/mocks/events/get_event_200.json b/test/mocks/events/get_event_200.json index f7b20849..aa38a408 100644 --- a/test/mocks/events/get_event_200.json +++ b/test/mocks/events/get_event_200.json @@ -286,5 +286,12 @@ "audio": 124.04347745512496 }, "rare_device": false, - "rare_device_percentile_bucket": "