API Endpoints
/
Live Scanning

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

http://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

Live Scanners

Request

API Endpoint to a list of available Live Scanning nodes along with their current metadata.

Security
apikeyAuth
curl -i -X GET \
  http://urlscan.io/api/v1/livescan/scanners/ \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Non-Blocking Trigger Live Scan

Request

Task a URL to be scanned. The HTTP request will return with the scan UUID immediately and then it is your responsibility to poll the result resource type until the scan has finished.

Security
apikeyAuth
Path
scannerIdstringrequired
Example: {{livescanner}}
Bodyapplication/json
taskobject
scannerobject
curl -i -X POST \
  'http://urlscan.io/api/v1/livescan/{{livescanner}}/task/' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "task": {
      "url": "http://example.com",
      "visibility": "public"
    },
    "scanner": {
      "pageTimeout": 0,
      "captureDelay": 0,
      "extraHeaders": {},
      "enableFeatures": [],
      "disableFeatures": []
    }
  }'

Responses

OK

Bodyapplication/json
uuidstring(uuid)

UUID of scan

Response
application/json
{
  "uuid": "92d683cd-1575-4bde-89d1-99cd46ae07a7"
}

Trigger Live Scan

Request

Task a URL to be scanned. The HTTP request will block until the scan has finished.

Security
apikeyAuth
Path
scannerIdstringrequired
Example: {{livescanner}}
Bodyapplication/json
taskobject
scannerobject
curl -i -X POST \
  'http://urlscan.io/api/v1/livescan/{{livescanner}}/scan/' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "task": {
      "url": "http://example.com",
      "visibility": "public"
    },
    "scanner": {
      "pageTimeout": 0,
      "captureDelay": 0,
      "extraHeaders": {},
      "enableFeatures": [],
      "disableFeatures": []
    }
  }'

Responses

OK

Bodyapplication/json
uuidstring(uuid)

UUID of scan

Response
application/json
{
  "uuid": "10dae531-a98a-42fc-8c6f-cb8610ec0c10"
}

Live Scan Get Resource

Request

Get the historical observations for a specific hostname in the "Hostnames" data source.

Security
apikeyAuth
Path
scannerIdstringrequired
Example: de01
resourceTypestringrequired
Enum"result""screenshot""dom""response""download"
Example: result
resourceIdstringrequired
  • For result, screenshot, dom: UUID of the scan
  • For response, download: The SHA256 of the resource
Example: {resourceId}
curl -i -X GET \
  'http://urlscan.io/api/v1/livescan/de01/result/{resourceId}' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Store Live Scan Result

Request

Store the temporary scan as a permanent snapshot on urlscan.io.

Security
apikeyAuth
Path
scannerIdstringrequired
Example: {{livescanner}}
scanIdstringrequired
Example: {{livescanId}}
Bodyapplication/json
taskobject
Example: {"visibility":"public"}
curl -i -X PUT \
  'http://urlscan.io/api/v1/livescan/{{livescanner}}/{{livescanId}}/' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "task": {
      "visibility": "public"
    }
  }'

Responses

Successful response

Purge Live Scan Result

Request

Purge temporary scan from scanner immediately. Scans will be automatically purged after 60 minutes.

Security
apikeyAuth
Path
scannerIdstringrequired
Example: {{livescanner}}
scanIdstringrequired
Example: {{livescanId}}
curl -i -X DELETE \
  'http://urlscan.io/api/v1/livescan/{{livescanner}}/{{livescanId}}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Successful response

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

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