# 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 - [GET /api/v1/quotas](https://docs.urlscan.io/apis/urlscan-openapi/generic/getquotas.md): API Endpoint to get available and used API quotas. - [GET /user/username](https://docs.urlscan.io/apis/urlscan-openapi/generic/getusername.md): Get information about the current user or API key making the request. ## Scanning - [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. - [GET /api/v1/result/{scanId}/](https://docs.urlscan.io/apis/urlscan-openapi/scanning/getresult.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 - [GET /screenshots/{scanId}.png](https://docs.urlscan.io/apis/urlscan-openapi/scanning/getscreenshot.md): Use the scan UUID to retrieve the screenshot for a scan once the scan has finished. - [GET /dom/{scanId}/](https://docs.urlscan.io/apis/urlscan-openapi/scanning/getdom.md): Use the scan UUID to retrieve the DOM snapshot for a scan once the scan has finished. - [GET /responses/{fileHash}/](https://docs.urlscan.io/apis/urlscan-openapi/scanning/getresponse.md): 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 download a binary file (like a ZIP file, etc - [PUT /api/v1/result/{scanId}/visibility/](https://docs.urlscan.io/apis/urlscan-openapi/scanning/updateresultvisibility.md): **urlscan Pro** - Change the visibility of a scan owned by you or your team. - [DELETE /api/v1/result/{scanId}/visibility/](https://docs.urlscan.io/apis/urlscan-openapi/scanning/deleteresultvisibility.md): **urlscan Pro** - Reset the visibility of a scan owned by you or your team to its original visibility - [GET /api/v1/availableCountries](https://docs.urlscan.io/apis/urlscan-openapi/scanning/getavailablecountries.md): Retrieve countries available for scanning using the Scan API - [GET /api/v1/userAgents](https://docs.urlscan.io/apis/urlscan-openapi/scanning/getuseragents.md): Get grouped user agents to use with the Scan API. ## Search - [GET /api/v1/search](https://docs.urlscan.io/apis/urlscan-openapi/search/searchdatasource.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 cou - [GET /api/v1/pro/result/{scanId}/similar/](https://docs.urlscan.io/apis/urlscan-openapi/search/getsimilarresults.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). - [GET /api/v1/pro/phishfeed](https://docs.urlscan.io/apis/urlscan-openapi/search/getphishfeed.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 - [GET /api/v1/livescan/scanners/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/getlivescanscanners.md): API Endpoint to a list of available Live Scanning nodes along with their current metadata. - [POST /api/v1/livescan/{scannerId}/task/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/createlivescantask.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. - [POST /api/v1/livescan/{scannerId}/scan/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/createlivescanscan.md): Task a URL to be scanned. The HTTP request will **block** until the scan has finished. - [GET /api/v1/livescan/{scannerId}/{resourceType}/{resourceId}](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/getlivescanresource.md): Retrieve the resource for a particular scan ID or SHA256 from this live scanner. - [PUT /api/v1/livescan/{scannerId}/{scanId}/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/storelivescanresult.md): Store the temporary scan as a permanent snapshot on urlscan.io. - [DELETE /api/v1/livescan/{scannerId}/{scanId}/](https://docs.urlscan.io/apis/urlscan-openapi/live-scanning/discardlivescanresult.md): Purge temporary scan from scanner immediately. Scans will be automatically purged after 60 minutes. ## Saved Searches - [GET /api/v1/user/searches/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/listsavedsearches.md): Get a list of Saved Searches for the current user. - [POST /api/v1/user/searches/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/createsavedsearch.md): Create a Saved Search. - [PUT /api/v1/user/searches/{searchId}/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/updatesavedsearch.md): Update a Saved Search. - [DELETE /api/v1/user/searches/{searchId}/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/deletesavedsearch.md): Delete a Saved Search - [GET /api/v1/user/searches/{searchId}/results/](https://docs.urlscan.io/apis/urlscan-openapi/saved-searches/getsavedsearchresults.md): Get the search results for a specific Saved Search. ## Subscriptions - [GET /api/v1/user/subscriptions/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/listsubscriptions.md): Get a list of Subscriptions for the current user. - [POST /api/v1/user/subscriptions/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/createsubscription.md): Create a new subscription. - [PUT /api/v1/user/subscriptions/{subscriptionId}/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/updatesubscription.md): Update the settings for a subscription. - [DELETE /api/v1/user/subscriptions/{subscriptionId}/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/deletesubscription.md): Delete a subscription. - [GET /api/v1/user/subscriptions/{subscriptionId}/results/{datasource}/](https://docs.urlscan.io/apis/urlscan-openapi/subscriptions/getsubscriptionresults.md): Get the search results for a specific subscription and datasource. ## Hostnames - [GET /api/v1/hostname/{hostname}](https://docs.urlscan.io/apis/urlscan-openapi/hostnames/gethostnamehistory.md): Get the historical observations for a specific hostname in the "Hostnames" data source. ## Brands - [GET /api/v1/pro/availableBrands](https://docs.urlscan.io/apis/urlscan-openapi/brands/getavailablebrands.md): API Endpoint to get a list of brands that are tracked as part of urlscan's brand and phishing detection. - [GET /api/v1/pro/brands](https://docs.urlscan.io/apis/urlscan-openapi/brands/getbrandsummary.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 - [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 co ## Incidents - [POST /api/v1/user/incidents](https://docs.urlscan.io/apis/urlscan-openapi/incidents/createincident.md): Create an incident with specific options - [GET /api/v1/user/incidents/{incidentId}](https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincident.md): Get details for a specific incident. - [PUT /api/v1/user/incidents/{incidentId}](https://docs.urlscan.io/apis/urlscan-openapi/incidents/updateincident.md): Update specific runtime options of the incident - [PUT /api/v1/user/incidents/{incidentId}/close](https://docs.urlscan.io/apis/urlscan-openapi/incidents/closeincident.md): Close (stop) the 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. - [POST /api/v1/user/incidents/{incidentId}/copy](https://docs.urlscan.io/apis/urlscan-openapi/incidents/copyincident.md): Copy an incident without its history. - [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 /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 /api/v1/user/incidentstates/{incidentId}/](https://docs.urlscan.io/apis/urlscan-openapi/incidents/getincidentstates.md): Retrieve individual incident states of an incident. ## Malicious - [GET /api/v1/malicious/{type}/{value}](https://docs.urlscan.io/apis/urlscan-openapi/malicious/lookupmaliciousobservable.md): **urlscan 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 what kind of observable to query: - * ## Channels - [GET /api/v1/user/channels/](https://docs.urlscan.io/apis/urlscan-openapi/channels/listchannels.md): Get a list of notification channels for the current user. - [POST /api/v1/user/channels/](https://docs.urlscan.io/apis/urlscan-openapi/channels/createchannel.md): Create a new channel. - [GET /api/v1/user/channels/{channelId}](https://docs.urlscan.io/apis/urlscan-openapi/channels/getchannel.md): Get the search results for a specific notification channel. - [PUT /api/v1/user/channels/{channelId}](https://docs.urlscan.io/apis/urlscan-openapi/channels/updatechannel.md): Update an existing channel. ## Data Dumps - [GET /api/v1/datadump/list/{timeWindow}/{fileType}/{date}](https://docs.urlscan.io/apis/urlscan-openapi/data-dumps/listdatadumps.md): **urlscan Pro** - List available data dump files for a specific time window, file type, and date. - [GET /api/v1/datadump/link/{path}](https://docs.urlscan.io/apis/urlscan-openapi/data-dumps/getdatadumplink.md): **urlscan Pro** - Generate a temporary download link for a specific data dump file.