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.

Request format

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

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"
    }
  ]
}