Lookup. URL-based check

You can use this request type to check URLs against Yandex-hosted Safe Browsing lists. If the URL of the resource is found on one or more lists, the request returns data about the threat posed by the resource.

You can use one request to check multiple URLs.

  1. Request format
  2. Response format
  3. Example

Request format

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

API key value.

Query parameters
key *

API key value.

*  Required

Request body

{
  "client": {
    "clientId": "{string}",
    "clientVersion": "{string}"
  },
  "threatInfo": {
    "threatTypes": ["{enum}"],
    "platformTypes": ["{enum}"],
    "threatEntryTypes": ["{enum}"],
    "threatEntries": [
      {"url": "{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.

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. Maximum count: 500.

url *

URL in the format: http:// or https://.

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

If none of the checked URLs are found on the Safe Browsing lists, the empty response body is returned. 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": {
        "url": "{string}"
      },
      "cacheDuration": "{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.

url

URL in the format: http:// or https://.

cacheDuration

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

Required

Example

Request URL:

https://sba.yandex.net/v4/threatMatches:find?key=2f8...8ea

Request body:

{
  "client": {
    "clientId": "{client_name}",
    "clientVersion": "{1.1.1}"
  },
  "threatInfo": {
    "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes": ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"url": "http://malware-driveby.test.safebrowsing.yandex"}
    ]
  }
}

Response:

{
  "matches": [
    {
      "threatType": "MALWARE",
      "threatEntryType": "URL",
      "platformType": "WINDOWS",
      "threat": {
        "url": "http://malware-driveby.test.safebrowsing.yandex"
      },
      "cacheDuration": "1200.00s"
    }
  ]
}