API Endpoints
/
Subscriptions

urlscan.io APIs (1.0.0)

Introduction

API endpoints for urlscan.io and urlscan Pro. Most of these API endpoints require authentication.

The fastest way to start working with our APIs is by using one of the many existing commercial or open-source integrations.

External Resources

Download OpenAPI description
urlscan-openapi.json
urlscan-openapi.yaml
Overview
urlscan Support

support@urlscan.io

Languages
Servers

https://urlscan.io/

Generic

API endpoints related to the platform or the user account.

Operations

Scanning

These APIs allow URLs to be scanned and the results of the scans to be retrieved.

Operations

Search

The Search API allows users to search for historically website scans, hostnames, domains, TLS certificates and incidents.

Operations

Live Scanning

urlscan Pro - Live Scanning allows users to scan websites from different geographical locations and using different device settings.

See additional info about this proprietary feature on urlscan Pro.

Operations

Saved Searches

urlscan Pro - Saved Searches are rules that are executed inline against new incoming scans and hostnames.

Operations

Subscriptions

urlscan Pro - Subscriptions allow notifications for Saved Searches.

Operations

Subscriptions

Request

Get a list of Subscriptions for the current user.

Security
apikeyAuth
curl -i -X GET \
  https://urlscan.io/api/v1/user/subscriptions/ \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Create Subscription

Request

Create a new subscription.

Security
apikeyAuth
Bodyapplication/json
subscriptionobjectrequired
Example: {"_id":"{{subscriptionId}}","searchIds":["{{searchId}}"],"frequency":"daily","emailAddresses":["test@urlscan.io"],"name":"Test Subscription","description":"Subscription for testing purposes","isActive":true,"ignoreTime":false}
subscription.​_idstring

Subscription ID

Example: "{{subscriptionId}}"
subscription.​searchIdsArray of stringsrequired

Array of search IDs associated with this subscription.

Example: ["{{searchId}}"]
subscription.​frequencystringrequired

Frequency of notifications.

Enum"live""hourly""daily"
Example: "daily"
subscription.​emailAddressesArray of strings(email)required

Email addresses receiving the notifications.

Example: ["test@urlscan.io"]
subscription.​namestringrequired

Name of the subscription.

Example: "Test Subscription"
subscription.​descriptionstring

Description of the subscription.

Example: "Subscription for testing purposes"
subscription.​isActivebooleanrequired

Whether the subscription is active.

Example: true
subscription.​ignoreTimebooleanrequired

Whether to ignore time constraints.

subscription.​weekDaysArray of strings

Days of the week alerts will be generated.

Items Enum"Monday""Tuesday""Wednesday""Thursday""Friday""Saturday""Sunday"
subscription.​permissionsArray of strings
Items Enum"team:read""team:write"
subscription.​channelIdsArray of strings

Array of channel IDs associated with this subscription.

subscription.​incidentChannelIdsArray of strings

Array of incident channel IDs associated with this subscription.

subscription.​incidentProfileIdstring

Incident Profile ID associated with this subscription.

subscription.​incidentVisibilitystring

Incident visibility for this subscription.

Enum"unlisted""private"
subscription.​incidentCreationModestring

Incident creation rule for this subscription.

Enum"none""default""always""ignore-if-exists"
subscription.​incidentWatchKeysstring

Source/key to watch in the incident.

Enum"scans/page.url""scans/page.domain""scans/page.ip""scans/page.apexDomain""hostnames/hostname""hostnames/ip""hostnames/domain"
curl -i -X POST \
  https://urlscan.io/api/v1/user/subscriptions/ \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "subscription": {
      "_id": "{{subscriptionId}}",
      "searchIds": [
        "{{searchId}}"
      ],
      "frequency": "daily",
      "emailAddresses": [
        "test@urlscan.io"
      ],
      "name": "Test Subscription",
      "description": "Subscription for testing purposes",
      "isActive": true,
      "ignoreTime": false
    }
  }'

Responses

OK

Bodyapplication/json
subscriptionobject
Example: {"_id":"{{subscriptionId}}","searchIds":["{{searchId}}"],"frequency":"daily","emailAddresses":["test@urlscan.io"],"name":"Test Subscription","description":"Subscription for testing purposes","isActive":true,"ignoreTime":false}
Response
application/json
{
  "subscription": {
    "_id": "{{subscriptionId}}",
    "searchIds": [ … ],
    "frequency": "daily",
    "emailAddresses": [ … ],
    "name": "Test Subscription",
    "description": "Subscription for testing purposes",
    "isActive": true,
    "ignoreTime": false
  }
}

Update Subscription

Request

Update the settings for a subscription.

Security
apikeyAuth
Path
subscriptionIdstringrequired
Example: {{subscriptionId}}
Bodyapplication/json
subscriptionobjectrequired
Example: {"_id":"{{subscriptionId}}","searchIds":["{{searchId}}"],"frequency":"daily","emailAddresses":["test@urlscan.io"],"name":"Test Subscription","description":"Subscription for testing purposes","isActive":true,"ignoreTime":false}
subscription.​_idstring

Subscription ID

Example: "{{subscriptionId}}"
subscription.​searchIdsArray of stringsrequired

Array of search IDs associated with this subscription.

Example: ["{{searchId}}"]
subscription.​frequencystringrequired

Frequency of notifications.

Enum"live""hourly""daily"
Example: "daily"
subscription.​emailAddressesArray of strings(email)required

Email addresses receiving the notifications.

Example: ["test@urlscan.io"]
subscription.​namestringrequired

Name of the subscription.

Example: "Test Subscription"
subscription.​descriptionstring

Description of the subscription.

Example: "Subscription for testing purposes"
subscription.​isActivebooleanrequired

Whether the subscription is active.

Example: true
subscription.​ignoreTimebooleanrequired

Whether to ignore time constraints.

subscription.​weekDaysArray of strings

Days of the week alerts will be generated.

Items Enum"Monday""Tuesday""Wednesday""Thursday""Friday""Saturday""Sunday"
subscription.​permissionsArray of strings
Items Enum"team:read""team:write"
subscription.​channelIdsArray of strings

Array of channel IDs associated with this subscription.

subscription.​incidentChannelIdsArray of strings

Array of incident channel IDs associated with this subscription.

subscription.​incidentProfileIdstring

Incident Profile ID associated with this subscription.

subscription.​incidentVisibilitystring

Incident visibility for this subscription.

Enum"unlisted""private"
subscription.​incidentCreationModestring

Incident creation rule for this subscription.

Enum"none""default""always""ignore-if-exists"
subscription.​incidentWatchKeysstring

Source/key to watch in the incident.

Enum"scans/page.url""scans/page.domain""scans/page.ip""scans/page.apexDomain""hostnames/hostname""hostnames/ip""hostnames/domain"
curl -i -X PUT \
  'https://urlscan.io/api/v1/user/subscriptions/{{subscriptionId}}/' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "subscription": {
      "_id": "{{subscriptionId}}",
      "searchIds": [
        "{{searchId}}"
      ],
      "frequency": "daily",
      "emailAddresses": [
        "test@urlscan.io"
      ],
      "name": "Test Subscription",
      "description": "Subscription for testing purposes",
      "isActive": true,
      "ignoreTime": false
    }
  }'

Responses

OK

Bodyapplication/json
subscriptionobject
Example: {"_id":"{{subscriptionId}}","searchIds":["{{searchId}}"],"frequency":"daily","emailAddresses":["test@urlscan.io"],"name":"Test Subscription","description":"Subscription for testing purposes","isActive":true,"ignoreTime":false}
Response
application/json
{
  "subscription": {
    "_id": "{{subscriptionId}}",
    "searchIds": [ … ],
    "frequency": "daily",
    "emailAddresses": [ … ],
    "name": "Test Subscription",
    "description": "Subscription for testing purposes",
    "isActive": true,
    "ignoreTime": false
  }
}

Delete Subscription

Request

Delete a subscription.

Security
apikeyAuth
Path
subscriptionIdstringrequired
Example: {{subscriptionId}}
curl -i -X DELETE \
  'https://urlscan.io/api/v1/user/subscriptions/{{subscriptionId}}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
object
Response
application/json
{}

Subscription Search Results

Request

Get the search results for a specific subscription and datasource.

Security
apikeyAuth
Path
subscriptionIdstringrequired
datasourcestringrequired
Example: scans
curl -i -X GET \
  'https://urlscan.io/api/v1/user/subscriptions/{subscriptionId}/results/scans/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK - This endpoint always responds with HTTP/302

Hostnames

urlscan Pro - Historical information on hostnames and domains

Operations

Brands

urlscan Pro - Information about tracked brands

Operations

Files

urlscan Pro - Downloaded files

Operations

Incidents

urlscan Pro - Incidents track observables, like hostnames and domains, and automatically scan and alert on changes.

Operations

Channels

Operations