Switch to V2 documentation
Switch to V2 documentation
Download OpenAPI specification:Download
This page contains the documentation for the Detectify API V3 accessible at https://api.detectify.com/rest/v3
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
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.
| cursor | string 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. |
{- "items": [
- {
- "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
- "ip_address": "127.0.0.1",
- "active": true,
- "enriched": true,
- "domain_name": "example.com",
- "asset_id": "5605b488634efe810dff4276e28ca7f9",
- "team_id": "0e54921c386c666710134a5deecdbfe4",
- "ip_version": "IPv4",
- "first_seen_at": "2019-08-24T14:15:22Z",
- "disappeared_at": "2019-08-24T14:15:22Z",
- "autonomous_system": {
- "name": "EDGECAST",
- "domain": "example.com",
- "number": 15133
}, - "geolocation": {
- "continent": "NA",
- "continent_name": "North America",
- "country": "US",
- "country_name": "United States"
}
}
], - "pagination": {
}
}This query returns all discovered technologies on your attack surface.
| cursor | string 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. |
{- "items": [
- {
- "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
- "asset_id": "5605b488634efe810dff4276e28ca7f9",
- "team_id": "0e54921c386c666710134a5deecdbfe4",
- "domain_name": "example.com",
- "service_protocol": "https",
- "port": 443,
- "name": "nginx",
- "version": "1.25.2",
- "categories": [
- "Web servers",
- "Reverse proxies"
], - "active": true,
- "first_seen_at": "2019-08-24T14:15:22Z",
- "disappeared_at": "2019-08-24T14:15:22Z"
}
], - "pagination": {
}
}This query returns all discovered ports on your attack surface, including information to which IP and asset it was discovered on.
| cursor | string 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. |
{- "items": [
- {
- "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
- "team_id": "0e54921c386c666710134a5deecdbfe4",
- "asset_id": "5605b488634efe810dff4276e28ca7f9",
- "domain_name": "example.com",
- "ip_address": "127.0.0.1",
- "port": 443,
- "status": "OPEN",
- "first_seen_at": "2019-08-24T14:15:22Z",
- "disappeared_at": "2019-08-24T14:15:22Z"
}
], - "pagination": {
}
}This query returns all policy breaches which have been detected on your assets.
| cursor | string 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. |
{- "items": [
- {
- "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
- "policy_id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
- "policy_name": "My Policy",
- "asset_id": "5605b488634efe810dff4276e28ca7",
- "asset_name": "example.com",
- "severity": "INFO",
- "active": true,
- "status": "NEW",
- "status_updated_at": "2019-08-24T14:15:22Z",
- "first_seen_at": "2019-08-24T14:15:22Z",
- "disappeared_at": "2019-08-24T14:15:22Z"
}
], - "pagination": {
}
}Returns all connectors owned by the teams associated with the API key.
| cursor | string 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. |
{- "items": [
- {
- "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
- "name": "detectify-aws-connector",
- "team_id": "5605b488634efe810dff4276e28ca7f9",
- "last_run": {
- "status": "SUCCESS",
- "error": "Invalid credentials: Make sure the access keys are active",
- "completed_at": "2023-09-18T12:12:00Z"
}, - "provider": "AWS_ROLE_BASED",
- "created_at": "2023-09-18T12:12:00Z",
- "updated_at": "2023-09-18T12:12:00Z"
}
], - "pagination": {
}
}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" |
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) |
{- "team_id": "5605b488634efe810dff4276e28ca7f9",
- "name": "My AWS Cred-Based Connector",
- "provider": "AWS_ROLE_BASED",
- "options": {
- "access_key": "AKIAIOSFODNN7EXAMPLE",
- "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
}{- "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
- "name": "detectify-aws-connector",
- "team_id": "5605b488634efe810dff4276e28ca7f9",
- "last_run": {
- "status": "SUCCESS",
- "error": "Invalid credentials: Make sure the access keys are active",
- "completed_at": "2023-09-18T12:12:00Z"
}, - "provider": "AWS_ROLE_BASED",
- "created_at": "2023-09-18T12:12:00Z",
- "updated_at": "2023-09-18T12:12:00Z"
}Returns a single connector by its ID.
| id required | string |
{- "id": "0b14fd3e-9c30-4038-9d78-b5e7d992dc01",
- "name": "detectify-aws-connector",
- "team_id": "5605b488634efe810dff4276e28ca7f9",
- "last_run": {
- "status": "SUCCESS",
- "error": "Invalid credentials: Make sure the access keys are active",
- "completed_at": "2023-09-18T12:12:00Z"
}, - "provider": "AWS_ROLE_BASED",
- "created_at": "2023-09-18T12:12:00Z",
- "updated_at": "2023-09-18T12:12:00Z"
}Delete a connector by its ID.
| id required | string ID of a connector that should be deleted. |
{- "type": "/invalid_request",
- "title": "some title for the error situation",
- "status": 100,
- "detail": "some description for the error situation",
- "instance": "/invalid_request/query_parameters"
}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.
| 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. |
{- "external_id": "string",
- "team_id": "string"
}