API | ShadowTrackr Documentation

You can use the API to integrate ShadowTrackr with your other tools. This is useful to automate your workflow or build custom dashboards. There are endpoints for hosts, websites, certificates, mailservers and domain data that you can use to enrich the data you already have in your other security systems. A feed of your events is available in both JSON and ArcSight CEF formats, all other endpoints only support JSON.

All returned JSON data will have the following structure:


{ results: "a string that describes what happened if the call to the endpoints was successful",
  data: [{"fields": "with",
         "your": "data"}
        ],
  error: "an error message if something went wrong"

If you are looking for the old documentation (please don't), look at API Version 3.

If you want to use the API, make sure you've enabled it under Settings->API access. This is also where you’ll find your API key. API access is only available to Business and Enterprise subscriptions.

Note that you don't need API access to use the webhooks. ShadowTrackr will happily process any alert through a webhook for you, but there might be rate limits at some point in the future if this is eating too many resources.

The easiest way to get started is by using the ShadowTrackr Python module. For any other language you can use the endpoints as described below.

Installation


    pip install shadowtrackr

Usage


    from shadowtrackr import ShadowTrackr
    import json

    st = ShadowTrackr(api_key="[API_KEY]")

    result = st.query("index=hosts problem=yes earliest=-10d")
    print(json.dumps(result, indent=2))

The current version of the python module uses the v4 API. If you updated the module with pip but your code still uses the v3 api, please do the following after initialization and you will be fine:


    st = ShadowTrackr(api_key="[API_KEY]")
    st.set_api_v3()

Endpoint: https://api.shadowtrackr.com/api/v4/query

From version 3 of the API you can use any query that works in the GUI, including the magic queries. For more information on how to make queries, please see Query syntax and Data Model. The returned data is a JSON formatted list of your search results. The exact structure depends on your query, just like in the GUI.

If you have a group account, query results will include an "organization" field showing which organization each result belongs to. You can also filter by organization name, e.g. index=hosts organization="My Organization".

All other endpoints are shortcuts that directly get data from the most used indexes. They often show more data fields than a standard query. This is because queries are designed to show you the most useful fields only and hide anything that clutters the screen. You can have queries show more columns, but you have to explictly select that. All other endpoints here are designed for API queries where you just want a bunch of useful data.

Endpoint: https://api.shadowtrackr.com/api/v4/events
This endpoint provides a stream with all your events. The endpoint by will always return the last 1000 messages. If you only want the updates this is not fun to parse, set updates_only to True.

Options

Parameter	Type	Description
update_only	bool	If set to True, only the new events since your last poll will be returned.
start	Timestamp	Start of the time period you want events for in UTC, e.g. "2026-03-13T10:00:00"
stop	Timestamp	End of the time period you want events for in UTC, e.g. "2026-03-13T12:00:00"
output_format	String	"JSON" (default) or "CEF" (Arcsight)

Endpoint: https://api.shadowtrackr.com/api/v4/mailservers

This will return a list of all the mailservers we found in your DNS MX or SPF records. Only data from the last 7 days is returned, if you want to list historical data you can do that through the query endpoint. You can use it to check against firewall or netflow logs to find out if any non published mailservers are sending mail. This should expose the spammers and phishers in your network.

Endpoint: https://api.shadowtrackr.com/api/v4/hosts

If you don't provide any of the optional parameters, all hosts seen in the last 7 days will be returned. You can add an ip address (ipv4 or ipv6) as an optional parameter.

Options

Parameter	Type	Description
ip	str	The ip address of the host you want data for
full	bool	If set to True, some extra data fields will be returned

Endpoint: https://api.shadowtrackr.com/api/v4/websites
If you don't provide any of the optional parameters, all websites seen in the last 7 days will be returned. You can add an ip address (ipv4 or ipv6), url ("www.shadowtrackr.com") or domain ("shadowtrackr.com") as optional parameters. Note that if a url has both an ipv4 and and ipv6 version you should see both returned.

Options

Parameter	Type	Description
url	str	The url of the website you want data for
domain	str	The domain of the websites you want data for
ip	str	The ip address of the websites you want data for
full	bool	If set to True, some extra data fields will be returned

Endpoint: https://api.shadowtrackr.com/api/v4/certificates

If you don't provide any of the optional parameters, all certificates seen in the last 7 days will be returned. You can add an ip address (ipv4 or ipv6), url ("www.shadowtrackr.com") or a domain ("shadowtrackr.com") as optional parameters. Note that if a url has both an ipv4 and and ipv6 version you should see both returned.

Options

Parameter	Type	Description
url	str	The url of the certificates you want data for
domain	str	The domain of the certficates you want data for
ip	str	The ip address of the certificate you want data for
full	bool	If set to True, some extra data fields will be returned

Endpoint: https://api.shadowtrackr.com/api/v4/dns

If you don't provide any of the optional parameters, all DNS records we seen for your urls and domains in the last 7 days will be returned. You can add an optional url ("shadowtrackr.com"), rrtype (A, AAAA, MX, TXT, NS) or rrdata ("139.162.198.183", "SPF") as optional parameters.

Options

Parameter	Type	Description
url	str	The url of the DNS records you want data for
rrdata	str	The content (rrdata) of the DNS records you want data for
rrtype	str	The record type (rrtype:A, AAAA, MX, SOA, etc) of DNS records you want data for

Domains

Endpoint: https://api.shadowtrackr.com/api/v4/domains

If you don't provide any of the optional parameters, all domain records we have for your domains seen in the last 7 days will be returned. You can add an optional domain ("shadowtrackr.com") to search for a specific domain.

Options

Parameter	Type	Description
domain	str	The domain you want data for

Endpoint: https://api.shadowtrackr.com/api/v4/urls

If you don't provide any of the optional parameters, all urls we have seen in the last 7 days will be returned. You can add a keyword (wildcard * is allowed: "shadowtrackr.com") as optional parameter.
This example query will return the urls we have for the domain shadowtrackr.com (which matches the wildcard).

Options

Parameter	Type	Description
url	str	The url you want data for

Endpoint: https://api.shadowtrackr.com/api/v4/subnets

If you don't provide any of the optional parameters, all your subnets will be returned (including those seen longer than 7 days ago. You can add a cidr (wildcard * is allowed: "1.1.1.*/27") as optional parameter.

Options

Parameter	Type	Description
cidr	str	The cidr (10.0.0.0/16) of the subnet you want data for

Endpoint: https://api.shadowtrackr.com/api/v4/cloud_providers

This endpoint will return all cloud providers we have seen for your assets in the last 7 days.

Endpoint: https://api.shadowtrackr.com/api/v4/remote_login_services

This endpoint will return all remote login services we have seen on your assets in the last 7 days.

Phishy domains

Endpoint: https://api.shadowtrackr.com/api/v4/phishy_domains

Phishy domains are domain names that resemble your domain name (think of typosquatting) and can be used for phishing. If you don't provide the optional domain, data for all phishy domains seen in the last 7 days will be returned.

Options

Parameter	Type	Description
domain	str	The domain you want the phishy domain data for

Endpoint: https://api.shadowtrackr.com/api/v4/exposed_email_addresses

If you don't provide any of the optional parameters, all email addresses seen in the last 7 days will be returned. You can add an email address (wildcard * is allowed) as optional parameter.

Options

Parameter	Type	Description
email	str	The email address you want data for

Endpoint: https://api.shadowtrackr.com/api/v4/suggestions

This will return all your current suggestions. ShadowTrackr will try to determine if an asset found in the discovery process is yours. If we are sure, it will be automatically added. If not, it will appear in your suggestions and you can decide for yourself.

Endpoint: https://api.shadowtrackr.com/api/v4/blacklisted_assets

If you don't provide any of the optional parameters, all blacklisted assets we have for you will be returned. You can add an ip or url (wildcard * is allowed) as optional parameter.
This example query will return all ip addresses (wildcard matches all ips, but no urls) that are or have been blacklisted in the last 7 days. Ip addresses will have a description, urls do not.

Options

Parameter	Type	Description
ip	str	The ip address you want data for
url	str	The url you want data for

Endpoint: https://api.shadowtrackr.com/api/v4/software

This provides an overview of all software found on your external attack surface and seen in the last 7 days. It's grouped by software category with a tally for how often the software is found and shows if any CVEs are known for the software.

Endpoint: https://api.shadowtrackr.com/api/v4/vulnerabilities

This provides an overview of all vulnerabilities found on your external attack surface and seen in the last 7 days. It's grouped by software and shows which assets are affected and which CVEs are known for the software.

Options

Parameter	Type	Description
exploited	str	Show only vulnerabilities that are exploited
cisa	bool	Show only vulnerabilities that are listed in the CISA KEV

Endpoint: https://api.shadowtrackr.com/api/v4/suppliers

The endpoint will return all suppliers that have been seen in the last 7 days. Suppliers can be ISPs, Certificate Authorities, Domain registrars, software suppliers, etc.

Endpoint: https://api.shadowtrackr.com/api/v4/internet_standards

This endpoint will return the data for items from the Internet Standards checks. The same checks as on internet.nl are done, although some are implemented differently.

Endpoint: https://api.shadowtrackr.com/api/v4/cves_assets

This endpoint returns a denormalized list of all vulnerabilities seen on your assets in the last 7 days. Each output item contains one CVE and one asset.

Endpoint: https://api.shadowtrackr.com/api/v4/assets

This endpoint gives you the amount of assets you currently have. It also has the number of suggestions.

Endpoint: https://api.shadowtrackr.com/api/v4/add_assets

This will (bulk) add assets. You can mix and match urls, ips and subnets.

If you add the optional extract_domains flag then all pay level domains will automatically be extracted from subdomains and added too. So, to domain "shadowtrackr.com" will be extracted from "www.shadowtrackr.com" in the example and added. After this Shadowtrackrs discovery function will start finding and monitoring more subdomains of shadowtrackr.com.
If you leave the optional extract_domains flag out, then by default it is of and no domains will be extracted.

Options

Parameter	Type	Description
assets	list of str	A list of urls, ip addresses and/or subnets you want to add
extract_domains	bool	If True, domains will be extracted from urls and added too

Endpoint: https://api.shadowtrackr.com/api/v4/delete_assets

This will (bulk) delete assets. You can mix and match urls, ips and subnets.

Options

Parameter	Type	Description
assets	list of str	A list of urls, ip addresses and/or subnets you want to add
timeline	bool	If True, deletes all messages on the timeline that relate to the deleted assets
related	bool	If True, deletes all related assets (like dns records, certificates, etc)
invclude	bool	If True, deletes all hosts in a subnet too (if you are deleting a subnet)

Endpoint: https://api.shadowtrackr.com/api/v4/add_tags

This will add all listed tags to all assets mentioned. You can mix and match urls, ips and subnets in the asset list.
There is an optional inherit flag that is True by default. If true, all hosts in a subnet will inherit tags you add to the subnet and all websites, certificates and domains will inherit the tag from a url. If you don't want this you should set the inherit to False like in the example.

Options

Parameter	Type	Description
assets	list of str	A list of urls, ip addresses and/or subnets you want to add the tags to
tags	list of str	A list of tags you want to add to the assets
inherit	bool	If True, all hosts in a subnet will inherit tags you add to the subnet and all websites, certificates and domains will inherit the tag from a url

Endpoint: https://api.shadowtrackr.com/api/v4/delete_tags

This will delete all listed tags from all assets mentioned. You can mix and match urls, ips and subnets in the asset list.
There is an optional inherit flag that is True by default. If true, all tags mentioned will be deleted from the hosts in a subnet too if your remove them from a subnet. Similarly, tags will be removed from all websites, certificates and domains for a url if you remove them from a url. If you don't want this you should set the inherit to False like this:

Options

Parameter	Type	Description
assets	list of str	A list of urls, ip addresses and/or subnets you want to remove the tags from
tags	list of str	A list of tags you want to remove from the assets
inherit	bool	If True, all tags mentioned will be deleted from the hosts in a subnet too if your remove them from a subnet

Endpoint: https://api.shadowtrackr.com/api/v4/ignore_urls

This will ignore all urls you specify. If you add extra options, these will be used for all urls listed.
This endpoint has extra options:

"ignore_subdomains": true
Sets the ignore flag for any existing and newly found subdomains of the urls listed too (default: true).

Options

Parameter	Type	Description
urls	list of str	A list of urls to ignore
ignore_subdomains	bool	If True, any existing and newly found subdomains of the urls listed too

Endpoint: https://api.shadowtrackr.com/api/v4/unignore_urls

This will ignore all urls you specify. If you add extra options, these will be used for all urls listed.

This endpoint has extra options:

"unignore_subdomains": true
Also removes the ignore flag for subdomains (default: true).

Options

Parameter	Type	Description
urls	list of str	A list of urls to unignore
unignore_subdomains	bool	If True, the ignore flag for subdomains is removed too

Endpoint: https://api.shadowtrackr.com/api/v4/delete_all_my_data

This will delete all your data. Everything. So only use this if you want to start over with a clean account.
Include_settings is true by default, and will delete all your settings (API keys for integrations, trusted CA roots, etc.) too.

Note that you'll need an extra [ADMINCODE] for this to work. The admin code can be found on the Settings->API access page if you are an admin. If you're not an admin, you'll have to ask one.

Endpoint: https://api.shadowtrackr.com/api/v4/initial_scan_progress

If you can't wait to play with the API but don't know if you're data is ready yet, you can use the endpoint to check the scan status. If total_assets is bigger than zero and scan_activity_in_last_5m is nearing zero (preferably zero), then your initial scan is done. See the Python API on Github for a working example. This endpoint has no parameters other then the api_key. Example:

{"api_key": "[API_KEY]"}

This example query will return how many assets you have and how many new things were found in the last five minutes.

You can get the graphs from the GUI in two ways: as an HTML rendered page that you can embed in a website, or as raw JSON data.

The HTML rendered graph is available at this endpoint:
https://api.shadowtrackr.com/api/v4/usergraphs

The JSON data is available at:
https://api.shadowtrackr.com/api/v4/usergraphs_data

For both endpoints, you get the default configured Attack Surface graph. It is possible to get other, custom graphs that you have created in the GUI. To do this, lookup the GID (Graph ID) in the GUI and add it to the endpoint url. For example, if your GID is 13, then add &gid=13 to get that graph. The default color scheme has a white background. If you rather have it dark, then add &darkmode=1 to the endpoint url.

The JSON data returned by usergraphs_data is returned as a list of nodes, follow by a list of links (or "edges") between those nodes. This is what you need if you're creating your own force-directed graph. The nodes have a label with the URL, IP or ASN information and a group. The group is what determines the color of the node in the graph:

Group	Color	Meaning
1	● #5659B1	ASN/ISP
2	● #46AF80	Host
3	● #477DA3	URL
5	● #000	Cloud
100	● #F70A03	Problem
101	● #FF8300	Warning

Endpoint: https://api.shadowtrackr.com/api/v4/scannernode_ip_addresses

If you need to whitelist the IP addresses of the shadowtrackr nodes in your firewall, it is best to automate it using this endpoint. Nodes ip addresses can change at any time.

Endpoint: https://api.shadowtrackr.com/api/v4/ip_info

This endpoint provides some common info on IP addresses that are used in ShadowTrackr. It has data on clouds, IANA ranges, common DNS servers, VSAT ranges, VPNs, residential IP addresses, and some more.
We still intent to further develop this, but since it can be useful to prevent false positives when processing IoC lists and generating ip blocklist, the data we have is now available.

The custom ID is an optional field (named "custom_id") in hosts and urls that allows you to set your own ID. This is useful if you want to link ShadowTrackr assets to your own internal asset management system.
It's an indexed text field and can be anything you want: a UUID, a number, a name, etc. The ID does not have to be a unique value per asset, so if you have a server with multiple ip addresses and urls you can give it the same custom ID.

Although the custom ID cannot be set in the GUI, it can be used in queries (GUI and API) and will be shown on asset pages. You can add or delete custom IDs through the API, it's available from v4.

Endpoint: https://api.shadowtrackr.com/api/v4/add_custom_id

You can use this endpoint to set a custom_id on either an orgnization or a list of assets. The code example is for assets, just replace the assets field with organization and the value with the name of the orgnization if you want to set a custom_id on that. Note that it might be easier to set the custom_id on creation of the orgnization, see the endpoint add_organization. You can mix and match urls and ips in the asset list. There is an optional inherit flag that is True by default. If true, all websites, certificates and domains will inherit the tag from a url. If you don't want this you should set the inherit to False. The inherit flag is not used for organizations.

Options

Parameter	Type	Description
assets	list of str	A list of urls and/or ip addresses you want to add the custom ID to
custom_id	str	The custom ID (any string, does not have to be unique)
inherit	bool	If True, all websites, certificates and domains will inherit the tag from a url

Endpoint: https://api.shadowtrackr.com/api/v4/delete_custom_id

You can use this endpoint to delete a custom_id from either an organization or a list of assets. The code example is for assets, just replace assets with organization and set the organization name as the value to delete its custom_id. You can mix and match urls and ips in the asset list. There is an optional inherit flag that is True by default. If true, the custom ID will be removed from all websites, certificates and domains related to the url. The inherit flag is not used for organizations.

Options

Parameter	Type	Description
assets	list of str	A list of urls and ip addresses you want to remove the custom ID from
custom_id	str	The custom ID you want to remove
inherit	bool	If True, the custom ID will be removed from domains, websites and certificates related to the url

Endpoint: https://api.shadowtrackr.com/api/v4/add_organization
This endpoint is only for multi-tenant users. It allows you to create an organization in your group. The organization is isolated from any other organizations in the group. The API endpoint returns the API key and admin code, so you can use it like any other organization.
There is an option to set a custom_id on creation, just leave it out if you don't want to set one. The custom_id is a string value that can be anything you want.
.

Note that by default the API is always enabled when creating an organization through the API.

Endpoint: https://api.shadowtrackr.com/api/v4/organizations
This endpoint is only for multi-tenant users. It shows a list of currently active organizations in your group. It returns the active organization names and IDs.

Endpoint: https://api.shadowtrackr.com/api/v4/delete_organization
This endpoint is only for multi-tenant users. It completely deletes the organization specified.

ShadowTrackr API v4

API Key

Python module

Query endpoint

Event feed

Mailservers

Hosts

Websites

Certificates

DNS

Domains

Urls

Subnets

Cloud providers

Remote login services

Phishy domains

Exposed email addresses

Suggestions

Blacklisted assets

Software

Vulnerabilities

Suppliers

Internet Standards

CVEs assets

Assets

Add assets

Delete assets

Add tags

Delete tags

Ignore urls

Unignore urls

Delete all my data

Initial scan progress

Get graphs

Scannernode IP addresses

Ip info

Custom ID

Add Custom ID

Delete Custom ID

Add organization

List organizations

Delete organization