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 informations 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,FILTERED 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 supplied teams as specified by their tokens.
| 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_token": "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": {
}
}