Detectify logo Switch to V3 documentation
API docs by Redocly

Detectify API (2.4.0)

Download OpenAPI specification:Download

Detectify API

This page contains the documentation for the Detectify API accessible at https://api.detectify.com.

The Detectify API enables connectivity and automation through a RESTful interface with the following features:

The API can be accessed using an API key. API keys can be managed using the API-keys page. For more details, see authentication. Depending on your subscription, some API functions may not be available.

Examples

Please have a look at our example implementations of the API if you need help to get started. You can find them on our GitHub page.

Authentication

All HTTP messages must be authenticated using the API key generated on the API-keys page. For additional security, the API also allows signing the messages based on the secret key specified for the API key.

You can specify the API key in the following ways:

  • HTTP Authentication using your API key as username (BASE64 encoded):

    GET /rest/v2/assets/ HTTP/1.1
Host: api.detectify.com
Authorization: Basic MTA4NDBiMGY5Mzg5NDJmZWFmYjcxODZkZTc0Yjk2ODI6

  • Using the X-Detectify-Key HTTP header:

    GET /rest/v2/assets/ HTTP/1.1
Host: api.detectify.com
X-Detectify-Key: 10840b0f938942feafb7186de74b9682

  • Include in URL:

    https://10840b0f938942feafb7186de74b9682@api.detectify.com/rest/v2/assets/

If you created a secret key for the API key, you need to include the message signature in the request using the X-Detectify-Signature HTTP header, and the time of message creation in Unix time using the X-Detectify-Timestamp HTTP header:

GET /rest/v2/assets/ HTTP/1.1
Host: api.detectify.com
X-Detectify-Key: 10840b0f938942feafb7186de74b9682
X-Detectify-Signature: 6jpu6S4cQwEY4uLk+xELSe1RhajVJP0QEDpGWZ5T+U0=
X-Detectify-Timestamp: 1519829567

Messages with a timestamp older than 10 seconds before the time of receiving the message, or newer than 5 seconds after the time of receiving the message will result in an authentication error.

The signature is a BASE64 hash value using the keyed-hash message authentication code (HMAC) with the SHA-256 compression function. The encryption uses the secret key specified in the settings (with BASE64 encoding). The input for the hash function is a semicolon-separated combination of

  • the HTTP method (capitalized, e.g., GET),
  • the relative URL path after https://api.detectify.com/rest (e.g., /v2/domains/),
  • the API key,
  • the UNIX timestamp specified in the X-Detectify-Timestamp header, and
  • the request body (left empty for requests without body).

Schema:

key = BASE64_DECODE({secret key})
value = {HTTP method};{relative URL};{API key};{timestamp};{request body}
signature = BASE64_ENCODE(HMAC_SHA256(key, value))

Example:

  • HTTP request GET https://api.detectify.com/rest/v2/domains/
  • at 2018-02-28T14:52:47Z, which is UNIX timestamp 1519829567
  • for API key 10840b0f938942feafb7186de74b9682
  • with secret key 0vyTnawJRFn0Q9tWLTM188Olizc72JczHSXoIlsPQIc=
  • generates message signature 6jpu6S4cQwEY4uLk+xELSe1RhajVJP0QEDpGWZ5T+U0=.
key = BASE64_DECODE("0vyTnawJRFn0Q9tWLTM188Olizc72JczHSXoIlsPQIc=")
value = "GET;/v2/domains/;10840b0f938942feafb7186de74b9682;1519829567;"
signature = BASE64_ENCODE(HMAC_SHA256(key, value))

Manage assets

Asset inventory allows managing assets, such as domains and IP addresses.

Assets can be identified by the domain token and the asset UUID. The domain token only exists for assets and IPs that were manually added. The asset UUID exists also for autodiscovered subdomains and can be used to manage owners.

The asset information contains the domain name or IP address, status (indicating whether the asset is verified), creation/update time, owner and whether Surface Monitoring is enabled.

Get root assets

Subdomains may also be retrieved if the optional query parameter include_subdomains is set to true.

To only retrieve assets created after a certain date, send in a timestamp in the query parameter from.

Returns an object containing an array of root assets for the team and pagination metadata(current marker, next marker, has more).

If the team has no assets, the response contains an empty object.

Timestamps are in YYYY-MM-DDTHH:mm:ssZ format (ISO 8601, UTC).

query Parameters
marker
string
Example: marker=60a0fae258d2c952765e81054929c8e6a6fdbdf77

Used to query next batch of assets.

pageSize
integer <int64>
Example: pageSize=20

Sets the maximum amount of assets in one response.

from
string
Example: from=YYYY-MM-DDTHH:mm:ssZ

Only return assets created after given date.

include_subdomains
boolean

Include subdomains in result. When set all asset regardless of place in the hierarchy will be returned.

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "current_marker": "0ea80070-5066-441c-ae58-10fd0076d4cb",
  • "has_more": true,
  • "next_marker": "fc6159c1-b877-4462-96f5-c01a4261135d"
}

Add asset

Adds a new asset for the team for the specified domain name or IP address. In case of domains the domain name can be a second level domain or subdomain. Optionally, you can specify a port number for the asset that will be used for asset verification. The call returns information about the newly created asset including the generated asset token and status.

Note: If your asset contains non-standard characters, make sure you punycode the name in advance

Request Body schema: application/json
name
string

Domain (subdomain) name, IP address

Responses

Request samples

Content type
application/json
{
  • "name": "example.com"
}

Response samples

Content type
application/json
{
  • "added_by": [
    ],
  • "created": "2021-07-27T10:19:38.014447Z",
  • "discovered": "2021-07-27T10:19:38.014447Z",
  • "last_seen": "2021-07-27T10:19:38.014447Z",
  • "monitored": false,
  • "name": "example.com",
  • "status": "string",
  • "token": "fc6159c1-b877-4462-96f5-c01a4261135d",
  • "updated": "2021-07-27T10:19:38.014447Z"
}

Delete asset

Deletes the asset identified by the asset token. The asset token can be retrieved using Get root assets.

path Parameters
assetToken
required
string
Example: 60a0fae258d2c952765e81054929c8e6a6fdbdf77

Asset token

Responses

Response samples

Content type
application/json
{}

Get subdomains

Retrieves subdomains for the root asset identified by the asset token. The asset token can be retrieved using Get root assets.

The response includes

  • manually added subdomains (tagged manual with general asset information) and
  • subdomains discovered using our internal scanners (with information about the way it was discovered and with discovery times).
path Parameters
assetToken
required
string
Example: 60a0fae258d2c952765e81054929c8e6a6fdbdf77

Asset token

query Parameters
marker
string
Example: marker=60a0fae258d2c952765e81054929c8e6a6fdbdf77

Used to query next batch of assets.

pageSize
integer <int64>
Example: pageSize=20

Sets the maximum amount of assets in one response.

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "current_marker": "0ea80070-5066-441c-ae58-10fd0076d4cb",
  • "has_more": true,
  • "next_marker": "fc6159c1-b877-4462-96f5-c01a4261135d"
}

Manage asset settings

Get asset settings

Gets the asset settings for an asset identified by the domain token. The domain token can be retrieved using Get root assets.

path Parameters
domainToken
required
string
Example: 60a0fae258d2c952765e81054929c8e6a6fdbdf77

Domain token

Responses

Response samples

Content type
application/json
{
  • "brute_force": true,
  • "custom_headers": {
    },
  • "enable_active_tls_assessments": true,
  • "enable_certificate_assessments": true,
  • "enable_passive_tls_assessments": true,
  • "enable_port_scanning": true,
  • "enable_tls_discovery": true,
  • "fingerprinting": true,
  • "include_discovered_ports_in_surface_monitoring": true,
  • "monitoring": true,
  • "port_scanning_avoid_list": [ ],
  • "port_scanning_force_list": [ ],
  • "port_scanning_include_recommended_ports": true,
  • "requests_per_second": 0,
  • "scrape": true,
  • "ssl_audit": true,
  • "stateless_tests": true,
  • "subdomain_takeover_tests": true
}

Update asset settings

Updates the asset settings for an asset identified by the domain token. The domain token can be retrieved using Get root assets.

path Parameters
domainToken
required
string
Example: 60a0fae258d2c952765e81054929c8e6a6fdbdf77

Domain token

Responses

Response samples

Content type
application/json
{
  • "brute_force": true,
  • "custom_headers": {
    },
  • "enable_active_tls_assessments": true,
  • "enable_certificate_assessments": true,
  • "enable_passive_tls_assessments": true,
  • "enable_port_scanning": true,
  • "enable_tls_discovery": true,
  • "fingerprinting": true,
  • "include_discovered_ports_in_surface_monitoring": true,
  • "monitoring": true,
  • "port_scanning_avoid_list": [ ],
  • "port_scanning_force_list": [ ],
  • "port_scanning_include_recommended_ports": true,
  • "requests_per_second": 0,
  • "scrape": true,
  • "ssl_audit": true,
  • "stateless_tests": true,
  • "subdomain_takeover_tests": true
}

Application Scan Profiles

An Application Scan Profile represents the target of a Application Scanning. Application Scan Profiles are associated with assets and have various settings that influence Application Scanning behavior.

Get Application Scan Profiles

Returns an array of all Application Scan Profiles for the team.

If the team has no Application Scan Profiles, the response contains an empty array.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Application Scan Profile

Adds a new Application Scan Profile using the specified endpoint and name. You can add an Application Scan Profile to an existing, verified root asset, which is specified by the asset token.

Request Body schema: application/json
asset_token
string

The token of the root asset on which the scan profile is created.

endpoint
string

The endpoint of the scan profile.

name
string

The name of the scan profile. If you do not provide the scan profile name, the endpoint will be used as scan profile name.

Responses

Request samples

Content type
application/json
{
  • "asset_token": "string",
  • "endpoint": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "endpoint": "string",
  • "latest_scan": {
    },
  • "name": "string",
  • "token": "string"
}

Get Application Scan Profiles for asset

Returns all Application Scan Profiles for the asset identified by the asset token. The asset token can be retrieved using Get root assets.

If the asset has no Application Scan Profiles, the response contains an empty array.

path Parameters
assetToken
required
string
Example: 9cf53dabf7e213189c89587db33c9cfa

The asset token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove Application Scan Profile

Removes the Application Scan Profile specified by the scan profile token. The scan profile token can be retrieved using Get Application Scan Profiles.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Responses

Response samples

Content type
application/json
{}

Application Scan Profile settings

Get Application Scan Profile settings

Returns settings for the Application Scan Profile specified by the scan profile token. The scan profile token can be retrieved using Get Application Scan Profiles.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Responses

Response samples

Content type
application/json
{
  • "basic_auth": {
    },
  • "blacklisted_paths": [
    ],
  • "blacklisted_ports": [
    ],
  • "blacklisted_subdomains": [
    ],
  • "crawl_subdomains": true,
  • "custom_cookies": [
    ],
  • "custom_headers": [
    ],
  • "report_lifespan_days": 0,
  • "requests_per_second": 0,
  • "scan_common_ports": true,
  • "scan_region": "string",
  • "session_cookie": {
    },
  • "whitelisted_paths": [
    ],
  • "whitelisted_ports": [
    ]
}

Update Application Scan Profile Settings

Updates settings for the Application Scan Profile specified by the scan profile token and returns the updated settings. The scan profile token can be retrieved using Get Application Scan Profiles.

You can update each value individually by specifying the setting in the request body. The update does not affect settings that are not present in the request body. The maximum allowed request body size is 30 KB.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Request Body schema: application/json
object (BasicAuthentication)

BasicAuthentication represents information for basic authentication

blacklisted_paths
Array of strings

The array of paths the scan should avoid. The list should only the relative path of the URL, e.g., /secret/path/of/page.php instead of https://www.example.com/secret/path/of/page.php. To remove all blacklisted paths send an empty array.

blacklisted_ports
Array of integers <int64> [ items <int64 > ]

The array of ports the scan should avoid. To remove all blacklisted ports send an empty array.

blacklisted_subdomains
Array of strings

The array of subdomains that the scan should avoid. The list should only contain the subdomain part, e.g., blog instead of blog.example.com. To remove all blacklisted domains send an empty array.

crawl_subdomains
boolean

Indicates whether to follow any links we find during crawling to discover subdomains.

Array of objects (ScanProfileCookie)

The array of custom cookies the Application Scanning should send with every request. Cookies must have specified name and value with optional secure and HttpOnly flags. To remove all custom cookies send an empty array.

Array of objects (ScanProfileHeader)

The array of custom headers the Application Scanning should send with every request. Headers must have specified name and value. To remove all custom headers send an empty array.

report_lifespan_days
integer <int64>

Indicates how many days should we keep the report. The value must be between 7 and 10000 days. Send 0 to reset the value to the global report lifetime.

requests_per_second
integer <int64>

Sets the maximum number of HTTP requests for every second during the scan. The value must be between 5 and 1000. Send 0 for unlimited number of requests per second.

scan_common_ports
boolean

Indicates whether to scan common HTTP ports such as 80, 443, 3000.

scan_region
string

AWS region to perform scan from. Supported regions are eu-west-1, us-east-1, ap-south-1, inherit-from-team. This setting can only be changed if the team associated with the API key has the required permissions. Otherwise, changing the value will result in an error.

object (ScanProfileCookie)

ScanProfileCookie represents a HTTP cookie used in scan profile settings

whitelisted_paths
Array of strings

The array of paths the scan should include. The list should only the relative path of the URL, e.g., /secret/path/of/page.php instead of https://www.example.com/secret/path/of/page.php. To remove all whitelisted paths send an empty array.

whitelisted_ports
Array of integers <int64> [ items <int64 > ]

The array of ports the scan should include. To remove all whitelisted ports send an empty array.

Responses

Request samples

Content type
application/json
{
  • "basic_auth": {
    },
  • "blacklisted_paths": [
    ],
  • "blacklisted_ports": [
    ],
  • "blacklisted_subdomains": [
    ],
  • "crawl_subdomains": true,
  • "custom_cookies": [
    ],
  • "custom_headers": [
    ],
  • "report_lifespan_days": 0,
  • "requests_per_second": 0,
  • "scan_common_ports": true,
  • "scan_region": "string",
  • "session_cookie": {
    },
  • "whitelisted_paths": [
    ],
  • "whitelisted_ports": [
    ]
}

Response samples

Content type
application/json
{
  • "basic_auth": {
    },
  • "blacklisted_paths": [
    ],
  • "blacklisted_ports": [
    ],
  • "blacklisted_subdomains": [
    ],
  • "crawl_subdomains": true,
  • "custom_cookies": [
    ],
  • "custom_headers": [
    ],
  • "report_lifespan_days": 0,
  • "requests_per_second": 0,
  • "scan_common_ports": true,
  • "scan_region": "string",
  • "session_cookie": {
    },
  • "whitelisted_paths": [
    ],
  • "whitelisted_ports": [
    ]
}

Execute scans

Application Scanning functionality includes executing scans, retrieving scan status and managing scan schedules. You can manage scans through Application Scan Profiles, which contains the settings for the scan. You can only execute scans on verified assets, and only one scan per Application Scan Profile can run at a time.

For optimization purposes, starting/stopping queries only requests the specified operation to be executed, and therefore scans might be delayed by a few minutes.

Get scan status

Retrieves the status of the Application Scanning currently running on the Application Scan Profile identified by the scan profile token. The status contains basic information, such as whether the scan is running. The scan profile token can be retrieved using Get Application Scan Profiles.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Responses

Response samples

Content type
application/json
{
  • "ended": "string",
  • "error": "string",
  • "started": "string",
  • "status": "string",
  • "warnings": [
    ]
}

Start scan

Requests to start a new Application Scanning for the Application Scan Profile identified by the scan profile token. The scan profile token can be retrieved using Get Application Scan Profiles.

The request sets the scan to starting phase, and the infrastructure starts the scan within a few minutes. You can only execute scans on verified assets, and only one scan per Application Scan Profile can run at a time. To validate whether the scan started, use Get scan status.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Responses

Response samples

Content type
application/json
{}

Stop scan

Requests stopping the Application Scanning currently running on the Application Scan Profile identified by the scan profile token. The scan profile token can be retrieved using Get Application Scan Profiles.

The request sets the scan to stopping phase, and is stopped by the infrastructure within a few seconds. To validate whether the scan stopped, use Get scan status.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Responses

Response samples

Content type
application/json
{}

Schedule scans

Get scan schedule

Retrieves scan schedule information on the Application Scan Profile identified by the scan profile token, such as frequency and timestamps for the first and next scans. If there is no scan scheduled for the specified profile, schedule information with never frequency is returned without timestamps. The scan profile token can be retrieved using Get Application Scan Profiles.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Responses

Response samples

Content type
application/json
{
  • "first_scan": "string",
  • "frequency": "string",
  • "next_scan": "string",
  • "scan_profile_token": "string"
}

Set scan schedule

Sets a scan schedule for the Application Scan Profile identified by the scan profile token and returns information on the schedule, such as the timestamp for the first and next scans. The scan profile token can be retrieved using Get Application Scan Profiles.

If no starting timestamp is specified, the current timestamp is taken, which results in an instant scan start. If schedule already existed for the specified Application Scan Profile, it is overwritten.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Request Body schema: application/json
frequency
required
string (Frequency represents the frequency of the scan.)

Can be once for a single scan or daily, weekly, biweekly or monthly for recurring scans.

start
string

Starting timestamp must be specified in YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss±hhmm format (ISO 8601, UTC or with offset, and encoded when containing offset) or Unix time. If no starting timestamp is specified, the current timestamp is taken, which results in an instant scan start.

Responses

Request samples

Content type
application/json
{
  • "frequency": "string",
  • "start": "string"
}

Response samples

Content type
application/json
{
  • "first_scan": "string",
  • "frequency": "string",
  • "next_scan": "string",
  • "scan_profile_token": "string"
}

Remove scan schedule

Removes scan schedule on the Application Scan Profile identified by the scan profile token. The scan profile token can be retrieved using Get Application Scan Profiles.

path Parameters
scanProfileToken
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The scan profile token.

Responses

Response samples

Content type
application/json
{}

DNS zones

DNS zone functionality includes uploading zone files and performing zone transfer to Detectify.

Upload zone file

Uploads a zone file to populate domain information. The request body contains the zone file itself as specified in RFC 1034 and RFC 1035. The maximum allowed size for zone files in 5 MB. The specified domains will be scheduled for indexing and will eventually populate Surface Monitoring and autodiscovery. The call returns the number of indexed zones.

Note that this action does not activate Surface Monitoring on the domains. For more information, see getting started with Surface Monitoring.

path Parameters
origin
required
string
Example: example.com

The starting origin for the file. If the $ORIGIN is specified in the zone file, this value is ignored.

If not provided, the root zone is assumed.

Responses

Response samples

Content type
application/json
{
  • "indexed": 12
}

Upload zone lookup file

Uploads a zone lookup file to populate domain information. A zone lookup file is a text file containing a domain name in every line. The maximum allowed size for zone lookup files is 50 MB. We will perform DNS lookups on each domain and use the results to schedule the domains for indexing and eventually populate Surface Monitoring and autodiscovery. The call returns a lookup job UUID, which can be used to probe the progress of the job by using Get zone lookup status.

The zone lookup status information will be available for 10 days after the upload of the zone lookup file.

This method can only be used to populate subdomains for preexisting assets, not for populating new apex domains or ips.

Note that this action does not activate Surface Monitoring. For more information, see getting started with Surface Monitoring.

Responses

Response samples

Content type
application/json
{
  • "lookup_job_uuid": "54563322-37cb-47b8-9bcb-5773b8b34d30"
}

Get zone lookup status

Retrieves the status of a zone lookup identified by the lookup job UUID. The response contains information such as the progress of the lookup job, the total number of domains received, how many failed to be indexed, and how many succeeded. Invalid and duplicate domains will count as failures.

The zone lookup status information will be available for 10 days after the upload of the zone lookup file.

path Parameters
lookupJobUUID
required
string
Example: 54563322-37cb-47b8-9bcb-5773b8b34d30

the unique identifier of the lookup job.

Responses

Response samples

Content type
application/json
{
  • "failed": 2,
  • "status": "string",
  • "succeeded": 56,
  • "total": 58,
  • "uuid": "54563322-37cb-47b8-9bcb-5773b8b34d30"
}

Zone transfer

Transfers zone information to populate domain information. The specified domains will be scheduled for indexing and will eventually populate Surface Monitoring and autodiscovery. The call returns the number of indexed zones.

Note that this action does not activate Surface Monitoring. For more information, see Surface Monitoring and getting started with Surface Monitoring. The call also requires whitelisting of Detectify IP addresses for zone transfer.

path Parameters
nameServer
required
string
Example: ns1.example.com

The host name or IP address of the name server

zone
required
string
Example: example.com

The zone origin

Responses

Response samples

Content type
application/json
{
  • "indexed": 12
}

Vulnerabilities

Vulnerabilities are the collection of all vulnerability findings detected on all levels.

Vulnerabilities have a multi-level structure and are identified by the finding universally unique identifier (UUID), which is unique for each vulnerability. Each vulnerability is unique by the combination of the type of vulnerability detected, the location of the vulnerability, and the scan source of the vulnerability.

Much like Surface Monitoring findings, vulnerabilities occur over a period of time indicated by the createdAt and updatedAt timestamps. The updatedAt specifies the last date the specific vulnerability was last detected.

List vulnerabilities

Returns vulnerabilities according to the provided filter settings, provided as query parameters.

Time interval values must be specified in YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss±hhmm format (ISO 8601, UTC or with offset, and encoded when containing offset) or Unix time.

The response is paginated. If the number of total vulnerabilities with the current filter settings exceeds the page size, the response will contain the field has_more that will be true. The field next_marker contains a UUID to pass using the marker parameter, which will be the offset for the next page.

In case individual details (HTML, Markdown or Text) are larger than 16.000 characters they will be truncated. For full details use Get vulnerability.

Some filters support multiple inputs. The correct syntax for appending array query parameters is setting the same query parameter multiple times in the same request, as following: .../vulnerabilities/?severity[]=high&severity[]=medium

query Parameters
severity[]
Array of strings (Severity of a finding. The value can be `information`, `low`, `medium`, `high` or `critical`.)
Example: severity[]=medium

Severities to include, based on CVSS v2.0 severity. Values can be information, low, medium or high.

severityV3[]
Array of strings (Severity of a finding. The value can be `information`, `low`, `medium`, `high` or `critical`.)
Example: severityV3[]=critical

Severities to include, based on CVSS v3.1 severity. Values can be information, low, medium, high or critical.

scan_source[]
Array of strings (SourceValue can be `application-scanning` or `surface-monitoring`.)
Example: scan_source[]=application-scanning

Scan sources to include. Values can be application-scanning or surface-monitoring.

status[]
Array of strings (Status of a vulnerability. The value can be `active`, `new`, `patched`, `regression`, `accepted_risk`, or `false_positive`.)
Example: status[]=active

Vulnerability statuses to include. Values can be accepted_risk, active, false_positive, new, patched or regression.

asset_token[]
Array of strings
Example: asset_token[]=0e54921c386c666710134a5deecdbfe4

Assets to include, defined by their UUID. Assets can be requested using Get root assets.

scan_profile_token[]
Array of strings

Scan profile tokens to include. Scan profiles can be requested using Get Application Scan profiles

tag[]
Array of strings
Example: tag[]=35be3436-2d0a-4f37-97a3-8a221cb2cdad

Tags to include, defined by their UUID.

group_token[]
Array of strings
Example: group_token[]=3defa7b52e63f89697b76cab14c7273e

Groups to include, defined by their group token. Groups can be requested using Get Groups.

exclude_asset_token[]
Array of strings
Example: exclude_asset_token[]=39a9a9d358259cebeb7dc456a5b7dbd0

Assets to exclude, defined by their UUID. Assets can be requested using Get root assets.

exclude_tag[]
Array of strings
Example: exclude_tag[]=a2d7f2d7-6399-499e-8bfc-312812bf9bfd

Tags to exclude, defined by their UUID.

created_before
string <date-time>
Example: created_before=2020-01-01T01:01:00Z

The upper limit for the creation timestamp of the vulnerability, equal to or less than the timestamp when it was first detected. The value can either be a timestamp in the YYYY-MM-DDTHH:mm:ssZ format (ISO 8601, UTC) or unix seconds integer.

created_after
string <date-time>
Example: created_after=2020-01-01T01:01:00Z

The lower limit for the creation timestamp of the vulnerability, equal to or greater than the timestamp when it was first detected. The value can either be a timestamp in the YYYY-MM-DDTHH:mm:ssZ format (ISO 8601, UTC) or unix seconds integer.

updated_before
string <date-time>
Example: updated_before=2020-01-01T01:01:00Z

The upper limit for the updated timestamp of the vulnerability, equal to or less than the timestamp when it was most recently detected. The value can either be a timestamp in the YYYY-MM-DDTHH:mm:ssZ format (ISO 8601, UTC) or unix seconds integer.

updated_after
string <date-time>
Example: updated_after=2020-01-01T01:01:00Z

The lower limit for the updated timestamp of the vulnerability, equal to or greater than the timestamp when it was most recently detected. The value can either be a timestamp in the YYYY-MM-DDTHH:mm:ssZ format (ISO 8601, UTC) or unix seconds integer.

host[]
Array of strings
Example: host[]=www.example.com

Filters vulnerabilities by host. The host can be a domain or an IP address.

marker
string
Example: marker=fa31514e-7edc-48f2-b8aa-7445a852a0a5

The marker token of the object to continue listing from for paginated requests. If omitted, objects are listed from the start according to any provided sorting and filtering parameters.

pageSize
integer <int64>
Example: pageSize=20

Sets the maximum amount of vulnerabilities in one response, max 100.

Responses

Response samples

Content type
application/json
{
  • "current_marker": "0ea80070-5066-441c-ae58-10fd0076d4cb",
  • "has_more": true,
  • "next_marker": "fc6159c1-b877-4462-96f5-c01a4261135d",
  • "total_vulnerabilities": 1337,
  • "vulnerabilities": [
    ]
}

Get vulnerability

Returns a specific vulnerability, by its UUID.

path Parameters
vulnerabilityUUID
required
string
Example: 0b14fd3e-9c30-4038-9d78-b5e7d992dc01

Vulnerability UUID

Responses

Response samples

Content type
application/json
{
  • "vulnerability": {
    }
}

Set status to accepted risk

Set the status of a single vulnerability to accepted risk

Responses

Response samples

Content type
application/json
{}

Set status to false positive

Set the status of a single vulnerability to false positive

Responses

Response samples

Content type
application/json
{}

Set status to fixed

Set the status of a single vulnerability to fixed

Responses

Response samples

Content type
application/json
{}

Unset accepted risk status

Unset the accepted risk status of a single vulnerability

Responses

Response samples

Content type
application/json
{}

Unset false positive status

Unset the false positive status of a single vulnerability

Responses

Response samples

Content type
application/json
{}

Unset fixed status

Unset the fixed status of a single vulnerability

Responses

Response samples

Content type
application/json
{}

Members

Members are the users belonging to a specific team.

This set of endpoints allow managing the members of your team using the API.

Get Members

Returns an array of all members that belong to the team

If the team has no members, the response contains an empty array.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Invite Members to the team

Invites new members to the team using their emails and corresponding user roles

Request Body schema: application/json
Array
email
string

Email address of the invited user

role
string (Role represents user role.)

The user role may be:

  • Admin, Admins can manage all aspects of your team, such as users, assets, surface monitoring, application scan profiles, billing.

  • Editor, Editors can manage application scan profiles and have access to all security reports for all domains added to your team.

  • Viewer, Viewers can access your security reports for all the domains added to your team.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "invitation_errors": [
    ]
}

Experimental

Warning! Here be Dragons! These are experimental versions of endpoints with new functionality. The design and output structure are not finalized and they may change.

Get assets for groups

This endpoint is experimental. This means that the endpoint has not yet been finalized and might change for any reason at any time. But feel free to try it out and give us feedback about it! Returns an object containing an array of assets for groups and pagination metadata(current marker, next marker, has more).

If the team has no assets, the response contains an empty object.

Timestamps are in YYYY-MM-DDTHH:mm:ssZ format (ISO 8601, UTC).

Request Body schema: application/json

Array of Group Tokens to get assets for. For example ["80f852b64a5a144731f1c0ae5884beb3", "30f852b64a5a144731f1c0ae5884beb3", "20d852b64b5a1447a1f1c0ae58a4bebb"]

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "current_marker": "0ea80070-5066-441c-ae58-10fd0076d4cb",
  • "has_more": true,
  • "next_marker": "fc6159c1-b877-4462-96f5-c01a4261135d"
}

Get Groups

Returns an array of all groups that belong to the team

If the team has no groups, the response contains an empty array.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Group

Creates a new group with a given name. Returned response will contain the newly created group with its unique token.

Request Body schema: application/json
description
string

Description given to the group

name
required
string

Name given to the group

Responses

Request samples

Content type
application/json
{
  • "description": "This group holds CDN assets",
  • "name": "My Group"
}

Response samples

Content type
application/json
{
  • "created": "2022-03-01T10:19:38.014447Z",
  • "description": "This group holds CDN assets",
  • "name": "my group",
  • "token": "80f852b64a5a144731f1c0ae5884beb3",
  • "updated": "2022-03-01T10:19:38.014447Z"
}

Update Group

Updates a group's name with its unique identifier token. The group token can be retrieved using Get Groups.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

Request Body schema: application/json
description
string

Description given to the group

name
string

Name given to the group

Responses

Request samples

Content type
application/json
{
  • "description": "This group holds CDN assets",
  • "name": "My group"
}

Response samples

Content type
application/json
{}

Remove Group

Removes a group with its unique identifier token. The group token can be retrieved using Get Groups.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

Responses

Response samples

Content type
application/json
{}

Get Group Members

Returns an array of all members that belong to the group. Group tokens can be retrieved using Get Groups. If the team has no member, the response contains an empty array.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Group Member

Add a user to the group as a member using its token. Returned response will contain the newly created member with its unique member token. User tokens can be retrieved using Get Team Members.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

Request Body schema: application/json
userToken
string

User token that will be added as a member to the group

Responses

Request samples

Content type
application/json
{
  • "userToken": "80f852b64a5a144731f1c0ae5884beb3"
}

Response samples

Content type
application/json
{
  • "created": "2022-03-01T10:19:38.014447Z",
  • "group_token": "80f852b64a5a144731f1c0ae5884beb3",
  • "token": "80f852b64a5a144731f1c0ae5884beb3",
  • "updated": "2022-03-01T10:19:38.014447Z",
  • "user_token": "80f852b64a5a144731f1c0ae5884beb3"
}

Remove Group Member

Removes a group member with its unique identifier token and the group token that it belongs to. The group token can be retrieved using Get Groups. The group member token can be retrieved using Get Group Members.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

groupMemberToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group member token.

Responses

Response samples

Content type
application/json
{}

Get Asset Patterns

Returns an array of all asset patterns that belong to the group. Group tokens can be retrieved using Get Group. If the team has no asset patterns, the response contains an empty array.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Asset Pattern

Creates a new asset pattern with a given pattern string. Returned response will contain the newly created asset pattern with its unique token.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

Request Body schema: application/json
pattern
string

Pattern string used for filtering

Responses

Request samples

Content type
application/json
{
  • "pattern": "*example.com"
}

Response samples

Content type
application/json
{
  • "created": "2022-03-01T10:19:38.014447Z",
  • "group_token": "80f852b64a5a144731f1c0ae5884beb3",
  • "pattern": "*example.com",
  • "token": "80f852b64a5a144731f1c0ae5884beb3",
  • "updated": "2022-03-01T10:19:38.014447Z"
}

Remove Asset Pattern

Removes an asset pattern with its unique identifier token and the group token that it belongs to. The group token can be retrieved using Get Groups. The asset pattern token can be retrieved using Get Asset Patrerns.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

assetPatternToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The asset pattern token.

Responses

Response samples

Content type
application/json
{}

Update Asset Pattern

Updates an asset pattern's pattern string. The group token can be retrieved using Get Groups. The asset pattern token can be retrieved using Get Asset Patrerns.

path Parameters
groupToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The group token.

assetPatternToken
required
string
Example: 80f852b64a5a144731f1c0ae5884beb3

The asset pattern token.

Request Body schema: application/json
pattern
string

Pattern string used for filtering

Responses

Request samples

Content type
application/json
{
  • "pattern": "*example.com"
}

Response samples

Content type
application/json
{}

Error codes

In addition to the HTTP response code, the response contains detailed information of the error. The information contains an error code and an error message. If the error is due to some specific request parameter, the parameter is also present.

Here is a list of error codes that you may encounter during usage:

Code Error cause
1001 The API key is missing. See authentication on ways to provide the API key.
1002 The API key is malformed. Ensure that the API key exactly matches the one generated on the API-keys page.
1003 The API key or message signature is invalid. Ensure that 1) the API key is valid and matches the one generated on the API-keys page; 2) if a secret key is specified, a) the message signature is generated as specified; b) the message timestamp is within the specified time limits. See the authentication section for detailed specification.
1009 The API key cannot access this endpoint. For professional and enterprise subscriptions, allowed endpoints can be controlled with each API key. Some endpoints are only available for enterprise subscription, as specified in the endpoint description. Ensure that your subscription and the API key have access to the endpoint.
1050 The request body is missing. Review whether the request body is set.
1051 The request body is malformed. You can use the provided JSON schema to validate the request body using various tools, e.g., JSON schema validator.
1052 The request body is too large. Review the endpoint description on the maximum allowed request body size.
1085 Timestamp is malformed. Use YYYY-MM-DDTHH:mm:ssZ or YYYY-MM-DDTHH:mm:ss±hhmm format (ISO 8601, UTC or with offset, and encoded when containing offset) or Unix time to specify timestamps.
1900 The endpoint is unavailable. Please review the HTTP method and URL path and ensure that all characters are matching (e.g., ending slash), and required parameters are specified.
1909 Temporary outage within the Detectify infrastructure, possibly due to an upgrade of a Detectify component. Please try again later. If the problem persists, please contact customer support.
1910 A technical issue has occurred while processing the request. Please check your input in case something is malformed or invalid. If you have verified the contents of the request, and if the problem persists, please contact customer support.
1999 The specified endpoint is no longer available. This response is returned for all calls towards the discontinued API v1 functionality. Please use API v2 functionality instead.
2011 The domain token is malformed. Use Get root assets to validate the token against existing domains.
2012 The domain name is malformed. The domain name must be a second level domain name, subdomain name or IP address with optional port number as specified in RFC 1035 and RFC 1918. If your domain name has non-standard characters, make sure to punycode it in advance.
2014 The asset does not exist. Use Get root assets to list existing assets.
2018 The asset already exists. Multiple assets are not allowed to have the same domain name or IP address. Use Get root assets to list existing assets.
2019 The asset was accepted to be added as subdomain. Root apex already exists so the domain will be added as subdomain and it might take time for it to appear in assets list.
2021 The asset is not verified. You can only scan verified assets. Use Get root assets to validate asset status. If your subscription does not include easy domain verification, you can use the Attack surface view to validate assets added through the API.
2026 The asset has one or more associated Application Scan Profiles. Remove these Application Scan Profiles first. Use Get Application Scan Profiles for asset to list all associated Application Scan Profiles.
2411 The zone origin is malformed. The origin must be a domain name as specified in RFC 1035.
2412 The zone server is malformed. The server must be a domain name or IP address as specified in RFC 1035.
2413 The zone name is malformed. The zone name must be a domain name as specified in RFC 1035.
2421 The zone file is malformed. The zone file must be formatted as specified in RFC 1035.
2422 Asset settings is malformed. All of the settings fields must be provided.
2423 Surface Monitoring can only be enabled for domains, and the specified asset is an IP address.
2424 Surface Monitoring can't be enabled, monitored domains is at capacity.
2425 Surface monitoring could not be enabled, asset is not a verified domain.
2601 The Application Scan Profile token is malformed. Use Get Application Scan Profiles to validate the token against existing scan profiles.
2602 The Application Scan Profile name is too long. The Application Scan Profile name cannot be longer than 255 characters.
2604 The Application Scan Profile does not exist. Use Get Application Scan Profiles to list existing Application Scan Profiles.
2605 The Application Scan Profile already exists, violating the specified unique condition. Use Get Application Scan Profiles to list existing Application Scan Profiles.
2606 The Application Scan Profile endpoint is malformed. The endpoint must be a second level domain name, subdomain name or IP address with optional port number as specified in RFC 1035 and RFC 1918.
2607 The Application Scan Profile endpoint does not match the name of the associated asset. Use Get root assets to list existing assets.
2609 Application Scan Profile endpoint validation failed, meaning the HTTP/HTTPS GET requests from Detectify to the specified endpoint failed to respond within 10 seconds.
2616 The Application Scan Profile is deactivated and cannot be scanned. Review your subscription status on the billing page.
2618 The Application Scan Profile limit for the subscription is reached. Review your subscription status on the billing page.
2641 A subdomain name specified in the settings is malformed. Subdomain names must contain only the subdomain part and must match specification in RFC 1035.
2642 A path specified in the settings is malformed. Paths must be root relative paths as specified in RFC 3986.
2643 A port specified in the settings is malformed. Port numbers must be an integer number between 1 and 65535.
2651 A cookie name is empty. All cookies must have the name specified.
2652 A cookie name is malformed. Cookie names cannot contain comma, semicolon or whitespace characters.
2653 A cookie value is empty. All cookies must have the value specified.
2654 A cookie value is malformed. Cookie values cannot contain comma, semicolon or whitespace characters.
2657 A header name is empty. All headers must have the name specified.
2658 A header value is empty. All headers must have the value specified.
2671 The report lifespan is invalid. The report lifespan must be an integer number between 7 and 10000 days, or 0 to reset to global report lifespan.
2672 The number of requests per second is invalid. The number of requests per second must be an integer number between 5 and 1000 or 0 to for an unlimited number of requests.
2673 Scan region is invalid. Possible values are eu-west-1, us-east-1, ap-south-1 and inherit-from-team.
4085 The severity is malformed. Severity must be high, medium, low or information.
4110 A scan source is malformed. Scan source must be surface-monitoring or application-scanning.
4111 The vulnerability UUID is malformed. Use Get vulnerabilities to validate the token against existing vulnerabilities.
4115 A status is malformed. Status must be active, new, patched, regression, accepted_risk, or false_positive.
4150 One or more of the query parameters are malformed.
5004 Scan is not running on the Application Scan Profile. Use Get scan status to retrieve the scan status for the profile.
5009 Scan already running on the Application Scan Profile. Use Get scan status to retrieve the scan status for the profile.
5066 Scan frequency is malformed. Scan frequency must be once, daily, weekly, biweekly, monthly or never.
6001 The lookup job UUID is malformed. Use the exact same token returned by Upload zone lookup file.
6002 The lookup job does not exist. The lookup job UUID provided is wrong or the corresponding lookup job was deleted.
7001 The identifier is malformed as it not a token or a UUID. Use Get root assets to validate the identifier against existing assets.
7002 The asset UUID is malformed. Use Get root assets to validate the UUID against existing assets.
7004 The asset does not exist. Use Get root assets to validate the identifier against existing assets.
7101 The recursive parameter is malformed. Recursive must be true or false.
8101 Invited member's role is malformed. The value should either be Admin, Editor or Viewer
9001 Group token is malformed.
9002 Group name is invalid. Name cannot be empty and should be shorter than 255 characters. It can only contain alphanumeric characters, underscore(_), dash(-) and space.
9003 Group does not exist.
9002 Group description is invalid. Description should be shorter than 255 characters.
9011 Asset pattern token is malformed.
9012 Asset pattern string is invalid.
9013 Asset pattern does not exist.
9021 Group member token is malformed.
9022 User token provided for the group member is malformed.
9023 Group member does not exist.
9024 Provided user does not belong to the team. Before adding them as a member to your group, make sure that they belong to your organization.