Detectify logo Switch to V2 documentation
API docs by Redocly

Detectify API (3.0.0)

Download OpenAPI specification:Download

Detectify: support@detectify.com URL: https://api.detectify.com

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

Authentication

All requests must be authenticated using an API key generated specifically for the V3 API on the API-keys page.

Using the Authorization HTTP header:

GET /rest/v3/ips HTTP/1.1
Host: api.detectify.com
Authorization: a47a82f1-7b6e-4562-8529-ff0b1e908a5b

IP Addresses

Get all IP Addresses

This query returns all the IP addresses which have been discovered on your attack surface. The returned information contains information about the IP such as what domain and asset it is connected to, when it was first seen, as well as metadata such as geolocation and ASN details.

Authorizations:
api-key
query Parameters
cursor
string
Example: cursor=ed99eb9a-bb0d-5dd5-a8e1-fff25e5ded54

Next cursor value to continue the pagination. This value is optional and the query will start from the first page if left blank.

limit
integer <int32> [ 1 .. 1000 ]
Example: limit=20

This value will be used to determine the amount of items to be returned for each request.

first_seen_before
string <date-time>
Example: first_seen_before=2023-09-18T12:12:00Z

All IP addresses first seen before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

first_seen_after
string <date-time>
Example: first_seen_after=2023-09-18T12:12:00Z

All IP addresses first seen after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

disappeared_before
string <date-time>
Example: disappeared_before=2023-09-18T12:12:00Z

All IP addresses which disappeared before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

disappeared_after
string <date-time>
Example: disappeared_after=2023-09-18T12:12:00Z

All IP addresses which disappeared after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

Responses

https://api.detectify.com/rest/v3/ips

Response samples

  • 200
  • 400
  • default
Content type
application/json
{}

Technology

Get all technologies

This query returns all discovered technologies on your attack surface.

Authorizations:
api-key
query Parameters
cursor
string
Example: cursor=ed99eb9a-bb0d-5dd5-a8e1-fff25e5ded54

Next cursor value to continue the pagination. This value is optional and the query will start from the first page if left blank.

limit
integer <int32> [ 1 .. 1000 ]
Example: limit=20

This value will be used to determine the amount of items to be returned for each request.

first_seen_before
string <date-time>
Example: first_seen_before=2023-09-18T12:12:00Z

All techs first seen before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

first_seen_after
string <date-time>
Example: first_seen_after=2023-09-18T12:12:00Z

All techs first seen after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

disappeared_before
string <date-time>
Example: disappeared_before=2023-09-18T12:12:00Z

All techs which disappeared before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

disappeared_after
string <date-time>
Example: disappeared_after=2023-09-18T12:12:00Z

All techs which disappeared after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

Responses

https://api.detectify.com/rest/v3/technologies

Response samples

  • 200
  • 400
  • default
Content type
application/json
{}

Ports

Get all ports

This query returns all discovered ports on your attack surface, including information to which IP and asset it was discovered on.

Authorizations:
api-key
query Parameters
cursor
string
Example: cursor=ed99eb9a-bb0d-5dd5-a8e1-fff25e5ded54

Next cursor value to continue the pagination. This value is optional and the query will start from the first page if left blank.

limit
integer <int32> [ 1 .. 1000 ]
Example: limit=20

This value will be used to determine the amount of items to be returned for each request.

first_seen_before
string <date-time>
Example: first_seen_before=2023-09-18T12:12:00Z

All ports first seen with open status before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

first_seen_after
string <date-time>
Example: first_seen_after=2023-09-18T12:12:00Z

All ports first seen with open status after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

disappeared_before
string <date-time>
Example: disappeared_before=2023-09-18T12:12:00Z

All ports which disappeared before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

disappeared_after
string <date-time>
Example: disappeared_after=2023-09-18T12:12:00Z

All ports which disappeared after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

status
Array of strings
Example: status=OPEN,CLOSED

Return only ports having any of the listed statuses.

port
Array of integers <int32> [ items <int32 > [ 0 .. 65535 ] ]
Example: port=80,443

Return only port numbers from the supplied list.

Responses

https://api.detectify.com/rest/v3/ports

Response samples

  • 200
  • 400
  • default
Content type
application/json
{}

Breaches

Get all breaches

This query returns all policy breaches which have been detected on your assets.

Authorizations:
api-key
query Parameters
cursor
string
Example: cursor=ed99eb9a-bb0d-5dd5-a8e1-fff25e5ded54

Next cursor value to continue the pagination. This value is optional and the query will start from the first page if left blank.

limit
integer <int32> [ 1 .. 1000 ]
Example: limit=20

This value will be used to determine the amount of items to be returned for each request.

first_seen_before
string <date-time>
Example: first_seen_before=2023-09-18T12:12:00Z

All breaches first seen with new status before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

first_seen_after
string <date-time>
Example: first_seen_after=2023-09-18T12:12:00Z

All breaches first seen with new status after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

disappeared_before
string <date-time>
Example: disappeared_before=2023-09-18T12:12:00Z

All breaches which disappeared before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

disappeared_after
string <date-time>
Example: disappeared_after=2023-09-18T12:12:00Z

All breaches which disappeared after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

status_updated_before
string <date-time>
Example: status_updated_before=2023-09-18T12:12:00Z

All breaches where status last updated before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

status_updated_after
string <date-time>
Example: status_updated_after=2023-09-18T12:12:00Z

All breaches where status last updated after the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.

Responses

https://api.detectify.com/rest/v3/breaches

Response samples

  • 200
  • 400
  • default
Content type
application/json
{}

Connectors

Get all connectors

Returns all connectors owned by the teams associated with the API key.

query Parameters
cursor
string
Example: cursor=ed99eb9a-bb0d-5dd5-a8e1-fff25e5ded54

Next cursor value to continue the pagination. This value is optional and the query will start from the first page if left blank.

limit
integer <int32> [ 1 .. 1000 ]
Example: limit=20

This value will be used to determine the amount of items to be returned for each request.

Responses

https://api.detectify.com/rest/v3/connectors

Response samples

  • 200
  • 400
  • default
Content type
application/json
{}

Create a connector

Create a connector for the supplied team.

Request Body schema: application/json
required

Create a connector for the supplied team. The input varies based on the connector being created.

team_id
string

Team ID for the team where the connector should be created. Optional in case a single team ID is associated with the API key. Required for multi team API-keys.

name
required
string

Name the connector should have in API and UI.

provider
required
string (ConnectorProvider)
Enum: "AWS_ROLE_BASED" "AWS_CRED_BASED" "DIGITAL_OCEAN" "GCP" "CLOUDFLARE" "ALIBABA" "AZURE" "GODADDY" "NS1"

Source of the connector.

required
ConnectorCreateAwsCredBasedInput (object) or ConnectorCreateAwsRoleBasedInput (object) or ConnectorCreateDigitalOceanInput (object) or ConnectorCreateGCPInput (object) or ConnectorCreateCloudflareInput (object) or ConnectorCreateAlibabaInput (object) or ConnectorCreateAzureInput (object) or ConnectorCreateGodaddyInput (object) or ConnectorCreateNS1Input (object) (CreateConnectorInputOptions)

Responses

https://api.detectify.com/rest/v3/connectors

Request samples

  • Payload
Content type
application/json
{
  • "team_id": "5605b488634efe810dff4276e28ca7f9",
  • "name": "My AWS Cred-Based Connector",
  • "provider": "AWS_ROLE_BASED",
  • "options": {
    }
}

Response samples

  • 201
  • 400
  • default
Content type
application/json
{
  • "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
  • "name": "detectify-aws-connector",
  • "team_id": "5605b488634efe810dff4276e28ca7f9",
  • "last_run": {
    },
  • "provider": "AWS_ROLE_BASED",
  • "created_at": "2023-09-18T12:12:00Z",
  • "updated_at": "2023-09-18T12:12:00Z"
}

Get a single connector

Returns a single connector by its ID.

path Parameters
id
required
string
Example: rgg44cb5-90a1-67c4-b10b-71d8d8f0a98e

The ID of the connector.

Responses

https://api.detectify.com/rest/v3/connectors/{id}

Response samples

  • 200
  • 400
  • 404
  • default
Content type
application/json
{
  • "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
  • "name": "detectify-aws-connector",
  • "team_id": "5605b488634efe810dff4276e28ca7f9",
  • "last_run": {
    },
  • "provider": "AWS_ROLE_BASED",
  • "created_at": "2023-09-18T12:12:00Z",
  • "updated_at": "2023-09-18T12:12:00Z"
}

Delete a single connector

Delete a connector by its ID.

path Parameters
id
required
string

ID of a connector that should be deleted.

Responses

https://api.detectify.com/rest/v3/connectors/{id}

Response samples

  • 400
  • 404
  • default
Content type
application/problem+json
{
  • "type": "/invalid_request",
  • "title": "some title for the error situation",
  • "status": 100,
  • "detail": "some description for the error situation",
  • "instance": "/invalid_request/query_parameters"
}

Get the external ID for setting up AWS role based authentication

Returns the external ID for setting up AWS role based authentication. Each team has a single associated external ID, and the same ID can be used for setting up multiple connectors.

query Parameters
team_id
string
Example: team_id=5605b488634efe810dff4276e28ca7f9

Team ID for the team for which the external ID should be returned. Optional in case a single team ID is associated with the API key. Required for multi team API-keys.

Responses

https://api.detectify.com/rest/v3/aws-external-id

Response samples

  • 200
  • default
Content type
application/json
{
  • "external_id": "string",
  • "team_id": "string"
}

Surface Monitoring

Get all domains monitoring settings

Returns the monitoring settings for all monitored domain assets accessible via the API key. Use the optional team_id parameter to limit results to a specific team.

Asset hierarchy

Domain assets exist in a two-level hierarchy:

  • Root asset — the asset closest to the apex domain (e.g. example.com)
  • Sub-assets — any subdomains of the root asset, regardless of how many subdomain levels deep they are (e.g. api.example.com, staging.api.example.com)

Inheritance

Sub-assets inherit their settings from their root asset by default. This is indicated by the inherited and inherited_from fields on each item.

Configuring settings directly on a sub-asset overrides the inherited values from the root asset for that sub-asset, allowing it to differ from the rest of the hierarchy — including disabling monitoring entirely on that specific sub-asset.

If the settings for a sub-asset are deleted, it reverts to inheriting all settings from its root asset if one is available. Inheritance is all-or-nothing: it applies to the whole settings object, not individual fields.

Settings and hierarchy changes

Settings always stay with the asset they are configured for. If an asset is elected a new root asset, its existing settings will no longer be inherited by others. This is intentional, to prevent accidentally applying scanning settings to unintended assets as the hierarchy changes.

Example: example.com is added as a new root asset, causing api.example.com to be reclassified from a root asset into a sub-asset:

Before:

  • api.example.com (root asset, has settings)
  • staging.api.example.com (sub-asset, inherits from api.example.com)

After:

  • example.com (root asset, has settings)
  • api.example.com (sub-asset, retains its own settings as an override — does not inherit)
  • staging.api.example.com (sub-asset, now inherits from example.com)
Authorizations:
api-key
query Parameters
cursor
string
Example: cursor=ed99eb9a-bb0d-5dd5-a8e1-fff25e5ded54

Next cursor value to continue the pagination. This value is optional and the query will start from the first page if left blank.

limit
integer <int32> [ 1 .. 1000 ]
Example: limit=20

This value will be used to determine the amount of items to be returned for each request.

team_id
string
Example: team_id=0e54921c386c666710134a5deecdbfe4

Limit results to a specific team. Optional when the API key is associated with a single team.

Responses

https://api.detectify.com/rest/v3/surface-monitoring/domains

Response samples

  • 200
  • 400
  • default
Content type
application/json
{
  • "items": [
    ],
  • "pagination": {}
}

Get domain monitoring settings

Returns the monitoring settings for a specific domain asset. The settings control which scanning modules are enabled, rate limits, port scanning configuration, and other scanning behaviour for the domain and its subdomains.

Authorizations:
api-key
path Parameters
asset_id
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The asset ID (asset token) of the domain, as returned by the domains listing.

Responses

https://api.detectify.com/rest/v3/surface-monitoring/domains/{asset_id}

Response samples

  • 200
  • 400
  • 404
  • default
Content type
application/json
{
  • "asset_id": "5605b488634efe810dff4276e28ca7f9",
  • "team_id": "0e54921c386c666710134a5deecdbfe4",
  • "inherited": false,
  • "inherited_from": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  • "enabled": true,
  • "scraping_enabled": true,
  • "bruteforcing_enabled": true,
  • "fingerprint_enabled": true,
  • "findings_enabled": true,
  • "request_rate_limit": 0,
  • "subdomain_takeover_enabled": true,
  • "ssl_audit_enabled": true,
  • "tls_discovery_enabled": true,
  • "passive_tls_assessments_enabled": true,
  • "active_tls_assessments_enabled": true,
  • "certificate_assessments_enabled": true,
  • "custom_headers": {
    },
  • "port_scanning_enabled": true,
  • "port_scanning_include_recommended_ports": true,
  • "port_scanning_force_ports": [
    ],
  • "port_scanning_avoid_ports": [
    ]
}

Update domain monitoring settings

Creates or updates the monitoring settings for a specific domain asset. If no settings exist for the asset yet, they will be created. When creating, any fields not included in the request body will receive their default values (not inherited values). When updating an existing record, omitted fields retain their current values.

The asset must be verified before settings can be created for it.

If the asset is a sub-asset (e.g. a subdomain), creating settings for it establishes an override, meaning it will no longer inherit settings from its root asset. Note that the override is initialised with default field values, not the parent's values — it is therefore recommended to first retrieve the parent's settings (GET on the root asset) and include those values in the request body when creating the override.

Authorizations:
api-key
path Parameters
asset_id
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The asset ID (asset token) of the domain, as returned by the domains listing.

Request Body schema: application/json
required
enabled
boolean

Whether monitoring is enabled for this domain asset.

scraping_enabled
boolean

Whether subdomain discoverability through scraping is enabled.

bruteforcing_enabled
boolean

Whether subdomain discoverability through bruteforcing is enabled.

fingerprint_enabled
boolean

Whether fingerprint modules will run.

findings_enabled
boolean

Whether finding modules will run.

request_rate_limit
integer <int32>

Indicates the maximum number of HTTP requests per second per origin when Surface Monitoring is enabled. A value of 0 means the scanner uses its default rate. Note that Surface Monitoring may perform concurrent scanning of different origins for the same domain.

subdomain_takeover_enabled
boolean

Whether the subdomain takeover service is enabled.

ssl_audit_enabled
boolean

Whether SSL auditing is enabled.

tls_discovery_enabled
boolean

Whether TLS handshakes should be performed on the domain and its subdomains.

passive_tls_assessments_enabled
boolean

Whether passive TLS assessments (no extra network calls) should run.

active_tls_assessments_enabled
boolean

Whether active TLS assessments (may trigger customer alerts) should run.

certificate_assessments_enabled
boolean

Whether TLS certificate assessments should run.

object

Custom HTTP headers passed to the scanner when running tests on this domain. Providing this field replaces all existing custom headers.

port_scanning_enabled
boolean

Whether port scanning is enabled.

port_scanning_include_recommended_ports
boolean

Whether the recommended ports list compiled by security researchers is included in port scanning.

port_scanning_force_ports
Array of integers <int32> [ items <int32 > [ 0 .. 65535 ] ]

Port numbers that are always scanned, taking priority over the avoid list. Providing this field replaces the existing list.

port_scanning_avoid_ports
Array of integers <int32> [ items <int32 > [ 0 .. 65535 ] ]

Port numbers that are excluded from scanning unless present in the force list. Providing this field replaces the existing list.

Responses

https://api.detectify.com/rest/v3/surface-monitoring/domains/{asset_id}

Request samples

  • Payload
Content type
application/json
{
  • "enabled": true,
  • "scraping_enabled": true,
  • "bruteforcing_enabled": true,
  • "fingerprint_enabled": true,
  • "findings_enabled": true,
  • "request_rate_limit": 0,
  • "subdomain_takeover_enabled": true,
  • "ssl_audit_enabled": true,
  • "tls_discovery_enabled": true,
  • "passive_tls_assessments_enabled": true,
  • "active_tls_assessments_enabled": true,
  • "certificate_assessments_enabled": true,
  • "custom_headers": {
    },
  • "port_scanning_enabled": true,
  • "port_scanning_include_recommended_ports": true,
  • "port_scanning_force_ports": [
    ],
  • "port_scanning_avoid_ports": [
    ]
}

Response samples

  • 200
  • 400
  • 404
  • default
Content type
application/json
{
  • "asset_id": "5605b488634efe810dff4276e28ca7f9",
  • "team_id": "0e54921c386c666710134a5deecdbfe4",
  • "inherited": false,
  • "inherited_from": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  • "enabled": true,
  • "scraping_enabled": true,
  • "bruteforcing_enabled": true,
  • "fingerprint_enabled": true,
  • "findings_enabled": true,
  • "request_rate_limit": 0,
  • "subdomain_takeover_enabled": true,
  • "ssl_audit_enabled": true,
  • "tls_discovery_enabled": true,
  • "passive_tls_assessments_enabled": true,
  • "active_tls_assessments_enabled": true,
  • "certificate_assessments_enabled": true,
  • "custom_headers": {
    },
  • "port_scanning_enabled": true,
  • "port_scanning_include_recommended_ports": true,
  • "port_scanning_force_ports": [
    ],
  • "port_scanning_avoid_ports": [
    ]
}

Delete domain monitoring settings

Deletes the monitoring settings for a specific domain asset. If the asset is a sub-asset, it will revert to inheriting all settings from its root asset if one is available.

Authorizations:
api-key
path Parameters
asset_id
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The asset ID (asset token) of the domain, as returned by the domains listing.

Responses

https://api.detectify.com/rest/v3/surface-monitoring/domains/{asset_id}

Response samples

  • 400
  • 404
  • default
Content type
application/problem+json
{
  • "type": "/invalid_request",
  • "title": "some title for the error situation",
  • "status": 100,
  • "detail": "some description for the error situation",
  • "instance": "/invalid_request/query_parameters"
}

Get all IPs monitoring settings

Returns the monitoring settings for all monitored IP address assets accessible via the API key. Use the optional team_id parameter to limit results to a specific team.

Asset hierarchy

IP assets exist in a two-level hierarchy:

  • Root asset — either an IP range (e.g. 10.0.0.0/24), or an individual IP that does not belong to any monitored IP range
  • Sub-assets — individual IPs that fall within a monitored IP range

An asset_id may therefore refer to either an IP range or an individual IP address.

Inheritance

Individual IPs inherit their settings from their parent IP range by default. This is indicated by the inherited and inherited_from fields on each item.

Configuring settings directly on an individual IP overrides the inherited values for that IP, allowing it to differ from the rest of the range — including disabling monitoring entirely on that specific IP.

If the settings for an individual IP are deleted, it reverts to inheriting all settings from its parent IP range if one is available. Inheritance is all-or-nothing: it applies to the whole settings object, not individual fields.

Settings and hierarchy changes

Settings always stay with the asset they are configured for. If an IP range is newly introduced and an individual IP is reclassified as a sub-asset of that range, any existing settings on that IP will not automatically propagate to other IPs in the range. This is intentional, to prevent accidentally applying scanning settings to unintended assets as the hierarchy changes.

Example: 10.0.0.0/24 is added as a new root asset, causing 10.0.0.1 to be reclassified from a root asset into a sub-asset:

Before:

  • 10.0.0.1 (root asset, has settings)
  • 10.0.0.2 (root asset, no settings)

After:

  • 10.0.0.0/24 (root asset, has settings)
  • 10.0.0.1 (sub-asset, retains its own settings as an override — does not inherit)
  • 10.0.0.2 (sub-asset, inherits from 10.0.0.0/24)
Authorizations:
api-key
query Parameters
cursor
string
Example: cursor=ed99eb9a-bb0d-5dd5-a8e1-fff25e5ded54

Next cursor value to continue the pagination. This value is optional and the query will start from the first page if left blank.

limit
integer <int32> [ 1 .. 1000 ]
Example: limit=20

This value will be used to determine the amount of items to be returned for each request.

team_id
string
Example: team_id=0e54921c386c666710134a5deecdbfe4

Limit results to a specific team. Optional when the API key is associated with a single team.

Responses

https://api.detectify.com/rest/v3/surface-monitoring/ips

Response samples

  • 200
  • 400
  • default
Content type
application/json
{}

Get IP monitoring settings

Returns the monitoring settings for a specific IP address asset. The settings control which scanning modules are enabled, rate limits, and port scanning configuration for the IP.

Authorizations:
api-key
path Parameters
asset_id
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The asset ID (asset token) of the IP address, as returned by the GET /ips endpoint.

Responses

https://api.detectify.com/rest/v3/surface-monitoring/ips/{asset_id}

Response samples

  • 200
  • 400
  • 404
  • default
Content type
application/json
{
  • "asset_id": "5605b488634efe810dff4276e28ca7f9",
  • "team_id": "0e54921c386c666710134a5deecdbfe4",
  • "inherited": false,
  • "inherited_from": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  • "enabled": true,
  • "fingerprint_enabled": true,
  • "findings_enabled": true,
  • "request_rate_limit": 0,
  • "custom_headers": {
    },
  • "port_scanning_enabled": true,
  • "port_scanning_include_recommended_ports": true,
  • "port_scanning_force_ports": [
    ],
  • "port_scanning_avoid_ports": [
    ]
}

Update IP monitoring settings

Creates or updates the monitoring settings for a specific IP address asset. If no settings exist for the asset yet, they will be created. When creating, any fields not included in the request body will receive their default values (not inherited values). When updating an existing record, omitted fields retain their current values.

The asset must be verified before settings can be created for it.

If the asset is a sub-asset, creating settings for it establishes an override, meaning it will no longer inherit settings from its root asset. Note that the override is initialised with default field values, not the parent's values — it is therefore recommended to first retrieve the parent's settings (GET on the root asset) and include those values in the request body when creating the override.

Authorizations:
api-key
path Parameters
asset_id
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The asset ID (asset token) of the IP address, as returned by the GET /ips endpoint.

Request Body schema: application/json
required
enabled
boolean

Whether monitoring is enabled for this IP address asset.

fingerprint_enabled
boolean

Whether fingerprint modules will run.

findings_enabled
boolean

Whether finding modules will run.

request_rate_limit
integer <int32>

Indicates the maximum number of HTTP requests per second per origin when Surface Monitoring is enabled. A value of 0 means the scanner uses its default rate. Note that Surface Monitoring may perform concurrent scanning of different origins for the same domain.

object

Custom HTTP headers passed to the scanner when running tests on this IP. Providing this field replaces all existing custom headers.

port_scanning_enabled
boolean

Whether port scanning is enabled.

port_scanning_include_recommended_ports
boolean

Whether the recommended ports list compiled by security researchers is included in port scanning.

port_scanning_force_ports
Array of integers <int32> [ items <int32 > [ 0 .. 65535 ] ]

Port numbers that are always scanned, taking priority over the avoid list. Providing this field replaces the existing list.

port_scanning_avoid_ports
Array of integers <int32> [ items <int32 > [ 0 .. 65535 ] ]

Port numbers that are excluded from scanning unless present in the force list. Providing this field replaces the existing list.

Responses

https://api.detectify.com/rest/v3/surface-monitoring/ips/{asset_id}

Request samples

  • Payload
Content type
application/json
{
  • "enabled": true,
  • "fingerprint_enabled": true,
  • "findings_enabled": true,
  • "request_rate_limit": 0,
  • "custom_headers": {
    },
  • "port_scanning_enabled": true,
  • "port_scanning_include_recommended_ports": true,
  • "port_scanning_force_ports": [
    ],
  • "port_scanning_avoid_ports": [
    ]
}

Response samples

  • 200
  • 400
  • 404
  • default
Content type
application/json
{
  • "asset_id": "5605b488634efe810dff4276e28ca7f9",
  • "team_id": "0e54921c386c666710134a5deecdbfe4",
  • "inherited": false,
  • "inherited_from": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  • "enabled": true,
  • "fingerprint_enabled": true,
  • "findings_enabled": true,
  • "request_rate_limit": 0,
  • "custom_headers": {
    },
  • "port_scanning_enabled": true,
  • "port_scanning_include_recommended_ports": true,
  • "port_scanning_force_ports": [
    ],
  • "port_scanning_avoid_ports": [
    ]
}

Delete IP monitoring settings

Deletes the monitoring settings for a specific IP address asset. If the asset is a sub-asset, it will revert to inheriting all settings from its root asset if one is available.

Authorizations:
api-key
path Parameters
asset_id
required
string
Example: 5605b488634efe810dff4276e28ca7f9

The asset ID (asset token) of the IP address, as returned by the GET /surface-monitoring/ips endpoint.

Responses

https://api.detectify.com/rest/v3/surface-monitoring/ips/{asset_id}

Response samples

  • 400
  • 404
  • default
Content type
application/problem+json
{
  • "type": "/invalid_request",
  • "title": "some title for the error situation",
  • "status": 100,
  • "detail": "some description for the error situation",
  • "instance": "/invalid_request/query_parameters"
}
Morty Proxy This is a proxified and sanitized view of the page, visit original site.