Skip to content
/Saved Searches

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.

Download OpenAPI description
urlscan-openapi.json
urlscan-openapi.yaml
Overview
urlscan Support
support@urlscan.io
Languages
Servers
https://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

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

Saved Searches

urlscan Pro - Saved Searches are rules that are executed inline against new incoming scans and hostnames.

Operations

Saved Searches

Request

Get a list of Saved Searches for the current user.

Security
apikeyAuth(Required scopes:
read
write
)
curl -i -X GET \
  https://urlscan.io/api/v1/user/searches/ \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Successful response

Bodyapplication/json
searchesArray of objects(savedSearchResponse)
Example: [{"_id":"{{searchId}}","datasource":"scans","query":"page.domain:urlscan.io","name":"Testsearch","description":"urlscan documentation example saved search.","longDescription":"Example saved search created from urlscan documentation","tlp":"red","userTags":["private.privatetag"],"permissions":["team:read","team:write"]}]
Response
application/json
{
  "searches": [
    { … }
  ]
}

Create Saved Search

Request

Create a Saved Search.

Security
apikeyAuth(Required scopes:
read
write
)
Bodyapplication/json
searchobjectrequired
Example: {"datasource":"scans","query":"page.domain:urlscan.io","name":"Testsearch","description":"urlscan documentation example saved search.","longDescription":"Example saved search created from urlscan documentation.","tlp":"red","userTags":["private.privatetag"],"permissions":["team:read","team:write"]}
search.​datasourcestringrequired

Which data this Saved Search operates on.

Enum"hostnames""scans"
Example: "scans"
search.​descriptionstring

Short description.

Example: "urlscan documentation example saved search."
search.​longDescriptionstring

Long description.

Example: "Example saved search created from urlscan documentation."
search.​namestringrequired

User-facing short name.

Example: "Testsearch"
search.​permissionsArray of strings

Determine whether only other users on the same team or everyone on urlscan Pro can see the search.

Items Enum"public:read""team:read""team:write"
Example: ["team:read","team:write"]
search.​querystringrequired

Search API query

Example: "page.domain:urlscan.io"
search.​tlpstring

TLP (Traffic Light Protocol) indicator for other users on the urlscan Pro platform.

Enum"red""amber+strict""amber""green""clear"
Example: "red"
search.​usertagsArray of strings

User-supplied tags to be applied to matching items. Apply the following prefixes to tags to define their visibility scope: pro. (urlscan Pro users), public. (all registered users), private. (only you), or team. (you and team members).

curl -i -X POST \
  https://urlscan.io/api/v1/user/searches/ \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "search": {
      "datasource": "scans",
      "query": "page.domain:urlscan.io",
      "name": "Testsearch",
      "description": "urlscan documentation example saved search.",
      "longDescription": "Example saved search created from urlscan documentation.",
      "tlp": "red",
      "userTags": [
        "private.privatetag"
      ],
      "permissions": [
        "team:read",
        "team:write"
      ]
    }
  }'

Responses

OK

Bodyapplication/json
searchobject(savedSearchResponse)
Example: {"_id":"{{searchId}}","datasource":"scans","query":"page.domain:urlscan.io","name":"Testsearch","description":"urlscan documentation example saved search.","longDescription":"Example saved search created from urlscan documentation","tlp":"red","userTags":["private.privatetag"],"permissions":["team:read","team:write"]}
Response
application/json
{
  "search": {
    "_id": "{{searchId}}",
    "datasource": "scans",
    "query": "page.domain:urlscan.io",
    "name": "Testsearch",
    "description": "urlscan documentation example saved search.",
    "longDescription": "Example saved search created from urlscan documentation",
    "tlp": "red",
    "userTags": [ … ],
    "permissions": [ … ]
  }
}

Update Saved Search

Request

Update a Saved Search.

Security
apikeyAuth(Required scopes:
read
write
)
Path
searchIdstringrequired
Example: {{searchId}}
Bodyapplication/json
searchobjectrequired
Example: {"datasource":"scans","query":"page.domain:urlscan.io","name":"Testsearch","description":"urlscan documentation example saved search.","longDescription":"Example saved search created from urlscan documentation.","tlp":"red","userTags":["private.privatetag"],"permissions":["team:read","team:write"]}
search.​datasourcestringrequired

Which data this Saved Search operates on.

Enum"hostnames""scans"
Example: "scans"
search.​descriptionstring

Short description.

Example: "urlscan documentation example saved search."
search.​longDescriptionstring

Long description.

Example: "Example saved search created from urlscan documentation."
search.​namestringrequired

User-facing short name.

Example: "Testsearch"
search.​permissionsArray of strings

Determine whether only other users on the same team or everyone on urlscan Pro can see the search.

Items Enum"public:read""team:read""team:write"
Example: ["team:read","team:write"]
search.​querystringrequired

Search API query

Example: "page.domain:urlscan.io"
search.​tlpstring

TLP (Traffic Light Protocol) indicator for other users on the urlscan Pro platform.

Enum"red""amber+strict""amber""green""clear"
Example: "red"
search.​usertagsArray of strings

User-supplied tags to be applied to matching items. Apply the following prefixes to tags to define their visibility scope: pro. (urlscan Pro users), public. (all registered users), private. (only you), or team. (you and team members).

curl -i -X PUT \
  'https://urlscan.io/api/v1/user/searches/{{searchId}}/' \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "search": {
      "datasource": "scans",
      "query": "page.domain:urlscan.io",
      "name": "Testsearch",
      "description": "urlscan documentation example saved search.",
      "longDescription": "Example saved search created from urlscan documentation.",
      "tlp": "red",
      "userTags": [
        "private.privatetag"
      ],
      "permissions": [
        "team:read",
        "team:write"
      ]
    }
  }'

Responses

OK

Bodyapplication/json
searchobject(savedSearchResponse)
Example: {"_id":"{{searchId}}","datasource":"scans","query":"page.domain:urlscan.io","name":"Testsearch","description":"urlscan documentation example saved search.","longDescription":"Example saved search created from urlscan documentation","tlp":"red","userTags":["private.privatetag"],"permissions":["team:read","team:write"]}
Response
application/json
{
  "search": {
    "_id": "{{searchId}}",
    "datasource": "scans",
    "query": "page.domain:urlscan.io",
    "name": "Testsearch",
    "description": "urlscan documentation example saved search.",
    "longDescription": "Example saved search created from urlscan documentation",
    "tlp": "red",
    "userTags": [ … ],
    "permissions": [ … ]
  }
}

Delete Saved Search

Request

Delete a Saved Search

Security
apikeyAuth(Required scopes:
read
write
)
Path
searchIdstringrequired
Example: {{searchId}}
curl -i -X DELETE \
  'https://urlscan.io/api/v1/user/searches/{{searchId}}/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
object
Response
application/json
{}

Saved Search Search Results

Request

Get the search results for a specific Saved Search.

Security
apikeyAuth(Required scopes:
read
write
)
Path
searchIdstringrequired
Example: {{searchId}}
curl -i -X GET \
  'https://urlscan.io/api/v1/user/searches/{{searchId}}/results/' \
  -H 'api-key: YOUR_API_KEY_HERE'

Responses

Successful response

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

Channels

Operations

Data Dumps

Operations