Web Pre-Malicious URLs API

The Web Pre-Malicious URLs API returns your brand's pre-malicious URLs from the Bolster platform for a date range. It covers the same URLs you see in the Pre-Malicious table of the Web module: suspicious URLs and lookalike domains that are being monitored and are not currently phish or scam.

Important Notes

• A URL is returned when it was first seen within your date range.
• Results cover the brands your API key has access to, the same as what you see on the platform.
• A single request returns at most 10,000 URLs. The total field always shows how many URLs matched. If total is more than 10,000, narrow your date range and make several smaller requests.
• All dates and times are in UTC. Dates without a time zone offset are read as UTC, and dates with an offset are converted to UTC.
• Results are sorted by first seen time, newest first.
• Responses can be large. We recommend requesting a compressed response by sending the Accept-Encoding: gzip header (--compressed in curl).

Step 1: Locate Your API Key

Before using the Web Pre-Malicious URLs API, you need your Bolster API key. Follow these steps to find it:

1. Click on the user dropdown in the top-right corner of the page.
2. Select Profile Information from the dropdown menu.
3. Copy the API key displayed on your profile screen.

Step 2: Initiate Request Through API

Endpoint:

/api/web/v1/pre-malicious-urls

API Host:

https://developers.bolster.ai

To make a request, use the following details.

Request Format

curl --compressed --location 'https://developers.bolster.ai/api/web/v1/pre-malicious-urls' \
--header 'Content-Type: application/json' \
--data '{
  "apiKey": "<your_api_key>",
  "startDate": "1970-01-01T00:00:00Z",
  "endDate": "1970-01-31T23:59:59Z"
}'

To only get URLs with a specific current disposition, add the optional disposition field:

curl --compressed --location 'https://developers.bolster.ai/api/web/v1/pre-malicious-urls' \
--header 'Content-Type: application/json' \
--data '{
  "apiKey": "<your_api_key>",
  "startDate": "1970-01-01T00:00:00Z",
  "endDate": "1970-01-31T23:59:59Z",
  "disposition": ["suspicious"]
}'

Request Parameters

• apiKey (required): Your user API key.
• startDate (required): Start of the date range, inclusive. ISO 8601 date and time, for example 1970-01-01T00:00:00Z.
• endDate (required): End of the date range, inclusive to the second. ISO 8601 date and time, for example 1970-01-31T23:59:59Z. Must not be earlier than startDate.
• disposition (optional): Only return URLs whose current disposition (currentDisposition in the response) is one of these values. An array with one or more of: suspicious, clean. When omitted, URLs of every disposition are returned.

Date Format

Both dates need a date and a time. A date on its own, such as 1970-01-01, is not accepted. Milliseconds and a time zone offset are optional:

Response

The API returns the matching URLs along with the total number of matches.

Response Fields

Per-URL Fields

Each object in the urls array contains the following fields. Every field is always present; fields with no value are returned as null.

Successful Response (Status Code: 200)

The following example shows one suspicious URL and one lookalike domain:

{
  "total": 2,
  "urls": [
    {
      "srcUrl": "http://example-account-verify.com/",
      "dstUrl": "https://example-account-verify.com/signin",
      "currentDisposition": "suspicious",
      "firstSeenTs": "1970-01-20T09:12:44.512Z",
      "insightsUrl": "https://platform.bolster.ai/web/insights/1675200000/4f1c2e8a9b7d6c5e3a2f1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e"
    },
    {
      "srcUrl": "http://examp1e.com/",
      "dstUrl": "http://examp1e.com/",
      "currentDisposition": "clean",
      "firstSeenTs": "1970-01-12T14:30:05.218Z",
      "insightsUrl": "https://platform.bolster.ai/web/insights/1036800000/9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d"
    }
  ]
}

Error Responses

If the request is invalid, the API returns an error response and no URLs.

Status Code: 401

{
  "error": {
    "statusCode": 401,
    "name": "Error",
    "message": "Invalid API key or API key not enabled."
  }
}

Status Code: 400

The following 400 errors may be returned:

Missing parameter:

{
  "error": {
    "statusCode": 400,
    "name": "Error",
    "message": "startDate is a required argument"
  }
}

Invalid date:

{
  "error": {
    "statusCode": 400,
    "name": "Error",
    "message": "startDate must be an ISO 8601 date-time such as 1970-01-01T00:00:00Z"
  }
}

Start date after end date:

{
  "error": {
    "statusCode": 400,
    "name": "Error",
    "message": "startDate must not be after endDate"
  }
}

Invalid disposition:

{
  "error": {
    "statusCode": 400,
    "name": "Error",
    "message": "disposition must be a non-empty array of: phish, scam, suspicious, clean"
  }
}

Support

If you have any questions or encounter any issues while using the Web Pre-Malicious URLs API, please
contact our support team at [email protected].