URLScan.io
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…
Identity & security#anti-malware
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
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
Endpoints 49
Generic
- GETAPI Quotas
/api/v1/quotasAPI Endpoint to get available and used API quotas. - GETUser Information
/user/usernameGet information about the current user or API key making the request.
Scanning
- POSTScan
/api/v1/scanSubmit a URL to be scanned and control options for how the scan should be performed. - GETResult
/api/v1/result/:scanId/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… - GETScreenshot
/screenshots/:scanId.pngUse the scan UUID to retrieve the screenshot for a scan once the scan has finished. - GETDOM
/dom/:scanId/Use the scan UUID to retrieve the DOM snapshot for a scan once the scan has finished. - GETResponse
/responses/:fileHash/Get a (Script|Document|Fetch|XHR) response in plain text format by SHA256 hash. Note that this endpoint returns the content as text/plain. If you need to… - PUTUpdate Result Visibility
/api/v1/result/:scanId/visibility/urlscan Pro - Change the visibility of a scan owned by you or your team. - DELETEReset to original visibility
/api/v1/result/:scanId/visibility/urlscan Pro - Reset the visibility of a scan owned by you or your team to its original visibility - GETAvailable Countries
/api/v1/availableCountriesRetrieve countries available for scanning using the Scan API
Search
- GETSearch
/api/v1/searchThe 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… - GETPhishfeed
/api/v1/pro/phishfeedDeprecated. urlscan Pro - The Phishing URL endpoint is a convenience method over the Search API for retrieving detected pages. Unless you have a specific… - GETStructure Search
/api/v1/pro/result/:scanId/similar/urlscan Pro - Get structurally similar results to a specific scan. See description for this propietary feature on urlscan Pro.
Live Scanning
- GETLive Scanners
/api/v1/livescan/scanners/API Endpoint to a list of available Live Scanning nodes along with their current metadata. - POSTNon-Blocking Trigger Live Scan
/api/v1/livescan/:scannerId/task/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… - POSTTrigger Live Scan
/api/v1/livescan/:scannerId/scan/Task a URL to be scanned. The HTTP request will block until the scan has finished. - GETLive Scan Get Resource
/api/v1/livescan/:scannerId/:resourceType/:resourceIdRetrieve the resource for a particular scan ID or SHA256 from this live scanner. - PUTStore Live Scan Result
/api/v1/livescan/:scannerId/:scanId/Store the temporary scan as a permanent snapshot on urlscan.io. - DELETEPurge Live Scan Result
/api/v1/livescan/:scannerId/:scanId/Purge temporary scan from scanner immediately. Scans will be automatically purged after 60 minutes.
Saved Searches
- GETSaved Searches
/api/v1/user/searches/Get a list of Saved Searches for the current user. - POSTCreate Saved Search
/api/v1/user/searches/Create a Saved Search. - PUTUpdate Saved Search
/api/v1/user/searches/:searchId/Update a Saved Search. - DELETEDelete Saved Search
/api/v1/user/searches/:searchId/Delete a Saved Search - GETSaved Search Search Results
/api/v1/user/searches/:searchId/results/Get the search results for a specific Saved Search.
Subscriptions
- GETSubscriptions
/api/v1/user/subscriptions/Get a list of Subscriptions for the current user. - POSTCreate Subscription
/api/v1/user/subscriptions/Create a new subscription. - PUTUpdate Subscription
/api/v1/user/subscriptions/:subscriptionId/Update the settings for a subscription. - DELETEDelete Subscription
/api/v1/user/subscriptions/:subscriptionId/Delete a subscription. - GETSubscription Search Results
/api/v1/user/subscriptions/:subscriptionId/results/:datasource/Get the search results for a specific subscription and datasource.
Hostnames
- GETHostname History
/api/v1/hostname/:hostnameGet the historical observations for a specific hostname in the "Hostnames" data source.
Brands
- GETAvailable Brands
/api/v1/pro/availableBrandsAPI Endpoint to get a list of brands that are tracked as part of urlscan's brand and phishing detection. - GETBrands
/api/v1/pro/brandsGet 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…
Files
- GETDownload a file
/downloads/:fileHashurlscan Pro - Download a file by SHA256 hash. For the ZIP files delivered by this endpoint, the default encryption password is urlscan! - including the…
Incidents
- POSTCreate Incident
/api/v1/user/incidentsCreate an incident with specific options - GETGet Incident
/api/v1/user/incidents/:incidentIdGet details for a specific incident. - PUTUpdate Incident options
/api/v1/user/incidents/:incidentIdUpdate specific runtime options of the incident - PUTClose Incident
/api/v1/user/incidents/:incidentId/closeClose (stop) the incident - PUTRestart Incident
/api/v1/user/incidents/:incidentId/restartRestart a closed incident. Automatically extends the incident expireAt. Starts with new incident states. - POSTCopy Incident
/api/v1/user/incidents/:incidentId/copyCopy an incident without its history. - POSTFork Incident
/api/v1/user/incidents/:incidentId/forkCopy an incident along with its history (incident states). - GETGet Watchable Attributes
/api/v1/user/watchableAttributesGet the list of attributes which can be supplied to the watchedAttributes property of the incident. - GETGet Incident States
/api/v1/user/incidentstates/:incidentId/Retrieve individual incident states of an incident.
Malicious
- GETMalicious observable lookup
/api/v1/malicious/:type/:valueurlscan Pro - Look up how often an observable has been seen in malicious scan results, along with first and last seen timestamps. The type parameter selects…
Channels
- GETChannels
/api/v1/user/channels/Get a list of notification channels for the current user. - POSTCreate Channel
/api/v1/user/channels/Create a new channel. - GETChannel Search Results
/api/v1/user/channels/:channelIdGet the search results for a specific notification channel. - PUTUpdate Channel
/api/v1/user/channels/:channelIdUpdate an existing channel.
Data Dumps
- GETList Data Dump Files
/api/v1/datadump/list/:timeWindow/:fileType/:dateurlscan Pro - List available data dump files for a specific time window, file type, and date. - GETGet Data Dump Download Link
/api/v1/datadump/link/:pathurlscan Pro - Generate a temporary download link for a specific data dump file.
API details
- Base URL
https://urlscan.io- Authentication
- An API key in the api-key header
- Operations
- 49 operations on 40 pathsGET 28POST 9PUT 8DELETE 4
1 marked deprecated - Main resources
- Incidents 9Scanning 8Live Scanning 6Saved Searches 5Subscriptions 5Channels 4Search 3Brands 2Data Dumps 2Generic 2
- Response formats
application/jsontext/plainapplication/gzipapplication/zip- Description format
- OpenAPI 3.0.0, API version
1.0.0 - Links
- OpenAPI document
How to test the URLScan.io in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the URLScan.io collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the api-key header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “API Quotas” (GET /api/v1/quotas), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the URLScan.io?
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… It is listed under Identity & security and has 49 endpoints.
Who publishes the URLScan.io?
It is listed from Urlscan's public API description (an OpenAPI document), not published by Urlscan on Swastik Codes. Anyone who controls urlscan.io can claim the profile by adding a DNS TXT record.
What is the base URL of the URLScan.io?
Requests go to https://urlscan.io. Endpoint paths are added to this base URL.
How do I authenticate with the URLScan.io?
With an API key in the api-key header.
How many endpoints does the URLScan.io have?
49 operations on 40 paths (28 GET, 9 POST, 8 PUT, 4 DELETE). The largest groups are Incidents, Scanning, Live Scanning, Saved Searches.
Is forking the URLScan.io free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.