How to get started with the new API?

The new v3 API uses the same domain as the old API, that is all requests are sent to api.detectify.com but instead of using the path /v2/ as in the previous API, you use the /v3/ path. For example, a request to list the technology data would go to https://api.detectify.com/rest/v3/technologies. What is new in this API is that you can retrieve all data from multiple teams with one endpoint and one API key. This makes it a lot easier to get insights from across multiple subsections of your organization.

For now, you cannot create API keys through the UI. Simply ask your CSM or support to get started.

To use the v2 API, create an API key here or read the documentation here.

IPs

This API endpoint allows you to list all IPs that are resolving from the DNS records discovered on your Attack Surface. The data will only be available for domains that are monitored by Surface Monitoring.

GET /rest/v3/ips

Query parameters

• cursor
  • string
    Next cursor value to continue the pagination. This value is optional and start from the first page if left blank.
• limit
  • integer <int32>
    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.
    

Return type: inline_response_200

Example data: Content-Type: application/json

{
  "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": {
    "self": "https://api.detectify.com/rest/v3/ips",
    "first": "https://api.detectify.com/rest/v3/ips",
    "prev": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54",
    "next": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54",
    "last": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54"
  }
}

Technologies

This API endpoint allows you to list all fingerprinted web technologies that have been found on your Attack Surface. The data will only be available for domains that are monitored by Surface Monitoring.

GET /rest/v3/technologies

Query parameters

• cursor
  • string
    Next cursor value to continue the pagination. This value is optional and start from the first page if left blank.
    
• limit
  • integer <int32>
    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.

Return type: inline_response_200

Example data: Content-Type: application/json

{
  "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": {
    "self": "https://api.detectify.com/rest/v3/ips",
    "first": "https://api.detectify.com/rest/v3/ips",
    "prev": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54",
    "next": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54",
    "last": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54"
  }
}

{
  "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": {
    "self": "https://api.detectify.com/rest/v3/ips",
    "first": "https://api.detectify.com/rest/v3/ips",
    "prev": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54",
    "next": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54",
    "last": "https://api.detectify.com/rest/v3/ips?cursor=2b0b2ccb-b228-42ee-a7ae-03971489ed54"
  }
}