urlscan.io

https://docs.urlscan.io
Admin
urlscan.io is a security service that scans and analyzes websites to detect phishing, malware, and...
Tokens:21,768
Snippets:223
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install CLI via Homebrew

Source: https://docs.urlscan.io/pages/cli-intro

Use this command to install the urlscan-cli on macOS systems.

```bash
brew install --cask urlscan/tap/urlscan-cli
```

--------------------------------

### GET /api/v1/user/channels/

Source: https://docs.urlscan.io/apis/urlscan-openapi/channels

Retrieves a list of all notification channels configured for the current user.

```APIDOC
## GET /api/v1/user/channels/

### Description
Get a list of notification channels for the current user.

### Method
GET

### Endpoint
/api/v1/user/channels/
```

--------------------------------

### GET /api/v1/user/channels/

Source: https://docs.urlscan.io/apis/urlscan-openapi/channels/listchannels

Retrieves the list of notification channels for the authenticated user.

```APIDOC
## GET /api/v1/user/channels/

### Description
Retrieves a list of all notification channels associated with the current user account.

### Method
GET

### Endpoint
/api/v1/user/channels/

### Response
#### Success Response (200)
- **channels** (array) - List of notification channels
  - **_id** (string) - Channel ID
  - **type** (string) - Type of channel, "webhook" or "email"
  - **webhookURL** (string) - Webhook URL for notifications
  - **frequency** (string) - Frequency of notifications ("live", "hourly", or "daily")
  - **emailAddresses** (array) - Email addresses receiving the notifications
  - **utcTime** (string) - 24 hour UTC time that daily emails are sent
  - **name** (string) - Name of the subscription
  - **isActive** (boolean) - Whether the channel is active
  - **isDefault** (boolean) - Whether the channel is the default
  - **ignoreTime** (boolean) - Whether to ignore time constraints
  - **weekDays** (array) - Days of the week alerts will be generated
  - **permissions** (array) - Channel permissions
```

--------------------------------

### GET /responses/{fileHash}/

Source: https://docs.urlscan.io/apis/urlscan-openapi/scanning/getresponse

Retrieves a response in plain text format by its SHA256 hash.

```APIDOC
## GET /responses/{fileHash}/

### Description
Get a (Script|Document|Fetch|XHR) response in plain text format by SHA256 hash. Note that this endpoint returns the content as text/plain.

### Method
GET

### Endpoint
/responses/{fileHash}/

### Parameters
#### Path Parameters
- **fileHash** (string) - Required - SHA256 hash of response
```

--------------------------------

### GET /downloads/{fileHash}

Source: https://docs.urlscan.io/apis/urlscan-openapi

Downloads a file by its SHA256 hash (urlscan Pro).

```APIDOC
## GET /downloads/{fileHash}

### Description
urlscan Pro - Download a file by SHA256 hash. For the ZIP files delivered by this endpoint, the default encryption password is urlscan! - including the trailing exclamation mark.

### Method
GET

### Endpoint
/downloads/{fileHash}

### Parameters
#### Path Parameters
- **fileHash** (string) - Required - The SHA256 hash of the file.
```

--------------------------------

### GET /api/v1/datadump/link/{path}

Source: https://docs.urlscan.io/apis/urlscan-openapi/data-dumps

Generate a temporary download link for a specific data dump file.

```APIDOC
## GET /api/v1/datadump/link/{path}

### Description
Generate a temporary download link for a specific data dump file. This endpoint is available for urlscan Pro users.

### Method
GET

### Endpoint
/api/v1/datadump/link/{path}

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the specific data dump file.
```

--------------------------------

### GET /api/v1/user/subscriptions/

Source: https://docs.urlscan.io/apis/urlscan-openapi/subscriptions

Retrieves a list of all subscriptions associated with the current user.

```APIDOC
## GET /api/v1/user/subscriptions/

### Description
Get a list of Subscriptions for the current user.

### Method
GET

### Endpoint
/api/v1/user/subscriptions/
```

--------------------------------

### GET /api/v1/hostname/{hostname}

Source: https://docs.urlscan.io/apis/urlscan-openapi/hostnames/gethostnamehistory

Retrieves historical observations for a specific hostname.

```APIDOC
## GET /api/v1/hostname/{hostname}

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

### Method
GET

### Endpoint
/api/v1/hostname/{hostname}

### Parameters
#### Path Parameters
- **hostname** (string) - Required - The hostname to query

#### Query Parameters
- **limit** (integer) - Optional - Return at most this many results. Minimum 10 Maximum 10000 Default 1000
- **pageState** (string) - Optional - Returns additional results starting from this page state from the previous API call.

### Response
#### Success Response (200)
- **pageState** (string) - If the pageState field is set then there are additional results available.
- **results** (array) - List of historical observations
- **results.seen_on** (string) - Date in YYYY-MM-DD format
- **results.source** (string) - The source of the observation (ct, scan, pdns, zonefile, scan-link, scan-cert-subject)
- **results.sub_id** (string) - Observation value
- **results.first_seen** (string) - First-seen timestamp, ISO8601
- **results.last_seen** (string) - Last-seen timestamp, ISO8601
- **results.data_type** (string) - Indicates if there is additional data in the data field (json)
- **results.data** (object) - Additional JSON content for this record
```

--------------------------------

### GET /api/v1/user/channels/{channelId}

Source: https://docs.urlscan.io/apis/urlscan-openapi/channels/getchannel

Retrieves the configuration and details for a specific notification channel.

```APIDOC
## GET /api/v1/user/channels/{channelId}

### Description
Get the search results for a specific notification channel.

### Method
GET

### Endpoint
/api/v1/user/channels/{channelId}

### Parameters
#### Path Parameters
- **channelId** (string) - Required - The unique identifier of the channel.

### Response
#### Success Response (200)
- **channel** (object) - The channel object containing configuration details.
- **channel._id** (string) - Channel ID
- **channel.type** (string) - Type of channel, "webhook" or "email".
- **channel.webhookURL** (string) - Frequency of notifications.
- **channel.frequency** (string) - Frequency of notifications ("live", "hourly", or "daily").
- **channel.emailAddresses** (array) - Email addresses receiving the notifications.
- **channel.utcTime** (string) - 24 hour UTC time that daily emails are sent (e.g. 09:00).
- **channel.name** (string) - Name of the subscription.
- **channel.isActive** (boolean) - Whether the channel is active.
- **channel.isDefault** (boolean) - Whether the channel is the default.
- **channel.ignoreTime** (boolean) - Whether to ignore time constraints.
- **channel.weekDays** (array) - Days of the week alerts will be generated.
- **channel.permissions** (array) - Permissions associated with the channel.

#### Response Example
{
  "channel": {
    "_id": "{{channelId}}",
    "type": "webhook",
    "webhookURL": "https://example.com/cgi-bin/urlscan",
    "name": "Test webhook",
    "description": "Webhook testing channel.",
    "isActive": true,
    "ignoreTime": false
  }
}
```

--------------------------------

### GET /api/v1/user/incidentstates/{incidentId}/

Source: https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincidentstates

Retrieve individual incident states of an incident.

```APIDOC
## GET /api/v1/user/incidentstates/{incidentId}/

### Description
Retrieve individual incident states of an incident.

### Method
GET

### Endpoint
/api/v1/user/incidentstates/{incidentId}/

### Parameters
#### Path Parameters
- **incidentId** (string) - Required - ID of incident

### Response
#### Success Response (200)
- **incidentstates** (array) - List of incident states
- **incidentstates._id** (string) - Unique ID of incident state interval
- **incidentstates.incident** (string) - ID of the incident
- **incidentstates.state** (object) - Current state of the interval
- **incidentstates.timeStart** (string) - Start time of the interval
- **incidentstates.timeEnd** (string) - End time of the interval
```

--------------------------------

### GET /api/v1/datadump/list/{timeWindow}/{fileType}/{date}

Source: https://docs.urlscan.io/apis/urlscan-openapi/data-dumps

List available data dump files for a specific time window, file type, and date.

```APIDOC
## GET /api/v1/datadump/list/{timeWindow}/{fileType}/{date}

### Description
List available data dump files for a specific time window, file type, and date. This endpoint is available for urlscan Pro users.

### Method
GET

### Endpoint
/api/v1/datadump/list/{timeWindow}/{fileType}/{date}

### Parameters
#### Path Parameters
- **timeWindow** (string) - Required - The time window for the data dump.
- **fileType** (string) - Required - The type of file to list.
- **date** (string) - Required - The date of the data dump.
```

--------------------------------

### GET /api/v1/livescan/scanners/

Source: https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/getlivescanscanners

Retrieves a list of available Live Scanning nodes along with their current metadata.

```APIDOC
## GET /api/v1/livescan/scanners/

### Description
Retrieves a list of available Live Scanning nodes along with their current metadata.

### Method
GET

### Endpoint
/api/v1/livescan/scanners/

### Security
apikeyAuth
```

--------------------------------

### GET /dom/{scanId}/

Source: https://docs.urlscan.io/apis/urlscan-openapi/scanning/getdom

Retrieves the DOM snapshot for a scan once the scan has finished.

```APIDOC
## GET /dom/{scanId}/

### Description
Use the scan UUID to retrieve the DOM snapshot for a scan once the scan has finished.

### Method
GET

### Endpoint
/dom/{scanId}/

### Parameters
#### Path Parameters
- **scanId** (string) - Required - UUID of scan result
```

--------------------------------

### GET /user/username

Source: https://docs.urlscan.io/apis/urlscan-openapi/generic/getusername

Retrieves information about the current user or API key making the request.

```APIDOC
## GET /user/username

### Description
Get information about the current user or API key making the request.

### Method
GET

### Endpoint
/user/username

### Security
- apikeyAuth
```

--------------------------------

### GET /downloads/{fileHash}

Source: https://docs.urlscan.io/apis/urlscan-openapi/files/downloadfile

Downloads a file by its SHA256 hash as an encrypted ZIP archive.

```APIDOC
## GET /downloads/{fileHash}

### Description
Download a file by SHA256 hash. The file is returned as a ZIP archive, which is encrypted by default with the password 'urlscan!'.

### Method
GET

### Endpoint
/downloads/{fileHash}

### Parameters
#### Path Parameters
- **fileHash** (string) - Required - SHA256 hash of file

#### Query Parameters
- **password** (string) - Optional - The password to use to encrypt the ZIP file. Using a password is mandatory, the default password is urlscan!
- **filename** (string) - Optional - Specify the name of the ZIP file that should be downloaded. The default filename is $fileHash.zip
```

--------------------------------

### GET /api/v1/user/incidents/{incidentId}

Source: https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincident

Retrieves the configuration and status details for a specific incident.

```APIDOC
## GET /api/v1/user/incidents/{incidentId}

### Description
Get details for a specific incident.

### Method
GET

### Endpoint
/api/v1/user/incidents/{incidentId}

### Parameters
#### Path Parameters
- **incidentId** (string) - Required - ID of incident

### Response
#### Success Response (200)
- **incident** (object) - The incident object
- **incident.channels** (array) - Channels subscribed to this incident.
- **incident.observable** (string) - Hostname, domain, IP, or URL to observe
- **incident.extraPath** (string) - Optional path appended to hostname type incidents
- **incident.visibility** (string) - Scan visibility (Enum: "unlisted", "private")
- **incident.scanInterval** (integer) - Interval (seconds) between triggering full website scans.
- **incident.scanIntervalMode** (string) - Scan interval mode (Enum: "manual", "automatic")
- **incident.watchedAttributes** (array) - Determine which items will be monitored for.
- **incident.userAgents** (array) - Browser User-Agents to use during scanning
- **incident.userAgentsPerInterval** (integer) - How many userAgents to use per scanInterval
- **incident.countries** (array) - List of countries to scan from as ISO-3166-1 country codes.
- **incident.countriesPerInterval** (integer) - How many countries to use per scan interval.
- **incident.stopDelaySuspended** (integer) - When to automatically close the incident after the observable was suspended.
- **incident.stopDelayInactive** (integer) - When to automatically close the incident after the observable became inactive.
- **incident.stopDelayMalicious** (integer) - When to automatically close the incident after the observable became malicious.
- **incident.scanIntervalAfterSuspended** (integer) - How to change the scan interval after the observable was suspended.
- **incident.scanIntervalAfterMalicious** (integer) - How to change the scan interval after the observable became malicious.
- **incident.incidentProfile** (string) - ID of the incident profile to use when creating this incident.
```

--------------------------------

### GET /api/v1/quotas

Source: https://docs.urlscan.io/apis/urlscan-openapi/generic/getquotas

Retrieves the current API quota usage and limits for the authenticated user.

```APIDOC
## GET /api/v1/quotas

### Description
Retrieves the available and used API quotas for the authenticated user.

### Method
GET

### Endpoint
/api/v1/quotas

### Response
#### Success Response (200)
- **scope** (string) - Scope of the quota limits
- **limits** (object) - Container for quota limits
- **limits.private** (object) - Private scan limits
- **limits.private.day** (object) - Daily private scan limits
- **limits.private.day.limit** (integer) - Maximum allowed usage for this period
- **limits.private.day.used** (integer) - Amount of quota used in this period
- **limits.private.day.remaining** (integer) - Remaining quota for this period
- **limits.private.day.percent** (number) - Percentage of quota used
```

--------------------------------

### API Rate Limit Response Headers

Source: https://docs.urlscan.io/pages/api-rate-limits

Example of the HTTP headers returned by the API to indicate current rate limit status for a specific action.

```curl
X-Rate-Limit-Scope: ip-address
X-Rate-Limit-Action: search
X-Rate-Limit-Window: minute
X-Rate-Limit-Limit: 30
X-Rate-Limit-Remaining: 24
X-Rate-Limit-Reset: 2025-05-18T20:19:00.000Z
X-Rate-Limit-Reset-After: 17
```

--------------------------------

### GET /api/v1/userAgents

Source: https://docs.urlscan.io/apis/urlscan-openapi/scanning/getuseragents

Retrieves a list of user agents grouped by browser or device type.

```APIDOC
## GET /api/v1/userAgents

### Description
Retrieves a list of user agents grouped by browser or device type for use with the Scan API.

### Method
GET

### Endpoint
/api/v1/userAgents

### Response
#### Success Response (200)
- **userAgents** (array) - List of user agent groups
- **userAgents.group** (string) - Browser or device group name
- **userAgents.useragents** (array) - Array of user agent strings for this group
```

--------------------------------

### GET /screenshots/{scanId}.png

Source: https://docs.urlscan.io/apis/urlscan-openapi/scanning/getscreenshot

Retrieves the screenshot for a specific scan by its UUID.

```APIDOC
## GET /screenshots/{scanId}.png

### Description
Use the scan UUID to retrieve the screenshot for a scan once the scan has finished.

### Method
GET

### Endpoint
/screenshots/{scanId}.png

### Parameters
#### Path Parameters
- **scanId** (string) - Required - UUID of scan result
```

--------------------------------

### GET /api/v1/availableCountries

Source: https://docs.urlscan.io/apis/urlscan-openapi/scanning/getavailablecountries

Retrieve the list of countries available for scanning using the Scan API.

```APIDOC
## GET /api/v1/availableCountries

### Description
Retrieve countries available for scanning using the Scan API.

### Method
GET

### Endpoint
/api/v1/availableCountries

### Response
#### Success Response (200)
- **countries** (array) - List of available countries
```

--------------------------------

### Standard API Error Response Structure

Source: https://docs.urlscan.io/pages/error-codes

Example of a validation error response returned by the API.

```json
{
    "code": "validationerror",
    "type": "query",
    "message": "ValidationError: \"size\" must be greater than or equal to 0",
    "errors": [
        {
            "code": "validationerror",
            "title": "Field Validation Error",
            "description": "ValidationError: \"size\" must be greater than or equal to 0",
            "status": 400
        }
    ]
}
```

--------------------------------

### GET /api/v1/user/subscriptions/{subscriptionId}/results/{datasource}/

Source: https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/getsubscriptionresults

Retrieves the search results for a specific subscription and datasource.

```APIDOC
## GET /api/v1/user/subscriptions/{subscriptionId}/results/{datasource}/

### Description
Get the search results for a specific subscription and datasource.

### Method
GET

### Endpoint
/api/v1/user/subscriptions/{subscriptionId}/results/{datasource}/

### Parameters
#### Path Parameters
- **subscriptionId** (string) - Required - The ID of the subscription.
- **datasource** (string) - Required - The datasource identifier.
```

--------------------------------

### GET /api/v1/pro/availableBrands

Source: https://docs.urlscan.io/apis/urlscan-openapi/brands

Retrieves a list of brands that are tracked as part of urlscan's brand and phishing detection.

```APIDOC
## GET /api/v1/pro/availableBrands

### Description
API Endpoint to get a list of brands that are tracked as part of urlscan's brand and phishing detection.

### Method
GET

### Endpoint
/api/v1/pro/availableBrands
```

--------------------------------

### GET /api/v1/livescan/{scannerId}/{resourceType}/{resourceId}

Source: https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/getlivescanresource

Retrieve the resource for a particular scan ID or SHA256 from this live scanner.

```APIDOC
## GET /api/v1/livescan/{scannerId}/{resourceType}/{resourceId}

### Description
Retrieve the resource for a particular scan ID or SHA256 from this live scanner.

### Method
GET

### Endpoint
/api/v1/livescan/{scannerId}/{resourceType}/{resourceId}

### Parameters
#### Path Parameters
- **scannerId** (string) - Required - The ID of the scanner.
- **resourceType** (string) - Required - The type of resource to retrieve.
- **resourceId** (string) - Required - The identifier for the resource. For result, screenshot, or dom, use the UUID of the scan. For response or download, use the SHA256 of the resource.
```

--------------------------------

### GET /api/v1/pro/brands

Source: https://docs.urlscan.io/apis/urlscan-openapi/brands

Retrieves a summary of brands, including the total number of detected phishing pages and the latest hit for each brand.

```APIDOC
## GET /api/v1/pro/brands

### Description
Get the list of brands that we are able to detect phishing pages, the total number of detected pages and the latest hit for each brand. This is slower than the availableBrands endpoint.

### Method
GET

### Endpoint
/api/v1/pro/brands
```

--------------------------------

### GET /api/v1/pro/result/{scanId}/similar/

Source: https://docs.urlscan.io/apis/urlscan-openapi/search/getsimilarresults

Retrieves a list of structurally similar scan results based on a provided scan ID.

```APIDOC
## GET /api/v1/pro/result/{scanId}/similar/

### Description
Retrieves structurally similar results to a specific scan. This feature is part of urlscan Pro.

### Method
GET

### Endpoint
/api/v1/pro/result/{scanId}/similar/

### Parameters
#### Path Parameters
- **scanId** (string) - Required - The original scan to compare to

#### Query Parameters
- **q** (string) - Optional - Additional query filter
- **size** (integer) - Optional - Maximum results per call
- **search_after** (string) - Optional - Parameter to iterate over older results

### Response
#### Success Response (200)
- **results** (array) - Array of search results
- **total** (integer) - Total number of results with an exact count up to 10,000 results
- **took** (integer) - Search request time in milliseconds
- **has_more** (boolean) - True if there are more than 10,000 results
```

--------------------------------

### Configure API Key

Source: https://docs.urlscan.io/pages/cli-intro

Set up authentication by either storing the key in the system keyring or using an environment variable.

```bash
# Set the API key via keyring
urlscan key set


# Alternatively you can simply supply the API key via the environment
export URLSCAN_API_KEY=xxx
```

--------------------------------

### GET /api/v1/pro/phishfeed

Source: https://docs.urlscan.io/apis/urlscan-openapi/search/getphishfeed

Retrieves a feed of detected phishing pages.

```APIDOC
## GET /api/v1/pro/phishfeed

### Description
A convenience method over the Search API for retrieving detected phishing pages. Note that this endpoint is deprecated and the Search API should be used instead.

### Method
GET

### Endpoint
/api/v1/pro/phishfeed

### Parameters
#### Query Parameters
- **q** (string) - Optional
- **limit** (integer) - Optional - How many results to return
- **format** (string) - Optional - Can be one of csv, tsv, or json

### Response
#### Success Response (200)
- **results** (array) - Array of search results
- **total** (integer) - Total number of results with an exact count up to 10,000 results
- **took** (integer) - Search request time in milliseconds
- **has_more** (boolean) - True if there are more than 10,000 results
```

--------------------------------

### Submit a URL for scanning

Source: https://docs.urlscan.io/guides/quickstart

Use this POST request to initiate a scan for a specific URL. Replace YOUR_API_KEY with your actual API key.

```bash
curl -X POST https://urlscan.io/api/v1/scan \
-H "Content-Type: application/json" \
-H "API-Key: YOUR_API_KEY" \
-d '{
  "url": "https://example.com",
  "visibility": "public"
}'
```

--------------------------------

### POST /api/v1/user/subscriptions/

Source: https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/createsubscription

Creates a new subscription with the specified parameters.

```APIDOC
## POST /api/v1/user/subscriptions/

### Description
Create a new subscription for monitoring and notifications.

### Method
POST

### Endpoint
/api/v1/user/subscriptions/

### Request Body
- **subscription** (object) - Required - The subscription configuration object.
- **subscription.searchIds** (array) - Required - Array of search IDs associated with this subscription.
- **subscription.frequency** (string) - Required - Frequency of notifications (live, hourly, daily).
- **subscription.emailAddresses** (array) - Required - Email addresses receiving the notifications.
- **subscription.name** (string) - Required - Name of the subscription.
- **subscription.description** (string) - Optional - Description of the subscription.
- **subscription.isActive** (boolean) - Required - Whether the subscription is active.
- **subscription.ignoreTime** (boolean) - Required - Whether to ignore time constraints.
- **subscription.weekDays** (array) - Optional - Days of the week alerts will be generated.
- **subscription.permissions** (array) - Optional - Subscription permissions.
- **subscription.channelIds** (array) - Optional - Array of channel IDs associated with this subscription.
- **subscription.incidentChannelIds** (array) - Optional - Array of incident channel IDs associated with this subscription.
- **subscription.incidentProfileId** (string) - Optional - Incident Profile ID associated with this subscription.
- **subscription.incidentVisibility** (string) - Optional - Incident visibility (unlisted, private).
- **subscription.incidentCreationMode** (string) - Optional - Incident creation rule (none, default, always, ignore-if-exists).
- **subscription.incidentWatchKeys** (string) - Optional - Source/key to watch in the incident.

### Response
#### Success Response (200)
- **subscription** (object) - The created subscription object containing all defined fields.
```

--------------------------------

### POST /api/v1/user/channels/

Source: https://docs.urlscan.io/apis/urlscan-openapi/channels/createchannel

Creates a new channel for notifications.

```APIDOC
## POST /api/v1/user/channels/

### Description
Create a new notification channel for the user.

### Method
POST

### Endpoint
/api/v1/user/channels/

### Request Body
- **channel** (object) - Required - The channel configuration object
- **channel._id** (string) - Optional - Channel ID
- **channel.type** (string) - Required - Type of channel, "webhook" (default) or "email"
- **channel.webhookURL** (string) - Optional - Webhook URL receiving the notifications
- **channel.frequency** (string) - Optional - Frequency of notifications ("live", "hourly", or "daily")
- **channel.emailAddresses** (array) - Optional - Email addresses receiving the notifications
- **channel.utcTime** (string) - Optional - 24 hour UTC time that daily emails are sent (e.g. 09:00)
- **channel.name** (string) - Required - Name of the channel
- **channel.isActive** (boolean) - Optional - Whether the channel is active
- **channel.isDefault** (boolean) - Optional - Whether the channel is the default (default: false)
- **channel.ignoreTime** (boolean) - Optional - Whether to ignore time constraints (default: false)
- **channel.weekDays** (array) - Optional - Days of the week alerts will be generated
- **channel.permissions** (array) - Optional - Channel permissions

### Response
#### Success Response (200)
- **channel** (object) - The created channel object

#### Response Example
{
  "channel": {
    "_id": "{{channelId}}",
    "type": "webhook",
    "webhookURL": "https://example.com/cgi-bin/urlscan",
    "name": "Test webhook",
    "description": "Webhook testing channel.",
    "isActive": true,
    "ignoreTime": false
  }
}
```

--------------------------------

### POST /api/v1/livescan/{scannerId}/task/

Source: https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/createlivescantask

Initiates a new live scan task for a specified URL. The request is non-blocking and returns a scan UUID.

```APIDOC
## POST /api/v1/livescan/{scannerId}/task/

### Description
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.

### Method
POST

### Endpoint
/api/v1/livescan/{scannerId}/task/

### Parameters
#### Path Parameters
- **scannerId** (string) - Required - The ID of the scanner to use.

#### Request Body
- **task** (object) - Required
  - **task.url** (string) - Required - URL to scan
  - **task.visibility** (string) - Optional - Enum: "public", "unlisted", "private"
  - **task.tags** (array) - Optional - User-defined tags to annotate this scan
- **scanner** (object) - Optional
  - **scanner.pageTimeout** (integer) - Optional - Time to wait for the whole scan process (in ms)
  - **scanner.captureDelay** (integer) - Optional - Delay after page has finished loading before capturing page content
  - **scanner.extraHeaders** (object) - Optional - Extra Key-Value headers to send via the HTTP headers
  - **scanner.enableFeatures** (array) - Optional
  - **scanner.disableFeatures** (array) - Optional

### Response
#### Success Response (200)
- **uuid** (string) - UUID of scan
```

--------------------------------

### Retrieve screenshots and DOM snapshots

Source: https://docs.urlscan.io/guides/quickstart

Fetch the visual screenshot or the DOM snapshot for a completed scan using the scan UUID.

```bash
curl -H "API-Key: YOUR_API_KEY" https://urlscan.io/screenshots/$uuid.png
curl -H "API-Key: YOUR_API_KEY" https://urlscan.io/dom/$uuid/
```

--------------------------------

### GET /api/v1/user/searches/

Source: https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/listsavedsearches

Retrieves a list of all saved searches associated with the authenticated user.

```APIDOC
## GET /api/v1/user/searches/

### Description
Get a list of Saved Searches for the current user.

### Method
GET

### Endpoint
/api/v1/user/searches/

### Response
#### Success Response (200)
- **searches** (array) - List of saved search objects
- **searches.datasource** (string) - Which data this Saved Search operates on (Enum: "hostnames", "scans")
- **searches.createdAt** (string) - Time when the Saved Search was created
- **searches.description** (string) - Short description
- **searches.longDescription** (string) - Long description
- **searches.name** (string) - User-facing short name
- **searches.ownerDescription** (string) - User-facing owner description
- **searches.permissions** (array) - Determine whether only other users on the same team or everyone on urlscan Pro can see the search
- **searches.query** (string) - Search API query
- **searches.tlp** (string) - TLP (Traffic Light Protocol) indicator (Enum: "red", "amber+strict", "amber", "green", "clear")
- **searches.usertags** (array) - User-supplied tags to be applied to matching items
- **searches._id** (string) - Unique ID of the Saved Search
```

--------------------------------

### POST /api/v1/livescan/{scannerId}/task/

Source: https://docs.urlscan.io/apis/urlscan-openapi

Task a URL to be scanned asynchronously.

```APIDOC
## POST /api/v1/livescan/{scannerId}/task/

### Description
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.

### Method
POST

### Endpoint
/api/v1/livescan/{scannerId}/task/

### Parameters
#### Path Parameters
- **scannerId** (string) - Required - The ID of the scanner node.
```

--------------------------------

### GET /api/v1/user/watchableAttributes

Source: https://docs.urlscan.io/apis/urlscan-openapi/incidents/getwatchableattributes

Retrieves the list of attributes which can be supplied to the watchedAttributes property of the incident.

```APIDOC
## GET /api/v1/user/watchableAttributes

### Description
Get the list of attributes which can be supplied to the watchedAttributes property of the incident.

### Method
GET

### Endpoint
/api/v1/user/watchableAttributes

### Security
apikeyAuth
```

--------------------------------

### API Overview

Source: https://docs.urlscan.io/apis/urlscan-openapi/section/introduction

This page provides an overview of the available API endpoints for urlscan.io. Users can interact with the platform for scanning URLs, retrieving results, searching historical data, and managing Pro-specific features like Live Scanning and Saved Searches.

```APIDOC
## urlscan.io API Overview

### Description
The urlscan.io API allows users to perform website scans, retrieve scan results, search historical data, and manage account-specific configurations. Access to most endpoints requires authentication.

### Base URL
https://urlscan.io

### Categories
- **Generic**: Platform and user account management.
- **Scanning**: URL scanning and result retrieval.
- **Search**: Historical search for scans, domains, and certificates.
- **Live Scanning (Pro)**: Geographical and device-specific scanning.
- **Saved Searches (Pro)**: Automated rules for incoming scans.
```

--------------------------------

### GET /api/v1/search

Source: https://docs.urlscan.io/apis/urlscan-openapi/search/searchdatasource

Retrieve historical scan results based on a search query.

```APIDOC
## GET /api/v1/search

### Description
Find historical scans performed on the platform. The API returns an exact count up to 10,000 results; for larger datasets, use the `search_after` parameter.

### Method
GET

### Endpoint
/api/v1/search

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search Query (Elasticsearch Query String)
- **size** (integer) - Optional - Number of results to return
- **search_after** (string) - Optional - For retrieving the next batch of results, send the value of the `sort` attribute of the last (oldest) result received.
- **datasource** (string) - Optional - Datasources to search: scans, hostnames, incidents, notifications, certificates (urlscan Pro)
- **collapse** (string) - Optional - Field to collapse results on. Only works on current page of results.

### Response
#### Success Response (200)
- **results** (array) - Array of search results
- **total** (integer) - Total number of results with an exact count up to 10,000 results.
- **took** (integer) - Search request time in milliseconds.
- **has_more** (boolean) - True if there are more than 10,000 results.
```

--------------------------------

### POST /api/v1/user/incidents

Source: https://docs.urlscan.io/apis/urlscan-openapi/incidents/createincident

Creates a new incident with the provided configuration parameters.

```APIDOC
## POST /api/v1/user/incidents

### Description
Create an incident with specific options.

### Method
POST

### Endpoint
/api/v1/user/incidents

### Request Body
- **incident** (object) - Required - The incident configuration object.
- **incident.channels** (array) - Required - Channels subscribed to this incident.
- **incident.observable** (string) - Required - Hostname, domain, IP, or URL to observe.
- **incident.extraPath** (string) - Optional - Optional path appended to hostname type incidents.
- **incident.visibility** (string) - Required - Scan visibility (Enum: "unlisted", "private").
- **incident.scanInterval** (integer) - Optional - Interval (seconds) between triggering full website scans.
- **incident.scanIntervalMode** (string) - Optional - Scan interval mode (Enum: "manual", "automatic").
- **incident.watchedAttributes** (array) - Optional - Determine which items will be monitored for.
- **incident.userAgents** (array) - Optional - Browser User-Agents to use during scanning.
- **incident.userAgentsPerInterval** (integer) - Optional - How many userAgents to use per scanInterval.
- **incident.countries** (array) - Optional - List of countries to scan from as ISO-3166-1 country codes.
- **incident.countriesPerInterval** (integer) - Optional - How many countries to use per scan interval.
- **incident.stopDelaySuspended** (integer) - Optional - When to automatically close the incident after the observable was suspended.
- **incident.stopDelayInactive** (integer) - Optional - When to automatically close the incident after the observable became inactive.
- **incident.stopDelayMalicious** (integer) - Optional - When to automatically close the incident after the observable became malicious.
- **incident.scanIntervalAfterSuspended** (integer) - Optional - How to change the scan interval after the observable was suspended.
- **incident.scanIntervalAfterMalicious** (integer) - Optional - How to change the scan interval after the observable became malicious.
- **incident.incidentProfile** (string) - Optional - ID of the incident profile to use when creating this incident.

### Response
#### Success Response (200)
- **incident** (object) - The created incident object containing all configured fields.
```

--------------------------------

### PUT /api/v1/user/subscriptions/{subscriptionId}/

Source: https://docs.urlscan.io/apis/urlscan-openapi/subscriptions

Updates the configuration settings for an existing subscription.

```APIDOC
## PUT /api/v1/user/subscriptions/{subscriptionId}/

### Description
Update the settings for a subscription.

### Method
PUT

### Endpoint
/api/v1/user/subscriptions/{subscriptionId}/

### Parameters
#### Path Parameters
- **subscriptionId** (string) - Required - The unique identifier of the subscription.
```

--------------------------------

### GET /api/v1/user/channels/{channelId}

Source: https://docs.urlscan.io/apis/urlscan-openapi/channels

Retrieves the search results associated with a specific notification channel.

```APIDOC
## GET /api/v1/user/channels/{channelId}

### Description
Get the search results for a specific notification channel.

### Method
GET

### Endpoint
/api/v1/user/channels/{channelId}

### Parameters
#### Path Parameters
- **channelId** (string) - Required - The unique identifier of the notification channel.
```

--------------------------------

### POST /api/v1/user/searches/

Source: https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/createsavedsearch

Creates a new Saved Search for the authenticated user.

```APIDOC
## POST /api/v1/user/searches/

### Description
Create a new Saved Search on the urlscan platform.

### Method
POST

### Endpoint
/api/v1/user/searches/

### Parameters
#### Request Body
- **search** (object) - Required - The search configuration object.
- **search.datasource** (string) - Required - Which data this Saved Search operates on. Enum: "hostnames", "scans".
- **search.name** (string) - Required - User-facing short name.
- **search.query** (string) - Required - Search API query.
- **search.description** (string) - Optional - Short description.
- **search.longDescription** (string) - Optional - Long description.
- **search.permissions** (array) - Optional - Determine visibility scope.
- **search.tlp** (string) - Optional - TLP indicator. Enum: "red", "amber+strict", "amber", "green", "clear".
- **search.usertags** (array) - Optional - User-supplied tags.

### Response
#### Success Response (201)
- **search** (object) - The created search object containing its unique ID and configuration.
```

--------------------------------

### POST /api/v1/user/incidents/{incidentId}/fork

Source: https://docs.urlscan.io/apis/urlscan-openapi/incidents/forkincident

Copies an incident along with its history (incident states).

```APIDOC
## POST /api/v1/user/incidents/{incidentId}/fork

### Description
Copy an incident along with its history (incident states).

### Method
POST

### Endpoint
/api/v1/user/incidents/{incidentId}/fork

### Parameters
#### Path Parameters
- **incidentId** (string) - Required - ID of incident

### Response
#### Success Response (200)
- **incident** (object) - The created incident object
- **incident.channels** (array) - Channels subscribed to this incident.
- **incident.observable** (string) - Hostname, domain, IP, or URL to observe
- **incident.extraPath** (string) - Optional path appended to hostname type incidents
- **incident.visibility** (string) - Scan visibility (Enum: "unlisted", "private")
- **incident.scanInterval** (integer) - Interval (seconds) between triggering full website scans.
- **incident.scanIntervalMode** (string) - Scan interval mode (Enum: "manual", "automatic")
- **incident.watchedAttributes** (array) - Determine which items will be monitored for.
- **incident.userAgents** (array) - Browser User-Agents to use during scanning
- **incident.userAgentsPerInterval** (integer) - How many userAgents to use per scanInterval
- **incident.countries** (array) - List of countries to scan from as ISO-3166-1 country codes.
- **incident.countriesPerInterval** (integer) - How many countries to use per scan interval.
- **incident.stopDelaySuspended** (integer) - When to automatically close the incident after the observable was suspended.
- **incident.stopDelayInactive** (integer) - When to automatically close the incident after the observable became inactive.
- **incident.stopDelayMalicious** (integer) - When to automatically close the incident after the observable became malicious.
- **incident.scanIntervalAfterSuspended** (integer) - How to change the scan interval after the observable was suspended.
- **incident.scanIntervalAfterMalicious** (integer) - How to change the scan interval after the observable became malicious.
- **incident.incidentProfile** (string) - ID of the incident profile to use when creating this incident.
```

--------------------------------

### POST /api/v1/scan

Source: https://docs.urlscan.io/apis/urlscan-openapi/scanning/submitscan

Submit a URL to be scanned and control options for how the scan should be performed.

```APIDOC
## POST /api/v1/scan

### Description
Submit a URL to be scanned and control options for how the scan should be performed.

### Method
POST

### Endpoint
/api/v1/scan

### Parameters
#### Request Body
- **url** (string) - Required - The URL to be scanned
- **visibility** (string) - Optional - Intended visibility of the final scan result (Enum: "public", "unlisted", "private")
- **country** (string) - Optional - Country to scan from. ISO 3166-1 alpha-2 format.
- **tags** (array) - Optional - User-defined tags to annotate this scan
- **overrideSafety** (string) - Optional - If set, disables reclassification of URLs with potential PII
- **referer** (string) - Optional - Override HTTP referer for this scan
- **customagent** (string) - Optional - Override HTTP User-Agent for this scan

### Response
#### Success Response (200)
- **uuid** (string) - UUID for scan result
- **country** (string) - Country for scanning
- **visibility** (string) - Determined visibility for scan
- **url** (string) - Determined URL being scanned
```

--------------------------------

### GET /api/v1/user/searches/{searchId}/results/

Source: https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/getsavedsearchresults

Retrieves the results for a specific saved search identified by the searchId.

```APIDOC
## GET /api/v1/user/searches/{searchId}/results/

### Description
Get the search results for a specific Saved Search.

### Method
GET

### Endpoint
/api/v1/user/searches/{searchId}/results/

### Parameters
#### Path Parameters
- **searchId** (string) - Required - The unique identifier of the saved search.
```

--------------------------------

### PUT /api/v1/livescan/{scannerId}/{scanId}/

Source: https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/storelivescanresult

Stores a temporary scan as a permanent snapshot on urlscan.io.

```APIDOC
## PUT /api/v1/livescan/{scannerId}/{scanId}/

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

### Method
PUT

### Endpoint
/api/v1/livescan/{scannerId}/{scanId}/

### Parameters
#### Path Parameters
- **scannerId** (string) - Required - The identifier for the scanner.
- **scanId** (string) - Required - The identifier for the scan.

### Request Body
- **task** (object) - Optional - The task object containing scan details.
- **task.visibility** (string) - Optional - The visibility of the scan. Enum: "public", "unlisted", "private"
```

--------------------------------

### POST /api/v1/livescan/{scannerId}/scan/

Source: https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/createlivescanscan

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

```APIDOC
## POST /api/v1/livescan/{scannerId}/scan/

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

### Method
POST

### Endpoint
/api/v1/livescan/{scannerId}/scan/

### Parameters
#### Path Parameters
- **scannerId** (string) - Required - The ID of the scanner to use.

#### Request Body
- **task** (object) - Required - The task configuration.
- **task.url** (string) - Required - URL to scan.
- **task.visibility** (string) - Optional - Enum: "public", "unlisted", "private".
- **task.tags** (array) - Optional - User-defined tags to annotate this scan.
- **scanner** (object) - Optional - Scanner configuration.
- **scanner.pageTimeout** (integer) - Optional - Time to wait for the whole scan process (in ms).
- **scanner.captureDelay** (integer) - Optional - Delay after page has finished loading before capturing page content.
- **scanner.extraHeaders** (object) - Optional - Extra Key-Value headers to send via the HTTP headers.
- **scanner.enableFeatures** (array) - Optional - Features to enable.
- **scanner.disableFeatures** (array) - Optional - Features to disable.

### Response
#### Success Response (200)
- **uuid** (string) - UUID of scan
```

--------------------------------

### GET /api/v1/result/{scanId}/

Source: https://docs.urlscan.io/apis/urlscan-openapi/scanning

Retrieve the results of a scan using the Scan ID received from the Submission API.

```APIDOC
## GET /api/v1/result/{scanId}/

### Description
Using the Scan ID received from the Submission API, you can use the Result API to poll for the scan. The most efficient approach would be to wait at least 10 seconds before starting to poll.
```
Tokens:
Raw