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. The audit log has its own, separate key.

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()

Every answer, successful or not, is a JSON object with the same three fields: results (a short description), error (empty when all is well) and data. When something goes wrong, error says what, and the HTTP status tells your tool that it failed.

Status	When
200	The call worked. Some endpoints also use 200 with a text in error for a problem with the content of your request, for example an asset that could not be added.
400	A parameter that is not allowed or out of range.
401	No API key, or an unknown or revoked one.
403	The key is valid but API access is not enabled for the account (see API Key), or the key does not cover the organization you asked for.
404	That endpoint does not exist. The answer is JSON too, not a web page.
429	Reserved for rate limiting, see below. When it is used it comes with a Retry-After header: the number of seconds to wait.

These statuses apply to API v4. Versions v1 to v3 keep answering 200 with the text in error.

Rate limits
The API does not enforce a fixed rate limit at the moment. To collect events, use since_id and poll every 15 minutes; once an hour is fine too. You do not miss anything by polling less often, because since_id continues exactly where you stopped. If a call returns as many events as your limit, there may be more: call again straight away with the new next_since_id, until a call returns fewer events than your limit. Write your client so that it waits for the number of seconds in Retry-After when it gets a 429 and then tries again, so it keeps working if limits are introduced.

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 of your events. For a SIEM or log collector, poll it with since_id (see below): every event has a unique, increasing id, so you never miss an event and never need overlapping time windows or de-duplication.

Options

Parameter	Type	Description
since_id	int	Return only events with an id greater than this, oldest first. Start with 0. Store the next_since_id from the response and send it next time. A call that returns fewer events than your limit, or an empty data list, means you are up to date. The answer also has latest_id: the highest event id your key can see, at any level. Compare it with next_since_id to see how far behind you are. Events that ShadowTrackr records late, with an older timestamp, still show up after your last since_id.
limit	int	The number of events per call. Default 1000, maximum 5000. With since_id it is the page size. On its own it returns the newest limit events, newest first. In both cases the answer also has latest_id.
update_only	bool	Only the new events since your last poll. ShadowTrackr remembers where you stopped, so a second client on the same key shares that position. updates_only and update are accepted as the same flag. Prefer since_id, which keeps the position on your side. Not available for group keys.
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"
min_level	int	Only events with a level greater than this value: min_level 90 gives 91 and up, but not 90. This is not "at least", use level_gte for that.
level_gte	int	Only events with a level greater than or equal to this value: level_gte 90 gives 90 and up. If you send both, the stricter one counts.
organization_id	int	Group keys only: only the events of this organization. Without it you get all organizations in the group.
output_format	String	"json" (default) or "cef" (ArcSight), not case sensitive. CEF has no id, no organization and no next_since_id, so use JSON with since_id for a SIEM unless you need CEF.

Which events do you get?

You send	You get
since_id	Up to limit events after that id, oldest first.
start and stop	Every event in the period. There is no 1000 event cap, so a month can be tens of thousands of events. Both ends are inclusive, to the second. The events are grouped by event type, not sorted by time.
start only	At most 1000 events after start, in no particular order. Use start and stop, or since_id, instead.
update_only	At most 5000 events since your last poll (the first call: the last month).
limit only	The newest limit events (at most 5000) of the last 6 months, newest first, and latest_id.
nothing	The latest 1000 events of the last 6 months, newest first.

Start following your events
To begin collecting without pulling your whole history, and without gaps:
1. Call the endpoint with {"limit": 1} and keep latest_id. This is your starting point, call it M0. Use latest_id and not the id of the event you got back: that is the newest event by time, and an event that ShadowTrackr records late can have a higher id.
2. Collect the past you want, for example the last 7 days, with start and stop.
3. From then on call with since_id set to M0, then to each next_since_id. Events with an id you already stored in step 2 can come back; skip them. Everything that was recorded after step 1, including what arrived while you were busy with step 2, is in this stream.
Event ids are unique, so the id is the key for skipping.

Fields of an event

Field	Description
id	Unique id of this one event. Increases over time.
timestamp	When the event was recorded, UTC.
eventid	The event type. It is the same for every event of that kind, so it does not identify a single event: use id for that.
level	Importance, higher is more important.
source	The part of ShadowTrackr that found it, e.g. ssl, hosts or websites.
msg	A description of the event. May contain <br> line breaks.
cs1	More detail, when there is any.
request, dst	The asset the event is about: a url (request) or an ip address (dst).
dpt, act, fname, outcome	Only on some event types: the port, whether it was opened or closed, a certificate field name, an outcome.
message_text	The same as msg, without HTML. A <br> becomes a line break.
asset, asset_type	The asset the event is about (a hostname, url, ip address, domain, ...) and what kind it is: url, ip, dom, cert, asn, net, mail, ...
ip	The ip address the event is about, when there is one.
port, protocol	Port events: the port, and tcp or udp. For an event that changes several ports at once, ports lists them as {"port", "state" (opened, closed or changed), "name"}, and port is only set when it is exactly one.
cert_serial	Serial number of the certificate, on certificate events.
cve	List of the CVE ids the event mentions.
old_value, new_value	For an event that is one change from X to Y: the old and the new value. A value that was added has no old_value. For events with several changes, changes lists each one as {"attribute", "old_value", "new_value"}.
grade, previous_grade	TLS grade on certificate and TLS events, and the grade before when it changed.
cvss, cvss_severity	On events that mention a CVE: the CVSS score, and its severity (critical, high, medium or low). With several CVEs it is the highest score and the severity of that CVE. Left out when the score is not known.
affected_assets	On CISA KEV and NCSC advisory events (event types 3306 and 3307): the assets of yours the event is about, as {"asset", "software", "status"}. Status is confirmed (the vulnerable software was found there) or possible (the software version is not known). An address also has ip and port, and for NCSC advisories cve lists the CVEs found there. At most 50 assets are listed: affected_assets_more says how many more there are.
action	On events that report a change: created (a port opened, a value or record added), deleted (a port closed, a value removed) or modified (a value replaced, several changes at once). For some change types it follows from the type, see event_types.
cloud_provider	The cloud provider behind the asset, when known.
link	Link to the asset in the ShadowTrackr GUI.
organization	Group keys only: {"id": ..., "name": "..."} of the organization the event belongs to.

Fields that do not apply to an event are left out, they are never null. New fields can be added to events at any time. Ignore the fields you do not know.

Group (MSSP) keys
With the API key of a group, the event feed returns the events of every organization in the group, and each event carries an organization with the id and name. Send organization_id to get one organization only; an organization that is not part of your group is refused with a 403 status. To split data per customer in a SIEM, use since_id on the group key and the organization of each event.

To list the organizations in your group, call organizations with the group key: you get the id, name and custom id of each. (With the extra groupcode you also get the API keys, see List organizations.)

The group key can read these endpoints for one organization at a time, by sending organization_id: assets, hosts, websites, certificates, dns, domains, urls, subnets, mailservers, software, vulnerabilities, cves_assets, phishy_domains, remote_login_services, exposed_email_addresses, internet_standards, cloud_providers, suppliers, suggestions, blacklisted_assets and whois. The answer then also has an organization field, next to results, error and data. Without organization_id these endpoints return nothing for a group key. Endpoints that change data (adding and deleting assets, tags and so on) and the timeline and newsfeed endpoints do not accept organization_id: use the key of the organization for those.

Endpoint: https://api.shadowtrackr.com/api/v4/event_types
The catalogue of all event types. Every event has an eventid that says what kind of event it is. Use this list to classify events in your SIEM without a hard-coded table: new event types appear here when they are added. The list is the same for every account.

Options

Parameter	Type	Description
category	String	Only the types in this category.
source	String	Only the types with this source.
eventid	int	Only this event type.

Fields

Field	Description
eventid	The event type, as in the eventid of an event.
source	The part of ShadowTrackr that normally reports this type, as in the source of an event.
name	A short name that does not change. Use it as an identifier.
title	A readable title for people, such as "Certificate renewed (problems)". Unique per type. The titles of the types that occur most are written by hand; those of the rarer ones are made from the name. The wording of a title can improve over time, so do not use it as an identifier.
category	certificate, website, host, dns, domain, network, discovery, vulnerability, phishing, breach, availability, alert or other.
default_level	The usual level of events of this type, or null when the level depends on the finding (for example on the TLS grade). The level of the event itself is what counts.
is_change	True if the event reports that something changed (opened, closed, added, removed, renewed, ...), false if it reports that something was found or is the case.
action	For a type that reports a change: created, modified or deleted, or null when the type does not say (found and down/up types). The action of an event is more precise where the event itself tells more, for instance a port bundle in which ports were both opened and closed is modified.
aliases	Only when the same eventid also has another name in the scanner.

Endpoint: https://api.shadowtrackr.com/api/v4/audit_log
The audit log records who did what in your account: logins, changes to assets, reports, alerts, users and settings, exports and more. This endpoint lets you collect it into a SIEM or log collector. See Audit Log for what is logged and who can see it. The audit log is only available on Enterprise accounts and up (the Enterprise and Reseller Enterprise plans).

This endpoint does not use your regular API key, and your regular API key can't read the audit log. It needs a separate audit log key, which an administrator creates on the Audit log page. The audit log key can read the audit log and nothing else. It is shown only once when it is created; if you lose it, replace it on the same page. A key created by a group administrator covers the whole group.

Send the key in the Authorization: Bearer [AUDIT_KEY] header. If something between you and ShadowTrackr strips that header, POST it in a JSON body as {"audit_key": "[AUDIT_KEY]"} instead. The key is never accepted in the URL, so it doesn't end up in access logs.

Lines are returned oldest first, starting after since_id. Every response includes next_since_id: store it, and send it as since_id on your next call to get only what is new. An empty data list means you are up to date. To fetch everything from the start, begin with since_id 0 and keep calling until data is empty.

Options

Parameter	Type	Description
since_id	int	Return lines with an id higher than this. Default 0 (the oldest line still kept).
limit	int	Number of lines to return, 1 to 1000. Default 500.
organization_id	int	Group keys only: return the lines of one organization in the group.

Fields

Field	Description
id	Increasing id of the line. Use the highest one you have as since_id.
time	When it happened, in UTC.
user_id, user	Who did it. API actions show user "API" and user_id 0, because API keys belong to the organization, not to a person. Deleted users show as "deleted user #id".
organization_id	The organization it happened in. 0 for group-level actions by a group administrator.
channel	Where it came from: web, app or api.
ip	IP address of the request.
category, event	What happened, e.g. auth / login_failed, asset / delete, settings / change. See What is logged.
object_type, object_id	What it happened to, e.g. url / www.example.com or report / 42.
description	A readable description of the action.

Errors: 401 for a missing, wrong or revoked key, or when the plan no longer includes the audit log. 400 for a limit outside 1 to 1000. 403 for an organization_id the key doesn't cover. Reading the audit log through the API is not itself recorded in the audit log.

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)
include_hosts	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.

Date	Change
2026-10-31	Fewer level 90+ certificate events: a certificate that was already a problem, renewed (event 1415) with the same or a better grade, is now level 60 instead of 91. "Found a certificate with problems" (event 1412) for a certificate and grade your organization already has on another asset is level 60 too. A new problem, or a grade that gets worse, keeps level 91. The events are still recorded and keep their event ids, so alerts on the event type keep matching; only the level changes. Alerts and feeds filtering on level 90 or higher will see fewer certificate events.
2026-11-01	Alert webhooks, Splunk HEC event: because Splunk discards request headers, each event now also contains delivery_id, attempt and result_index, a fixed time for all attempts of a call, and organization (or group) {id, name}. The headers X-ShadowTrackr-Delivery and X-ShadowTrackr-Attempt are unchanged.
2026-11-01	Event types: every type now has a title (readable, unique) and an action (created, modified, deleted or null). default_level is filled for more types, from production data.
2026-11-01	Event feed: new fields cvss, cvss_severity (events with a CVE), affected_assets, affected_assets_more (CISA KEV and NCSC events) and action (created, modified or deleted, on change events).
2026-11-01	Event feed: latest_id in the answer (with since_id or limit), limit on its own returns the newest events, and level_gte (greater than or equal) next to min_level (greater than). The docs now spell out that min_level is "greater than".
2026-11-01	Alert webhooks: a TLS certificate error or an invalid URL is no longer retried (it cannot fix itself) and is recorded with a clear message. Documented: certificates are verified, redirects are not followed.
2026-10-31	Event feed: every event now has a unique id. New parameters since_id and limit (with next_since_id in the response) for reliable incremental polling, and organization_id for group keys. updates_only and update are accepted as aliases for update_only. output_format is no longer case sensitive. Group keys now work on the event feed and add an organization to each event.
2026-10-31	Group (MSSP) keys: the organizations endpoint lists the id, name and custom id of the organizations in a group with just the group key. The read-only list endpoints (hosts, websites, certificates, ...) accept organization_id with a group key and add an organization field to the answer. Nothing changes for organization keys.
2026-10-31	Status codes (v4): an invalid or revoked API key now gives HTTP 401, an account without API access 403 and an unknown endpoint a JSON 404, all in the usual {results, error, data} envelope. Before, a wrong key gave 200 with an error text, and an unknown endpoint an HTML page. Code that only looks at the error field keeps working; code that treats every non-2xx status as a failure now also sees authentication problems. v1 to v3 are unchanged.
2026-10-31	New endpoint: event_types, the catalogue of event types with source, name, category, default level and whether the event is a change.
2026-10-31	Event feed: new fields message_text, asset, asset_type, ip, port, protocol, ports, cert_serial, cve, old_value, new_value, changes, grade, previous_grade, cloud_provider and link. Nothing was renamed or removed.
2026-10-31	Alert webhooks: new payload Splunk HEC event, one event per result row, for Splunk's /services/collector/event endpoint.
2026-10-31	Alert webhooks: custom HTTP headers per webhook, for example Authorization: Splunk [HEC token] to send alerts straight to Splunk's HTTP Event Collector. Header values are stored encrypted and never shown again.
2026-10-31	Alert webhooks: calls are retried (up to 3 attempts) on timeouts, connection errors, 429 and 5xx, and carry X-ShadowTrackr-Delivery and X-ShadowTrackr-Attempt headers. The request and the retry behaviour are now documented under Webhooks.
2026-10-31	Documentation: the event feed section now describes the real fields (eventid, msg, cs1, request), ordering and limits. Corrected the names of the delete_assets endpoint and its include_hosts, vulnerabilities and extract_domains parameters.

ShadowTrackr API v4

API Key

Python module

Status codes and errors

Query endpoint

Event feed

Event types

Audit log

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

Changelog