# urlscan.io APIs ### 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 * [urlscan.io website](https://urlscan.io) * [urlscan.io Documentation Hub](https://docs.urlscan.io) * [urlscan.io API Status](https://status.urlscan.io) Version: 1.0.0 ## Servers ``` https://urlscan.io ``` ## Security ### apikeyAuth Type: apiKey In: header Name: api-key ## Download OpenAPI description [urlscan.io APIs](https://docs.urlscan.io/_bundle/apis/urlscan-openapi.yaml) ## Generic API endpoints related to the platform or the user account. ### API Quotas - [GET /api/v1/quotas](https://docs.urlscan.io/apis/urlscan-openapi/generic/quotas.md): API Endpoint to get available and used API quotas. ### User Information - [GET /api/v1/pro/username](https://docs.urlscan.io/apis/urlscan-openapi/generic/prousername.md): Get information about the current user or API key making the request. ## Scanning These APIs allow URLs to be scanned and the results of the scans to be retrieved. ### Scan - [POST /api/v1/scan](https://docs.urlscan.io/apis/urlscan-openapi/scanning/submitscan.md): Submit a URL to be scanned and control options for how the scan should be performed. ### Result - [GET /api/v1/result/{scanId}/](https://docs.urlscan.io/apis/urlscan-openapi/scanning/resultapi.md): 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, and then only polling 2-second intervals with an eventual upper timeout in case the scan does not return. ### Screenshot - [GET /screenshots/{scanId}.png](https://docs.urlscan.io/apis/urlscan-openapi/scanning/screenshot.md): Use the scan UUID to retrieve the screenshot for a scan once the scan has finished. ### DOM - [GET /dom/{scanId}/](https://docs.urlscan.io/apis/urlscan-openapi/scanning/dom.md): Use the scan UUID to retrieve the DOM snapshot for a scan once the scan has finished. ### Available Countries - [GET /api/v1/availableCountries](https://docs.urlscan.io/apis/urlscan-openapi/scanning/availablecountries.md): Retrieve countries available for scanning using the Scan API ### Available User Agents - [GET /api/v1/userAgents](https://docs.urlscan.io/apis/urlscan-openapi/scanning/useragents.md): Get grouped user agents to use with the Scan API. ## Search The Search API allows users to search for historically website scans, hostnames, domains, TLS certificates and incidents. ### Search - [GET /api/v1/search](https://docs.urlscan.io/apis/urlscan-openapi/search/search.md): The Search API is used to find historical scans performed on the platform. Some data sources and searchable fields are only available on urlscan Pro. The API search will only indicate an exact count of results up to 10,000 results in the total property. After that the has_more flag will be true. Use the sort value of the last (i.e. oldest) scan result in the current list of results as a parameter for the next Search API call. Supply this value in the search_after query parameter for getting the next (older) batch of results. API search will find Public scans performed by anyone as well as Unlisted and Private scans performed by you or your teams. For query syntax and searchable fields, refer to https://docs.urlscan.io/pages/search-api-reference ### Structure Search - [GET /api/v1/pro/result/{scanId}/similar/](https://docs.urlscan.io/apis/urlscan-openapi/search/similarsearch.md): urlscan Pro - Get structurally similar results to a specific scan. See description for this propietary feature on [urlscan Pro](https://pro.urlscan.io/help/structuresearch). ### Phishfeed (deprecated) - [GET /api/v1/pro/phishfeed](https://docs.urlscan.io/apis/urlscan-openapi/search/phishfeed.md): urlscan Pro - The Phishing URL endpoint is a convenience method over the Search API for retrieving detected pages. Unless you have a specific reason not to, you should use the Search API instead! ## 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](https://pro.urlscan.io/help/livescan). ### Live Scanners - [GET /api/v1/livescan/scanners/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanscanners.md): API Endpoint to a list of available Live Scanning nodes along with their current metadata. ### Non-Blocking Trigger Live Scan - [POST /api/v1/livescan/{scannerId}/task/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescantask.md): 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. ### Trigger Live Scan - [POST /api/v1/livescan/{scannerId}/scan/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanscan.md): Task a URL to be scanned. The HTTP request will block until the scan has finished. ### Live Scan Get Resource - [GET /api/v1/livescan/{scannerId}/{resourceType}/{resourceId}](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescangetresource.md): Get the historical observations for a specific hostname in the "Hostnames" data source. ### Store Live Scan Result - [PUT /api/v1/livescan/{scannerId}/{scanId}/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescanstore.md): Store the temporary scan as a permanent snapshot on urlscan.io. ### Purge Live Scan Result - [DELETE /api/v1/livescan/{scannerId}/{scanId}/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/livescandiscard.md): Purge temporary scan from scanner immediately. Scans will be automatically purged after 60 minutes. ## Saved Searches **urlscan Pro** - Saved Searches are rules that are executed inline against new incoming scans and hostnames. ### Saved Searches - [GET /api/v1/user/searches/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearches.md): Get a list of Saved Searches for the current user. ### Create Saved Search - [POST /api/v1/user/searches/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearchescreate.md): Create a Saved Search. ### Update Saved Search - [PUT /api/v1/user/searches/{searchId}/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearchesupdate.md): Update a Saved Search. ### Delete Saved Search - [DELETE /api/v1/user/searches/{searchId}/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearchesdelete.md): Delete a Saved Search ### Saved Search Search Results - [GET /api/v1/user/searches/{searchId}/results/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/savedsearchesresult.md): Get the search results for a specific Saved Search. ## Subscriptions **urlscan Pro** - Subscriptions allow notifications for Saved Searches. ### Subscriptions - [GET /api/v1/user/subscriptions/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptions.md): Get a list of Subscriptions for the current user. ### Create Subscription - [POST /api/v1/user/subscriptions/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionscreate.md): Create a new subscription. ### Update Subscription - [PUT /api/v1/user/subscriptions/{subscriptionId}/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsget.md): Update the settings for a subscription. ### Delete Subscription - [DELETE /api/v1/user/subscriptions/{subscriptionId}/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsdelete.md): Delete a subscription. ### Subscription Search Results - [GET /api/v1/user/subscriptions/{subscriptionId}/results/{datasource}/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/subscriptionsresults.md): Get the search results for a specific subscription and datasource. ## Hostnames **urlscan Pro** - Historical information on hostnames and domains ### Hostname History - [GET /api/v1/hostname/{hostname}](https://docs.urlscan.io/apis/urlscan-openapi/hostnames/hostnamehistory.md): Get the historical observations for a specific hostname in the "Hostnames" data source. ## Brands **urlscan Pro** - Information about tracked brands ### Available Brands - [GET /api/v1/pro/availableBrands](https://docs.urlscan.io/apis/urlscan-openapi/brands/availablebrands.md): API Endpoint to get a list of brands that are tracked as part of urlscan's brand and phishing detection. ### Brands - [GET /api/v1/pro/brands](https://docs.urlscan.io/apis/urlscan-openapi/brands/brandsummary.md): 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. ## Files **urlscan Pro** - Downloaded files ### Download a file - [GET /downloads/{fileHash}](https://docs.urlscan.io/apis/urlscan-openapi/files/downloadfile.md): 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. The ZIP file contains a single file named after the SHA256 of the requested file. ## Incidents **urlscan Pro** - Incidents track observables, like hostnames and domains, and automatically scan and alert on changes. ### Create Incident - [POST /api/v1/user/incidents](https://docs.urlscan.io/apis/urlscan-openapi/incidents/createincident.md): Create an incident with specific options ### Get Incident - [GET /api/v1/user/incidents/{incidentId}](https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincident.md): Get details for a specific incident. ### Update Incident options - [PUT /api/v1/user/incidents/{incidentId}](https://docs.urlscan.io/apis/urlscan-openapi/incidents/updateincident.md): Update specific runtime options of the incident ### Close Incident - [PUT /api/v1/user/incidents/{incidentId}/close](https://docs.urlscan.io/apis/urlscan-openapi/incidents/closeincident.md): Close (stop) the incident ### Restart Incident - [PUT /api/v1/user/incidents/{incidentId}/restart](https://docs.urlscan.io/apis/urlscan-openapi/incidents/restartincident.md): Restart a closed incident. Automatically extends the incident expireAt. Starts with new incident states. ### Copy Incident - [POST /api/v1/user/incidents/{incidentId}/copy](https://docs.urlscan.io/apis/urlscan-openapi/incidents/copyincident.md): Copy an incident without its history. ### Fork Incident - [POST /api/v1/user/incidents/{incidentId}/fork](https://docs.urlscan.io/apis/urlscan-openapi/incidents/forkincident.md): Copy an incident along with its history (incident states). ### Get Watchable Attributes - [GET /api/v1/user/watchableAttributes](https://docs.urlscan.io/apis/urlscan-openapi/incidents/getwatchableattributes.md): Get the list of attributes which can be supplied to the watchedAttributes property of the incident. ### Get Incident States - [GET /api/v1/user/incidentstates/{incidentId}/](https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincidentstates.md): Retrieve individual incident states of an incident. ## Channels ### Channels - [GET /api/v1/user/channels/](https://docs.urlscan.io/apis/urlscan-openapi/channels/channels.md): Get a list of notification channels for the current user. ### Create Channel - [POST /api/v1/user/channels/](https://docs.urlscan.io/apis/urlscan-openapi/channels/channelscreate.md): Create a new channel. ### Channel Search Results - [GET /api/v1/user/channels/{channelId}](https://docs.urlscan.io/apis/urlscan-openapi/channels/channelsget.md): Get the search results for a specific notification channel. ### Update Channel - [PUT /api/v1/user/channels/{channelId}](https://docs.urlscan.io/apis/urlscan-openapi/channels/channelsupdate.md): Update an existing channel. ## Data Dumps ### List Data Dump Files - [GET /api/v1/datadump/list/{timeWindow}/{fileType}/{date}](https://docs.urlscan.io/apis/urlscan-openapi/data-dumps/datadumplist.md): urlscan Pro - List available data dump files for a specific time window, file type, and date. ### Get Data Dump Download Link - [GET /api/v1/datadump/link/{path}](https://docs.urlscan.io/apis/urlscan-openapi/data-dumps/datadumplink.md): urlscan Pro - Generate a temporary download link for a specific data dump file.