Update. Hash-based check

You can use the request to see if URLs are present on Safe Browsing lists. Compute the hash prefix for the URL and search the local database. If the hash prefix is found in at least one of the lists, the request returns data about the threat posed by the URL for the user.

Note. Before searching, make sure that you completely downloaded the Safe Browsing lists you need and that the local database is up-to-date. Otherwise, use a Lookup. URL-based check request.
  1. Request format
  2. Response format
  3. Example

Request format

POST https://sba.yandex.net/v4/fullHashes:find
 ? key=<API key>
key *

API key value.

key *

API key value.

*  Required

Request body

{
  "client": {
    "clientId": "{string}",
    "clientVersion": "{string}"
  },
  "clientStates": ["{string}"],
  "threatInfo": {
    "threatTypes": ["{enum}"],
    "platformTypes": ["{enum}"],
    "threatEntryTypes": ["{enum}"],
    "threatEntries": [
      {"hash": "string"}
    ]
  }
}
client *

Safe Browsing API user data. This data is used to identify the requests made on behalf of the user.

clientId *

User name.

clientVersion *

Implementation version.

clientStates

Safe Browsing list statuses at the time of the last update. Array of objects.

The up-to-date value for each list is returned in the newClientState parameter of the Update. Update local SB database request.

threatInfo *

Safe Browsing list parameters and checked resources.

threatTypes *

Type of threat. Array of objects.

Possible values:

  • THREAT_TYPE_UNSPECIFIED: An unknown type of threat.

  • MALWARE: Malicious software.

  • SOCIAL_ENGINEERING: A threat related to social engineering.

  • UNWANTED_SOFTWARE: Unwanted software.

  • POTENTIALLY_HARMFUL_APPLICATION: An application that may pose a threat.

platformTypes *

Platform. Array of objects.

Possible values:

  • PLATFORM_TYPE_UNSPECIFIED: An unknown platform.

  • WINDOWS: A Windows operating system.

  • LINUX: A Linux operating system.

  • ANDROID: An Android operating system.

  • OSX: An OS X operating system.

  • IOS: An iOS operating system.

  • ANY_PLATFORM: At least one platform from the list.

  • ALL_PLATFORMS: All platforms.

  • CHROME: A Chrome platform.

threatEntryTypes *

The type of object that poses a threat. Array of objects.

Possible values:

  • THREAT_ENTRY_TYPE_UNSPECIFIED: The threat type is unknown.

  • URL: A URL address.

  • EXECUTABLE: An executable program.

threatEntries *

Checked resources. Array of objects.

hash *

Hash prefix.

* Required

The response format is shown below. The sequence and presence of elements is not guaranteed. The response may contain auxiliary parameters not described in this document.

Response format

The response contains detailed information about the threat posed by each of the resources found.

If none of the checked hash prefixes are found on the server-hosted Safe Browsing lists, the response body contains only the negativeCacheDuration parameter. If matches are found, the response contains detailed information about the danger posed by each of the resources found.

{
  "matches": [
    {
      "threatType": "{enum}",
      "platformType": "{enum}",
      "threatEntryType": "{enum}",
      "threat": {"hash": "{string}"},
      "cacheDuration": "{string}"
    }
  ],
  "minimumWaitDuration": "{string}",
  "negativeCacheDuration": "{string}"
}
matches

Data about the resources found on the Safe Browsing lists. Array of objects.

threatType *

Type of threat.

Possible values:

  • THREAT_TYPE_UNSPECIFIED: An unknown type of threat.

  • MALWARE: Malicious software.

  • SOCIAL_ENGINEERING: A threat related to social engineering.

  • UNWANTED_SOFTWARE: Unwanted software.

  • POTENTIALLY_HARMFUL_APPLICATION: An application that may pose a threat.

platformType *

A platform susceptible to the threat.

Possible values:

  • PLATFORM_TYPE_UNSPECIFIED: An unknown platform.

  • WINDOWS: A Windows operating system.

  • LINUX: A Linux operating system.

  • ANDROID: An Android operating system.

  • OSX: An OS X operating system.

  • IOS: An iOS operating system.

  • ANY_PLATFORM: At least one platform from the list.

  • ALL_PLATFORMS: All platforms.

  • CHROME: A Chrome platform.

threatEntryType *

The type of object that poses a threat.

Possible values:

  • THREAT_ENTRY_TYPE_UNSPECIFIED: The threat type is unknown.

  • URL: A URL address.

  • EXECUTABLE: An executable program.

threat

The resource that poses a threat.

hash

A full-length hash for the URL.

cacheDuration

The time to cache the data about the threat posed by the resource. It's specified in seconds in the format "<time>s".

minimumWaitDuration

Minimum time in seconds before re-sending the request. Specified in the format "minimumWaitDuration": "<time>s". Up to nine decimal digits are supported.

negativeCacheDuration

The time to cache data for resources not found on the local Safe Browsing lists. It's specified in seconds in the format "<time>s". During the specified time, the documents are considered safe for the user.

* Required